File 1088-otp-Update-documentation-around-exceptions... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 1088-otp-Update-documentation-around-exceptions-and-error.patch of Package erlang (Revision a0b3ae25eeaaf8007a46a3a2b2ca2729)

Currently displaying revision a0b3ae25eeaaf8007a46a3a2b2ca2729 , Show latest

From 8690f3e5a298092135c8bf70abc34e91141ad431 Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Fri, 23 Apr 2021 15:16:08 +0200
Subject: [PATCH 08/13] otp: Update documentation around exceptions and
 error_info

---
 erts/doc/src/erlang.xml                 |  89 +++++++------
 lib/stdlib/doc/src/Makefile             |   2 +-
 lib/stdlib/doc/src/erl_error.xml        |  96 --------------
 lib/stdlib/doc/src/erl_error.xmlsrc     | 161 ++++++++++++++++++++++++
 lib/stdlib/examples/my_error_module.erl |  17 +++
 system/doc/reference_manual/errors.xml  | 122 +++++++++---------
 6 files changed, 287 insertions(+), 200 deletions(-)
 delete mode 100644 lib/stdlib/doc/src/erl_error.xml
 create mode 100644 lib/stdlib/doc/src/erl_error.xmlsrc
 create mode 100644 lib/stdlib/examples/my_error_module.erl

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 5a7d35714b..6b3a2ea96e 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1763,17 +1763,14 @@ b</pre>
 <fsummary>Raise an exception of class error.</fsummary>
 <desc>
 Raises an exception of class <c>error</c> with the reason
