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 info_pair() = {key(), term()}:
16 key() = attributes | errors | exports | functions | imports | module
19 | records | warnings:
20 ordset(T) = ordsets:ordset(T):
23 set(T) = sets:set(T):
26 syntaxTree() = erl_syntax:syntaxTree():
29 An abstract syntax tree. See the erl_syntax module for details.
32
34 analyze_application(Node::syntaxTree()) -> FunctionName | Arity
35 Types:
37 FunctionName = {atom(), Arity} | {ModuleName, FunctionName}
39 Arity = integer()
40 ModuleName = atom()
41 Returns the name of a called function. The result is a represen‐
43 tation of the name of the applied function F/A, if Node repre‐
44 sents a function application "<em>F</em>(<em>X_1</em>, ...,
45 <em>X_A</em>)". If the function is not explicitly named (i.e., F
46 is given by some expression), only the arity A is returned.
47 The evaluation throws syntax_error if Node does not represent a
49 well-formed application expression.
50 See also: analyze_function_name/1.
52 analyze_attribute(Node::syntaxTree()) -> preprocessor | {atom(),
54 atom()}
55 Analyzes an attribute node. If Node represents a preprocessor
57 directive, the atom preprocessor is returned. Otherwise, if Node
58 represents a module attribute "-<em>Name</em>...", a tuple
59 {Name, Info} is returned, where Info depends on Name, as fol‐
60 lows:
61 {module, Info}:
63 where Info = analyze_module_attribute(Node).
64 {export, Info}:
66 where Info = analyze_export_attribute(Node).
67 {import, Info}:
69 where Info = analyze_import_attribute(Node).
70 {file, Info}:
72 where Info = analyze_file_attribute(Node).
73 {record, Info}:
75 where Info = analyze_record_attribute(Node).
76 {Name, Info}:
78 where {Name, Info} = analyze_wild_attribute(Node).
79 The evaluation throws syntax_error if Node does not represent a
81 well-formed module attribute.
82 See also: analyze_export_attribute/1, analyze_file_attribute/1,
84 analyze_import_attribute/1, analyze_module_attribute/1, ana‐
85 lyze_record_attribute/1, analyze_wild_attribute/1.
86 analyze_export_attribute(Node::syntaxTree()) -> [FunctionName]
88 Types:
90 FunctionName = atom() | {atom(), integer()} | {ModuleName,
92 FunctionName}
93 ModuleName = atom()
94 Returns the list of function names declared by an export
96 attribute. We do not guarantee that each name occurs at most
97 once in the list. The order of listing is not defined.
98 The evaluation throws syntax_error if Node does not represent a
100 well-formed export attribute.
101 See also: analyze_attribute/1.
103 analyze_file_attribute(Node::syntaxTree()) -> {string(), integer()}
105 Returns the file name and line number of a file attribute. The
107 result is the pair {File, Line} if Node represents "-file(File,
108 Line).".
109 The evaluation throws syntax_error if Node does not represent a
111 well-formed file attribute.
112 See also: analyze_attribute/1.
114 analyze_form(Node::syntaxTree()) -> {atom(), term()} | atom()
116 Analyzes a "source code form" node. If Node is a "form" type
118 (cf. erl_syntax:is_form/1), the returned value is a tuple {Type,
119 Info} where Type is the node type and Info depends on Type, as
120 follows:
121 {attribute, Info}:
123 where Info = analyze_attribute(Node).
124 {error_marker, Info}:
126 where Info = erl_syntax:error_marker_info(Node).
127 {function, Info}:
129 where Info = analyze_function(Node).
130 {warning_marker, Info}:
132 where Info = erl_syntax:warning_marker_info(Node).
133 For other types of forms, only the node type is returned.
135 The evaluation throws syntax_error if Node is not well-formed.
137 See also: analyze_attribute/1, analyze_function/1, erl_syn‐
139 tax:error_marker_info/1, erl_syntax:is_form/1, erl_syntax:warn‐
140 ing_marker_info/1.
141 analyze_forms(Forms) -> [{Key, term()}]
143 Types:
145 Forms = syntaxTree() | [syntaxTree()]
147 Key = attributes | errors | exports | functions | imports |
148 module | records | warnings
149 Analyzes a sequence of "program forms". The given Forms may be a
151 single syntax tree of type form_list, or a list of "program
152 form" syntax trees. The returned value is a list of pairs {Key,
153 Info}, where each value of Key occurs at most once in the list;
154 the absence of a particular key indicates that there is no well-
155 defined value for that key.
156 Each entry in the resulting list contains the following corre‐
158 sponding information about the program forms:
159 {attributes, Attributes}:
161 * Attributes = [{atom(), term()}]
164 Attributes is a list of pairs representing the names and
166 corresponding values of all so-called "wild" attributes (as
167 e.g. "-compile(...)") occurring in Forms (cf. ana‐
168 lyze_wild_attribute/1). We do not guarantee that each name
169 occurs at most once in the list. The order of listing is not
170 defined.
171 {errors, Errors}:
173 * Errors = [term()]
176 Errors is the list of error descriptors of all error_marker
178 nodes that occur in Forms. The order of listing is not
179 defined.
180 {exports, Exports}:
182 * Exports = [FunctionName]
185 * FunctionName = atom() | {atom(), integer()} | {ModuleName,
187 FunctionName}
188 * ModuleName = atom()
190 Exports is a list of representations of those function names
192 that are listed by export declaration attributes in Forms
193 (cf. analyze_export_attribute/1). We do not guarantee that
194 each name occurs at most once in the list. The order of
195 listing is not defined.
196 {functions, Functions}:
198 * Functions = [{atom(), integer()}]
201 Functions is a list of the names of the functions that are
203 defined in Forms (cf. analyze_function/1). We do not guaran‐
204 tee that each name occurs at most once in the list. The
205 order of listing is not defined.
206 {imports, Imports}:
208 * Imports = [{Module, Names}]
211 * Module = atom()
213 * Names = [FunctionName]
215 * FunctionName = atom() | {atom(), integer()} | {ModuleName,
217 FunctionName}
218 * ModuleName = atom()
220 Imports is a list of pairs representing those module names
222 and corresponding function names that are listed by import
223 declaration attributes in Forms (cf. ana‐
224 lyze_import_attribute/1), where each Module occurs at most
225 once in Imports. We do not guarantee that each name occurs
226 at most once in the lists of function names. The order of
227 listing is not defined.
228 {module, ModuleName}:
230 * ModuleName = atom()
233 ModuleName is the name declared by a module attribute in
235 Forms. If no module name is defined in Forms, the result
236 will contain no entry for the module key. If multiple module
237 name declarations should occur, all but the first will be
238 ignored.
239 {records, Records}:
241 * Records = [{atom(), Fields}]
244 * Fields = [{atom(), {Default, Type}}]
246 * Default = none | syntaxTree()
248 * Type = none | syntaxTree()
250 Records is a list of pairs representing the names and corre‐
252 sponding field declarations of all record declaration
253 attributes occurring in Forms. For fields declared without a
254 default value, the corresponding value for Default is the
255 atom none. Similarly, for fields declared without a type,
256 the corresponding value for Type is the atom none (cf. ana‐
257 lyze_record_attribute/1). We do not guarantee that each
258 record name occurs at most once in the list. The order of
259 listing is not defined.
260 {warnings, Warnings}:
262 * Warnings = [term()]
265 Warnings is the list of error descriptors of all warn‐
267 ing_marker nodes that occur in Forms. The order of listing
268 is not defined.
269 The evaluation throws syntax_error if an ill-formed Erlang con‐
271 struct is encountered.
272 See also: analyze_export_attribute/1, analyze_function/1, ana‐
274 lyze_import_attribute/1, analyze_record_attribute/1, ana‐
275 lyze_wild_attribute/1, erl_syntax:error_marker_info/1, erl_syn‐
276 tax:warning_marker_info/1.
277 analyze_function(Node::syntaxTree()) -> {atom(), integer()}
279 Returns the name and arity of a function definition. The result
281 is a pair {Name, A} if Node represents a function definition
282 "Name(<em>P_1</em>, ..., <em>P_A</em>) -> ...".
283 The evaluation throws syntax_error if Node does not represent a
285 well-formed function definition.
286 analyze_function_name(Node::syntaxTree()) -> FunctionName
288 Types:
290 FunctionName = atom() | {atom(), integer()} | {ModuleName,
292 FunctionName}
293 ModuleName = atom()
294 Returns the function name represented by a syntax tree. If Node
296 represents a function name, such as "foo/1" or "bloggs:fred/2",
297 a uniform representation of that name is returned. Different
298 nestings of arity and module name qualifiers in the syntax tree
299 does not affect the result.
300 The evaluation throws syntax_error if Node does not represent a
302 well-formed function name.
303 analyze_implicit_fun(Node::syntaxTree()) -> FunctionName
305 Types:
307 FunctionName = atom() | {atom(), integer()} | {ModuleName,
309 FunctionName}
310 ModuleName = atom()
311 Returns the name of an implicit fun expression "fun <em>F</em>".
313 The result is a representation of the function name F. (Cf. ana‐
314 lyze_function_name/1.)
315 The evaluation throws syntax_error if Node does not represent a
317 well-formed implicit fun.
318 See also: analyze_function_name/1.
320 analyze_import_attribute(Node::syntaxTree()) -> {atom(), [Function‐
322 Name]} | atom()
323 Types:
325 FunctionName = atom() | {atom(), integer()} | {ModuleName,
327 FunctionName}
328 ModuleName = atom()
329 Returns the module name and (if present) list of function names
331 declared by an import attribute. The returned value is an atom
332 Module or a pair {Module, Names}, where Names is a list of func‐
333 tion names declared as imported from the module named by Module.
334 We do not guarantee that each name occurs at most once in Names.
335 The order of listing is not defined.
336 The evaluation throws syntax_error if Node does not represent a
338 well-formed import attribute.
339 See also: analyze_attribute/1.
341 analyze_module_attribute(Node::syntaxTree()) -> Name::atom() |
343 {Name::atom(), Variables::[atom()]}
344 Returns the module name and possible parameters declared by a
346 module attribute. If the attribute is a plain module declaration
347 such as -module(name), the result is the module name. If the
348 attribute is a parameterized module declaration, the result is a
349 tuple containing the module name and a list of the parameter
350 variable names.
351 The evaluation throws syntax_error if Node does not represent a
353 well-formed module attribute.
354 See also: analyze_attribute/1.
356 analyze_record_attribute(Node::syntaxTree()) -> {atom(), Fields}
358 Types:
360 Fields = [{atom(), {Default, Type}}]
362 Default = none | syntaxTree()
363 Type = none | syntaxTree()
364 Returns the name and the list of fields of a record declaration
366 attribute. The result is a pair {Name, Fields}, if Node repre‐
367 sents "-record(Name, {...}).", where Fields is a list of pairs
368 {Label, {Default, Type}} for each field "Label", "Label =
369 <em>Default</em>", "Label :: <em>Type</em>", or "Label =
370 <em>Default</em> :: <em>Type</em>" in the declaration, listed in
371 left-to-right order. If the field has no default-value declara‐
372 tion, the value for Default will be the atom none. If the field
373 has no type declaration, the value for Type will be the atom
374 none. We do not guarantee that each label occurs at most once in
375 the list.
376 The evaluation throws syntax_error if Node does not represent a
378 well-formed record declaration attribute.
379 See also: analyze_attribute/1, analyze_record_field/1.
381 analyze_record_expr(Node::syntaxTree()) -> {atom(), Info} | atom()
383 Types:
385 Info = {atom(), [{atom(), Value}]} | {atom(), atom()} |
387 atom()
388 Value = syntaxTree()
389 Returns the record name and field name/names of a record expres‐
391 sion. If Node has type record_expr, record_index_expr or
392 record_access, a pair {Type, Info} is returned, otherwise an
393 atom Type is returned. Type is the node type of Node, and Info
394 depends on Type, as follows:
395 record_expr::
397 {atom(), [{atom(), Value}]}
398 record_access::
400 {atom(), atom()}
401 record_index_expr::
403 {atom(), atom()}
404 For a record_expr node, Info represents the record name and the
406 list of descriptors for the involved fields, listed in the order
407 they appear. A field descriptor is a pair {Label, Value}, if
408 Node represents "Label = <em>Value</em>". For a record_access
409 node, Info represents the record name and the field name. For a
410 record_index_expr node, Info represents the record name and the
411 name field name.
412 The evaluation throws syntax_error if Node represents a record
414 expression that is not well-formed.
415 See also: analyze_record_attribute/1, analyze_record_field/1.
417 analyze_record_field(Node::syntaxTree()) -> {atom(), {Default, Type}}
419 Types:
421 Default = none | syntaxTree()
423 Type = none | syntaxTree()
424 Returns the label, value-expression, and type of a record field
426 specifier. The result is a pair {Label, {Default, Type}}, if
427 Node represents "Label", "Label = <em>Default</em>", "Label ::
428 <em>Type</em>", or "Label = <em>Default</em> :: <em>Type</em>".
429 If the field has no value-expression, the value for Default will
430 be the atom none. If the field has no type, the value for Type
431 will be the atom none.
432 The evaluation throws syntax_error if Node does not represent a
434 well-formed record field specifier.
435 See also: analyze_record_attribute/1, analyze_record_expr/1.
437 analyze_type_application(Node::syntaxTree()) -> TypeName
439 Types:
441 TypeName = {atom(), integer()} | {ModuleName, {atom(), inte‐
443 ger()}}
444 ModuleName = atom()
445 Returns the name of a used type. The result is a representation
447 of the name of the used pre-defined or local type N/A, if Node
448 represents a local (user) type application
449 "<em>N</em>(<em>T_1</em>, ..., <em>T_A</em>)", or a representa‐
450 tion of the name of the used remote type M:N/A if Node repre‐
451 sents a remote user type application
452 "<em>M</em>:<em>N</em>(<em>T_1</em>, ..., <em>T_A</em>)".
453 The evaluation throws syntax_error if Node does not represent a
455 well-formed (user) type application expression.
456 See also: analyze_type_name/1.
458 analyze_type_name(Node::syntaxTree()) -> TypeName
460 Types:
462 TypeName = atom() | {atom(), integer()} | {ModuleName,
464 {atom(), integer()}}
465 ModuleName = atom()
466 Returns the type name represented by a syntax tree. If Node rep‐
468 resents a type name, such as "foo/1" or "bloggs:fred/2", a uni‐
469 form representation of that name is returned.
470 The evaluation throws syntax_error if Node does not represent a
472 well-formed type name.
473 analyze_wild_attribute(Node::syntaxTree()) -> {atom(), term()}
475 Returns the name and value of a "wild" attribute. The result is
477 the pair {Name, Value}, if Node represents "-Name(Value)".
478 Note that no checking is done whether Name is a reserved
480 attribute name such as module or export: it is assumed that the
481 attribute is "wild".
482 The evaluation throws syntax_error if Node does not represent a
484 well-formed wild attribute.
485 See also: analyze_attribute/1.
487 annotate_bindings(Tree::syntaxTree()) -> syntaxTree()
489 Adds or updates annotations on nodes in a syntax tree. Equiva‐
491 lent to annotate_bindings(Tree, Bindings) where the top-level
492 environment Bindings is taken from the annotation {env, Bind‐
493 ings} on the root node of Tree. An exception is thrown if no
494 such annotation should exist.
495 See also: annotate_bindings/2.
497 annotate_bindings(Tree::syntaxTree(), Bindings::ordset(atom())) -> syn‐
499 taxTree()
500 Adds or updates annotations on nodes in a syntax tree. Bindings
502 specifies the set of bound variables in the environment of the
503 top level node. The following annotations are affected:
504 * {env, Vars}, representing the input environment of the sub‐
506 tree.
507 * {bound, Vars}, representing the variables that are bound in
509 the subtree.
510 * {free, Vars}, representing the free variables in the sub‐
512 tree.
513 Bindings and Vars are ordered-set lists (cf. module ordsets) of
515 atoms representing variable names.
516 See also: ordsets(3), annotate_bindings/1.
518 fold(F::Function, Start::term(), Tree::syntaxTree()) -> term()
520 Types:
522 Function = (syntaxTree(), term()) -> term()
524 Folds a function over all nodes of a syntax tree. The result is
526 the value of Function(X1, Function(X2, ... Function(Xn, Start)
527 ... )), where [X1, X2, ..., Xn] are the nodes of Tree in a post-
528 order traversal.
529 See also: fold_subtrees/3, foldl_listlist/3.
531 fold_subtrees(F::Function, Start::term(), Tree::syntaxTree()) -> term()
533 Types:
535 Function = (syntaxTree(), term()) -> term()
537 Folds a function over the immediate subtrees of a syntax tree.
539 This is similar to fold/3, but only on the immediate subtrees of
540 Tree, in left-to-right order; it does not include the root node
541 of Tree.
542 See also: fold/3.
544 foldl_listlist(F::Function, Start::term(), Ls::[[term()]]) -> term()
546 Types:
548 Function = (term(), term()) -> term()
550 Like lists:foldl/3, but over a list of lists.
552 See also: lists:foldl/3, fold/3.
554 function_name_expansions(Names::[Name]) -> [{ShortName, Name}]
556 Types:
558 Name = ShortName | {atom(), Name}
560 ShortName = atom() | {atom(), integer()}
561 Creates a mapping from corresponding short names to full func‐
563 tion names. Names are represented by nested tuples of atoms and
564 integers (cf. analyze_function_name/1). The result is a list
565 containing a pair {ShortName, Name} for each element Name in the
566 given list, where the corresponding ShortName is the rightmost-
567 innermost part of Name. The list thus represents a finite map‐
568 ping from unqualified names to the corresponding qualified
569 names.
570 Note: the resulting list can contain more than one tuple {Short‐
572 Name, Name} for the same ShortName, possibly with different val‐
573 ues for Name, depending on the given list.
574 See also: analyze_function_name/1.
576 is_fail_expr(Tree::syntaxTree()) -> boolean()
578 Returns true if Tree represents an expression which never termi‐
580 nates normally. Note that the reverse does not apply. Currently,
581 the detected cases are calls to exit/1, throw/1, erlang:error/1
582 and erlang:error/2.
583 See also: erlang:error/1, erlang:error/2, erlang:exit/1,
585 erlang:throw/1.
586 limit(Tree, Depth) -> syntaxTree()
588 Equivalent to limit(Tree, Depth, Text) using the text "..." as
590 default replacement.
591 See also: limit/3, erl_syntax:text/1.
593 limit(Tree::syntaxTree(), Depth::integer(), Node::syntaxTree()) -> syn‐
595 taxTree()
596 Limits a syntax tree to a specified depth. Replaces all non-leaf
598 subtrees in Tree at the given Depth by Node. If Depth is nega‐
599 tive, the result is always Node, even if Tree has no subtrees.
600 When a group of subtrees (as e.g., the argument list of an
602 application node) is at the specified depth, and there are two
603 or more subtrees in the group, these will be collectively
604 replaced by Node even if they are leaf nodes. Groups of subtrees
605 that are above the specified depth will be limited in size, as
606 if each subsequent tree in the group were one level deeper than
607 the previous. E.g., if Tree represents a list of integers "[1,
608 2, 3, 4, 5, 6, 7, 8, 9, 10]", the result of limit(Tree, 5) will
609 represent [1, 2, 3, 4, ...].
610 The resulting syntax tree is typically only useful for pretty-
612 printing or similar visual formatting.
613 See also: limit/2.
615 map(F::Function, Tree::syntaxTree()) -> syntaxTree()
617 Types:
619 Function = (syntaxTree()) -> syntaxTree()
621 Applies a function to each node of a syntax tree. The result of
623 each application replaces the corresponding original node. The
624 order of traversal is bottom-up.
625 See also: map_subtrees/2.
627 map_subtrees(F::Function, Tree::syntaxTree()) -> syntaxTree()
629 Types:
631 Function = (Tree) -> Tree1
633 Applies a function to each immediate subtree of a syntax tree.
635 The result of each application replaces the corresponding origi‐
636 nal node.
637 See also: map/2.
639 mapfold(F::Function, Start::term(), Tree::syntaxTree()) -> {syntax‐
641 Tree(), term()}
642 Types:
644 Function = (syntaxTree(), term()) -> {syntaxTree(), term()}
646 Combines map and fold in a single operation. This is similar to
648 map/2, but also propagates an extra value from each application
649 of the Function to the next, while doing a post-order traversal
650 of the tree like fold/3. The value Start is passed to the first
651 function application, and the final result is the result of the
652 last application.
653 See also: fold/3, map/2.
655 mapfold_subtrees(F::Function, Start::term(), Tree::syntaxTree()) ->
657 {syntaxTree(), term()}
658 Types:
660 Function = (syntaxTree(), term()) -> {syntaxTree(), term()}
662 Does a mapfold operation over the immediate subtrees of a syntax
664 tree. This is similar to mapfold/3, but only on the immediate
665 subtrees of Tree, in left-to-right order; it does not include
666 the root node of Tree.
667 See also: mapfold/3.
669 mapfoldl_listlist(F::Function, S::State, Ls::[[term()]]) ->
671 {[[term()]], term()}
672 Types:
674 Function = (term(), term()) -> {term(), term()}
676 Like lists:mapfoldl/3, but over a list of lists. The list of
678 lists in the result has the same structure as the given list of
679 lists.
680 new_variable_name(Used::set(atom())) -> atom()
682 Returns an atom which is not already in the set Used. This is
684 equivalent to new_variable_name(Function, Used), where Function
685 maps a given integer N to the atom whose name consists of "V"
686 followed by the numeral for N.
687 See also: new_variable_name/2.
689 new_variable_name(F::Function, Used::set(atom())) -> atom()
691 Types:
693 Function = (integer()) -> atom()
695 Returns a user-named atom which is not already in the set Used.
697 The atom is generated by applying the given Function to a gener‐
698 ated integer. Integers are generated using an algorithm which
699 tries to keep the names randomly distributed within a reasonably
700 small range relative to the number of elements in the set.
701 This function uses the module rand to generate new keys. The
703 seed it uses may be initialized by calling rand:seed/1 or
704 rand:seed/2 before this function is first called.
705 See also: random(3), sets(3), new_variable_name/1.
707 new_variable_names(N::integer(), Used::set(atom())) -> [atom()]
709 Like new_variable_name/1, but generates a list of N new names.
711 See also: new_variable_name/1.
713 new_variable_names(N::integer(), F::Function, Used::set(atom())) ->
715 [atom()]
716 Types:
718 Function = (integer()) -> atom()
720 Like new_variable_name/2, but generates a list of N new names.
722 See also: new_variable_name/2.
724 strip_comments(Tree::syntaxTree()) -> syntaxTree()
726 Removes all comments from all nodes of a syntax tree. All other
728 attributes (such as position information) remain unchanged.
729 Standalone comments in form lists are removed; any other stand‐
730 alone comments are changed into null-comments (no text, no
731 indentation).
732 to_comment(Tree) -> syntaxTree()
734 Equivalent to to_comment(Tree, "% ").
736 to_comment(Tree::syntaxTree(), Prefix::string()) -> syntaxTree()
738 Equivalent to to_comment(Tree, Prefix, F) for a default format‐
740 ting function F. The default F simply calls erl_prettypr:for‐
741 mat/1.
742 See also: to_comment/3, erl_prettypr:format/1.
744 to_comment(Tree::syntaxTree(), Prefix::string(), F::Printer) -> syntax‐
746 Tree()
747 Types:
749 Printer = (syntaxTree()) -> string()
751 Transforms a syntax tree into an abstract comment. The lines of
753 the comment contain the text for Node, as produced by the given
754 Printer function. Each line of the comment is prefixed by the
755 string Prefix (this does not include the initial "%" character
756 of the comment line).
757 For example, the result of to_comment(erl_syn‐
759 tax:abstract([a,b,c])) represents
760 %% [a,b,c]
762 (cf. to_comment/1).
764 Note: the text returned by the formatting function will be split
766 automatically into separate comment lines at each line break. No
767 extra work is needed.
768 See also: to_comment/1, to_comment/2.
770 variables(Tree::syntaxTree()) -> set(atom())
772 Returns the names of variables occurring in a syntax tree, The
774 result is a set of variable names represented by atoms. Macro
775 names are not included.
776 See also: sets(3).
778
780 Richard Carlsson <carlsson.richard@gmail.com>
781 syntax_tools 2.2.1 erl_syntax_lib(3)