--- name: "erl_parse" section: "3erl" platform: "linux" package: "erlang-manpages" version: "1:25.2.3+dfsg-1+deb12u4" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/erl_parse" --- # erl\_parse(3erl) The Erlang parser. ## NAME erl\_parse - The Erlang parser. ## DESCRIPTION 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 ERTS User's Guide. Notice that a token list must end with the *dot* token to be acceptable to the parse functions (see the *[erl\_scan(3erl)](/erl_scan/3erl.md)*) module. ## DATA TYPES ``` abstract_clause() ``` Abstract form of an Erlang clause. ``` abstract_expr() ``` Abstract form of an Erlang expression. ``` abstract_form() ``` Abstract form of an Erlang form. ``` abstract_type() ``` Abstract form of an Erlang type. ``` erl_parse_tree() = abstract_clause() | abstract_expr() | abstract_form() | abstract_type() ``` ``` af_binelement(_) ``` Abstract representation of an element of a bitstring. ``` af_field_decl() ``` Abstract representation of a record field. ``` af_generator() ``` Abstract representation of a generator or a bitstring generator. ``` af_remote_function()> ``` Abstract representation of a remote function call. ``` error_description() = term() ``` ``` error_info() = {erl_anno:location(), module(), error_description()} ``` ``` form_info() = {eof, erl_anno:location()} | {error, erl_scan:error_info() | error_info()} | {warning, erl_scan:error_info() | error_info()} ``` Tuples *{error, error\_info()}* and *{warning, error\_info()}*, denoting syntactically incorrect forms and warnings, and *{eof, line()}*, denoting an end-of-stream encountered before a complete form had been parsed. ``` token() = erl_scan:token() ``` ## EXPORTS ``` abstract(Data) -> AbsTerm ``` Types: Data = term()\ AbsTerm = abstract\_expr()\ Converts the Erlang data structure *Data* into an abstract form of type *AbsTerm*. This function is the inverse of *normalise/1*. *erl\_parse:abstract(T)* is equivalent to *erl\_parse:abstract(T, 0)*. ``` abstract(Data, Options) -> AbsTerm ``` Types: Data = term()\ Options = Location \| \[Option\]\ Option = \ \ {encoding, Encoding} \| {line, Line} \| {location, Location}\ Encoding = latin1 \| unicode \| utf8 \| none \| encoding\_func()\ Line = erl\_anno:line()\ Location = erl\_anno:location()\ AbsTerm = abstract\_expr()\ ``` encoding_func() = fun((integer() >= 0) -> boolean()) ``` Converts the Erlang data structure *Data* into an abstract form of type *AbsTerm*. Each node of *AbsTerm* is assigned an annotation, see *[erl\_anno(3erl)](/erl_anno/3erl.md)*. The annotation contains the location given by option *location* or by option *line*. Option *location* overrides option *line*. If neither option *location* nor option *line* is given, *0* is used as location. Option *Encoding* is used for selecting which integer lists to be considered as strings. The default is to use the encoding returned by function *epp:default\_encoding/0*. Value *none* means that no integer lists are considered as strings. *encoding\_func()* is called with one integer of a list at a time; if it returns *true* for every integer, the list is considered a string. ``` anno_from_term(Term) -> erl_parse_tree() | form_info() ``` Types: Term = term()\ Assumes that *Term* is a term with the same structure as a *erl\_parse* tree, but with terms, say *T*, where a *erl\_parse* tree has collections of annotations. Returns a *erl\_parse* tree where each term *T* is replaced by the value returned by *erl\_anno:from\_term(T)*. The term *Term* is traversed in a depth-first, left-to-right fashion. ``` anno_to_term(Abstr) -> term() ``` Types: Abstr = erl\_parse\_tree() \| form\_info()\ Returns a term where each collection of annotations *Anno* of the nodes of the *erl\_parse* tree *Abstr* is replaced by the term returned by *erl\_anno:to\_term(Anno)*. The *erl\_parse* tree is traversed in a depth-first, left-to-right fashion. ``` fold_anno(Fun, Acc0, Abstr) -> Acc1 ``` Types: Fun = fun((Anno, AccIn) -\> AccOut)\ Anno = erl\_anno:anno()\ Acc0 = Acc1 = AccIn = AccOut = term()\ Abstr = erl\_parse\_tree() \| form\_info()\ Updates an accumulator by applying *Fun* on each collection of annotations of the *erl\_parse* tree *Abstr*. The first call to *Fun* has *AccIn* as argument, the returned accumulator *AccOut* is passed to the next call, and so on. The final value of the accumulator is returned. The *erl\_parse* tree is traversed in a depth-first, left-to-right fashion. **format\_error(ErrorDescriptor) -\> Chars**\ Types: ErrorDescriptor = error\_description()\ Chars = \[char() \| Chars\]\ Uses an *ErrorDescriptor* and returns a string that describes the error. This function is usually called implicitly when an *ErrorInfo* structure is processed (see section Error Information). ``` map_anno(Fun, Abstr) -> NewAbstr ``` Types: Fun = fun((Anno) -\> NewAnno)\ Anno = NewAnno = erl\_anno:anno()\ Abstr = NewAbstr = erl\_parse\_tree() \| form\_info()\ Modifies the *erl\_parse* tree *Abstr* by applying *Fun* on each collection of annotations of the nodes of the *erl\_parse* tree. The *erl\_parse* tree is traversed in a depth-first, left-to-right fashion. ``` mapfold_anno(Fun, Acc0, Abstr) -> {NewAbstr, Acc1} ``` Types: Fun = fun((Anno, AccIn) -\> {NewAnno, AccOut})\ Anno = NewAnno = erl\_anno:anno()\ Acc0 = Acc1 = AccIn = AccOut = term()\ Abstr = NewAbstr = erl\_parse\_tree() \| form\_info()\ Modifies the *erl\_parse* tree *Abstr* by applying *Fun* on each collection of annotations of the nodes of the *erl\_parse* tree, while at the same time updating an accumulator. The first call to *Fun* has *AccIn* as second argument, the returned accumulator *AccOut* is passed to the next call, and so on. The modified *erl\_parse* tree and the final value of the accumulator are returned. The *erl\_parse* tree is traversed in a depth-first, left-to-right fashion. ``` new_anno(Term) -> Abstr ``` Types: Term = term()\ Abstr = erl\_parse\_tree() \| form\_info()\ Assumes that *Term* is a term with the same structure as a *erl\_parse* tree, but with locations where a *erl\_parse* tree has collections of annotations. Returns a *erl\_parse* tree where each location *L* is replaced by the value returned by *erl\_anno:new(L)*. The term *Term* is traversed in a depth-first, left-to-right fashion. ``` normalise(AbsTerm) -> Data ``` Types: AbsTerm = abstract\_expr()\ Data = term()\ Converts the abstract form *AbsTerm* of a term into a conventional Erlang data structure (that is, the term itself). This function is the inverse of *abstract/1*. ``` parse_exprs(Tokens) -> {ok, ExprList} | {error, ErrorInfo} ``` Types: Tokens = \[token()\]\ ExprList = \[abstract\_expr()\]\ ErrorInfo = error\_info()\ Parses *Tokens* as if it was a list of expressions. Returns one of the following: - ***{ok, ExprList}*:** The parsing was successful. *ExprList* is a list of the abstract forms of the parsed expressions. - ***{error, ErrorInfo}*:** An error occurred. ``` parse_form(Tokens) -> {ok, AbsForm} | {error, ErrorInfo} ``` Types: Tokens = \[token()\]\ AbsForm = abstract\_form()\ ErrorInfo = error\_info()\ Parses *Tokens* as if it was a form. Returns one of the following: - ***{ok, AbsForm}*:** The parsing was successful. *AbsForm* is the abstract form of the parsed form. - ***{error, ErrorInfo}*:** An error occurred. ``` parse_term(Tokens) -> {ok, Term} | {error, ErrorInfo} ``` Types: Tokens = \[token()\]\ Term = term()\ ErrorInfo = error\_info()\ Parses *Tokens* as if it was a term. Returns one of the following: - ***{ok, Term}*:** The parsing was successful. *Term* is the Erlang term corresponding to the token list. - ***{error, ErrorInfo}*:** An error occurred. ``` tokens(AbsTerm) -> Tokens ``` ``` tokens(AbsTerm, MoreTokens) -> Tokens ``` Types: AbsTerm = abstract\_expr()\ MoreTokens = Tokens = \[token()\]\ Generates a list of tokens representing the abstract form *AbsTerm* of an expression. Optionally, *MoreTokens* is appended. ## ERROR INFORMATION *ErrorInfo* is the standard *ErrorInfo* structure that is returned from all I/O modules. The format is as follows: ``` {ErrorLine, Module, ErrorDescriptor} ``` A string describing the error is obtained with the following call: ``` Module:format_error(ErrorDescriptor) ``` ## SEE ALSO *[erl\_anno(3erl)](/erl_anno/3erl.md)*, *[erl\_scan(3erl)](/erl_scan/3erl.md)*, *[io(3erl)](/io/3erl.md)*, section The Abstract Format in the ERTS User's Guide