erl_error behaviour (stdlib v7.1-rc0)

View Source

This module provides functions for pretty-printing errors and exceptions. It is used by both the shell and by proc_lib to print exceptions.

It is possible for the module raising an error to provide additional information by calling error/3 with extra error information. More details about this mechanism is described in EEP-54.

Callback Functions

The following functions are to be exported from an Error Info handler.

Summary

Types

column()

Start column number. Default is 1.

format_fun()

A fun used to format function arguments for BIF and function calls. By default the following fun will be used

format_options()

A map with formatting options.

stack_trim_fun()

A fun used to trim the end of the stacktrace. It is called with module, function, and arity from an entry from the stacktrace. The fun is to return true if the entry should be trimmed, and false otherwise. The default value is

Callbacks

format_error(Reason, StackTrace)

This callback is called when format_exception/4 or similar functionality wants to provide extra information about an error. The Module:Function called is the one specificed by the error_info map.

Functions

format_exception(Class, Reason, StackTrace)

Equivalent to format_exception/4.

format_exception(Class, Reason, StackTrace, Options)

Format the error reason and stack back-trace caught using try ... catch in the same style as the shell formats them.

Types

column()

(not exported) (since OTP 24.0) 
-type column() :: pos_integer().

Start column number. Default is 1.

format_fun()

(since OTP 24.0) 
-type format_fun() :: fun((term(), column()) -> iolist()).

A fun used to format function arguments for BIF and function calls. By default the following fun will be used:

fun(Term, I) -> io_lib:print(Term, I, 80, 30) end

format_options()

(since OTP 24.0) 
-type format_options() ::
          #{column => column(), stack_trim_fun => stack_trim_fun(), format_fun => format_fun()}.

A map with formatting options.

stack_trim_fun()

(since OTP 24.0) 
-type stack_trim_fun() :: fun((module(), atom(), arity()) -> boolean()).

A fun used to trim the end of the stacktrace. It is called with module, function, and arity from an entry from the stacktrace. The fun is to return true if the entry should be trimmed, and false otherwise. The default value is:

fun(_, _, _) -> false end

Callbacks

format_error(Reason, StackTrace)

(since OTP 24.0) 
-callback format_error(Reason, StackTrace) -> ErrorDescription
                          when
                              Reason :: term(),
                              StackTrace :: erlang:stacktrace(),
                              ArgumentPosition :: pos_integer(),
                              ErrorDescription ::
                                  #{ArgumentPosition => unicode:chardata(),
                                    general => unicode:chardata(),
                                    reason => unicode:chardata()}.

This callback is called when format_exception/4 or similar functionality wants to provide extra information about an error. The Module:Function called is the one specificed by the error_info map.

The function should return a map with additional information about what have caused the exception. The possible keys of the map are:

  • ArgumentPosition = pos_integer() - The position of the argument that caused the error starting at 1.

  • general - An error that is not associated with any argument caused the error.

  • reason - If the Reason should be printed differently than the default way.

If the text returned includes new-lines, format_exception/4 will indent the text correctly.

Example:

-module(my_error_module).
-export([atom_to_string/1, format_error/2]).

atom_to_string(Arg) when is_atom(Arg) ->
  atom_to_list(Arg);
atom_to_string(Arg) ->
  erlang:error(badarg,[Arg],
               [{error_info,#{ module => ?MODULE,
                               cause => #{ 1 => "should be an atom" }}}]).

format_error(Reason, [{_M,_F,_As,Info}|_]) ->
  ErrorInfo = proplists:get_value(error_info, Info, #{}),
  ErrorMap = maps:get(cause, ErrorInfo),
  ErrorMap#{ general => "optional general information",
             reason => io_lib:format("~p: ~p",[?MODULE, Reason]) }.
1> c(my_error_module).
{ok,my_error_module}
2> my_error_module:atom_to_string(1).
** exception error: my_error_module: badarg
     in function  my_error_module:atom_to_string/1
        called as my_error_module:atom_to_string(1)
        *** argument 1: should be an atom
        *** optional general information

Functions

format_exception(Class, Reason, StackTrace)

(since OTP 24.0) 
-spec format_exception(Class, Reason, StackTrace) -> unicode:chardata()
                          when
                              Class :: error | exit | throw,
                              Reason :: term(),
                              StackTrace :: erlang:stacktrace().

Equivalent to format_exception/4.

format_exception(Class, Reason, StackTrace, Options)

(since OTP 24.0) 
-spec format_exception(Class, Reason, StackTrace, Options) -> unicode:chardata()
                          when
                              Class :: error | exit | throw,
                              Reason :: term(),
                              StackTrace :: erlang:stacktrace(),
                              Options :: format_options().

Format the error reason and stack back-trace caught using try ... catch in the same style as the shell formats them.

Example:

try
    do_something()
catch
    C:R:Stk ->
        Message = erl_error:format_exception(C, R, Stk),
        io:format(LogFile, "~ts\n", [Message])
end

If error_info is provided with the exception, format_exception will use that information to provide additional information about the exception.

Example:

try
  erlang:raise(badarg,[],[{error_info,#{}}])
catch
    C:R:Stk ->
        Message = erl_error:format_exception(C, R, Stk),
        io:format(LogFile, "~ts\n", [Message])
end

See erlang:error/3 for details on how to raise an exception with error_info included.