- <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
- is any term. The error reason is <c>{<anno>Reason</anno>,
- Where}</c>, where <c>Where</c> is a list of the functions most
- recently called (the current function first). As evaluating
- this function causes an exception to be thrown, it has no
- return value. The intent of the exception class <c>error</c> is to
- signal that an unexpected error has happened (for example, a
- function is called with a parameter that has an incorrect
- type). See the guide about <seeguide
- marker="system/reference_manual:errors">errors and error
- handling</seeguide> for additional information. Example:
+ <c><anno>Reason</anno></c>. As evaluating this function causes
+ an exception to be thrown, it has no return value.
+ The intent of the exception class <c>error</c> is to
+ signal that an unexpected error has happened (for example, a
+ function is called with a parameter that has an incorrect
+ type). See the guide about <seeguide
+ marker="system/reference_manual:errors">errors and error
+ handling</seeguide> for additional information. Example:
 <pre>
 > <input>catch error(foobar).</input>
 {'EXIT',{foobar,[{shell,apply_fun,3,
@@ -1792,16 +1789,12 @@ b</pre>
 <fsummary>Raise an exception of class <c>error</c></fsummary>
 <desc>
 Raises an exception of class <c>error</c> with the reason
- <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
- is any term. The error reason is
- <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
- is a list of the functions most recently called (the current
- function first). <c><anno>Args</anno></c> is expected to be the
+ <c><anno>Reason</anno></c>. <c><anno>Args</anno></c> is expected to be the
 list of arguments for the current function; it is used
 to provide the arguments for the current function in
 the term <c>Where</c>. As evaluating this function causes
- an exception to be raised, it has no return value.
- The intent of the exception class <c>error</c> is to
+ an exception to be raised, it has no return value.
+ The intent of the exception class <c>error</c> is to
 signal that an unexpected error has happened (for example, a
 function is called with a parameter that has an incorrect
 type). See the guide about <seeguide
@@ -1832,20 +1825,26 @@ example_fun(A1, A2) ->
 <fsummary>Raise an exception of class <c>error</c></fsummary>
 <desc>
 Raises an exception of class <c>error</c> with the reason
- <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
- is any term. <c><anno>Args</anno></c> is expected to be the
- list of arguments for the current function; it is used to
- provide the arguments for the current function in the stack
- back-trace. If the <c>{error_info,
- <anno>ErrorInfoMap</anno>}</c> option is given, it will be injected
- into the stacktrace.
-	As evaluating this function causes an exception to be
-	raised, it has no return value. The intent of the exception
-	class <c>error</c> is to signal that an unexpected error has
-	happened (for example, a function is called with a parameter
-	that has an incorrect type). See the guide about <seeguide
-	marker="system/reference_manual:errors">errors and error
-	handling</seeguide> for additional information.
+ <c><anno>Reason</anno></c>. <c><anno>Args</anno></c> is expected to be the
+ list of arguments for the current function; it is used to
+ provide the arguments for the current function in the stack
+ back-trace. As evaluating this function causes an exception to be
+	 raised, it has no return value.
+ If the <c>error_info</c> option is given, the <c><anno>ErrorInfoMap</anno></c>
+ will be inserted into the stacktrace. The information given in the
+ <c><anno>ErrorInfoMap</anno></c> is to be used by error formatters such as
+ <seemfa marker="stdlib:erl_error#format_exception/4"><c>erl_error</c></seemfa>
+ to provide more context around an error.
+ The default <c>module</c> of the <c><anno>ErrorInfoMap</anno></c> is the
+ module that the call to <seemfa marker="#error/3"><c>erlang:error/3</c></seemfa>
+ is made. The default <c>function</c> is <c>format_error</c>. See
+ <seeerl marker="stdlib:erl_error#format_error"><c>format_error/2</c></seeerl>
+ for more details on how this Module:Function/2 is to be used
+ The intent of the exception class <c>error</c> is to signal that
+ an unexpected error has happened (for example, a function is called
+ with a parameter that has an incorrect type). See the guide about <seeguide
+	 marker="system/reference_manual:errors">errors and error
+	 handling</seeguide> for additional information.
 </desc>
 </func>
 
@@ -1854,16 +1853,16 @@ example_fun(A1, A2) ->
 <fsummary>Raise an exception of class <c>exit</c> with a specified reason.</fsummary>
 <desc>
 Raises an exception of class <c>exit</c> with exit reason
- <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
- is any term. As evaluating this function causes an exception
- to be raised, it has no return value. This function should be
- used when the intent is to stop the current process. This
- function differ from <seemfa
- marker="#error/1"><c>erlang:error/1</c></seemfa> and <seemfa
- marker="#error/1"><c>erlang:error/2</c></seemfa> by causing an
- exception of a different class and by having a reason that
- does not include the list of functions from the call
- stack.
+ <c><anno>Reason</anno></c>. As evaluating this function causes
+ an exception to be raised, it has no return value.
+ The intent of the exception class <c>exit</c> is that the current
+ process should be stopped (for example when a message telling a process
+ to stop is received).
+ This function differ from <seemfa
+ marker="#error/1"><c>error/1,2,3</c></seemfa> by causing an
+ exception of a different class and by having a reason that
+ does not include the list of functions from the call
+ stack.
 See the guide about <seeguide
 marker="system/reference_manual:errors">errors and error
 handling</seeguide> for additional information.
@@ -6509,12 +6508,12 @@ catch Class:Reason:Stacktrace ->
 end</pre>
 That is, a list of
 four-tuples <c>{Module, Function, Arity | Args,
- Location}</c>, where <c>Module</c> and <c>Function</c>
+ ExtraInfo}</c>, where <c>Module</c> and <c>Function</c>
 are atoms, and the third element is an integer arity or an
 argument list. The stacktrace can also contain <c>{Fun,
- Args, Location}</c> tuples, where <c>Fun</c> is a local
+ Args, ExtraInfo}</c> tuples, where <c>Fun</c> is a local
 fun and <c>Args</c> is an argument list.
- Element <c>Location</c> at the end is optional.
+ Element <c>ExtraInfo</c> at the end is optional.
 Omitting it is equivalent to specifying an empty list.
 The stacktrace is used as the exception stacktrace for the
 calling process; it is truncated to the current
diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile
index 068917dcb7..fbec85ec53 100644
--- a/lib/stdlib/doc/src/Makefile
+++ b/lib/stdlib/doc/src/Makefile
@@ -45,7 +45,7 @@ XML_REF3_FILES = \
 	digraph_utils.xml \
 	epp.xml \
 	erl_anno.xml \
-	erl_error.xml \
+	erl_error.xmlsrc \
 	erl_eval.xml \
 	erl_expand_records.xml \
 	erl_id_trans.xml \
diff --git a/lib/stdlib/doc/src/erl_error.xml b/lib/stdlib/doc/src/erl_error.xml
deleted file mode 100644
index c1d50e2d9a..0000000000
--- a/lib/stdlib/doc/src/erl_error.xml
+++ /dev/null
@@ -1,96 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE erlref SYSTEM "erlref.dtd">
-
-<erlref>
- <header>
- <copyright>
- <year>2020</year>
- <year>2020</year>
- <holder>Ericsson AB, All Rights Reserved</holder>
- </copyright>
- <legalnotice>
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-
- The Initial Developer of the Original Code is Ericsson AB.
- </legalnotice>
-
- <title>erl_error</title>
- <prepared>Bjorn Gustavsson</prepared>
- <responsible>Kenneth Lundin</responsible>
- <docno>1</docno>
- <approved></approved>
- <checked></checked>
- <date>2020-10-16</date>
- <rev>A</rev>
- <file>erl_error.xml</file>
- </header>
- <module since="OTP 24.0">erl_error</module>
- <modulesummary>Utilities for reporting errors.
- </modulesummary>
-
- <description>
- This module provides functions for pretty-printing errors and exceptions.
- </description>
-
- <datatypes>
- <datatype>
- <name name="format_options"/>
- <desc>A map with formatting options.</desc>
- </datatype>
- <datatype>
- <name name="stack_trim_fun"/>
- <desc>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 <c>true</c> if the entry
- should be trimmed, and <c>false</c> otherwise. The default value
- is:
- <pre>
-fun(_, _, _) -> false end</pre>
- </desc>
- </datatype>
- <datatype>
- <name name="format_fun"/>
- <desc>A fun used to format function arguments for BIF and function calls.
- By default the following fun will be used:
- <pre>
-fun(Term, I) -> io_lib:print(Term, I, 80, 30) end</pre>
- </desc>
- </datatype>
- <datatype>
- <name name="column"/>
- <desc>Start column number. Default is 1.</desc>
- </datatype>
- </datatypes>
-
- <funcs>
- <func>
- <name name="format_exception" arity="3" since="OTP 24.0"/>
- <name name="format_exception" arity="4" since="OTP 24.0"/>
- <fsummary>Format an exception.</fsummary>
- <desc>
- Format the error reason and stack back-trace caught using
- <c>try</c> ... <c>catch</c> in the same style as the shell
-	formats them.
-	Example:
-	<pre>
-try
- do_something()
-catch
- C:R:Stk ->
- Message = erl_error:format_exception(C, R, Stk),
- io:format(LogFile, "~ts\n", [Message])
-end</pre>
- </desc>
- </func>
- </funcs>
-</erlref>
diff --git a/lib/stdlib/doc/src/erl_error.xmlsrc b/lib/stdlib/doc/src/erl_error.xmlsrc
new file mode 100644
index 0000000000..1ba04d07e4
--- /dev/null
+++ b/lib/stdlib/doc/src/erl_error.xmlsrc
@@ -0,0 +1,161 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2020</year>
+ <year>2020</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>erl_error</title>
+ <prepared>Bjorn Gustavsson</prepared>
+ <responsible>Kenneth Lundin</responsible>
+ <docno>1</docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2020-10-16</date>
+ <rev>A</rev>
+ <file>erl_error.xml</file>
+ </header>
+ <module since="OTP 24.0">erl_error</module>
+ <modulesummary>Utilities for reporting errors.
+ </modulesummary>
+
+ <description>
+ This module provides functions for pretty-printing errors and exceptions.
+ </description>
+
+ <datatypes>
+ <datatype>
+ <name name="format_options"/>
+ <desc>A map with formatting options.</desc>
+ </datatype>
+ <datatype>
+ <name name="stack_trim_fun"/>
+ <desc>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 <c>true</c> if the entry
+ should be trimmed, and <c>false</c> otherwise. The default value
+ is:
+ <pre>
+fun(_, _, _) -> false end</pre>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="format_fun"/>
+ <desc>A fun used to format function arguments for BIF and function calls.
+ By default the following fun will be used:
+ <pre>
+fun(Term, I) -> io_lib:print(Term, I, 80, 30) end</pre>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="column"/>
+ <desc>Start column number. Default is 1.</desc>
+ </datatype>
+ </datatypes>
+
+ <funcs>
+ <func>
+ <name name="format_exception" arity="3" since="OTP 24.0"/>
+ <name name="format_exception" arity="4" since="OTP 24.0"/>
+ <fsummary>Format an exception.</fsummary>
+ <desc>
+ Format the error reason and stack back-trace caught using
+ <c>try</c> ... <c>catch</c> in the same style as the shell
+	 formats them.
+	Example:
+	<code type="erl">
+try
+ do_something()
+catch
+ C:R:Stk ->
+ Message = erl_error:format_exception(C, R, Stk),
+ io:format(LogFile, "~ts\n", [Message])
+end</code>
+ If <c>error_info</c> is provided with the exception,
+ <c>format_exception</c> will use that information to provide
+ additional information about the exception.
+ Example:
+ <code type="erl">
+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</code>
+ See <seemfa marker="erts:erlang#error/3"><c>erlang:error/3</c></seemfa>
+ for details on how to raise an exception with <c>error_info</c> included.
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>Callback Functions</title>
+ The following functions are to be exported from an Error Info handler.
+ </section>
+
+ <funcs>
+ <func>
+ <name anchor="format_error" since="OTP @OTP-12345@">Module:format_error(Reason, StackTrace) -> ErrorDescription</name>
+ <fsummary>Callback for formatting exceptions</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ <v>StackTrace = <seetype marker="erts:erlang#stacktrace">erlang:stacktrace()</seetype></v>
+ <v>ArgumentPosition = pos_integer()</v>
+ <v>ErrorDescription = </v>
+ <v>&nbsp;&nbsp;#{ ArgumentPosition => <seetype marker="unicode#chardata">unicode:chardata()</seetype>, </v>
+ <v>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;general => <seetype marker="unicode#chardata">unicode:chardata()</seetype>,</v>
+ <v>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reason => <seetype marker="unicode#chardata">unicode:chardata()</seetype> }</v>
+ </type>
+ <desc>
+ This callback is called when <seemfa marker="#format_exception/4"><c>
+ format_exception/4</c></seemfa> or similar functionality wants to provide
+ extra information about an error. The <c>Module</c>:<c>Function</c> called
+ is the one specificed by the <c>error_info</c> map.
+ The function should return a map with additional information about what
+ have caused the exception. The possible keys of the map are:
+ <taglist>
+ <tag><c>ArgumentPosition = pos_integer()</c></tag>
+ <item>The position of the argument that caused the error starting at 1.</item>
+ <tag><c>general</c></tag>
+ <item>An error that is not associated with any argument caused the error.</item>
+ <tag><c>reason</c></tag>
+ <item>If the <c>Reason</c> should be printed differently than the default way.</item>
+ </taglist>
+ If the text returned includes new-lines,
+ <seemfa marker="#format_exception/4"><c>format_exception/4</c></seemfa> will
+ indent the text correctly.
+ Example:
+ <codeinclude file="../../examples/my_error_module.erl" tag="%% example" type="erl"></codeinclude>
+ <pre>
+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</pre>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
diff --git a/lib/stdlib/examples/my_error_module.erl b/lib/stdlib/examples/my_error_module.erl
new file mode 100644
index 0000000000..0902574132
--- /dev/null
+++ b/lib/stdlib/examples/my_error_module.erl
@@ -0,0 +1,17 @@
+%% 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]) }.
+%% example
diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml
index a37af6aba7..3b6b98551c 100644
--- a/system/doc/reference_manual/errors.xml
+++ b/system/doc/reference_manual/errors.xml
@@ -33,56 +33,50 @@
 <section>
 <title>Terminology</title>
 Errors can roughly be divided into four different types:
