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

NAME

6       erl_parse - The Erlang parser.
7

DESCRIPTION

9       This  module  is  the basic Erlang parser that converts tokens into the
10       abstract form of either forms (that is, top-level constructs),  expres‐
11       sions,  or  terms.  The Abstract Format is described in the ERTS User's
12       Guide. Notice that a token list must end  with  the  dot  token  to  be
13       acceptable to the parse functions (see the erl_scan(3)) module.
14

DATA TYPES

16       abstract_clause()
17
18              Abstract form of an Erlang clause.
19
20       abstract_expr()
21
22              Abstract form of an Erlang expression.
23
24       abstract_form()
25
26              Abstract form of an Erlang form.
27
28       abstract_type()
29
30              Abstract form of an Erlang type.
31
32       erl_parse_tree() =
33           abstract_clause() |
34           abstract_expr() |
35           abstract_form() |
36           abstract_type()
37
38       error_description() = term()
39
40       error_info() = {erl_anno:line(), module(), error_description()}
41
42       form_info() =
43           {eof, erl_anno:line()} |
44           {error, erl_scan:error_info() | error_info()} |
45           {warning, erl_scan:error_info() | error_info()}
46
47              Tuples {error, error_info()} and {warning, error_info()}, denot‐
48              ing  syntactically  incorrect  forms  and  warnings,  and  {eof,
49              line()}, denoting an end-of-stream encountered before a complete
50              form had been parsed.
51
52       token() = erl_scan:token()
53

EXPORTS

