Exception behaviour

Functions to format throw/catch/exit and exceptions.

Note that stacktraces in Elixir are only available inside catch and rescue by using the __STACKTRACE__/0 variable.

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

arity_or_args()
kind(): The kind handled by formatting functions
location()
non_error_kind()
stacktrace()
stacktrace_entry()
t(): The exception type

Functions

blame(kind, error, stacktrace): Attaches information to exceptions for extra debugging.
blame_mfa(module, function, args): Blames the invocation of the given module, function and arguments.
exception?(term) deprecated: Returns true if the given term is an exception.
format(kind, payload, stacktrace \\ []): Normalizes and formats throw/errors/exits and stacktraces.
format_banner(kind, exception, stacktrace \\ []): Normalizes and formats any throw/error/exit.
format_exit(reason): Formats an exit. It 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, suffix \\ ""): Formats the given file and line as shown in stacktraces.
format_file_line_column(file, line, column, suffix \\ ""): Formats the given file, line, and column as shown in stacktraces.
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 \\ []): Normalizes an exception, converting Erlang exceptions to Elixir exceptions.

Callbacks

blame(t, stacktrace): Called from Exception.blame/3 to augment the exception struct.
exception(term)
message(t)

Types

arity_or_args()Source

Specs

arity_or_args() :: non_neg_integer() | list()

kind()Source

Specs

kind() :: :error | non_error_kind()

The kind handled by formatting functions

location()Source

Specs

location() :: keyword()

non_error_kind()Source

Specs

non_error_kind() :: :exit | :throw | {:EXIT, pid()}

stacktrace()Source

Specs

stacktrace() :: [stacktrace_entry()]

stacktrace_entry()Source

Specs

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

t()Source

Specs

t() :: %{
  :__struct__ => module(),
  :__exception__ => true,
  optional(atom()) => any()
}

The exception type

Functions

blame(kind, error, stacktrace)Source

Specs

blame(:error, any(), stacktrace()) :: {t(), stacktrace()}

blame(non_error_kind(), payload, stacktrace()) :: {payload, stacktrace()}
when payload: var

Attaches information to exceptions for extra debugging.

This operation is potentially expensive, as it reads data from the file system, parses beam files, evaluates code and so on.

If the exception module implements the optional blame/2 callback, it will be invoked to perform the computation.

blame_mfa(module, function, args)Source

Specs

blame_mfa(module(), function :: atom(), args :: [term()]) ::
  {:ok, :def | :defp | :defmacro | :defmacrop,
   [{args :: [term()], guards :: [term()]}]}
  | :error

Blames the invocation of the given module, function and arguments.

This function will retrieve the available clauses from bytecode and evaluate them against the given arguments. The clauses are returned as a list of {args, guards} pairs where each argument and each top-level condition in a guard separated by and/or is wrapped in a tuple with blame metadata.

This function returns either {:ok, definition, clauses} or :error. Where definition is :def, :defp, :defmacro or :defmacrop.

exception?(term)Source

This function is deprecated. Use Kernel.is_exception/1 instead.

Returns true if the given term is an exception.

format(kind, payload, stacktrace \\ [])Source

Specs

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

Normalizes and formats throw/errors/exits and stacktraces.

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

If kind is {:EXIT, pid}, it does not generate a stacktrace, as such exits are retrieved as messages without stacktraces.

format_banner(kind, exception, stacktrace \\ [])Source

Specs

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

Normalizes and formats any throw/error/exit.

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

The third argument is the stacktrace which is used to enrich a normalized error with more information. It is only used when the kind is an error.

format_exit(reason)Source

Specs

format_exit(any()) :: String.t()

Formats an exit. It 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)Source

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 -> nil end, 1)
#=> "#Function<...>/1"

format_file_line(file, line, suffix \\ "")Source

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_file_line_column(file, line, column, suffix \\ "")Source

Formats the given file, line, and column as shown in stacktraces.

If any of the values are nil, they are omitted.

Examples

iex> Exception.format_file_line_column("foo", 1, 2)
"foo:1:2:"

iex> Exception.format_file_line_column("foo", 1, nil)
"foo:1:"

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

iex> Exception.format_file_line_column("foo", nil, 2)
"foo:"

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

format_mfa(module, fun, arity)Source

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)Source

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)Source

Specs

format_stacktrace_entry(stacktrace_entry()) :: String.t()

Receives a stacktrace entry and formats it into a string.

message(exception)Source

Gets the message for an exception.

normalize(kind, payload, stacktrace \\ [])Source

Specs

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

normalize(non_error_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.

The third argument is the stacktrace which is used to enrich a normalized error with more information. It is only used when the kind is an error.

Callbacks

blame(t, stacktrace)Source

Specs

blame(t(), stacktrace()) :: {t(), stacktrace()}

Called from Exception.blame/3 to augment the exception struct.

Can be used to collect additional information about the exception or do some additional expensive computation.

exception(term)Source

Specs

exception(term()) :: t()

message(t)Source

Specs

message(t()) :: String.t()