- <list type="bulleted">
- <item>Compile-time errors</item>
- <item>Logical errors</item>
- <item>Run-time errors</item>
- <item>Generated errors</item>
- </list>
- A compile-time error, for example a syntax error, does not
- cause much trouble as it is caught by the compiler.
- A logical error is when a program does not behave as intended,
- but does not crash. An example is that nothing happens when
- a button in a graphical user interface is clicked.
- A run-time error is when a crash occurs. An example is
- when an operator is applied to arguments of the wrong type.
- The Erlang programming language has built-in features for
- handling of run-time errors.
- A run-time error can also be emulated by calling
- <c>erlang:error(Reason)</c> or <c>erlang:error(Reason, Args)</c>.
- A run-time error is another name for an exception
- of class <c>error</c>.
- 
- A generated error is when the code itself calls
- <c>exit/1</c> or <c>throw/1</c>. Notice that emulated run-time
- errors are not denoted as generated errors here.
- 
- Generated errors are exceptions of classes <c>exit</c> and
- <c>throw</c>.
- 
- When a run-time error or generated error occurs in Erlang, 
- execution for the process that evaluated
- the erroneous expression is stopped.
- This is referred to as a failure, that execution or
- evaluation fails, or that the process fails,
- terminates, or exits. Notice that a process can
- terminate/exit for other reasons than a failure.
+ <taglist>
+ <tag>Compile-time errors</tag>
+ <item>When the compiler fails to compile the program, for example a syntax error.</item>
+ <tag>Logical errors</tag>
+ <item>When a program does not behave as intended, but does not crash.
+ An example is that nothing happens when a button in a graphical user
+ interface is clicked.</item>
+ <tag><marker id="run-time-errors"/>Run-time errors</tag>
+ <item>When a crash occurs. An example is
+ when an operator is applied to arguments of the wrong type.
+ The Erlang programming language has built-in features for
+ handling of run-time errors. A run-time error can also be
+ emulated by calling <seemfa marker="erts:erlang#error/1">
+ <c>error(Reason)</c></seemfa>. Run-time errors are exceptions of
+ class <c>error</c>.</item>
+ <tag><marker id="generated-errors"/>Generated errors</tag>
+ <item>When the code itself calls <seemfa marker="erts:erlang#exit/1">
+ <c>exit/1</c></seemfa> or <seemfa marker="erts:erlang#throw/1">
+ <c>throw/1</c></seemfa>. Generated errors are exceptions of
+ class <c>exit</c> or <c>throw</c>.</item>
+ </taglist>
+ When an exception occurs in Erlang, execution of the process that
+ evaluated the erroneous expression is stopped. This is referred to as a
+ failure, that execution or evaluation fails, or that the
+ process fails, terminates, or exits. Notice that
+ a process can terminate/exit for other reasons than a failure.
 A process that terminates emits an exit signal with
