Module: FormatException

Defined in:
lib/format_exception.rb,
lib/format_exception/version.rb

Overview

Simple exception formatter

Provides utility methods for formatting an exception as a String.

Examples:

Classic format


require "format_exception"

def make_mistake
  begin
    raise "Deliberate mistake"
  rescue Exception => ex
    $stderr.puts FormatException.classic(ex)
  end
end

make_mistake

# Prints:
#
# example.rb:7:in `make_mistake': Deliberate mistake (RuntimeError)
#         example.rb:13:in `<main>'

Contextual clean format to Logger


require "logger"
require "format_exception"

logger = Logger.new($stderr)
begin
  File.open("message.txt", "r") do |io|
    puts io.read
  end
rescue StandardError => ex
  logger.error(FormatException[ex, "Printing welcome message"])
end

# Prints
#
# E, [2017-02-11T01:56:08.763049 #4302] ERROR -- : Printing welcome message: Errno::ENOENT: No such file or directory @ rb_sysopen - message.txt:
#         foo.rb:10:in `initialize'
#         foo.rb:10:in `open'
#         foo.rb:10:in `<main>'

Contextual custom format


require "format_exception"

def make_mistake
  begin
    raise "Deliberate mistake"
  rescue Exception => ex
    $stderr.puts FormatException.format("%:m%C(\"%M\") at %f\n%R", ex, "Testing formatter")
  end
end

make_mistake

# Prints
#
# Testing formatter: RuntimeError("Deliberate mistake") at example.rb:7:in `make_mistake'
#         example.rb:13:in `<main>'

Data format


require "format_exception"

def make_mistake
  begin
    raise "Deliberate mistake"
  rescue Exception => ex
    $stderr.puts FormatException.classic(ex).to_s
  end
end

make_mistake

# Prints:
#
# {:name=>"RuntimeError", :message=>"Deliberate mistake", :backtrace=>["(irb):19:in `make_mistake'", ...]}

Constant Summary collapse

CLASSIC_FORMAT =

The classic format (see classic)

"%f: %:m%M (%C)\n%R"
CLEAN_FORMAT =

The clean format (see clean)

"%:m%C: %M:\n%B"
VERSION = 
"0.3.0"

Class Method Summary collapse

Class Method Details

.[](e, context_message = nil) ⇒ Object

Alias for clean



101
102
103
 
# File 'lib/format_exception.rb', line 101

def self.[](e, context_message = nil)
  clean(e, context_message)
end

.classic(e, context_message = nil) ⇒ String

The Ruby interpreter’s default format

Formats the exception exactly as the Ruby interpreter would if the exception was uncaught. The first line includes the first line of the backtrace, and the exception message and class name, with the rest of the backtrace on subsequent, indented lines.

If the context_message is given, it is included on the first line, between the first line of the backtrace and the exception message.

Parameters:

  • e (Exception) —

    the exception to format

  • context_message (String) (defaults to: nil) —

    the additional message to include in the formatted exception

Returns:

  • (String) —

    the formatted exception



122
123
124
 
# File 'lib/format_exception.rb', line 122

def self.classic(e, context_message = nil)
  format(CLASSIC_FORMAT, e, context_message)
end

.clean(e, context_message = nil) ⇒ String

The log-friendly format

Formats the exception as the Rails logger would, with the exception class name and message on the first line, with the backtrace on subsequent, indented lines.

If the context_message is given, it is prepended to the first line.

Parameters:

  • e (Exception) —

    the exception to format

  • context_message (String) (defaults to: nil) —

    the additional message to prepend to the formatted exception

Returns:

  • (String) —

    the formatted exception



140
141
142
 
# File 'lib/format_exception.rb', line 140

def self.clean(e, context_message = nil)
  format(CLEAN_FORMAT, e, context_message)
end

.data(e, context_message = nil) ⇒ Hash

Format exception as symbol-keyed dictionary

If the context_message is given, it is included as the :context_message key.

Parameters:

  • e (Exception) —

    the exception to format

  • context_message (String) (defaults to: nil) —

    the additional message to include in the dictionary

Returns:

  • (Hash) —

    the data representation of the exception

    • :name (String) exception class name

    • :message (String) exception message

    • :backtrace (Array) exception backtrace

    • :context_message (String) context_message if specified



159
160
161
162
163
164
165
166
167
 
# File 'lib/format_exception.rb', line 159

def self.data(e, context_message = nil)
  {
    name: e.class.to_s,
    message: e.message,
    backtrace: e.backtrace,
  }.tap { |h|
    h[:context_message] = context_message if context_message
  }
end

.format(f, e, c = nil) ⇒ Object

Format exception as per printf-like format specifier

The following format specifiers are supported:

  • %C - the exception class name

  • %M - the exception message

  • %m - the context message if given

  • %:m - the context message, a colon and a space, if the context message is given

  • %f - the first line of the backtrace, unindented

  • %r - all lines of the backtrace but the first, newline-separated, unindented

  • %R - all lines of the backtrace but the first, newline-separated, indented

  • %b - all lines of the backtrace, newline-separated, unindented

  • %B - all lines of the backtrace, newline-separated, indented

  • %% - a literal %



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/format_exception.rb', line 185

def self.format(f, e, c = nil)
  scanner = StringScanner.new(f)
  formatted = ""
  loop do
    formatted << scanner.scan(/[^%]*/)
    token = scanner.scan(/%:?./)
    case token
    when "%C" then formatted << e.class.to_s
    when "%M" then formatted << e.message
    when "%m" then formatted << c if c
    when "%:m" then formatted << "#{c}: " if c
    when "%f" then formatted << e.backtrace.first
    when "%r" then formatted << e.backtrace.drop(1).join("\n")
    when "%R" then formatted << ("\t" + e.backtrace.drop(1).join("\n\t"))
    when "%b" then formatted << e.backtrace.join("\n")
    when "%B" then formatted << ("\t" + e.backtrace.join("\n\t"))
    when "%%" then formatted << "%"
    when nil then break
    else
      raise ArgumentError, "unknown format specifier '#{scanner.matched}'"
    end
    break if scanner.eos?
  end
  formatted
end