Elixir v1.1.0 Exception behaviour

Functions to format throw/catch/exit and exceptions.

Note that stacktraces in Elixir are updated on throw, errors and exits. For example, at any given moment, System.stacktrace/0 will return the stacktrace for the last throw/error/exit that occurred in the current process.

Do not rely on the particular format returned by the format functions in this module. They may be changed in future releases in order to better suit Elixir’s tool chain. In other words, by using the functions in this module it is guaranteed you will format exceptions as in the current Elixir version being used.

Summary

Types

kind()

The kind handled by formatting functions

stacktrace()

stacktrace_entry()

t()

The exception type

Functions

exception?(term)

Returns true if the given term is an exception

format(kind, payload, stacktrace \\ nil)

Normalizes and formats throw/errors/exits and stacktrace

format_banner(kind, exception, stacktrace \\ nil)

Normalizes and formats any throw, error and exit

format_exit(reason)

Formats an exit, returns a string

format_fa(fun, arity)

Receives an anonymous function and arity and formats it as shown in stacktraces. The arity may also be a list of arguments

format_file_line(file, line)

Formats the given file and line as shown in stacktraces. If any of the values are nil, they are omitted

format_mfa(module, fun, arity)

Receives a module, fun and arity and formats it as shown in stacktraces. The arity may also be a list of arguments

format_stacktrace(trace \\ nil)

Formats the stacktrace

format_stacktrace_entry(entry)

Receives a stacktrace entry and formats it into a string

message(exception)

Gets the message for an exception

normalize(kind, payload, stacktrace \\ nil)

Normalizes an exception, converting Erlang exceptions to Elixir exceptions

Callbacks

exception(term)

message(t)

Types

kind :: :error | :exit | :throw | {:EXIT, pid}

The kind handled by formatting functions

stacktrace :: [stacktrace_entry]

stacktrace_entry ::
  {module, atom, arity_or_args, location} |
  {(... -> any), arity_or_args, location}

t :: %module{__exception__: true}

The exception type

Functions

exception?(term)

Returns true if the given term is an exception.

format(kind, payload, stacktrace \\ nil)

Specs

format(kind, any, stacktrace | nil) :: String.t

Normalizes and formats throw/errors/exits and stacktrace.

It relies on format_banner/3 and format_stacktrace/1 to generate the final format.

Note that {:EXIT, pid} do not generate a stacktrace though (as they are retrieved as messages without stacktraces).

format_banner(kind, exception, stacktrace \\ nil)

Specs

format_banner(kind, any, stacktrace | nil) :: String.t

Normalizes and formats any throw, error and exit.

The message is formatted and displayed in the same format as used by Elixir’s CLI.

The third argument, a stacktrace, is optional. If it is not supplied System.stacktrace/0 will sometimes be used to get additional information for the kind :error. If the stacktrace is unknown and System.stacktrace/0 would not return the stacktrace corresponding to the exception an empty stacktrace, [], must be used.

format_exit(reason)

Specs

format_exit(any) :: String.t

Formats an exit, returns a string.

Often there are errors/exceptions inside exits. Exits are often wrapped by the caller and provide stacktraces too. This function formats exits in a way to nicely show the exit reason, caller and stacktrace.

format_fa(fun, arity)

Receives an anonymous function and arity and formats it as shown in stacktraces. The arity may also be a list of arguments.

Examples

Exception.format_fa(fn -> end, 1)
#=> "#Function<...>/1"

format_file_line(file, line)

Formats the given file and line as shown in stacktraces. If any of the values are nil, they are omitted.

Examples

iex> Exception.format_file_line("foo", 1)
"foo:1:"

iex> Exception.format_file_line("foo", nil)
"foo:"

iex> Exception.format_file_line(nil, nil)
""

format_mfa(module, fun, arity)

Receives a module, fun and arity and formats it as shown in stacktraces. The arity may also be a list of arguments.

Examples

iex> Exception.format_mfa Foo, :bar, 1
"Foo.bar/1"

iex> Exception.format_mfa Foo, :bar, []
"Foo.bar()"

iex> Exception.format_mfa nil, :bar, []
"nil.bar()"

Anonymous functions are reported as -func/arity-anonfn-count-, where func is the name of the enclosing function. Convert to “anonymous fn in func/arity”

format_stacktrace(trace \\ nil)

Formats the stacktrace.

A stacktrace must be given as an argument. If not, the stacktrace is retrieved from Process.info/2.

format_stacktrace_entry(entry)

Specs

format_stacktrace_entry(stacktrace_entry) :: String.t

Receives a stacktrace entry and formats it into a string.

message(exception)

Gets the message for an exception.

normalize(kind, payload, stacktrace \\ nil)

Specs

normalize(:error, any, stacktrace) :: t

normalize(kind, payload, stacktrace) :: payload when payload: var

Normalizes an exception, converting Erlang exceptions to Elixir exceptions.

It takes the kind spilled by catch as an argument and normalizes only :error, returning the untouched payload for others.

Callbacks

exception(term)

Specs

exception(term) :: t

message(t)

Specs

message(t) :: String.t