- an exit reason that says something about which error
- has occurred. Normally, some information about the error is
- printed to the terminal.
+ an exit reason that describes why the process terminated.
+ Normally, some information about any erroneous termination is printed
+ to the terminal. See <seeguide marker="processes#term">
+ Process Termination</seeguide> in the Processes chapter for more details
+ on termination.
 </section>
 
 <section>
 <title>Exceptions</title>
- Exceptions are run-time errors or generated errors and 
+ Exceptions are <seeguide marker="#run-time-errors">run-time errors</seeguide> or
+ <seeguide marker="#generated-errors">generated errors</seeguide> and
 are of three different classes, with different origins. The
- <seeguide marker="expressions#try">try</seeguide> expression 
+ <seeguide marker="expressions#try">try</seeguide> expression
 can distinguish between the different classes, whereas the
 <seeguide marker="expressions#catch">catch</seeguide>
- expression cannot. They are described in
- <seeguide marker="expressions">Expressions
- </seeguide>.
+ expression cannot. <c>try</c> and <c>catch</c> are described in
+ <seeguide marker="expressions">Expressions</seeguide>.
 <table>
 <row>
 <cell align="left" valign="middle">Class</cell>
@@ -92,7 +86,7 @@
 <cell align="left" valign="middle"><c>error</c></cell>
 <cell align="left" valign="middle">Run-time error,
 for example, <c>1+a</c>, or the process called
