erl_parse(3erl)

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  ac‐
13       ceptable 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       af_binelement(_)
39
40              Abstract representation of an element of a bitstring.
41
42       af_field_decl()
43
44              Abstract representation of a record field.
45
46       af_generator()
47
48              Abstract representation of a generator or a bitstring generator.
49
50       af_remote_function()>
51
52              Abstract representation of a remote function call.
53
54       error_description() = term()
55
56       error_info() =
57           {erl_anno:location(), module(), error_description()}
58
59       form_info() =
60           {eof, erl_anno:location()} |
61           {error, erl_scan:error_info() | error_info()} |
62           {warning, erl_scan:error_info() | error_info()}
63
64              Tuples {error, error_info()} and {warning, error_info()}, denot‐
65              ing  syntactically  incorrect  forms  and  warnings,  and  {eof,
66              line()}, denoting an end-of-stream encountered before a complete
67              form had been parsed.
68
69       token() = erl_scan:token()
70

EXPORTS

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

ERROR INFORMATION

287       ErrorInfo is the standard ErrorInfo structure that is returned from all
288       I/O modules. The format is as follows:
289
290       {ErrorLine, Module, ErrorDescriptor}
291
292       A string describing the error is obtained with the following call:
293
294       Module:format_error(ErrorDescriptor)
295

NAME

DESCRIPTION

DATA TYPES

EXPORTS

ERROR INFORMATION

SEE ALSO