1erl_syntax_lib(3) Erlang Module Definition erl_syntax_lib(3)
2
6 erl_syntax_lib - Support library for abstract Erlang syntax trees.
7
9 Support library for abstract Erlang syntax trees.
10 This module contains utility functions for working with the abstract
12 data type defined in the module erl_syntax.
13
15 appFunName() = {atom(), arity()} | {atom(), {atom(), arity()}}:
16 field() = {atom(), {field_default(), field_type()}}:
19 field_default() = none | erl_syntax:syntaxTree():
22 field_type() = none | erl_syntax:syntaxTree():
25 fields() = [field()]:
28 functionN() = atom() | {atom(), arity()}:
31 functionName() = functionN() | {atom(), functionN()}:
34 info() = {atom(), [{atom(), erl_syntax:syntaxTree()}]} | {atom(),
37 atom()} | atom():
38 info_pair() = {key(), term()}:
41 key() = attributes | errors | exports | functions | imports | module
44 | records | warnings:
45 name() = shortname() | {atom(), shortname()}:
48 ordset(T) = ordsets:ordset(T):
51 set(T) = sets:set(T):
54 shortname() = atom() | {atom(), arity()}:
57 syntaxTree() = erl_syntax:syntaxTree():
60 An abstract syntax tree. See the erl_syntax module for details.
63 typeName() = atom() | {module(), {atom(), arity()}} | {atom(), ar‐
65 ity()}:
66
69 analyze_application(Node::erl_syntax:syntaxTree()) -> appFunName() |
70 arity()
71 Returns the name of a called function. The result is a represen‐
73 tation of the name of the applied function F/A, if Node repre‐
74 sents a function application "<em>F</em>(<em>X_1</em>, ...,
75 <em>X_A</em>)". If the function is not explicitly named (i.e., F
76 is given by some expression), only the arity A is returned.
77 The evaluation throws syntax_error if Node does not represent a
79 well-formed application expression.
80 See also: analyze_function_name/1.
82 analyze_attribute(Node::erl_syntax:syntaxTree()) -> preprocessor |
84 {atom(), term()}
85 Analyzes an attribute node. If Node represents a preprocessor
87 directive, the atom preprocessor is returned. Otherwise, if Node
88 represents a module attribute "-<em>Name</em>...", a tuple
89 {Name, Info} is returned, where Info depends on Name, as fol‐
90 lows:
91 {module, Info}:
93 where Info = analyze_module_attribute(Node).
94 {export, Info}:
96 where Info = analyze_export_attribute(Node).
97 {import, Info}:
99 where Info = analyze_import_attribute(Node).
100 {file, Info}:
102 where Info = analyze_file_attribute(Node).
103 {record, Info}:
105 where Info = analyze_record_attribute(Node).
106 {Name, Info}:
108 where {Name, Info} = analyze_wild_attribute(Node).
109 The evaluation throws syntax_error if Node does not represent a
111 well-formed module attribute.
112 See also: analyze_export_attribute/1, analyze_file_attribute/1,
114 analyze_import_attribute/1, analyze_module_attribute/1, ana‐
115 lyze_record_attribute/1, analyze_wild_attribute/1.
116 analyze_export_attribute(Node::erl_syntax:syntaxTree()) -> [function‐
118 Name()]
119 Returns the list of function names declared by an export attri‐
121 bute. We do not guarantee that each name occurs at most once in
122 the list. The order of listing is not defined.
123 The evaluation throws syntax_error if Node does not represent a
125 well-formed export attribute.
126 See also: analyze_attribute/1.
128 analyze_file_attribute(Node::erl_syntax:syntaxTree()) -> {string(), in‐
130 teger()}
131 Returns the file name and line number of a file attribute. The
133 result is the pair {File, Line} if Node represents "-file(File,
134 Line).".
135 The evaluation throws syntax_error if Node does not represent a
137 well-formed file attribute.
138 See also: analyze_attribute/1.
140 analyze_form(Node::erl_syntax:syntaxTree()) -> {atom(), term()} |
142 atom()
143 Analyzes a "source code form" node. If Node is a "form" type
145 (cf. erl_syntax:is_form/1), the returned value is a tuple {Type,
146 Info} where Type is the node type and Info depends on Type, as
147 follows:
148 {attribute, Info}:
150 where Info = analyze_attribute(Node).
151 {error_marker, Info}:
153 where Info = erl_syntax:error_marker_info(Node).
154 {function, Info}:
156 where Info = analyze_function(Node).
157 {warning_marker, Info}:
159 where Info = erl_syntax:warning_marker_info(Node).
160 For other types of forms, only the node type is returned.
162 The evaluation throws syntax_error if Node is not well-formed.
164 See also: analyze_attribute/1, analyze_function/1, erl_syn‐
166 tax:error_marker_info/1, erl_syntax:is_form/1, erl_syntax:warn‐
167 ing_marker_info/1.
168 analyze_forms(Forms::erl_syntax:forms()) -> [info_pair()]
170 Analyzes a sequence of "program forms". The given Forms may be a
172 single syntax tree of type form_list, or a list of "program
173 form" syntax trees. The returned value is a list of pairs {Key,
174 Info}, where each value of Key occurs at most once in the list;
175 the absence of a particular key indicates that there is no well-
176 defined value for that key.
177 Each entry in the resulting list contains the following corre‐
179 sponding information about the program forms:
180 {attributes, Attributes}:
182 * Attributes = [{atom(), term()}]
185 Attributes is a list of pairs representing the names and
187 corresponding values of all so-called "wild" attributes (as
188 e.g. "-compile(...)") occurring in Forms (cf. ana‐
189 lyze_wild_attribute/1). We do not guarantee that each name
190 occurs at most once in the list. The order of listing is not
191 defined.
192 {errors, Errors}:
194 * Errors = [term()]
197 Errors is the list of error descriptors of all error_marker
199 nodes that occur in Forms. The order of listing is not de‐
200 fined.
201 {exports, Exports}:
203 * Exports = [FunctionName]
206 * FunctionName = atom() | {atom(), integer()} | {ModuleName,
208 FunctionName}
209 * ModuleName = atom()
211 Exports is a list of representations of those function names
213 that are listed by export declaration attributes in Forms
214 (cf. analyze_export_attribute/1). We do not guarantee that
215 each name occurs at most once in the list. The order of
216 listing is not defined.
217 {functions, Functions}:
219 * Functions = [{atom(), integer()}]
222 Functions is a list of the names of the functions that are
224 defined in Forms (cf. analyze_function/1). We do not guaran‐
225 tee that each name occurs at most once in the list. The or‐
226 der of listing is not defined.
227 {imports, Imports}:
229 * Imports = [{Module, Names}]
232 * Module = atom()
234 * Names = [FunctionName]
236 * FunctionName = atom() | {atom(), integer()} | {ModuleName,
238 FunctionName}
239 * ModuleName = atom()
241 Imports is a list of pairs representing those module names
243 and corresponding function names that are listed by import
244 declaration attributes in Forms (cf. analyze_import_attri‐
245 bute/1), where each Module occurs at most once in Imports.
246 We do not guarantee that each name occurs at most once in
247 the lists of function names. The order of listing is not de‐
248 fined.
249 {module, ModuleName}:
251 * ModuleName = atom()
254 ModuleName is the name declared by a module attribute in
256 Forms. If no module name is defined in Forms, the result
257 will contain no entry for the module key. If multiple module
258 name declarations should occur, all but the first will be
259 ignored.
260 {records, Records}:
262 * Records = [{atom(), Fields}]
265 * Fields = [{atom(), {Default, Type}}]
267 * Default = none | syntaxTree()
269 * Type = none | syntaxTree()
271 Records is a list of pairs representing the names and corre‐
273 sponding field declarations of all record declaration at‐
274 tributes occurring in Forms. For fields declared without a
275 default value, the corresponding value for Default is the
276 atom none. Similarly, for fields declared without a type,
277 the corresponding value for Type is the atom none (cf. ana‐
278 lyze_record_attribute/1). We do not guarantee that each
279 record name occurs at most once in the list. The order of
280 listing is not defined.
281 {warnings, Warnings}:
283 * Warnings = [term()]
286 Warnings is the list of error descriptors of all warn‐
288 ing_marker nodes that occur in Forms. The order of listing
289 is not defined.
290 The evaluation throws syntax_error if an ill-formed Erlang con‐
292 struct is encountered.
293 See also: analyze_export_attribute/1, analyze_function/1, ana‐
295 lyze_import_attribute/1, analyze_record_attribute/1, ana‐
296 lyze_wild_attribute/1, erl_syntax:error_marker_info/1, erl_syn‐
297 tax:warning_marker_info/1.
298 analyze_function(Node::erl_syntax:syntaxTree()) -> {atom(), arity()}
300 Returns the name and arity of a function definition. The result
302 is a pair {Name, A} if Node represents a function definition
303 "Name(<em>P_1</em>, ..., <em>P_A</em>) -> ...".
304 The evaluation throws syntax_error if Node does not represent a
306 well-formed function definition.
307 analyze_function_name(Node::erl_syntax:syntaxTree()) -> functionName()
309 Returns the function name represented by a syntax tree. If Node
311 represents a function name, such as "foo/1" or "bloggs:fred/2",
312 a uniform representation of that name is returned. Different
313 nestings of arity and module name qualifiers in the syntax tree
314 does not affect the result.
315 The evaluation throws syntax_error if Node does not represent a
317 well-formed function name.
318 analyze_implicit_fun(Node::erl_syntax:syntaxTree()) -> functionName()
320 Returns the name of an implicit fun expression "fun <em>F</em>".
322 The result is a representation of the function name F. (Cf. ana‐
323 lyze_function_name/1.)
324 The evaluation throws syntax_error if Node does not represent a
326 well-formed implicit fun.
327 See also: analyze_function_name/1.
329 analyze_import_attribute(Node::erl_syntax:syntaxTree()) -> {atom(),
331 [functionName()]} | atom()
332 Returns the module name and (if present) list of function names
334 declared by an import attribute. The returned value is an atom
335 Module or a pair {Module, Names}, where Names is a list of func‐
336 tion names declared as imported from the module named by Module.
337 We do not guarantee that each name occurs at most once in Names.
338 The order of listing is not defined.
339 The evaluation throws syntax_error if Node does not represent a
341 well-formed import attribute.
342 See also: analyze_attribute/1.
344 analyze_module_attribute(Node::erl_syntax:syntaxTree()) -> atom() |
346 {atom(), [atom()]}
347 Returns the module name and possible parameters declared by a
349 module attribute. If the attribute is a plain module declaration
350 such as -module(name), the result is the module name. If the at‐
351 tribute is a parameterized module declaration, the result is a
352 tuple containing the module name and a list of the parameter
353 variable names.
354 The evaluation throws syntax_error if Node does not represent a
356 well-formed module attribute.
357 See also: analyze_attribute/1.
359 analyze_record_attribute(Node::erl_syntax:syntaxTree()) -> {atom(),
361 fields()}
362 Returns the name and the list of fields of a record declaration
364 attribute. The result is a pair {Name, Fields}, if Node repre‐
365 sents "-record(Name, {...}).", where Fields is a list of pairs
366 {Label, {Default, Type}} for each field "Label", "Label =
367 <em>Default</em>", "Label :: <em>Type</em>", or "Label = <em>De‐
368 fault</em> :: <em>Type</em>" in the declaration, listed in left-
369 to-right order. If the field has no default-value declaration,
370 the value for Default will be the atom none. If the field has no
371 type declaration, the value for Type will be the atom none. We
372 do not guarantee that each label occurs at most once in the
373 list.
374 The evaluation throws syntax_error if Node does not represent a
376 well-formed record declaration attribute.
377 See also: analyze_attribute/1, analyze_record_field/1.
379 analyze_record_expr(Node::erl_syntax:syntaxTree()) -> {atom(), info()}
381 | atom()
382 Returns the record name and field name/names of a record expres‐
384 sion. If Node has type record_expr, record_index_expr or
385 record_access, a pair {Type, Info} is returned, otherwise an
386 atom Type is returned. Type is the node type of Node, and Info
387 depends on Type, as follows:
388 record_expr::
390 {atom(), [{atom(), Value}]}
391 record_access::
393 {atom(), atom()}
394 record_index_expr::
396 {atom(), atom()}
397 For a record_expr node, Info represents the record name and the
399 list of descriptors for the involved fields, listed in the order
400 they appear. A field descriptor is a pair {Label, Value}, if
401 Node represents "Label = <em>Value</em>". For a record_access
402 node, Info represents the record name and the field name. For a
403 record_index_expr node, Info represents the record name and the
404 name field name.
405 The evaluation throws syntax_error if Node represents a record
407 expression that is not well-formed.
408 See also: analyze_record_attribute/1, analyze_record_field/1.
410 analyze_record_field(Node::erl_syntax:syntaxTree()) -> field()
412 Returns the label, value-expression, and type of a record field
414 specifier. The result is a pair {Label, {Default, Type}}, if
415 Node represents "Label", "Label = <em>Default</em>", "Label ::
416 <em>Type</em>", or "Label = <em>Default</em> :: <em>Type</em>".
417 If the field has no value-expression, the value for Default will
418 be the atom none. If the field has no type, the value for Type
419 will be the atom none.
420 The evaluation throws syntax_error if Node does not represent a
422 well-formed record field specifier.
423 See also: analyze_record_attribute/1, analyze_record_expr/1.
425 analyze_type_application(Node::erl_syntax:syntaxTree()) -> typeName()
427 Returns the name of a used type. The result is a representation
429 of the name of the used pre-defined or local type N/A, if Node
430 represents a local (user) type application
431 "<em>N</em>(<em>T_1</em>, ..., <em>T_A</em>)", or a representa‐
432 tion of the name of the used remote type M:N/A if Node repre‐
433 sents a remote user type application
434 "<em>M</em>:<em>N</em>(<em>T_1</em>, ..., <em>T_A</em>)".
435 The evaluation throws syntax_error if Node does not represent a
437 well-formed (user) type application expression.
438 See also: analyze_type_name/1.
440 analyze_type_name(Node::erl_syntax:syntaxTree()) -> typeName()
442 Returns the type name represented by a syntax tree. If Node rep‐
444 resents a type name, such as "foo/1" or "bloggs:fred/2", a uni‐
445 form representation of that name is returned.
446 The evaluation throws syntax_error if Node does not represent a
448 well-formed type name.
449 analyze_wild_attribute(Node::erl_syntax:syntaxTree()) -> {atom(),
451 term()}
452 Returns the name and value of a "wild" attribute. The result is
454 the pair {Name, Value}, if Node represents "-Name(Value)".
455 Note that no checking is done whether Name is a reserved attri‐
457 bute name such as module or export: it is assumed that the at‐
458 tribute is "wild".
459 The evaluation throws syntax_error if Node does not represent a
461 well-formed wild attribute.
462 See also: analyze_attribute/1.
464 annotate_bindings(Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntax‐
466 Tree()
467 Adds or updates annotations on nodes in a syntax tree. Equiva‐
469 lent to annotate_bindings(Tree, Bindings) where the top-level
470 environment Bindings is taken from the annotation {env, Bind‐
471 ings} on the root node of Tree. An exception is thrown if no
472 such annotation should exist.
473 See also: annotate_bindings/2.
475 annotate_bindings(Tree::erl_syntax:syntaxTree(), Env::ordsets:ord‐
477 set(atom())) -> erl_syntax:syntaxTree()
478 Adds or updates annotations on nodes in a syntax tree. Bindings
480 specifies the set of bound variables in the environment of the
481 top level node. The following annotations are affected:
482 * {env, Vars}, representing the input environment of the sub‐
484 tree.
485 * {bound, Vars}, representing the variables that are bound in
487 the subtree.
488 * {free, Vars}, representing the free variables in the sub‐
490 tree.
491 Bindings and Vars are ordered-set lists (cf. module ordsets) of
493 atoms representing variable names.
494 See also: ordsets(3), annotate_bindings/1.
496 fold(F::(erl_syntax:syntaxTree(), term()) -> term(), S::term(),
498 Tree::erl_syntax:syntaxTree()) -> term()
499 Folds a function over all nodes of a syntax tree. The result is
501 the value of Function(X1, Function(X2, ... Function(Xn, Start)
502 ... )), where [X1, X2, ..., Xn] are the nodes of Tree in a post-
503 order traversal.
504 See also: fold_subtrees/3, foldl_listlist/3.
506 fold_subtrees(F::(erl_syntax:syntaxTree(), term()) -> term(),
508 S::term(), Tree::erl_syntax:syntaxTree()) -> term()
509 Folds a function over the immediate subtrees of a syntax tree.
511 This is similar to fold/3, but only on the immediate subtrees of
512 Tree, in left-to-right order; it does not include the root node
513 of Tree.
514 See also: fold/3.
516 foldl_listlist(F::(term(), term()) -> term(), S::term(),
518 Ls::[[term()]]) -> term()
519 Like lists:foldl/3, but over a list of lists.
521 See also: lists:foldl/3, fold/3.
523 function_name_expansions(Fs::[name()]) -> [{shortname(), name()}]
525 Creates a mapping from corresponding short names to full func‐
527 tion names. Names are represented by nested tuples of atoms and
528 integers (cf. analyze_function_name/1). The result is a list
529 containing a pair {ShortName, Name} for each element Name in the
530 given list, where the corresponding ShortName is the rightmost-
531 innermost part of Name. The list thus represents a finite map‐
532 ping from unqualified names to the corresponding qualified
533 names.
534 Note: the resulting list can contain more than one tuple {Short‐
536 Name, Name} for the same ShortName, possibly with different val‐
537 ues for Name, depending on the given list.
538 See also: analyze_function_name/1.
540 is_fail_expr(E::erl_syntax:syntaxTree()) -> boolean()
542 Returns true if Tree represents an expression which never termi‐
544 nates normally. Note that the reverse does not apply. Currently,
545 the detected cases are calls to exit/1, throw/1, erlang:error/1
546 and erlang:error/2.
547 See also: erlang:error/1, erlang:error/2, erlang:exit/1, er‐
549 lang:throw/1.
550 limit(Tree::erl_syntax:syntaxTree(), Depth::integer()) -> erl_syn‐
552 tax:syntaxTree()
553 Equivalent to limit(Tree, Depth, Text) using the text "..." as
555 default replacement.
556 See also: limit/3, erl_syntax:text/1.
558 limit(Tree::erl_syntax:syntaxTree(), Depth::integer(), Node::erl_syn‐
560 tax:syntaxTree()) -> erl_syntax:syntaxTree()
561 Limits a syntax tree to a specified depth. Replaces all non-leaf
563 subtrees in Tree at the given Depth by Node. If Depth is nega‐
564 tive, the result is always Node, even if Tree has no subtrees.
565 When a group of subtrees (as e.g., the argument list of an ap‐
567 plication node) is at the specified depth, and there are two or
568 more subtrees in the group, these will be collectively replaced
569 by Node even if they are leaf nodes. Groups of subtrees that are
570 above the specified depth will be limited in size, as if each
571 subsequent tree in the group were one level deeper than the pre‐
572 vious. E.g., if Tree represents a list of integers "[1, 2, 3, 4,
573 5, 6, 7, 8, 9, 10]", the result of limit(Tree, 5) will represent
574 [1, 2, 3, 4, ...].
575 The resulting syntax tree is typically only useful for pretty-
577 printing or similar visual formatting.
578 See also: limit/2.
580 map(F::(erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree(),
582 Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
583 Applies a function to each node of a syntax tree. The result of
585 each application replaces the corresponding original node. The
586 order of traversal is bottom-up.
587 See also: map_subtrees/2.
589 map_subtrees(F::(erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree(),
591 Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
592 Applies a function to each immediate subtree of a syntax tree.
594 The result of each application replaces the corresponding origi‐
595 nal node.
596 See also: map/2.
598 mapfold(F::(erl_syntax:syntaxTree(), term()) -> {erl_syntax:syntax‐
600 Tree(), term()}, S::term(), Tree::erl_syntax:syntaxTree()) -> {erl_syn‐
601 tax:syntaxTree(), term()}
602 Combines map and fold in a single operation. This is similar to
604 map/2, but also propagates an extra value from each application
605 of the Function to the next, while doing a post-order traversal
606 of the tree like fold/3. The value Start is passed to the first
607 function application, and the final result is the result of the
608 last application.
609 See also: fold/3, map/2.
611 mapfold_subtrees(F::(erl_syntax:syntaxTree(), term()) -> {erl_syn‐
613 tax:syntaxTree(), term()}, S::term(), Tree::erl_syntax:syntaxTree()) ->
614 {erl_syntax:syntaxTree(), term()}
615 Does a mapfold operation over the immediate subtrees of a syntax
617 tree. This is similar to mapfold/3, but only on the immediate
618 subtrees of Tree, in left-to-right order; it does not include
619 the root node of Tree.
620 See also: mapfold/3.
622 mapfoldl_listlist(F::(term(), term()) -> {term(), term()}, S::term(),
624 Ls::[[term()]]) -> {[[term()]], term()}
625 Like lists:mapfoldl/3, but over a list of lists. The list of
627 lists in the result has the same structure as the given list of
628 lists.
629 new_variable_name(S::sets:set(atom())) -> atom()
631 Returns an atom which is not already in the set Used. This is
633 equivalent to new_variable_name(Function, Used), where Function
634 maps a given integer N to the atom whose name consists of "V"
635 followed by the numeral for N.
636 See also: new_variable_name/2.
638 new_variable_name(F::(integer()) -> atom(), S::sets:set(atom())) ->
640 atom()
641 Returns a user-named atom which is not already in the set Used.
643 The atom is generated by applying the given Function to a gener‐
644 ated integer. Integers are generated using an algorithm which
645 tries to keep the names randomly distributed within a reasonably
646 small range relative to the number of elements in the set.
647 This function uses the module rand to generate new keys. The
649 seed it uses may be initialized by calling rand:seed/1 or
650 rand:seed/2 before this function is first called.
651 See also: random(3), sets(3), new_variable_name/1.
653 new_variable_names(N::integer(), S::sets:set(atom())) -> [atom()]
655 Like new_variable_name/1, but generates a list of N new names.
657 See also: new_variable_name/1.
659 new_variable_names(N::integer(), F::(integer()) -> atom(),
661 S::sets:set(atom())) -> [atom()]
662 Like new_variable_name/2, but generates a list of N new names.
664 See also: new_variable_name/2.
666 strip_comments(Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntax‐
668 Tree()
669 Removes all comments from all nodes of a syntax tree. All other
671 attributes (such as position information) remain unchanged.
672 Standalone comments in form lists are removed; any other stand‐
673 alone comments are changed into null-comments (no text, no in‐
674 dentation).
675 to_comment(Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
677 Equivalent to to_comment(Tree, "% ").
679 to_comment(Tree::erl_syntax:syntaxTree(), Prefix::string()) -> erl_syn‐
681 tax:syntaxTree()
682 Equivalent to to_comment(Tree, Prefix, F) for a default format‐
684 ting function F. The default F simply calls erl_prettypr:for‐
685 mat/1.
686 See also: to_comment/3, erl_prettypr:format/1.
688 to_comment(Tree::erl_syntax:syntaxTree(), Prefix::string(),
690 F::(erl_syntax:syntaxTree()) -> string()) -> erl_syntax:syntaxTree()
691 Transforms a syntax tree into an abstract comment. The lines of
693 the comment contain the text for Node, as produced by the given
694 Printer function. Each line of the comment is prefixed by the
695 string Prefix (this does not include the initial "%" character
696 of the comment line).
697 For example, the result of to_comment(erl_syntax:ab‐
699 stract([a,b,c])) represents
700 %% [a,b,c]
702 (cf. to_comment/1).
704 Note: the text returned by the formatting function will be split
706 automatically into separate comment lines at each line break. No
707 extra work is needed.
708 See also: to_comment/1, to_comment/2.
710 variables(Tree::erl_syntax:syntaxTree()) -> sets:set(atom())
712 Returns the names of variables occurring in a syntax tree, The
714 result is a set of variable names represented by atoms. Macro
715 names are not included.
716 See also: sets(3).
718
720 Richard Carlsson <carlsson.richard@gmail.com>
721 syntax_tools 2.6 erl_syntax_lib(3)