- <c>erlang:error/1,2</c></cell>
+ <c>error/1,2</c></cell>
 </row>
 <row>
 <cell align="left" valign="middle"><c>exit</c></cell>
@@ -104,23 +98,33 @@
 </row>
 <tcaption>Exception Classes.</tcaption>
 </table>
+ All of the above exceptions can also be generated by calling
+ <seemfa marker="erts:erlang#raise/3"><c>erlang:raise/3</c></seemfa>.
 An exception consists of its class, an exit reason
 (see <seeguide marker="#exit_reasons">Exit Reason</seeguide>),
 and a stack trace (which aids in finding the code location of
 the exception).
- The stack trace can be bound to a variable from within
- a <c>try</c> expression.
- An exception of class <c>error</c> is also known as a run-time 
- error.
-
+ The stack trace can be bound to a variable from within a <c>try</c>
+ expression for any exception class, or as part of the exit reason when
+ a run-time error is caught by a <c>catch</c>. Example:
+ <pre>
+> <input>{'EXIT',{test,Stacktrace}} = (catch error(test)), Stacktrace.</input>
+[{shell,apply_fun,3,[]},
+ {erl_eval,do_apply,6,[]},
+ ...]
+> <input>try throw(test) catch Class:Reason:Stacktrace -> Stacktrace end.</input>
+[{shell,apply_fun,3,[]},
+ {erl_eval,do_apply,6,[]},
+ ...]</pre>
 <section>
 	<marker id="stacktrace"></marker>
 	<title>The call-stack back trace (stacktrace)</title>
