Exception behaviour View Source
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.
Link to this section Summary
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
kind()
View Source
kind() :: :error | non_error_kind()
kind() :: :error | non_error_kind()
The kind handled by formatting functions
stacktrace()
View Source
stacktrace() :: [stacktrace_entry()]
stacktrace() :: [stacktrace_entry()]
stacktrace_entry() View Source
The exception type
Link to this section Functions
blame(kind, error, stacktrace)
View Source
(since 1.5.0)
blame(:error, any(), stacktrace()) :: {t(), stacktrace()}
blame(non_error_kind(), payload, stacktrace()) :: {payload, stacktrace()}
when payload: var
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) View Source (since 1.5.0)
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) View Source
Returns true
if the given term
is an exception.
format(kind, payload, stacktrace \\ [])
View Source
format(kind(), any(), stacktrace()) :: String.t()
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 \\ [])
View Source
format_banner(kind(), any(), stacktrace()) :: String.t()
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) View Source
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) View 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 \\ "") 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)
""
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"
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
.
format_stacktrace_entry(entry)
View Source
format_stacktrace_entry(stacktrace_entry()) :: String.t()
format_stacktrace_entry(stacktrace_entry()) :: String.t()
Receives a stacktrace entry and formats it into a string.
message(exception) View Source
Gets the message for an exception
.
normalize(kind, payload, stacktrace \\ [])
View Source
normalize(:error, any(), stacktrace()) :: t()
normalize(non_error_kind(), payload, stacktrace()) :: payload when payload: var
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.
Link to this section Callbacks
blame(t, stacktrace)
View Source
(optional)
blame(t(), stacktrace()) :: {t(), stacktrace()}
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.