55       abstract(Data) -> AbsTerm
56
57              Types:
58
59                 Data = term()
60                 AbsTerm = abstract_expr()
61
62              Converts the Erlang data structure Data into an abstract form of
63              type AbsTerm. This function is the inverse of normalise/1.
64
65              erl_parse:abstract(T) is equivalent to erl_parse:abstract(T, 0).
66
67       abstract(Data, Options) -> AbsTerm
68
69              Types:
70
71                 Data = term()
72                 Options = Line | [Option]
73                 Option = {line, Line} | {encoding, Encoding}
74                 Encoding = latin1 | unicode | utf8 | none | encoding_func()
75                 Line = erl_anno:line()
76                 AbsTerm = abstract_expr()
77                 encoding_func() = fun((integer() >= 0) -> boolean())
78
79              Converts the Erlang data structure Data into an abstract form of
80              type AbsTerm.
81
82              Option Line is the line to be assigned to each node of AbsTerm.
83
84              Option Encoding is used for selecting which integer lists to  be
85              considered  as  strings.  The  default  is  to  use the encoding
86              returned by function epp:default_encoding/0.  Value  none  means
87              that no integer lists are considered as strings. encoding_func()
88              is called with one integer of a list at a time;  if  it  returns
89              true for every integer, the list is considered a string.
90
91       anno_from_term(Term) -> erl_parse_tree() | form_info()
92
93              Types:
94
95                 Term = term()
96
97              Assumes  that  Term  is  a  term  with  the  same structure as a
98              erl_parse tree, but with terms, say T, where  a  erl_parse  tree
99              has  collections  of annotations. Returns a erl_parse tree where
100              each  term  T   is   replaced   by   the   value   returned   by
101              erl_anno:from_term(T).  The  term  Term is traversed in a depth-
102              first, left-to-right fashion.
103
104       anno_to_term(Abstr) -> term()
105
106              Types:
107
108                 Abstr = erl_parse_tree() | form_info()
109
110              Returns a term where each collection of annotations Anno of  the
111              nodes  of  the  erl_parse  tree  Abstr  is  replaced by the term
112              returned by erl_anno:to_term(Anno). The erl_parse tree  is  tra‐
113              versed in a depth-first, left-to-right fashion.
114
115       fold_anno(Fun, Acc0, Abstr) -> Acc1
116
117              Types:
118
119                 Fun = fun((Anno, AccIn) -> AccOut)
120                 Anno = erl_anno:anno()
121                 Acc0 = Acc1 = AccIn = AccOut = term()
122                 Abstr = erl_parse_tree() | form_info()
123
124              Updates  an  accumulator  by  applying Fun on each collection of
125              annotations of the erl_parse tree Abstr. The first call  to  Fun
126              has AccIn as argument, the returned accumulator AccOut is passed
127              to the next call, and so on. The final value of the  accumulator
128              is  returned.  The erl_parse tree is traversed in a depth-first,
129              left-to-right fashion.
130
131       format_error(ErrorDescriptor) -> Chars
132
133              Types:
134
135                 ErrorDescriptor = error_description()
136                 Chars = [char() | Chars]
137
138              Uses an ErrorDescriptor and returns a string that describes  the
139              error. This function is usually called implicitly when an Error‐
140              Info structure is processed (see section  Error Information).
141
142       map_anno(Fun, Abstr) -> NewAbstr
143
144              Types:
145
146                 Fun = fun((Anno) -> NewAnno)
147                 Anno = NewAnno = erl_anno:anno()
148                 Abstr = NewAbstr = erl_parse_tree() | form_info()
149
150              Modifies the erl_parse tree Abstr by applying Fun on  each  col‐
151              lection  of  annotations of the nodes of the erl_parse tree. The
152              erl_parse tree is  traversed  in  a  depth-first,  left-to-right
153              fashion.
154
155       mapfold_anno(Fun, Acc0, Abstr) -> {NewAbstr, Acc1}
156
157              Types:
158
159                 Fun = fun((Anno, AccIn) -> {NewAnno, AccOut})
160                 Anno = NewAnno = erl_anno:anno()
161                 Acc0 = Acc1 = AccIn = AccOut = term()
162                 Abstr = NewAbstr = erl_parse_tree() | form_info()
163
164              Modifies  the  erl_parse tree Abstr by applying Fun on each col‐
165              lection of annotations of the nodes of the erl_parse tree, while
166              at  the same time updating an accumulator. The first call to Fun
167              has AccIn as second argument, the returned accumulator AccOut is
168              passed  to the next call, and so on. The modified erl_parse tree
169              and the  final  value  of  the  accumulator  are  returned.  The
170              erl_parse  tree  is  traversed  in  a depth-first, left-to-right
171              fashion.
172
173       new_anno(Term) -> Abstr
174
175              Types:
176
177                 Term = term()
178                 Abstr = erl_parse_tree() | form_info()
179
180              Assumes that Term is  a  term  with  the  same  structure  as  a
181              erl_parse  tree,  but  with locations where a erl_parse tree has
182              collections of annotations. Returns a erl_parse tree where  each
183              location L is replaced by the value returned by erl_anno:new(L).
184              The term Term is traversed in a depth-first, left-to-right fash‐
185              ion.
186
187       normalise(AbsTerm) -> Data
188
189              Types:
190
191                 AbsTerm = abstract_expr()
192                 Data = term()
193
194              Converts the abstract form AbsTerm of a term into a conventional
195              Erlang data structure (that is, the term itself). This  function
196              is the inverse of abstract/1.
197
198       parse_exprs(Tokens) -> {ok, ExprList} | {error, ErrorInfo}
199
200              Types:
201
202                 Tokens = [token()]
203                 ExprList = [abstract_expr()]
204                 ErrorInfo = error_info()
205
206              Parses Tokens as if it was a list of expressions. Returns one of
207              the following:
208
209                {ok, ExprList}:
210                  The parsing was  successful.  ExprList  is  a  list  of  the
211                  abstract forms of the parsed expressions.
212
213                {error, ErrorInfo}:
214                  An error occurred.
215
216       parse_form(Tokens) -> {ok, AbsForm} | {error, ErrorInfo}
217
218              Types:
219
220                 Tokens = [token()]
221                 AbsForm = abstract_form()
222                 ErrorInfo = error_info()
223
224              Parses Tokens as if it was a form. Returns one of the following:
225
226                {ok, AbsForm}:
227                  The  parsing was successful. AbsForm is the abstract form of
228                  the parsed form.
229
230                {error, ErrorInfo}:
231                  An error occurred.
232
233       parse_term(Tokens) -> {ok, Term} | {error, ErrorInfo}
234
235              Types:
236
237                 Tokens = [token()]
238                 Term = term()
239                 ErrorInfo = error_info()
240
241              Parses Tokens as if it was a term. Returns one of the following:
242
243                {ok, Term}:
244                  The parsing was successful. Term is the Erlang  term  corre‐
245                  sponding to the token list.
246
247                {error, ErrorInfo}:
248                  An error occurred.
249
250       tokens(AbsTerm) -> Tokens
251
252       tokens(AbsTerm, MoreTokens) -> Tokens
253
254              Types:
255
256                 AbsTerm = abstract_expr()
257                 MoreTokens = Tokens = [token()]
258
259              Generates  a  list  of  tokens  representing  the  abstract form
260              AbsTerm of an expression. Optionally, MoreTokens is appended.
261

ERROR INFORMATION

263       ErrorInfo is the standard ErrorInfo structure that is returned from all
264       I/O modules. The format is as follows:
265
266       {ErrorLine, Module, ErrorDescriptor}
267
268       A string describing the error is obtained with the following call:
269
270       Module:format_error(ErrorDescriptor)
271

SEE ALSO

273       erl_anno(3),  erl_scan(3),  io(3),  section  The Abstract Format in the
274       ERTS User's Guide
275
276
277
278Ericsson AB                       stdlib 3.10                     erl_parse(3)
Impressum