1erl_error(3)               Erlang Module Definition               erl_error(3)
2
3
4

NAME

6       erl_error - Utilities for reporting errors.
7
8

DESCRIPTION

10       This  module  provides  functions for pretty-printing errors and excep‐
11       tions. It is used by both the shell and by  proc_lib  to  print  excep‐
12       tions.
13
14       It  is  possible  for the module raising an error to provide additional
15       information by calling error/3 with extra error information.  More  de‐
16       tails about this mechanism is described in EEP-54.
17

DATA TYPES

19       format_options() =
20           #{column => column(),
21             stack_trim_fun => stack_trim_fun(),
22             format_fun => format_fun()}
23
24              A map with formatting options.
25
26       stack_trim_fun() =
27           fun((module(), atom(), arity()) -> boolean())
28
29              A  fun used to trim the end of the stacktrace. It is called with
30              module, function, and arity from an entry from  the  stacktrace.
31              The  fun  is  to return true if the entry should be trimmed, and
32              false otherwise. The default value is:
33
34              fun(_, _, _) -> false end
35
36       format_fun() = fun((term(), column()) -> iolist())
37
38              A fun used to format function arguments  for  BIF  and  function
39              calls. By default the following fun will be used:
40
41              fun(Term, I) -> io_lib:print(Term, I, 80, 30) end
42
43       column() = integer() >= 1
44
45              Start column number. Default is 1.
46

EXPORTS

48       format_exception(Class, Reason, StackTrace) -> unicode:chardata()
49
50       format_exception(Class, Reason, StackTrace, Options) ->
51                           unicode:chardata()
52
53              Types:
54
55                 Class = error | exit | throw
56                 Reason = term()
57                 StackTrace = erlang:stacktrace()
58                 Options = format_options()
59
60              Format  the  error  reason and stack back-trace caught using try
61              ... catch in the same style as the shell formats them.
62
63              Example:
64
65              try
66                  do_something()
67              catch
68                  C:R:Stk ->
69                      Message = erl_error:format_exception(C, R, Stk),
70                      io:format(LogFile, "~ts\n", [Message])
71              end
72
73              If error_info is provided with the  exception,  format_exception
74              will  use  that  information  to  provide additional information
75              about the exception.
76
77              Example:
78
79              try
80                erlang:raise(badarg,[],[{error_info,#{}}])
81              catch
82                  C:R:Stk ->
83                      Message = erl_error:format_exception(C, R, Stk),
84                      io:format(LogFile, "~ts\n", [Message])
85              end
86
87              See erlang:error/3 for details on how to raise an exception with
88              error_info included.
89

CALLBACK FUNCTIONS

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

EXPORTS

94       Module:format_error(Reason, StackTrace) -> ErrorDescription
95
96              Types:
97
98                 Reason = term()
99                 StackTrace = erlang:stacktrace()
100                 ArgumentPosition = pos_integer()
101                 ErrorDescription =
102                  #{ ArgumentPosition => unicode:chardata(),
103                  general => unicode:chardata(),
104                  reason => unicode:chardata() }
105
106              This  callback  is  called  when   format_exception/4 or similar
107              functionality wants to provide extra information about an error.
108              The  Module:Function  called  is  the  one specificed by the er‐
109              ror_info map.
110
111              The function should return a  map  with  additional  information
112              about  what  have caused the exception. The possible keys of the
113              map are:
114
115                ArgumentPosition = pos_integer():
116                  The position of the argument that caused the error  starting
117                  at 1.
118
119                general:
120                  An error that is not associated with any argument caused the
121                  error.
122
123                reason:
124                  If the Reason should be printed differently than the default
125                  way.
126
127              If the text returned includes new-lines, format_exception/4 will
128              indent the text correctly.
129
130              Example:
131
132              -module(my_error_module).
133              -export([atom_to_string/1, format_error/2]).
134
135              atom_to_string(Arg) when is_atom(Arg) ->
136                atom_to_list(Arg);
137              atom_to_string(Arg) ->
138                erlang:error(badarg,[Arg],
139                             [{error_info,#{ module => ?MODULE,
140                                             cause => #{ 1 => "should be an atom" }}}]).
141
142              format_error(Reason, [{_M,_F,_As,Info}|_]) ->
143                ErrorInfo = proplists:get_value(error_info, Info, #{}),
144                ErrorMap = maps:get(cause, ErrorInfo),
145                ErrorMap#{ general => "optional general information",
146                           reason => io_lib:format("~p: ~p",[?MODULE, Reason]) }.
147
148              1> c(my_error_module).
149              {ok,my_error_module}
150              2> my_error_module:atom_to_string(1).
151              ** exception error: my_error_module: badarg
152                   in function  my_error_module:atom_to_string/1
153                      called as my_error_module:atom_to_string(1)
154                      *** argument 1: should be an atom
155                      *** optional general information
156
157
158
159Ericsson AB                     stdlib 4.3.1.3                    erl_error(3)