erl_error — stdlib v8.0

Search documentation of stdlib

# erl_error behaviour (stdlib v8.0)

Copy Markdown 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.

## 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.