- The stack back-trace (stacktrace) is a list of
- <c>{Module,Function,Arity,ExtraInfo}</c>
- tuples. The field <c>Arity</c> in the first tuple can be the
- argument list of that function call instead of an arity integer,
- depending on the exception.
+ The stack back-trace
+ (<seetype marker="erts:erlang#stacktrace">stacktrace</seetype>)
+ is a list contains <c>{Module, Function, Arity, ExtraInfo}</c>
+ and/or <c>{Fun, Arity, ExtraInfo}</c> tuples. The field <c>Arity</c> in the
+ tuple can be the argument list of that function call instead of an
+ arity integer, depending on the exception.
 	 <c>ExtraInfo</c> is a (possibly empty) list of two-element tuples
 	 in any order that provides additional information about the exception.
 	 The first element is an atom describing the type of
@@ -130,7 +134,11 @@
 <tag><c>error_info</c></tag>
 <item>The second element of the tuple is a map
 	 providing additional information about what caused the
-	 exception.
+	 exception. This information can be created by calling
+ <seemfa marker="erts:erlang#error/3"><c>erlang:error/3</c></seemfa>
+ and is used by
+ <seemfa marker="stdlib:erl_error#format_exception/4">
+ <c>erl_error:format_exception/4</c></seemfa>.
 </item>
 <tag><c>file</c></tag>
 <item>The second element of the tuple is a string (list of
@@ -167,8 +175,7 @@
 <section>
 <title>Error Handling Within Processes</title>
 It is possible to prevent run-time errors and other
- exceptions from causing
- the process to terminate by using <c>catch</c> or
+ exceptions from causing the process to terminate by using <c>catch</c> or
 <c>try</c>, see <seeguide marker="expressions">
 Expressions</seeguide> about
 <seeguide marker="expressions#catch">catch</seeguide>
@@ -186,8 +193,7 @@
 <section>
 <marker id="exit_reasons"></marker>
 <title>Exit Reasons</title>
- When a run-time error occurs,
- that is an exception of class <c>error</c>.
+ When a run-time error occurs, that is an exception of class <c>error</c>.
 The exit reason is a tuple <c>{Reason,Stack}</c>, where
 <c>Reason</c> is a term indicating the type of error:
 <table>
-- 
2.26.2

Places

File 1088-otp-Update-documentation-around-exceptions-and-error.patch of Package erlang (Revision a0b3ae25eeaaf8007a46a3a2b2ca2729)

Places