Elixir v1.6.0 Exception behaviour View Source

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.

Link to this section Summary

Types

The kind handled by formatting functions

t()

The exception type

Functions

Attaches information to exceptions for extra debugging

Blames the invocation of the given module, function and arguments

Returns true if the given term is an exception

Normalizes and formats throw/errors/exits and stacktraces

Normalizes and formats any throw/error/exit

Formats an exit. It returns a string

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

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

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

Formats the stacktrace

Receives a stacktrace entry and formats it into a string

Gets the message for an exception

Normalizes an exception, converting Erlang exceptions to Elixir exceptions

Callbacks

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

Link to this section Types

Link to this type kind() View Source
kind() :: :error | non_error_kind()

The kind handled by formatting functions

Link to this type stacktrace() View Source
stacktrace() :: [stacktrace_entry()]
Link to this type stacktrace_entry() View Source
stacktrace_entry() ::
  {module(), atom(), arity_or_args(), location()}
  | {(... -> any()), arity_or_args(), location()}
Link to this type t() View Source
t() :: %module(){:__exception__ => true, optional(atom()) => any()}

The exception type

Link to this section Functions

Link to this function blame(kind, error, stacktrace) View Source
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 filesystem, parse beam files, evaluates code and so on.

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

Link to this function blame_mfa(module, function, args) View Source
blame_mfa(module(), function(), 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. Note this functionality requires Erlang/OTP 20, otherwise :error is always returned.

Returns true if the given term is an exception.

Link to this function format(kind, payload, stacktrace \\ nil) View Source
format(kind(), any(), stacktrace() | nil) :: 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.

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

Link to this function format_banner(kind, exception, stacktrace \\ nil) View Source
format_banner(kind(), any(), stacktrace() | nil) :: 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, 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.

Link to this function format_exit(reason) View Source
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.

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"
Link to this function format_file_line(file, line, suffix \\ "") View 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)
""
Link to this function format_mfa(module, fun, arity) View 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”

Link to this function format_stacktrace(trace \\ nil) View Source

Formats the stacktrace.

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

Link to this function format_stacktrace_entry(entry) View Source
format_stacktrace_entry(stacktrace_entry()) :: String.t()

Receives a stacktrace entry and formats it into a string.

Gets the message for an exception.

Link to this function normalize(kind, payload, stacktrace \\ nil) View Source
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, 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.

Link to this section Callbacks

Link to this callback blame(t, stacktrace) View Source (optional)
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.

Link to this callback exception(term) View Source
exception(term()) :: t()