diff options
Diffstat (limited to 'lib/stdlib/doc/src/erl_parse.xml')
-rw-r--r-- | lib/stdlib/doc/src/erl_parse.xml | 401 |
1 files changed, 216 insertions, 185 deletions
diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml index 0938b5dec3..647f36883c 100644 --- a/lib/stdlib/doc/src/erl_parse.xml +++ b/lib/stdlib/doc/src/erl_parse.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2015</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,284 +28,315 @@ <docno>1</docno> <approved>Bjarne Däcker</approved> <checked></checked> - <date>97-01-24</date> + <date>1997-01-24</date> <rev>B</rev> - <file>erl_parse.sgml</file> + <file>erl_parse.xml</file> </header> <module>erl_parse</module> - <modulesummary>The Erlang Parser</modulesummary> + <modulesummary>The Erlang parser.</modulesummary> <description> - <p>This module is the basic Erlang parser which converts tokens into - the abstract form of either forms (i.e., top-level constructs), + <p>This module is the basic Erlang parser that converts tokens into + the abstract form of either forms (that is, top-level constructs), expressions, or terms. The Abstract Format is described in the <seealso marker="erts:absform">ERTS User's Guide</seealso>. - Note that a token list must end with the <em>dot</em> token in order - to be acceptable to the parse functions (see <seealso marker="erl_scan">erl_scan(3)</seealso>).</p> + Notice that a token list must end with the <em>dot</em> token to be + acceptable to the parse functions (see the <seealso marker="erl_scan"> + <c>erl_scan(3)</c></seealso>) module.</p> </description> + <datatypes> <datatype> - <name name="abstract_clause"></name> - <desc><p>Parse tree for Erlang clause.</p> + <name>abstract_clause()</name> + <desc><p>Abstract form of an Erlang clause.</p> + </desc> + </datatype> + <datatype> + <name>abstract_expr()</name> + <desc><p>Abstract form of an Erlang expression.</p> </desc> </datatype> <datatype> - <name name="abstract_expr"></name> - <desc><p>Parse tree for Erlang expression.</p> + <name>abstract_form()</name> + <desc><p>Abstract form of an Erlang form.</p> </desc> </datatype> <datatype> - <name name="abstract_form"></name> - <desc><p>Parse tree for Erlang form.</p> + <name>abstract_type()</name> + <desc><p>Abstract form of an Erlang type.</p> </desc> </datatype> <datatype> + <name name="erl_parse_tree"></name> + </datatype> + <datatype> <name name="error_description"></name> </datatype> <datatype> <name name="error_info"></name> </datatype> <datatype> + <name name="form_info"></name> + <desc><p>Tuples <c>{error, error_info()}</c> and <c>{warning, + error_info()}</c>, denoting syntactically incorrect forms and + warnings, and <c>{eof, line()}</c>, denoting an end-of-stream + encountered before a complete form had been parsed.</p> + </desc> + </datatype> + <datatype> <name name="token"></name> </datatype> </datatypes> + <funcs> <func> - <name name="parse_form" arity="1"/> - <fsummary>Parse an Erlang form</fsummary> + <name name="abstract" arity="1"/> + <fsummary>Convert an Erlang term into an abstract form.</fsummary> <desc> - <p>This function parses <c><anno>Tokens</anno></c> as if it were - a form. It returns:</p> - <taglist> - <tag><c>{ok, <anno>AbsForm</anno>}</c></tag> - <item> - <p>The parsing was successful. <c><anno>AbsForm</anno></c> is the - abstract form of the parsed form.</p> - </item> - <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag> - <item> - <p>An error occurred.</p> - </item> - </taglist> + <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an + abstract form of type <c><anno>AbsTerm</anno></c>. + This function is the inverse of + <seealso marker="#normalise/1"><c>normalise/1</c></seealso>.</p> + <p><c>erl_parse:abstract(T)</c> is equivalent to + <c>erl_parse:abstract(T, 0)</c>.</p> </desc> </func> + <func> - <name name="parse_exprs" arity="1"/> - <fsummary>Parse Erlang expressions</fsummary> + <name name="abstract" arity="2"/> + <fsummary>Convert an Erlang term into an abstract form.</fsummary> + <type name="encoding_func"/> <desc> - <p>This function parses <c><anno>Tokens</anno></c> as if it were - a list of expressions. It returns:</p> - <taglist> - <tag><c>{ok, <anno>ExprList</anno>}</c></tag> - <item> - <p>The parsing was successful. <c><anno>ExprList</anno></c> is a - list of the abstract forms of the parsed expressions.</p> - </item> - <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag> - <item> - <p>An error occurred.</p> - </item> - </taglist> + <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an + abstract form of type <c><anno>AbsTerm</anno></c>.</p> + <p>Option <c><anno>Line</anno></c> is the line to be + assigned to each node of <c><anno>AbsTerm</anno></c>.</p> + <p>Option <c><anno>Encoding</anno></c> is used for + selecting which integer lists to be considered + as strings. The default is to use the encoding returned by + function <seealso marker="epp#default_encoding/0"> + <c>epp:default_encoding/0</c></seealso>. + Value <c>none</c> means that no integer lists are + considered as strings. <c>encoding_func()</c> is + called with one integer of a list at a time; if it + returns <c>true</c> for every integer, the list is + considered a string.</p> </desc> </func> + <func> - <name name="parse_term" arity="1"/> - <fsummary>Parse an Erlang term</fsummary> + <name name="anno_from_term" arity="1"/> + <fsummary>Return annotations as terms.</fsummary> <desc> - <p>This function parses <c><anno>Tokens</anno></c> as if it were - a term. It returns:</p> - <taglist> - <tag><c>{ok, <anno>Term</anno>}</c></tag> - <item> - <p>The parsing was successful. <c><anno>Term</anno></c> is - the Erlang term corresponding to the token list.</p> - </item> - <tag><c>{error, ErrorInfo}</c></tag> - <item> - <p>An error occurred.</p> - </item> - </taglist> + <p>Assumes that <c><anno>Term</anno></c> is a term with the same + structure as a <c>erl_parse</c> tree, but with terms, + say <c>T</c>, where a <c>erl_parse</c> tree has collections + of annotations. Returns a <c>erl_parse</c> tree where each + term <c>T</c> is replaced by the value returned by + <seealso marker="erl_anno#from_term/1"> + <c>erl_anno:from_term(T)</c></seealso>. The term + <c><anno>Term</anno></c> is traversed in a depth-first, + left-to-right fashion.</p> </desc> </func> + <func> - <name>format_error(ErrorDescriptor) -> Chars</name> - <fsummary>Format an error descriptor</fsummary> - <type> - <v>ErrorDescriptor = <seealso - marker="#type-error_info">error_description()</seealso></v> - <v>Chars = [char() | Chars]</v> - </type> + <name name="anno_to_term" arity="1"/> + <fsummary>Return the representation of annotations.</fsummary> <desc> - <p>Uses an <c>ErrorDescriptor</c> and returns a string - which describes the error. This function is usually called - implicitly when an <c>ErrorInfo</c> structure is processed - (see below).</p> + <p>Returns a term where each collection of annotations + <c>Anno</c> of the nodes of the <c>erl_parse</c> tree + <c><anno>Abstr</anno></c> is replaced by the term + returned by <seealso marker="erl_anno#to_term/1"> + <c>erl_anno:to_term(Anno)</c></seealso>. The + <c>erl_parse</c> tree is traversed in a depth-first, + left-to-right fashion.</p> </desc> </func> + <func> - <name name="tokens" arity="1"/> - <name name="tokens" arity="2"/> - <fsummary>Generate a list of tokens for an expression</fsummary> + <name name="fold_anno" arity="3"/> + <fsummary>Fold a function over the annotations of an <c>erl_parse</c> tree. + </fsummary> <desc> - <p>This function generates a list of tokens representing the abstract - form <c><anno>AbsTerm</anno></c> of an expression. Optionally, it - appends <c><anno>MoreTokens</anno></c>.</p> + <p>Updates an accumulator by applying <c><anno>Fun</anno></c> on + each collection of annotations of the <c>erl_parse</c> tree + <c><anno>Abstr</anno></c>. The first call to + <c><anno>Fun</anno></c> has <c><anno>AccIn</anno></c> as + argument, the returned accumulator + <c><anno>AccOut</anno></c> is passed to the next call, and + so on. The final value of the accumulator is returned. The + <c>erl_parse</c> tree is traversed in a depth-first, left-to-right + fashion.</p> </desc> </func> + <func> - <name name="normalise" arity="1"/> - <fsummary>Convert abstract form to an Erlang term</fsummary> + <name>format_error(ErrorDescriptor) -> Chars</name> + <fsummary>Format an error descriptor.</fsummary> + <type> + <v>ErrorDescriptor = <seealso + marker="#type-error_info">error_description()</seealso></v> + <v>Chars = [char() | Chars]</v> + </type> <desc> - <p>Converts the abstract form <c><anno>AbsTerm</anno></c> of a - term into a - conventional Erlang data structure (i.e., the term itself). - This is the inverse of <c>abstract/1</c>.</p> + <p>Uses an <c>ErrorDescriptor</c> and returns a string + that describes the error. This function is usually called + implicitly when an <c>ErrorInfo</c> structure is processed + (see section <seealso marker="#errorinfo"> + Error Information</seealso>).</p> </desc> </func> + <func> - <name name="abstract" arity="1"/> - <fsummary>Convert an Erlang term into an abstract form</fsummary> + <name name="map_anno" arity="2"/> + <fsummary>Map a function over the annotations of an <c>erl_parse</c> tree. + </fsummary> <desc> - <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an - abstract form of type <c><anno>AbsTerm</anno></c>. - This is the inverse of <c>normalise/1</c>.</p> - <p><c>erl_parse:abstract(T)</c> is equivalent to - <c>erl_parse:abstract(T, 0)</c>.</p> + <p>Modifies the <c>erl_parse</c> tree <c><anno>Abstr</anno></c> + by applying <c><anno>Fun</anno></c> on each collection of + annotations of the nodes of the <c>erl_parse</c> tree. The + <c>erl_parse</c> tree is traversed in a depth-first, + left-to-right fashion.</p> </desc> </func> + <func> - <name name="abstract" arity="2"/> - <fsummary>Convert an Erlang term into an abstract form</fsummary> - <type name="encoding_func"/> + <name name="mapfold_anno" arity="3"/> + <fsummary>Map and fold a function over the annotations of an + <c>erl_parse</c> tree.</fsummary> <desc> - <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an - abstract form of type <c><anno>AbsTerm</anno></c>.</p> - <p>The <c><anno>Line</anno></c> option is the line that will - be assigned to each node of the abstract form.</p> - <p>The <c><anno>Encoding</anno></c> option is used for - selecting which integer lists will be considered - as strings. The default is to use the encoding returned by - <seealso marker="epp#default_encoding/0"> - <c>epp:default_encoding/0</c></seealso>. - The value <c>none</c> means that no integer lists will be - considered as strings. The <c>encoding_func()</c> will be - called with one integer of a list at a time, and if it - returns <c>true</c> for every integer the list will be - considered a string.</p> + <p>Modifies the <c>erl_parse</c> tree <c><anno>Abstr</anno></c> + by applying <c><anno>Fun</anno></c> on each collection of + annotations of the nodes of the <c>erl_parse</c> tree, while + at the same time updating an accumulator. The first call to + <c><anno>Fun</anno></c> has <c><anno>AccIn</anno></c> as + second argument, the returned accumulator + <c><anno>AccOut</anno></c> is passed to the next call, and + so on. The modified <c>erl_parse</c> tree and the + final value of the accumulator are returned. The + <c>erl_parse</c> tree is traversed in a depth-first, + left-to-right fashion.</p> </desc> </func> + <func> - <name name="map_anno" arity="2"/> - <fsummary> - Map a function over the annotations of an abstract form - </fsummary> + <name name="new_anno" arity="1"/> + <fsummary>Create new annotations.</fsummary> <desc> - <p>Modifies the abstract form <anno>Abstr</anno> by applying - <anno>Fun</anno> on every collection of annotations of the - abstract form. The abstract form is traversed in a - depth-first, left-to-right, fashion. - </p> + <p>Assumes that <c><anno>Term</anno></c> is a term with the same + structure as a <c>erl_parse</c> tree, but with <seealso + marker="erl_anno#type-location">locations</seealso> where a + <c>erl_parse</c> tree has collections of annotations. + Returns a <c>erl_parse</c> tree where each location <c>L</c> + is replaced by the value returned by <seealso + marker="erl_anno#new/1"><c>erl_anno:new(L)</c></seealso>. + The term <c><anno>Term</anno></c> is traversed in a + depth-first, left-to-right fashion.</p> </desc> </func> + <func> - <name name="fold_anno" arity="3"/> - <fsummary> - Fold a function over the annotations of an abstract form - </fsummary> + <name name="normalise" arity="1"/> + <fsummary>Convert abstract form to an Erlang term.</fsummary> <desc> - <p>Updates an accumulator by applying <anno>Fun</anno> on - every collection of annotations of the abstract form - <anno>Abstr</anno>. The first call to <anno>Fun</anno> has - <anno>AccIn</anno> as argument, and the returned accumulator - <anno>AccOut</anno> is passed to the next call, and so on. - The final value of the accumulator is returned. The abstract - form is traversed in a depth-first, left-to-right, fashion. - </p> + <p>Converts the abstract form <c><anno>AbsTerm</anno></c> of a + term into a conventional Erlang data structure (that is, the + term itself). This function is the inverse of + <seealso marker="#abstract/1"><c>abstract/1</c></seealso>.</p> </desc> </func> + <func> - <name name="mapfold_anno" arity="3"/> - <fsummary> - Map and fold a function over the annotations of an abstract form - </fsummary> + <name name="parse_exprs" arity="1"/> + <fsummary>Parse Erlang expressions.</fsummary> <desc> - <p>Modifies the abstract form <anno>Abstr</anno> by applying - <anno>Fun</anno> on every collection of annotations of the - abstract form, while at the same time updating an - accumulator. The first call to <anno>Fun</anno> has - <anno>AccIn</anno> as second argument, and the returned - accumulator <anno>AccOut</anno> is passed to the next call, - and so on. The modified abstract form as well as the the - final value of the accumulator is returned. The abstract - form is traversed in a depth-first, left-to-right, fashion. - </p> + <p>Parses <c><anno>Tokens</anno></c> as if it was a list of expressions. + Returns one of the following:</p> + <taglist> + <tag><c>{ok, <anno>ExprList</anno>}</c></tag> + <item> + <p>The parsing was successful. <c><anno>ExprList</anno></c> is a + list of the abstract forms of the parsed expressions.</p> + </item> + <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag> + <item> + <p>An error occurred.</p> + </item> + </taglist> </desc> </func> + <func> - <name name="new_anno" arity="1"/> - <fsummary> - Create new annotations - </fsummary> + <name name="parse_form" arity="1"/> + <fsummary>Parse an Erlang form.</fsummary> <desc> - <p>Creates an abstract form from a term which has the same - structure as an abstract form, but <seealso - marker="erl_anno#type-location">locations</seealso> where the - abstract form has annotations. For each location, <seealso - marker="erl_anno#new/1"><c>erl_anno:new/1</c></seealso> is - called, and the annotations replace the location. - </p> + <p>Parses <c><anno>Tokens</anno></c> as if it was a form. Returns one + of the following:</p> + <taglist> + <tag><c>{ok, <anno>AbsForm</anno>}</c></tag> + <item> + <p>The parsing was successful. <c><anno>AbsForm</anno></c> is the + abstract form of the parsed form.</p> + </item> + <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag> + <item> + <p>An error occurred.</p> + </item> + </taglist> </desc> </func> + <func> - <name name="anno_from_term" arity="1"/> - <fsummary> - Return annotations as terms - </fsummary> + <name name="parse_term" arity="1"/> + <fsummary>Parse an Erlang term.</fsummary> <desc> - <p>Assumes that <anno>Term</anno> is a term with the same - structure as an abstract form, but with terms, T say, on - those places where an abstract form has annotations. Returns - an abstract form where every term T has been replaced by the - value returned by calling <c>erl_anno:from_term(T)</c>. The - term <anno>Term</anno> is traversed in a depth-first, - left-to-right, fashion. - </p> + <p>Parses <c><anno>Tokens</anno></c> as if it was a term. Returns + one of the following:</p> + <taglist> + <tag><c>{ok, <anno>Term</anno>}</c></tag> + <item> + <p>The parsing was successful. <c><anno>Term</anno></c> is + the Erlang term corresponding to the token list.</p> + </item> + <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag> + <item> + <p>An error occurred.</p> + </item> + </taglist> </desc> </func> + <func> - <name name="anno_to_term" arity="1"/> - <fsummary> - Return the representation of annotations - </fsummary> + <name name="tokens" arity="1"/> + <name name="tokens" arity="2"/> + <fsummary>Generate a list of tokens for an expression.</fsummary> <desc> - <p>Returns a term where every collection of annotations Anno of - <anno>Abstr</anno> has been replaced by the term returned by - calling <c>erl_anno:to_term(Anno)</c>. The abstract form is - traversed in a depth-first, left-to-right, fashion. - </p> + <p>Generates a list of tokens representing the abstract + form <c><anno>AbsTerm</anno></c> of an expression. Optionally, + <c><anno>MoreTokens</anno></c> is appended.</p> </desc> </func> </funcs> <section> + <marker id="errorinfo"/> <title>Error Information</title> - <p>The <c>ErrorInfo</c> mentioned above is the standard - <c>ErrorInfo</c> structure which is returned from all IO - modules. It has the format: - </p> + <p><c>ErrorInfo</c> is the standard <c>ErrorInfo</c> structure that is + returned from all I/O modules. The format is as follows:</p> <code type="none"> - {ErrorLine, Module, ErrorDescriptor} </code> - <p>A string which describes the error is obtained with the following call: - </p> +{ErrorLine, Module, ErrorDescriptor}</code> + <p>A string describing the error is obtained with the following call:</p> <code type="none"> - Module:format_error(ErrorDescriptor) </code> +Module:format_error(ErrorDescriptor)</code> </section> <section> <title>See Also</title> - <p><seealso marker="io">io(3)</seealso>, - <seealso marker="erl_anno">erl_anno(3)</seealso>, - <seealso marker="erl_scan">erl_scan(3)</seealso>, - <seealso marker="erts:absform">ERTS User's Guide</seealso></p> + <p><seealso marker="erl_anno"><c>erl_anno(3)</c></seealso>, + <seealso marker="erl_scan"><c>erl_scan(3)</c></seealso>, + <seealso marker="io"><c>io(3)</c></seealso>, + section <seealso marker="erts:absform">The Abstract Format</seealso> + in the ERTS User's Guide</p> </section> </erlref> |