1erl_syntax(3) Erlang Module Definition erl_syntax(3)
2
6 erl_syntax - Abstract Erlang syntax trees.
7
9 Abstract Erlang syntax trees.
10 This module defines an abstract data type for representing Erlang
12 source code as syntax trees, in a way that is backwards compatible with
13 the data structures created by the Erlang standard library parser mod‐
14 ule erl_parse (often referred to as "parse trees", which is a bit of a
15 misnomer). This means that all erl_parse trees are valid abstract syn‐
16 tax trees, but the reverse is not true: abstract syntax trees can in
17 general not be used as input to functions expecting an erl_parse tree.
18 However, as long as an abstract syntax tree represents a correct Erlang
19 program, the function revert/1 should be able to transform it to the
20 corresponding erl_parse representation.
21 A recommended starting point for the first-time user is the documenta‐
23 tion of the syntaxTree() data type, and the function type/1.
24 NOTES:
26 This module deals with the composition and decomposition of syntactic
28 entities (as opposed to semantic ones); its purpose is to hide all
29 direct references to the data structures used to represent these enti‐
30 ties. With few exceptions, the functions in this module perform no
31 semantic interpretation of their inputs, and in general, the user is
32 assumed to pass type-correct arguments - if this is not done, the
33 effects are not defined.
34 With the exception of the erl_parse() data structures, the internal
36 representations of abstract syntax trees are subject to change without
37 notice, and should not be documented outside this module. Furthermore,
38 we do not give any guarantees on how an abstract syntax tree may or may
39 not be represented, with the following exceptions: no syntax tree is
40 represented by a single atom, such as none, by a list constructor [X |
41 Y], or by the empty list []. This can be relied on when writing func‐
42 tions that operate on syntax trees.
43
45 encoding() = utf8 | unicode | latin1:
46 erl_parse() = erl_parse:abstract_clause() | erl_parse:abstract_expr()
49 | erl_parse:abstract_form() | erl_parse:abstract_type() |
50 erl_parse:form_info() | erl_parse:af_binelement(term()) |
51 erl_parse:af_generator() | erl_parse:af_remote_function():
52 forms() = syntaxTree() | [syntaxTree()]:
55 guard() = none | syntaxTree() | [syntaxTree()] | [[syntaxTree()]]:
58 padding() = none | integer():
61 syntaxTree():
64 An abstract syntax tree. The erl_parse() "parse tree" representa‐
67 tion is a proper subset of the syntaxTree() representation.
68 Every abstract syntax tree node has a type, given by the function
70 type/1. Each node also has associated attributes; see get_attrs/1
71 for details. The functions make_tree/2 and subtrees/1 are generic
72 constructor/decomposition functions for abstract syntax trees. The
73 functions abstract/1 and concrete/1 convert between constant Erlang
74 terms and their syntactic representations. The set of syntax tree
75 nodes is extensible through the tree/2 function.
76 A syntax tree can be transformed to the erl_parse() representation
78 with the revert/1 function.
79 syntaxTreeAttributes():
81 This is an abstract representation of syntax tree node attributes;
84 see the function get_attrs/1.
85 tree() = #tree{type=atom(), attr=#attr{pos=term(), ann=[term()],
87 com=none | #com{pre=[syntaxTree()], post=[syntaxTree()]}},
88 data=term()}:
89
92 abstract(T::term()) -> syntaxTree()
93 Returns the syntax tree corresponding to an Erlang term. Term
95 must be a literal term, i.e., one that can be represented as a
96 source code literal. Thus, it may not contain a process identi‐
97 fier, port, reference or function value as a subterm. The func‐
98 tion recognises printable strings, in order to get a compact and
99 readable representation. Evaluation fails with reason badarg if
100 Term is not a literal term.
101 See also: concrete/1, is_literal/1.
103 add_ann(A::term(), Node::syntaxTree()) -> syntaxTree()
105 Appends the term Annotation to the list of user annotations of
107 Node.
108 Note: this is equivalent to set_ann(Node, [Annotation |
110 get_ann(Node)]), but potentially more efficient.
111 See also: get_ann/1, set_ann/2.
113 add_postcomments(Cs::[syntaxTree()], Node::syntaxTree()) -> syntax‐
115 Tree()
116 Appends Comments to the post-comments of Node.
118 Note: This is equivalent to set_postcomments(Node, get_postcom‐
120 ments(Node) ++ Comments), but potentially more efficient.
121 See also: add_precomments/2, comment/2, get_postcomments/1,
123 join_comments/2, set_postcomments/2.
124 add_precomments(Cs::[syntaxTree()], Node::syntaxTree()) -> syntaxTree()
126 Appends Comments to the pre-comments of Node.
128 Note: This is equivalent to set_precomments(Node, get_precom‐
130 ments(Node) ++ Comments), but potentially more efficient.
131 See also: add_postcomments/2, comment/2, get_precomments/1,
133 join_comments/2, set_precomments/2.
134 annotated_type(Name::syntaxTree(), Type::syntaxTree()) -> syntaxTree()
136 Creates an abstract annotated type expression. The result repre‐
138 sents "Name :: Type".
139 See also: annotated_type_body/1, annotated_type_name/1.
141 annotated_type_body(Node::syntaxTree()) -> syntaxTree()
143 Returns the type subtrees of an annotated_type node.
145 See also: annotated_type/2.
147 annotated_type_name(Node::syntaxTree()) -> syntaxTree()
149 Returns the name subtree of an annotated_type node.
151 See also: annotated_type/2.
153 application(Operator::syntaxTree(), Arguments::[syntaxTree()]) -> syn‐
155 taxTree()
156 Creates an abstract function application expression. If Argu‐
158 ments is [A1, ..., An], the result represents "Operator(A1, ...,
159 An)".
160 See also: application/3, application_arguments/1, applica‐
162 tion_operator/1.
163 application(Module::none | syntaxTree(), Name::syntaxTree(), Argu‐
165 ments::[syntaxTree()]) -> syntaxTree()
166 Creates an abstract function application expression. If Module
168 is none, this is call is equivalent to application(Function,
169 Arguments), otherwise it is equivalent to application(mod‐
170 ule_qualifier(Module, Function), Arguments).
171 (This is a utility function.)
173 See also: application/2, module_qualifier/2.
175 application_arguments(Node::syntaxTree()) -> [syntaxTree()]
177 Returns the list of argument subtrees of an application node.
179 See also: application/2.
181 application_operator(Node::syntaxTree()) -> syntaxTree()
183 Returns the operator subtree of an application node.
185 Note: if Node represents "M:F(...)", then the result is the sub‐
187 tree representing "M:F".
188 See also: application/2, module_qualifier/2.
190 arity_qualifier(Body::syntaxTree(), Arity::syntaxTree()) -> syntax‐
192 Tree()
193 Creates an abstract arity qualifier. The result represents
195 "Body/Arity".
196 See also: arity_qualifier_argument/1, arity_qualifier_body/1.
198 arity_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
200 Returns the argument (the arity) subtree of an arity_qualifier
202 node.
203 See also: arity_qualifier/2.
205 arity_qualifier_body(Node::syntaxTree()) -> syntaxTree()
207 Returns the body subtree of an arity_qualifier node.
209 See also: arity_qualifier/2.
211 atom(Name::atom() | string()) -> syntaxTree()
213 Creates an abstract atom literal. The print name of the atom is
215 the character sequence represented by Name.
216 See also: atom_literal/1, atom_literal/2, atom_name/1,
218 atom_value/1, is_atom/2.
219 atom_literal(Node::syntaxTree()) -> string()
221 Returns the literal string represented by an atom node. This
223 includes surrounding single-quote characters if necessary. Char‐
224 acters beyond 255 will be escaped.
225 Note that e.g. the result of atom("x\ny") represents any and all
227 of `x\ny'', `x\12y'', `x\012y'' and `x\^Jy\''; see string/1.
228 See also: atom/1, string/1.
230 atom_literal(Node, X2) -> term()
232 Returns the literal string represented by an atom node. This
234 includes surrounding single-quote characters if necessary.
235 Depending on the encoding a character beyond 255 will be escaped
236 (latin1) or copied as is (utf8).
237 See also: atom/1, atom_literal/1, string/1.
239 atom_name(Node::syntaxTree()) -> string()
241 Returns the printname of an atom node.
243 See also: atom/1.
245 atom_value(Node::syntaxTree()) -> atom()
247 Returns the value represented by an atom node.
249 See also: atom/1.
251 attribute(Name::syntaxTree()) -> syntaxTree()
253 Equivalent to attribute(Name, none).
255 attribute(Name::syntaxTree(), Args::none | [syntaxTree()]) -> syntax‐
257 Tree()
258 Creates an abstract program attribute. If Arguments is [A1, ...,
260 An], the result represents "-Name(A1, ..., An).". Otherwise, if
261 Arguments is none, the result represents "-Name.". The latter
262 form makes it possible to represent preprocessor directives such
263 as "-endif.". Attributes are source code forms.
264 Note: The preprocessor macro definition directive "-define(Name,
266 Body)." has relatively few requirements on the syntactical form
267 of Body (viewed as a sequence of tokens). The text node type can
268 be used for a Body that is not a normal Erlang construct.
269 See also: attribute/1, attribute_arguments/1, attribute_name/1,
271 is_form/1, text/1.
272 attribute_arguments(Node::syntaxTree()) -> none | [syntaxTree()]
274 Returns the list of argument subtrees of an attribute node, if
276 any. If Node represents "-Name.", the result is none. Otherwise,
277 if Node represents "-Name(E1, ..., En).", [E1, ..., E1] is
278 returned.
279 See also: attribute/1.
281 attribute_name(Node::syntaxTree()) -> syntaxTree()
283 Returns the name subtree of an attribute node.
285 See also: attribute/1.
287 binary(List::[syntaxTree()]) -> syntaxTree()
289 Creates an abstract binary-object template. If Fields is [F1,
291 ..., Fn], the result represents "<<F1, ..., Fn>>".
292 See also: binary_field/2, binary_fields/1.
294 binary_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntax‐
296 Tree()
297 Creates an abstract binary comprehension. If Body is [E1, ...,
299 En], the result represents "<<Template || E1, ..., En>>".
300 See also: binary_comp_body/1, binary_comp_template/1, genera‐
302 tor/2.
303 binary_comp_body(Node::syntaxTree()) -> [syntaxTree()]
305 Returns the list of body subtrees of a binary_comp node.
307 See also: binary_comp/2.
309 binary_comp_template(Node::syntaxTree()) -> syntaxTree()
311 Returns the template subtree of a binary_comp node.
313 See also: binary_comp/2.
315 binary_field(Body::syntaxTree()) -> syntaxTree()
317 Equivalent to binary_field(Body, []).
319 binary_field(Body::syntaxTree(), Types::[syntaxTree()]) -> syntaxTree()
321 Creates an abstract binary template field. If Types is the empty
323 list, the result simply represents "Body", otherwise, if Types
324 is [T1, ..., Tn], the result represents "Body/T1-...-Tn".
325 See also: binary/1, binary_field/1, binary_field/3,
327 binary_field_body/1, binary_field_size/1, binary_field_types/1.
328 binary_field(Body::syntaxTree(), Size::none | syntaxTree(),
330 Types::[syntaxTree()]) -> syntaxTree()
331 Creates an abstract binary template field. If Size is none, this
333 is equivalent to "binary_field(Body, Types)", otherwise it is
334 equivalent to "binary_field(size_qualifier(Body, Size), Types)".
335 (This is a utility function.)
337 See also: binary/1, binary_field/2, size_qualifier/2.
339 binary_field_body(Node::syntaxTree()) -> syntaxTree()
341 Returns the body subtree of a binary_field.
343 See also: binary_field/2.
345 binary_field_size(Node::syntaxTree()) -> none | syntaxTree()
347 Returns the size specifier subtree of a binary_field node, if
349 any. If Node represents "Body:Size" or "Body:Size/T1, ..., Tn",
350 the result is Size, otherwise none is returned.
351 (This is a utility function.)
353 See also: binary_field/2, binary_field/3.
355 binary_field_types(Node::syntaxTree()) -> [syntaxTree()]
357 Returns the list of type-specifier subtrees of a binary_field
359 node. If Node represents ".../T1, ..., Tn", the result is [T1,
360 ..., Tn], otherwise the result is the empty list.
361 See also: binary_field/2.
363 binary_fields(Node::syntaxTree()) -> [syntaxTree()]
365 Returns the list of field subtrees of a binary node.
367 See also: binary/1, binary_field/2.
369 binary_generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntax‐
371 Tree()
372 Creates an abstract binary_generator. The result represents
374 "Pattern <- Body".
375 See also: binary_comp/2, binary_generator_body/1, binary_genera‐
377 tor_pattern/1, list_comp/2.
378 binary_generator_body(Node::syntaxTree()) -> syntaxTree()
380 Returns the body subtree of a generator node.
382 See also: binary_generator/2.
384 binary_generator_pattern(Node::syntaxTree()) -> syntaxTree()
386 Returns the pattern subtree of a generator node.
388 See also: binary_generator/2.
390 bitstring_type(M::syntaxTree(), N::syntaxTree()) -> syntaxTree()
392 Creates an abstract bitstring type. The result represents
394 "<<_:M, _:_*N>>".
395 See also: bitstring_type_m/1, bitstring_type_n/1.
397 bitstring_type_m(Node::syntaxTree()) -> syntaxTree()
399 Returns the number of start bits, M, of a bitstring_type node.
401 See also: bitstring_type/2.
403 bitstring_type_n(Node::syntaxTree()) -> syntaxTree()
405 Returns the segment size, N, of a bitstring_type node.
407 See also: bitstring_type/2.
409 block_expr(Body::[syntaxTree()]) -> syntaxTree()
411 Creates an abstract block expression. If Body is [B1, ..., Bn],
413 the result represents "begin B1, ..., Bn end".
414 See also: block_expr_body/1.
416 block_expr_body(Node::syntaxTree()) -> [syntaxTree()]
418 Returns the list of body subtrees of a block_expr node.
420 See also: block_expr/1.
422 case_expr(Argument::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
424 Tree()
425 Creates an abstract case-expression. If Clauses is [C1, ...,
427 Cn], the result represents "case Argument of C1; ...; Cn end".
428 More exactly, if each Ci represents "(Pi) Gi -> Bi", then the
429 result represents "case Argument of P1 G1 -> B1; ...; Pn Gn ->
430 Bn end".
431 See also: case_expr_argument/1, case_expr_clauses/1, clause/3,
433 if_expr/1.
434 case_expr_argument(Node::syntaxTree()) -> syntaxTree()
436 Returns the argument subtree of a case_expr node.
438 See also: case_expr/2.
440 case_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
442 Returns the list of clause subtrees of a case_expr node.
444 See also: case_expr/2.
446 catch_expr(Expr::syntaxTree()) -> syntaxTree()
448 Creates an abstract catch-expression. The result represents
450 "catch Expr".
451 See also: catch_expr_body/1.
453 catch_expr_body(Node::syntaxTree()) -> syntaxTree()
455 Returns the body subtree of a catch_expr node.
457 See also: catch_expr/1.
459 char(Char::char()) -> syntaxTree()
461 Creates an abstract character literal. The result represents
463 "$Name", where Name corresponds to Value.
464 Note: the literal corresponding to a particular character value
466 is not uniquely defined. E.g., the character "a" can be written
467 both as "$a" and "$\141", and a Tab character can be written as
468 "$\11", "$\011" or "$\t".
469 See also: char_literal/1, char_literal/2, char_value/1,
471 is_char/2.
472 char_literal(Node::syntaxTree()) -> nonempty_string()
474 Returns the literal string represented by a char node. This
476 includes the leading "$" character. Characters beyond 255 will
477 be escaped.
478 See also: char/1.
480 char_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
482 Returns the literal string represented by a char node. This
484 includes the leading "$" character. Depending on the encoding a
485 character beyond 255 will be escaped (latin1) or copied as is
486 (utf8).
487 See also: char/1.
489 char_value(Node::syntaxTree()) -> char()
491 Returns the value represented by a char node.
493 See also: char/1.
495 class_qualifier(Class::syntaxTree(), Body::syntaxTree()) -> syntax‐
497 Tree()
498 Creates an abstract class qualifier. The result represents
500 "Class:Body".
501 See also: class_qualifier_argument/1, class_qualifier_body/1,
503 class_qualifier_stacktrace/1, try_expr/4.
504 class_qualifier(Class::syntaxTree(), Body::syntaxTree(), Stack‐
506 trace::syntaxTree()) -> syntaxTree()
507 Creates an abstract class qualifier. The result represents
509 "Class:Body:Stacktrace".
510 See also: class_qualifier_argument/1, class_qualifier_body/1,
512 try_expr/4.
513 class_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
515 Returns the argument (the class) subtree of a class_qualifier
517 node.
518 See also: class_qualifier/2.
520 class_qualifier_body(Node::syntaxTree()) -> syntaxTree()
522 Returns the body subtree of a class_qualifier node.
524 See also: class_qualifier/2.
526 class_qualifier_stacktrace(Node::syntaxTree()) -> syntaxTree()
528 Returns the stacktrace subtree of a class_qualifier node.
530 See also: class_qualifier/2.
532 clause(Guard::guard(), Body::[syntaxTree()]) -> syntaxTree()
534 Equivalent to clause([], Guard, Body).
536 clause(Patterns::[syntaxTree()], Guard::guard(), Body::[syntaxTree()])
538 -> syntaxTree()
539 Creates an abstract clause. If Patterns is [P1, ..., Pn] and
541 Body is [B1, ..., Bm], then if Guard is none, the result repre‐
542 sents "(P1, ..., Pn) -> B1, ..., Bm", otherwise, unless Guard is
543 a list, the result represents "(P1, ..., Pn) when Guard -> B1,
544 ..., Bm".
545 For simplicity, the Guard argument may also be any of the fol‐
547 lowing:
548 * An empty list []. This is equivalent to passing none.
550 * A nonempty list [E1, ..., Ej] of syntax trees. This is
552 equivalent to passing conjunction([E1, ..., Ej]).
553 * A nonempty list of lists of syntax trees [[E1_1, ...,
555 E1_k1], ..., [Ej_1, ..., Ej_kj]], which is equivalent to
556 passing disjunction([conjunction([E1_1, ..., E1_k1]), ...,
557 conjunction([Ej_1, ..., Ej_kj])]).
558 See also: clause/2, clause_body/1, clause_guard/1, clause_pat‐
560 terns/1.
561 clause_body(Node::syntaxTree()) -> [syntaxTree()]
563 Return the list of body subtrees of a clause node.
565 See also: clause/3.
567 clause_guard(Node::syntaxTree()) -> none | syntaxTree()
569 Returns the guard subtree of a clause node, if any. If Node rep‐
571 resents "(P1, ..., Pn) when Guard -> B1, ..., Bm", Guard is
572 returned. Otherwise, the result is none.
573 See also: clause/3.
575 clause_patterns(Node::syntaxTree()) -> [syntaxTree()]
577 Returns the list of pattern subtrees of a clause node.
579 See also: clause/3.
581 comment(Strings::[string()]) -> syntaxTree()
583 Equivalent to comment(none, Strings).
585 comment(Pad::padding(), Strings::[string()]) -> syntaxTree()
587 Creates an abstract comment with the given padding and text. If
589 Strings is a (possibly empty) list ["Txt1", ..., "TxtN"], the
590 result represents the source code text
591 %Txt1
593 ...
594 %TxtN
595 Padding states the number of empty character positions to the
597 left of the comment separating it horizontally from source code
598 on the same line (if any). If Padding is none, a default posi‐
599 tive number is used. If Padding is an integer less than 1, there
600 should be no separating space. Comments are in themselves
601 regarded as source program forms.
602 See also: comment/1, is_form/1.
604 comment_padding(Node::syntaxTree()) -> padding()
606 Returns the amount of padding before the comment, or none. The
608 latter means that a default padding may be used.
609 See also: comment/2.
611 comment_text(Node::syntaxTree()) -> [string()]
613 Returns the lines of text of the abstract comment.
615 See also: comment/2.
617 compact_list(Node::syntaxTree()) -> syntaxTree()
619 Yields the most compact form for an abstract list skeleton. The
621 result either represents "[E1, ..., En | Tail]", where Tail is
622 not a list skeleton, or otherwise simply "[E1, ..., En]". Anno‐
623 tations on subtrees of Node that represent list skeletons may be
624 lost, but comments will be propagated to the result. Returns
625 Node itself if Node does not represent a list skeleton.
626 See also: list/2, normalize_list/1.
628 concrete(Node::syntaxTree()) -> term()
630 Returns the Erlang term represented by a syntax tree. Evaluation
632 fails with reason badarg if Node does not represent a literal
633 term.
634 Note: Currently, the set of syntax trees which have a concrete
636 representation is larger than the set of trees which can be
637 built using the function abstract/1. An abstract character will
638 be concretised as an integer, while abstract/1 does not at
639 present yield an abstract character for any input. (Use the
640 char/1 function to explicitly create an abstract character.)
641 Note: arity_qualifier nodes are recognized. This is to follow
643 The Erlang Parser when it comes to wild attributes: both {F, A}
644 and F/A are recognized, which makes it possible to turn wild
645 attributes into recognized attributes without at the same time
646 making it impossible to compile files using the new syntax with
647 the old version of the Erlang Compiler.
648 See also: abstract/1, char/1, is_literal/1.
650 conjunction(Tests::[syntaxTree()]) -> syntaxTree()
652 Creates an abstract conjunction. If List is [E1, ..., En], the
654 result represents "E1, ..., En".
655 See also: conjunction_body/1, disjunction/1.
657 conjunction_body(Node::syntaxTree()) -> [syntaxTree()]
659 Returns the list of body subtrees of a conjunction node.
661 See also: conjunction/1.
663 cons(Head::syntaxTree(), Tail::syntaxTree()) -> syntaxTree()
665 "Optimising" list skeleton cons operation. Creates an abstract
667 list skeleton whose first element is Head and whose tail corre‐
668 sponds to Tail. This is similar to list([Head], Tail), except
669 that Tail may not be none, and that the result does not neces‐
670 sarily represent exactly "[Head | Tail]", but may depend on the
671 Tail subtree. E.g., if Tail represents [X, Y], the result may
672 represent "[Head, X, Y]", rather than "[Head | [X, Y]]". Annota‐
673 tions on Tail itself may be lost if Tail represents a list
674 skeleton, but comments on Tail are propagated to the result.
675 See also: list/2, list_head/1, list_tail/1.
677 constrained_function_type(FunctionType::syntaxTree(), FunctionCon‐
679 straint::[syntaxTree()]) -> syntaxTree()
680 Creates an abstract constrained function type. If FunctionCon‐
682 straint is [C1, ..., Cn], the result represents "FunctionType
683 when C1, ...Cn".
684 See also: constrained_function_type_argument/1, con‐
686 strained_function_type_body/1.
687 constrained_function_type_argument(Node::syntaxTree()) -> syntaxTree()
689 Returns the function constraint subtree of a constrained_func‐
691 tion_type node.
692 See also: constrained_function_type/2.
694 constrained_function_type_body(Node::syntaxTree()) -> syntaxTree()
696 Returns the function type subtree of a constrained_function_type
698 node.
699 See also: constrained_function_type/2.
701 constraint(Name::syntaxTree(), Types::[syntaxTree()]) -> syntaxTree()
703 Creates an abstract (subtype) constraint. The result represents
705 "Name :: Type".
706 See also: constraint_argument/1, constraint_body/1.
708 constraint_argument(Node::syntaxTree()) -> syntaxTree()
710 Returns the name subtree of a constraint node.
712 See also: constraint/2.
714 constraint_body(Node::syntaxTree()) -> [syntaxTree()]
716 Returns the type subtree of a constraint node.
718 See also: constraint/2.
720 copy_ann(Source::syntaxTree(), Target::syntaxTree()) -> syntaxTree()
722 Copies the list of user annotations from Source to Target.
724 Note: this is equivalent to set_ann(Target, get_ann(Source)),
726 but potentially more efficient.
727 See also: get_ann/1, set_ann/2.
729 copy_attrs(S::syntaxTree(), T::syntaxTree()) -> syntaxTree()
731 Copies the attributes from Source to Target.
733 Note: this is equivalent to set_attrs(Target,
735 get_attrs(Source)), but potentially more efficient.
736 See also: get_attrs/1, set_attrs/2.
738 copy_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
740 Tree()
741 Copies the pre- and postcomments from Source to Target.
743 Note: This is equivalent to set_postcomments(set_precom‐
745 ments(Target, get_precomments(Source)), get_postcom‐
746 ments(Source)), but potentially more efficient.
747 See also: comment/2, get_postcomments/1, get_precomments/1,
749 set_postcomments/2, set_precomments/2.
750 copy_pos(Source::syntaxTree(), Target::syntaxTree()) -> syntaxTree()
752 Copies the position information from Source to Target.
754 This is equivalent to set_pos(Target, get_pos(Source)), but
756 potentially more efficient.
757 See also: get_pos/1, set_pos/2.
759 data(Tree::syntaxTree()) -> term()
761 For special purposes only. Returns the associated data of a syn‐
763 tax tree node. Evaluation fails with reason badarg if
764 is_tree(Node) does not yield true.
765 See also: tree/2.
767 disjunction(Tests::[syntaxTree()]) -> syntaxTree()
769 Creates an abstract disjunction. If List is [E1, ..., En], the
771 result represents "E1; ...; En".
772 See also: conjunction/1, disjunction_body/1.
774 disjunction_body(Node::syntaxTree()) -> [syntaxTree()]
776 Returns the list of body subtrees of a disjunction node.
778 See also: disjunction/1.
780 eof_marker() -> syntaxTree()
782 Creates an abstract end-of-file marker. This represents the end
784 of input when reading a sequence of source code forms. An end-
785 of-file marker is itself regarded as a source code form (namely,
786 the last in any sequence in which it occurs). It has no defined
787 lexical form.
788 Note: this is retained only for backwards compatibility with
790 existing parsers and tools.
791 See also: error_marker/1, is_form/1, warning_marker/1.
793 error_marker(Error::term()) -> syntaxTree()
795 Creates an abstract error marker. The result represents an
797 occurrence of an error in the source code, with an associated
798 Erlang I/O ErrorInfo structure given by Error (see module io(3)
799 for details). Error markers are regarded as source code forms,
800 but have no defined lexical form.
801 Note: this is supported only for backwards compatibility with
803 existing parsers and tools.
804 See also: eof_marker/0, error_marker_info/1, is_form/1, warn‐
806 ing_marker/1.
807 error_marker_info(Node::syntaxTree()) -> term()
809 Returns the ErrorInfo structure of an error_marker node.
811 See also: error_marker/1.
813 flatten_form_list(Node::syntaxTree()) -> syntaxTree()
815 Flattens sublists of a form_list node. Returns Node with all
817 subtrees of type form_list recursively expanded, yielding a sin‐
818 gle "flat" abstract form sequence.
819 See also: form_list/1.
821 float(Value::float()) -> syntaxTree()
823 Creates an abstract floating-point literal. The lexical repre‐
825 sentation is the decimal floating-point numeral of Value.
826 See also: float_literal/1, float_value/1.
828 float_literal(Node::syntaxTree()) -> string()
830 Returns the numeral string represented by a float node.
832 See also: float/1.
834 float_value(Node::syntaxTree()) -> float()
836 Returns the value represented by a float node. Note that float‐
838 ing-point values should usually not be compared for equality.
839 See also: float/1.
841 form_list(Forms::[syntaxTree()]) -> syntaxTree()
843 Creates an abstract sequence of "source code forms". If Forms is
845 [F1, ..., Fn], where each Fi is a form (see is_form/1, the
846 result represents
847 F1
849 ...
850 Fn
851 where the Fi are separated by one or more line breaks. A node of
853 type form_list is itself regarded as a source code form; see
854 flatten_form_list/1.
855 Note: this is simply a way of grouping source code forms as a
857 single syntax tree, usually in order to form an Erlang module
858 definition.
859 See also: flatten_form_list/1, form_list_elements/1, is_form/1.
861 form_list_elements(Node::syntaxTree()) -> [syntaxTree()]
863 Returns the list of subnodes of a form_list node.
865 See also: form_list/1.
867 fun_expr(Clauses::[syntaxTree()]) -> syntaxTree()
869 Creates an abstract fun-expression. If Clauses is [C1, ..., Cn],
871 the result represents "fun C1; ...; Cn end". More exactly, if
872 each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then the result
873 represents "fun (P11, ..., P1m) G1 -> B1; ...; (Pn1, ..., Pnm)
874 Gn -> Bn end".
875 See also: fun_expr_arity/1, fun_expr_clauses/1.
877 fun_expr_arity(Node::syntaxTree()) -> arity()
879 Returns the arity of a fun_expr node. The result is the number
881 of parameter patterns in the first clause of the fun-expression;
882 subsequent clauses are ignored.
883 An exception is thrown if fun_expr_clauses(Node) returns an
885 empty list, or if the first element of that list is not a syntax
886 tree C of type clause such that clause_patterns(C) is a nonempty
887 list.
888 See also: clause/3, clause_patterns/1, fun_expr/1,
890 fun_expr_clauses/1.
891 fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
893 Returns the list of clause subtrees of a fun_expr node.
895 See also: fun_expr/1.
897 fun_type() -> syntaxTree()
899 Creates an abstract fun of any type. The result represents
901 "fun()".
902 function(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntaxTree()
904 Creates an abstract function definition. If Clauses is [C1, ...,
906 Cn], the result represents "Name C1; ...; Name Cn.". More
907 exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then
908 the result represents "Name(P11, ..., P1m) G1 -> B1; ...;
909 Name(Pn1, ..., Pnm) Gn -> Bn.". Function definitions are source
910 code forms.
911 See also: function_arity/1, function_clauses/1, function_name/1,
913 is_form/1.
914 function_arity(Node::syntaxTree()) -> arity()
916 Returns the arity of a function node. The result is the number
918 of parameter patterns in the first clause of the function; sub‐
919 sequent clauses are ignored.
920 An exception is thrown if function_clauses(Node) returns an
922 empty list, or if the first element of that list is not a syntax
923 tree C of type clause such that clause_patterns(C) is a nonempty
924 list.
925 See also: clause/3, clause_patterns/1, function/2, func‐
927 tion_clauses/1.
928 function_clauses(Node::syntaxTree()) -> [syntaxTree()]
930 Returns the list of clause subtrees of a function node.
932 See also: function/2.
934 function_name(Node::syntaxTree()) -> syntaxTree()
936 Returns the name subtree of a function node.
938 See also: function/2.
940 function_type(Type) -> term()
942 Equivalent to function_type(any_arity, Type).
944 function_type(Arguments::any_arity | syntaxTree(), Return::syntax‐
946 Tree()) -> syntaxTree()
947 Creates an abstract function type. If Arguments is [T1, ...,
949 Tn], then if it occurs within a function specification, the
950 result represents "(T1, ...Tn) -> Return"; otherwise it repre‐
951 sents "fun((T1, ...Tn) -> Return)". If Arguments is any_arity,
952 it represents "fun((...) -> Return)".
953 Note that the erl_parse representation is identical for "Func‐
955 tionType" and "fun(FunctionType)".
956 See also: function_type_arguments/1, function_type_return/1.
958 function_type_arguments(Node::syntaxTree()) -> any_arity | [syntax‐
960 Tree()]
961 Returns the argument types subtrees of a function_type node. If
963 Node represents "fun((...) -> Return)", any_arity is returned;
964 otherwise, if Node represents "(T1, ...Tn) -> Return" or
965 "fun((T1, ...Tn) -> Return)", [T1, ..., Tn] is returned.
966 See also: function_type/1, function_type/2.
968 function_type_return(Node::syntaxTree()) -> syntaxTree()
970 Returns the return type subtrees of a function_type node.
972 See also: function_type/1, function_type/2.
974 generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
976 Creates an abstract generator. The result represents "Pattern <-
978 Body".
979 See also: binary_comp/2, generator_body/1, generator_pattern/1,
981 list_comp/2.
982 generator_body(Node::syntaxTree()) -> syntaxTree()
984 Returns the body subtree of a generator node.
986 See also: generator/2.
988 generator_pattern(Node::syntaxTree()) -> syntaxTree()
990 Returns the pattern subtree of a generator node.
992 See also: generator/2.
994 get_ann(Tree::syntaxTree()) -> [term()]
996 Returns the list of user annotations associated with a syntax
998 tree node. For a newly created node, this is the empty list. The
999 annotations may be any terms.
1000 See also: get_attrs/1, set_ann/2.
1002 get_attrs(Tree::syntaxTree()) -> syntaxTreeAttributes()
1004 Returns a representation of the attributes associated with a
1006 syntax tree node. The attributes are all the extra information
1007 that can be attached to a node. Currently, this includes posi‐
1008 tion information, source code comments, and user annotations.
1009 The result of this function cannot be inspected directly; only
1010 attached to another node (see set_attrs/2).
1011 For accessing individual attributes, see get_pos/1, get_ann/1,
1013 get_precomments/1 and get_postcomments/1.
1014 See also: get_ann/1, get_pos/1, get_postcomments/1, get_precom‐
1016 ments/1, set_attrs/2.
1017 get_pos(Tree::syntaxTree()) -> term()
1019 Returns the position information associated with Node. This is
1021 usually a nonnegative integer (indicating the source code line
1022 number), but may be any term. By default, all new tree nodes
1023 have their associated position information set to the integer
1024 zero.
1025 See also: get_attrs/1, set_pos/2.
1027 get_postcomments(Tree::syntaxTree()) -> [syntaxTree()]
1029 Returns the associated post-comments of a node. This is a possi‐
1031 bly empty list of abstract comments, in top-down textual order.
1032 When the code is formatted, post-comments are typically dis‐
1033 played to the right of and/or below the node. For example:
1034 {foo, X, Y} % Post-comment of tuple
1036 If possible, the comment should be moved past any following sep‐
1038 arator characters on the same line, rather than placing the sep‐
1039 arators on the following line. E.g.:
1040 foo([X | Xs], Y) ->
1042 foo(Xs, bar(X)); % Post-comment of 'bar(X)' node
1043 ...
1044 (where the comment is moved past the rightmost ")" and the ";").
1046 See also: comment/2, get_attrs/1, get_precomments/1, set_post‐
1048 comments/2.
1049 get_precomments(Tree::syntaxTree()) -> [syntaxTree()]
1051 Returns the associated pre-comments of a node. This is a possi‐
1053 bly empty list of abstract comments, in top-down textual order.
1054 When the code is formatted, pre-comments are typically displayed
1055 directly above the node. For example:
1056 % Pre-comment of function
1058 foo(X) -> {bar, X}.
1059 If possible, the comment should be moved before any preceding
1061 separator characters on the same line. E.g.:
1062 foo([X | Xs]) ->
1064 % Pre-comment of 'bar(X)' node
1065 [bar(X) | foo(Xs)];
1066 ...
1067 (where the comment is moved before the "[").
1069 See also: comment/2, get_attrs/1, get_postcomments/1, set_pre‐
1071 comments/2.
1072 has_comments(Tree::syntaxTree()) -> boolean()
1074 Yields false if the node has no associated comments, and true
1076 otherwise.
1077 Note: This is equivalent to (get_precomments(Node) == []) and
1079 (get_postcomments(Node) == []), but potentially more efficient.
1080 See also: get_postcomments/1, get_precomments/1, remove_com‐
1082 ments/1.
1083 if_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1085 Creates an abstract if-expression. If Clauses is [C1, ..., Cn],
1087 the result represents "if C1; ...; Cn end". More exactly, if
1088 each Ci represents "() Gi -> Bi", then the result represents "if
1089 G1 -> B1; ...; Gn -> Bn end".
1090 See also: case_expr/2, clause/3, if_expr_clauses/1.
1092 if_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1094 Returns the list of clause subtrees of an if_expr node.
1096 See also: if_expr/1.
1098 implicit_fun(Name::syntaxTree()) -> syntaxTree()
1100 Creates an abstract "implicit fun" expression. The result repre‐
1102 sents "fun Name". Name should represent either F/A or M:F/A
1103 See also: arity_qualifier/2, implicit_fun/2, implicit_fun/3,
1105 implicit_fun_name/1, module_qualifier/2.
1106 implicit_fun(Name::syntaxTree(), Arity::none | syntaxTree()) -> syntax‐
1108 Tree()
1109 Creates an abstract "implicit fun" expression. If Arity is none,
1111 this is equivalent to implicit_fun(Name), otherwise it is equiv‐
1112 alent to implicit_fun(arity_qualifier(Name, Arity)).
1113 (This is a utility function.)
1115 See also: implicit_fun/1, implicit_fun/3.
1117 implicit_fun(Module::none | syntaxTree(), Name::syntaxTree(),
1119 Arity::syntaxTree()) -> syntaxTree()
1120 Creates an abstract module-qualified "implicit fun" expression.
1122 If Module is none, this is equivalent to implicit_fun(Name,
1123 Arity), otherwise it is equivalent to implicit_fun(module_quali‐
1124 fier(Module, arity_qualifier(Name, Arity)).
1125 (This is a utility function.)
1127 See also: implicit_fun/1, implicit_fun/2.
1129 implicit_fun_name(Node::syntaxTree()) -> syntaxTree()
1131 Returns the name subtree of an implicit_fun node.
1133 Note: if Node represents "fun N/A" or "fun M:N/A", then the
1135 result is the subtree representing "N/A" or "M:N/A", respec‐
1136 tively.
1137 See also: arity_qualifier/2, implicit_fun/1, module_qualifier/2.
1139 infix_expr(Left::syntaxTree(), Operator::syntaxTree(), Right::syntax‐
1141 Tree()) -> syntaxTree()
1142 Creates an abstract infix operator expression. The result repre‐
1144 sents "Left Operator Right".
1145 See also: infix_expr_left/1, infix_expr_operator/1,
1147 infix_expr_right/1, prefix_expr/2.
1148 infix_expr_left(Node::syntaxTree()) -> syntaxTree()
1150 Returns the left argument subtree of an infix_expr node.
1152 See also: infix_expr/3.
1154 infix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1156 Returns the operator subtree of an infix_expr node.
1158 See also: infix_expr/3.
1160 infix_expr_right(Node::syntaxTree()) -> syntaxTree()
1162 Returns the right argument subtree of an infix_expr node.
1164 See also: infix_expr/3.
1166 integer(Value::integer()) -> syntaxTree()
1168 Creates an abstract integer literal. The lexical representation
1170 is the canonical decimal numeral of Value.
1171 See also: integer_literal/1, integer_value/1, is_integer/2.
1173 integer_literal(Node::syntaxTree()) -> string()
1175 Returns the numeral string represented by an integer node.
1177 See also: integer/1.
1179 integer_range_type(Low::syntaxTree(), High::syntaxTree()) -> syntax‐
1181 Tree()
1182 Creates an abstract range type. The result represents "Low ..
1184 High".
1185 See also: integer_range_type_high/1, integer_range_type_low/1.
1187 integer_range_type_high(Node::syntaxTree()) -> syntaxTree()
1189 Returns the high limit of an integer_range_type node.
1191 See also: integer_range_type/2.
1193 integer_range_type_low(Node::syntaxTree()) -> syntaxTree()
1195 Returns the low limit of an integer_range_type node.
1197 See also: integer_range_type/2.
1199 integer_value(Node::syntaxTree()) -> integer()
1201 Returns the value represented by an integer node.
1203 See also: integer/1.
1205 is_atom(Node::syntaxTree(), Value::atom()) -> boolean()
1207 Returns true if Node has type atom and represents Value, other‐
1209 wise false.
1210 See also: atom/1.
1212 is_char(Node::syntaxTree(), Value::char()) -> boolean()
1214 Returns true if Node has type char and represents Value, other‐
1216 wise false.
1217 See also: char/1.
1219 is_form(Node::syntaxTree()) -> boolean()
1221 Returns true if Node is a syntax tree representing a so-called
1223 "source code form", otherwise false. Forms are the Erlang source
1224 code units which, placed in sequence, constitute an Erlang pro‐
1225 gram. Current form types are:
1226 attribute comment error_marker eof_marker
1228 form_list function warning_marker text
1229 See also: attribute/2, comment/2, eof_marker/0, error_marker/1,
1232 form_list/1, function/2, type/1, warning_marker/1.
1233 is_integer(Node::syntaxTree(), Value::integer()) -> boolean()
1235 Returns true if Node has type integer and represents Value, oth‐
1237 erwise false.
1238 See also: integer/1.
1240 is_leaf(Node::syntaxTree()) -> boolean()
1242 Returns true if Node is a leaf node, otherwise false. The cur‐
1244 rently recognised leaf node types are:
1245 atom char comment eof_marker error_marker
1247 float fun_type integer nil operator string
1248 text underscore variable warning_marker
1249 A node of type map_expr is a leaf node if and only if it has no
1252 argument and no fields. A node of type map_type is a leaf node
1253 if and only if it has no fields (any_size). A node of type tuple
1254 is a leaf node if and only if its arity is zero. A node of type
1255 tuple_type is a leaf node if and only if it has no elements
1256 (any_size).
1257 Note: not all literals are leaf nodes, and vice versa. E.g.,
1259 tuples with nonzero arity and nonempty lists may be literals,
1260 but are not leaf nodes. Variables, on the other hand, are leaf
1261 nodes but not literals.
1262 See also: is_literal/1, type/1.
1264 is_list_skeleton(Node::syntaxTree()) -> boolean()
1266 Returns true if Node has type list or nil, otherwise false.
1268 See also: list/2, nil/0.
1270 is_literal(T::syntaxTree()) -> boolean()
1272 Returns true if Node represents a literal term, otherwise false.
1274 This function returns true if and only if the value of con‐
1275 crete(Node) is defined.
1276 See also: abstract/1, concrete/1.
1278 is_proper_list(Node::syntaxTree()) -> boolean()
1280 Returns true if Node represents a proper list, and false other‐
1282 wise. A proper list is a list skeleton either on the form "[]"
1283 or "[E1, ..., En]", or "[... | Tail]" where recursively Tail
1284 also represents a proper list.
1285 Note: Since Node is a syntax tree, the actual run-time values
1287 corresponding to its subtrees may often be partially or com‐
1288 pletely unknown. Thus, if Node represents e.g. "[... | Ns]"
1289 (where Ns is a variable), then the function will return false,
1290 because it is not known whether Ns will be bound to a list at
1291 run-time. If Node instead represents e.g. "[1, 2, 3]" or "[A |
1292 []]", then the function will return true.
1293 See also: list/2.
1295 is_string(Node::syntaxTree(), Value::string()) -> boolean()
1297 Returns true if Node has type string and represents Value, oth‐
1299 erwise false.
1300 See also: string/1.
1302 is_tree(Tree::syntaxTree()) -> boolean()
1304 For special purposes only. Returns true if Tree is an abstract
1306 syntax tree and false otherwise.
1307 Note: this function yields false for all "old-style" erl_parse-
1309 compatible "parse trees".
1310 See also: tree/2.
1312 join_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
1314 Tree()
1315 Appends the comments of Source to the current comments of Tar‐
1317 get.
1318 Note: This is equivalent to add_postcomments(get_postcom‐
1320 ments(Source), add_precomments(get_precomments(Source), Tar‐
1321 get)), but potentially more efficient.
1322 See also: add_postcomments/2, add_precomments/2, comment/2,
1324 get_postcomments/1, get_precomments/1.
1325 list(List::[syntaxTree()]) -> syntaxTree()
1327 Equivalent to list(List, none).
1329 list(Elements::[syntaxTree()], Tail::none | syntaxTree()) -> syntax‐
1331 Tree()
1332 Constructs an abstract list skeleton. The result has type list
1334 or nil. If List is a nonempty list [E1, ..., En], the result has
1335 type list and represents either "[E1, ..., En]", if Tail is
1336 none, or otherwise "[E1, ..., En | Tail]". If List is the empty
1337 list, Tail must be none, and in that case the result has type
1338 nil and represents "[]" (see nil/0).
1339 The difference between lists as semantic objects (built up of
1341 individual "cons" and "nil" terms) and the various syntactic
1342 forms for denoting lists may be bewildering at first. This mod‐
1343 ule provides functions both for exact control of the syntactic
1344 representation as well as for the simple composition and decon‐
1345 struction in terms of cons and head/tail operations.
1346 Note: in list(Elements, none), the "nil" list terminator is
1348 implicit and has no associated information (see get_attrs/1),
1349 while in the seemingly equivalent list(Elements, Tail) when Tail
1350 has type nil, the list terminator subtree Tail may have attached
1351 attributes such as position, comments, and annotations, which
1352 will be preserved in the result.
1353 See also: compact_list/1, cons/2, get_attrs/1, is_list_skele‐
1355 ton/1, is_proper_list/1, list/1, list_elements/1, list_head/1,
1356 list_length/1, list_prefix/1, list_suffix/1, list_tail/1, nil/0,
1357 normalize_list/1.
1358 list_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntaxTree()
1360 Creates an abstract list comprehension. If Body is [E1, ...,
1362 En], the result represents "[Template || E1, ..., En]".
1363 See also: generator/2, list_comp_body/1, list_comp_template/1.
1365 list_comp_body(Node::syntaxTree()) -> [syntaxTree()]
1367 Returns the list of body subtrees of a list_comp node.
1369 See also: list_comp/2.
1371 list_comp_template(Node::syntaxTree()) -> syntaxTree()
1373 Returns the template subtree of a list_comp node.
1375 See also: list_comp/2.
1377 list_elements(Node::syntaxTree()) -> [syntaxTree()]
1379 Returns the list of element subtrees of a list skeleton. Node
1381 must represent a proper list. E.g., if Node represents "[X1, X2
1382 | [X3, X4 | []]", then list_elements(Node) yields the list [X1,
1383 X2, X3, X4].
1384 See also: is_proper_list/1, list/2.
1386 list_head(Node::syntaxTree()) -> syntaxTree()
1388 Returns the head element subtree of a list node. If Node repre‐
1390 sents "[Head ...]", the result will represent "Head".
1391 See also: cons/2, list/2, list_tail/1.
1393 list_length(Node::syntaxTree()) -> non_neg_integer()
1395 Returns the number of element subtrees of a list skeleton. Node
1397 must represent a proper list. E.g., if Node represents "[X1 |
1398 [X2, X3 | [X4, X5, X6]]]", then list_length(Node) returns the
1399 integer 6.
1400 Note: this is equivalent to length(list_elements(Node)), but
1402 potentially more efficient.
1403 See also: is_proper_list/1, list/2, list_elements/1.
1405 list_prefix(Node::syntaxTree()) -> [syntaxTree()]
1407 Returns the prefix element subtrees of a list node. If Node rep‐
1409 resents "[E1, ..., En]" or "[E1, ..., En | Tail]", the returned
1410 value is [E1, ..., En].
1411 See also: list/2.
1413 list_suffix(Node::syntaxTree()) -> none | syntaxTree()
1415 Returns the suffix subtree of a list node, if one exists. If
1417 Node represents "[E1, ..., En | Tail]", the returned value is
1418 Tail, otherwise, i.e., if Node represents "[E1, ..., En]", none
1419 is returned.
1420 Note that even if this function returns some Tail that is not
1422 none, the type of Tail can be nil, if the tail has been given
1423 explicitly, and the list skeleton has not been compacted (see
1424 compact_list/1).
1425 See also: compact_list/1, list/2, nil/0.
1427 list_tail(Node::syntaxTree()) -> syntaxTree()
1429 Returns the tail of a list node. If Node represents a single-
1431 element list "[E]", then the result has type nil, representing
1432 "[]". If Node represents "[E1, E2 ...]", the result will repre‐
1433 sent "[E2 ...]", and if Node represents "[Head | Tail]", the
1434 result will represent "Tail".
1435 See also: cons/2, list/2, list_head/1.
1437 macro(Name::syntaxTree()) -> syntaxTree()
1439 Equivalent to macro(Name, none).
1441 macro(Name::syntaxTree(), Arguments::none | [syntaxTree()]) -> syntax‐
1443 Tree()
1444 Creates an abstract macro application. If Arguments is none, the
1446 result represents "?Name", otherwise, if Arguments is [A1, ...,
1447 An], the result represents "?Name(A1, ..., An)".
1448 Notes: if Arguments is the empty list, the result will thus rep‐
1450 resent "?Name()", including a pair of matching parentheses.
1451 The only syntactical limitation imposed by the preprocessor on
1453 the arguments to a macro application (viewed as sequences of
1454 tokens) is that they must be balanced with respect to parenthe‐
1455 ses, brackets, begin ... end, case ... end, etc. The text node
1456 type can be used to represent arguments which are not regular
1457 Erlang constructs.
1458 See also: macro/1, macro_arguments/1, macro_name/1, text/1.
1460 macro_arguments(Node::syntaxTree()) -> none | [syntaxTree()]
1462 Returns the list of argument subtrees of a macro node, if any.
1464 If Node represents "?Name", none is returned. Otherwise, if Node
1465 represents "?Name(A1, ..., An)", [A1, ..., An] is returned.
1466 See also: macro/2.
1468 macro_name(Node::syntaxTree()) -> syntaxTree()
1470 Returns the name subtree of a macro node.
1472 See also: macro/2.
1474 make_tree(X1::atom(), X2::[[syntaxTree()]]) -> syntaxTree()
1476 Creates a syntax tree with the given type and subtrees. Type
1478 must be a node type name (see type/1) that does not denote a
1479 leaf node type (see is_leaf/1). Groups must be a nonempty list
1480 of groups of syntax trees, representing the subtrees of a node
1481 of the given type, in left-to-right order as they would occur in
1482 the printed program text, grouped by category as done by sub‐
1483 trees/1.
1484 The result of copy_attrs(Node, make_tree(type(Node), sub‐
1486 trees(Node))) (see update_tree/2) represents the same source
1487 code text as the original Node, assuming that subtrees(Node)
1488 yields a nonempty list. However, it does not necessarily have
1489 the same data representation as Node.
1490 See also: copy_attrs/2, is_leaf/1, subtrees/1, type/1,
1492 update_tree/2.
1493 map_expr(Fields::[syntaxTree()]) -> syntaxTree()
1495 Equivalent to map_expr(none, Fields).
1497 map_expr(Argument::none | syntaxTree(), Fields::[syntaxTree()]) -> syn‐
1499 taxTree()
1500 Creates an abstract map expression. If Fields is [F1, ..., Fn],
1502 then if Argument is none, the result represents "#{F1, ...,
1503 Fn}", otherwise it represents "Argument#{F1, ..., Fn}".
1504 See also: map_expr/1, map_expr_argument/1, map_expr_fields/1,
1506 map_field_assoc/2, map_field_exact/2.
1507 map_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1509 Returns the argument subtree of a map_expr node, if any. If Node
1511 represents "#{...}", none is returned. Otherwise, if Node repre‐
1512 sents "Argument#{...}", Argument is returned.
1513 See also: map_expr/2.
1515 map_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1517 Returns the list of field subtrees of a map_expr node.
1519 See also: map_expr/2.
1521 map_field_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1523 Tree()
1524 Creates an abstract map assoc field. The result represents "Name
1526 => Value".
1527 See also: map_expr/2, map_field_assoc_name/1,
1529 map_field_assoc_value/1.
1530 map_field_assoc_name(Node::syntaxTree()) -> syntaxTree()
1532 Returns the name subtree of a map_field_assoc node.
1534 See also: map_field_assoc/2.
1536 map_field_assoc_value(Node::syntaxTree()) -> syntaxTree()
1538 Returns the value subtree of a map_field_assoc node.
1540 See also: map_field_assoc/2.
1542 map_field_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1544 Tree()
1545 Creates an abstract map exact field. The result represents "Name
1547 := Value".
1548 See also: map_expr/2, map_field_exact_name/1,
1550 map_field_exact_value/1.
1551 map_field_exact_name(Node::syntaxTree()) -> syntaxTree()
1553 Returns the name subtree of a map_field_exact node.
1555 See also: map_field_exact/2.
1557 map_field_exact_value(Node::syntaxTree()) -> syntaxTree()
1559 Returns the value subtree of a map_field_exact node.
1561 See also: map_field_exact/2.
1563 map_type() -> term()
1565 Equivalent to map_type(any_size).
1567 map_type(Fields::any_size | [syntaxTree()]) -> syntaxTree()
1569 Creates an abstract type map. If Fields is [F1, ..., Fn], the
1571 result represents "#{F1, ..., Fn}"; otherwise, if Fields is
1572 any_size, it represents "map()".
1573 See also: map_type_fields/1.
1575 map_type_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1577 Creates an abstract map type assoc field. The result represents
1579 "Name => Value".
1580 See also: map_type/1, map_type_assoc_name/1,
1582 map_type_assoc_value/1.
1583 map_type_assoc_name(Node::syntaxTree()) -> syntaxTree()
1585 Returns the name subtree of a map_type_assoc node.
1587 See also: map_type_assoc/2.
1589 map_type_assoc_value(Node::syntaxTree()) -> syntaxTree()
1591 Returns the value subtree of a map_type_assoc node.
1593 See also: map_type_assoc/2.
1595 map_type_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1597 Creates an abstract map type exact field. The result represents
1599 "Name := Value".
1600 See also: map_type/1, map_type_exact_name/1,
1602 map_type_exact_value/1.
1603 map_type_exact_name(Node::syntaxTree()) -> syntaxTree()
1605 Returns the name subtree of a map_type_exact node.
1607 See also: map_type_exact/2.
1609 map_type_exact_value(Node::syntaxTree()) -> syntaxTree()
1611 Returns the value subtree of a map_type_exact node.
1613 See also: map_type_exact/2.
1615 map_type_fields(Node::syntaxTree()) -> any_size | [syntaxTree()]
1617 Returns the list of field subtrees of a map_type node. If Node
1619 represents "map()", any_size is returned; otherwise, if Node
1620 represents "#{F1, ..., Fn}", [F1, ..., Fn] is returned.
1621 See also: map_type/0, map_type/1.
1623 match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
1625 Creates an abstract match-expression. The result represents
1627 "Pattern = Body".
1628 See also: match_expr_body/1, match_expr_pattern/1.
1630 match_expr_body(Node::syntaxTree()) -> syntaxTree()
1632 Returns the body subtree of a match_expr node.
1634 See also: match_expr/2.
1636 match_expr_pattern(Node::syntaxTree()) -> syntaxTree()
1638 Returns the pattern subtree of a match_expr node.
1640 See also: match_expr/2.
1642 meta(T::syntaxTree()) -> syntaxTree()
1644 Creates a meta-representation of a syntax tree. The result rep‐
1646 resents an Erlang expression "MetaTree" which, if evaluated,
1647 will yield a new syntax tree representing the same source code
1648 text as Tree (although the actual data representation may be
1649 different). The expression represented by MetaTree is implemen‐
1650 tation independent with regard to the data structures used by
1651 the abstract syntax tree implementation. Comments attached to
1652 nodes of Tree will be preserved, but other attributes are lost.
1653 Any node in Tree whose node type is variable (see type/1), and
1655 whose list of annotations (see get_ann/1) contains the atom
1656 meta_var, will remain unchanged in the resulting tree, except
1657 that exactly one occurrence of meta_var is removed from its
1658 annotation list.
1659 The main use of the function meta/1 is to transform a data
1661 structure Tree, which represents a piece of program code, into a
1662 form that is representation independent when printed. E.g., sup‐
1663 pose Tree represents a variable named "V". Then (assuming a
1664 function print/1 for printing syntax trees), evaluating
1665 print(abstract(Tree)) - simply using abstract/1 to map the
1666 actual data structure onto a syntax tree representation - would
1667 output a string that might look something like "{tree, variable,
1668 ..., "V", ...}", which is obviously dependent on the implementa‐
1669 tion of the abstract syntax trees. This could e.g. be useful for
1670 caching a syntax tree in a file. However, in some situations
1671 like in a program generator generator (with two "generator"), it
1672 may be unacceptable. Using print(meta(Tree)) instead would out‐
1673 put a representation independent syntax tree generating expres‐
1674 sion; in the above case, something like "erl_syntax:vari‐
1675 able("V")".
1676 See also: abstract/1, get_ann/1, type/1.
1678 module_qualifier(Module::syntaxTree(), Body::syntaxTree()) -> syntax‐
1680 Tree()
1681 Creates an abstract module qualifier. The result represents
1683 "Module:Body".
1684 See also: module_qualifier_argument/1, module_qualifier_body/1.
1686 module_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
1688 Returns the argument (the module) subtree of a module_qualifier
1690 node.
1691 See also: module_qualifier/2.
1693 module_qualifier_body(Node::syntaxTree()) -> syntaxTree()
1695 Returns the body subtree of a module_qualifier node.
1697 See also: module_qualifier/2.
1699 named_fun_expr(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
1701 Tree()
1702 Creates an abstract named fun-expression. If Clauses is [C1,
1704 ..., Cn], the result represents "fun Name C1; ...; Name Cn end".
1705 More exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi",
1706 then the result represents "fun Name(P11, ..., P1m) G1 -> B1;
1707 ...; Name(Pn1, ..., Pnm) Gn -> Bn end".
1708 See also: named_fun_expr_arity/1, named_fun_expr_clauses/1,
1710 named_fun_expr_name/1.
1711 named_fun_expr_arity(Node::syntaxTree()) -> arity()
1713 Returns the arity of a named_fun_expr node. The result is the
1715 number of parameter patterns in the first clause of the named
1716 fun-expression; subsequent clauses are ignored.
1717 An exception is thrown if named_fun_expr_clauses(Node) returns
1719 an empty list, or if the first element of that list is not a
1720 syntax tree C of type clause such that clause_patterns(C) is a
1721 nonempty list.
1722 See also: clause/3, clause_patterns/1, named_fun_expr/2,
1724 named_fun_expr_clauses/1.
1725 named_fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1727 Returns the list of clause subtrees of a named_fun_expr node.
1729 See also: named_fun_expr/2.
1731 named_fun_expr_name(Node::syntaxTree()) -> syntaxTree()
1733 Returns the name subtree of a named_fun_expr node.
1735 See also: named_fun_expr/2.
1737 nil() -> syntaxTree()
1739 Creates an abstract empty list. The result represents "[]". The
1741 empty list is traditionally called "nil".
1742 See also: is_list_skeleton/1, list/2.
1744 normalize_list(Node::syntaxTree()) -> syntaxTree()
1746 Expands an abstract list skeleton to its most explicit form. If
1748 Node represents "[E1, ..., En | Tail]", the result represents
1749 "[E1 | ... [En | Tail1] ... ]", where Tail1 is the result of
1750 normalize_list(Tail). If Node represents "[E1, ..., En]", the
1751 result simply represents "[E1 | ... [En | []] ... ]". If Node
1752 does not represent a list skeleton, Node itself is returned.
1753 See also: compact_list/1, list/2.
1755 operator(Name::atom() | string()) -> syntaxTree()
1757 Creates an abstract operator. The name of the operator is the
1759 character sequence represented by Name. This is analogous to the
1760 print name of an atom, but an operator is never written within
1761 single-quotes; e.g., the result of operator('++') represents
1762 "++" rather than "'++'".
1763 See also: atom/1, operator_literal/1, operator_name/1.
1765 operator_literal(Node::syntaxTree()) -> string()
1767 Returns the literal string represented by an operator node. This
1769 is simply the operator name as a string.
1770 See also: operator/1.
1772 operator_name(Node::syntaxTree()) -> atom()
1774 Returns the name of an operator node. Note that the name is
1776 returned as an atom.
1777 See also: operator/1.
1779 parentheses(Expr::syntaxTree()) -> syntaxTree()
1781 Creates an abstract parenthesised expression. The result repre‐
1783 sents "(Body)", independently of the context.
1784 See also: parentheses_body/1.
1786 parentheses_body(Node::syntaxTree()) -> syntaxTree()
1788 Returns the body subtree of a parentheses node.
1790 See also: parentheses/1.
1792 prefix_expr(Operator::syntaxTree(), Argument::syntaxTree()) -> syntax‐
1794 Tree()
1795 Creates an abstract prefix operator expression. The result rep‐
1797 resents "Operator Argument".
1798 See also: infix_expr/3, prefix_expr_argument/1, pre‐
1800 fix_expr_operator/1.
1801 prefix_expr_argument(Node::syntaxTree()) -> syntaxTree()
1803 Returns the argument subtree of a prefix_expr node.
1805 See also: prefix_expr/2.
1807 prefix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1809 Returns the operator subtree of a prefix_expr node.
1811 See also: prefix_expr/2.
1813 receive_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1815 Equivalent to receive_expr(Clauses, none, []).
1817 receive_expr(Clauses::[syntaxTree()], Timeout::none | syntaxTree(),
1819 Action::[syntaxTree()]) -> syntaxTree()
1820 Creates an abstract receive-expression. If Timeout is none, the
1822 result represents "receive C1; ...; Cn end" (the Action argument
1823 is ignored). Otherwise, if Clauses is [C1, ..., Cn] and Action
1824 is [A1, ..., Am], the result represents "receive C1; ...; Cn
1825 after Timeout -> A1, ..., Am end". More exactly, if each Ci rep‐
1826 resents "(Pi) Gi -> Bi", then the result represents "receive P1
1827 G1 -> B1; ...; Pn Gn -> Bn ... end".
1828 Note that in Erlang, a receive-expression must have at least one
1830 clause if no timeout part is specified.
1831 See also: case_expr/2, clause/3, receive_expr/1,
1833 receive_expr_action/1, receive_expr_clauses/1,
1834 receive_expr_timeout/1.
1835 receive_expr_action(Node::syntaxTree()) -> [syntaxTree()]
1837 Returns the list of action body subtrees of a receive_expr node.
1839 If Node represents "receive C1; ...; Cn end", this is the empty
1840 list.
1841 See also: receive_expr/3.
1843 receive_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1845 Returns the list of clause subtrees of a receive_expr node.
1847 See also: receive_expr/3.
1849 receive_expr_timeout(Node::syntaxTree()) -> none | syntaxTree()
1851 Returns the timeout subtree of a receive_expr node, if any. If
1853 Node represents "receive C1; ...; Cn end", none is returned.
1854 Otherwise, if Node represents "receive C1; ...; Cn after Timeout
1855 -> ... end", Timeout is returned.
1856 See also: receive_expr/3.
1858 record_access(Argument::syntaxTree(), Type::syntaxTree(), Field::syn‐
1860 taxTree()) -> syntaxTree()
1861 Creates an abstract record field access expression. The result
1863 represents "Argument#Type.Field".
1864 See also: record_access_argument/1, record_access_field/1,
1866 record_access_type/1, record_expr/3.
1867 record_access_argument(Node::syntaxTree()) -> syntaxTree()
1869 Returns the argument subtree of a record_access node.
1871 See also: record_access/3.
1873 record_access_field(Node::syntaxTree()) -> syntaxTree()
1875 Returns the field subtree of a record_access node.
1877 See also: record_access/3.
1879 record_access_type(Node::syntaxTree()) -> syntaxTree()
1881 Returns the type subtree of a record_access node.
1883 See also: record_access/3.
1885 record_expr(Type::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1887 Equivalent to record_expr(none, Type, Fields).
1889 record_expr(Argument::none | syntaxTree(), Type::syntaxTree(),
1891 Fields::[syntaxTree()]) -> syntaxTree()
1892 Creates an abstract record expression. If Fields is [F1, ...,
1894 Fn], then if Argument is none, the result represents "#Type{F1,
1895 ..., Fn}", otherwise it represents "Argument#Type{F1, ..., Fn}".
1896 See also: record_access/3, record_expr/2, record_expr_argu‐
1898 ment/1, record_expr_fields/1, record_expr_type/1,
1899 record_field/2, record_index_expr/2.
1900 record_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1902 Returns the argument subtree of a record_expr node, if any. If
1904 Node represents "#Type{...}", none is returned. Otherwise, if
1905 Node represents "Argument#Type{...}", Argument is returned.
1906 See also: record_expr/3.
1908 record_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1910 Returns the list of field subtrees of a record_expr node.
1912 See also: record_expr/3.
1914 record_expr_type(Node::syntaxTree()) -> syntaxTree()
1916 Returns the type subtree of a record_expr node.
1918 See also: record_expr/3.
1920 record_field(Name::syntaxTree()) -> syntaxTree()
1922 Equivalent to record_field(Name, none).
1924 record_field(Name::syntaxTree(), Value::none | syntaxTree()) -> syntax‐
1926 Tree()
1927 Creates an abstract record field specification. If Value is
1929 none, the result represents simply "Name", otherwise it repre‐
1930 sents "Name = Value".
1931 See also: record_expr/3, record_field_name/1,
1933 record_field_value/1.
1934 record_field_name(Node::syntaxTree()) -> syntaxTree()
1936 Returns the name subtree of a record_field node.
1938 See also: record_field/2.
1940 record_field_value(Node::syntaxTree()) -> none | syntaxTree()
1942 Returns the value subtree of a record_field node, if any. If
1944 Node represents "Name", none is returned. Otherwise, if Node
1945 represents "Name = Value", Value is returned.
1946 See also: record_field/2.
1948 record_index_expr(Type::syntaxTree(), Field::syntaxTree()) -> syntax‐
1950 Tree()
1951 Creates an abstract record field index expression. The result
1953 represents "#Type.Field".
1954 (Note: the function name record_index/2 is reserved by the
1956 Erlang compiler, which is why that name could not be used for
1957 this constructor.)
1958 See also: record_expr/3, record_index_expr_field/1,
1960 record_index_expr_type/1.
1961 record_index_expr_field(Node::syntaxTree()) -> syntaxTree()
1963 Returns the field subtree of a record_index_expr node.
1965 See also: record_index_expr/2.
1967 record_index_expr_type(Node::syntaxTree()) -> syntaxTree()
1969 Returns the type subtree of a record_index_expr node.
1971 See also: record_index_expr/2.
1973 record_type(Name::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1975 Creates an abstract record type. If Fields is [F1, ..., Fn], the
1977 result represents "#Name{F1, ..., Fn}".
1978 See also: record_type_fields/1, record_type_name/1.
1980 record_type_field(Name::syntaxTree(), Type::syntaxTree()) -> syntax‐
1982 Tree()
1983 Creates an abstract record type field. The result represents
1985 "Name :: Type".
1986 See also: record_type_field_name/1, record_type_field_type/1.
1988 record_type_field_name(Node::syntaxTree()) -> syntaxTree()
1990 Returns the name subtree of a record_type_field node.
1992 See also: record_type_field/2.
1994 record_type_field_type(Node::syntaxTree()) -> syntaxTree()
1996 Returns the type subtree of a record_type_field node.
1998 See also: record_type_field/2.
2000 record_type_fields(Node::syntaxTree()) -> [syntaxTree()]
2002 Returns the fields subtree of a record_type node.
2004 See also: record_type/2.
2006 record_type_name(Node::syntaxTree()) -> syntaxTree()
2008 Returns the name subtree of a record_type node.
2010 See also: record_type/2.
2012 remove_comments(Node::syntaxTree()) -> syntaxTree()
2014 Clears the associated comments of Node.
2016 Note: This is equivalent to set_precomments(set_postcom‐
2018 ments(Node, []), []), but potentially more efficient.
2019 See also: set_postcomments/2, set_precomments/2.
2021 revert(Node::syntaxTree()) -> syntaxTree()
2023 Returns an erl_parse-compatible representation of a syntax tree,
2025 if possible. If Tree represents a well-formed Erlang program or
2026 expression, the conversion should work without problems. Typi‐
2027 cally, is_tree/1 yields true if conversion failed (i.e., the
2028 result is still an abstract syntax tree), and false otherwise.
2029 The is_tree/1 test is not completely foolproof. For a few spe‐
2031 cial node types (e.g. arity_qualifier), if such a node occurs in
2032 a context where it is not expected, it will be left unchanged as
2033 a non-reverted subtree of the result. This can only happen if
2034 Tree does not actually represent legal Erlang code.
2035 See also: erl_parse(3), revert_forms/1.
2037 revert_forms(Forms::forms()) -> [erl_parse()]
2039 Reverts a sequence of Erlang source code forms. The sequence can
2041 be given either as a form_list syntax tree (possibly nested), or
2042 as a list of "program form" syntax trees. If successful, the
2043 corresponding flat list of erl_parse-compatible syntax trees is
2044 returned (see revert/1). If some program form could not be
2045 reverted, {error, Form} is thrown. Standalone comments in the
2046 form sequence are discarded.
2047 See also: form_list/1, is_form/1, revert/1.
2049 set_ann(Node::syntaxTree(), As::[term()]) -> syntaxTree()
2051 Sets the list of user annotations of Node to Annotations.
2053 See also: add_ann/2, copy_ann/2, get_ann/1.
2055 set_attrs(Node::syntaxTree(), Attr::syntaxTreeAttributes()) -> syntax‐
2057 Tree()
2058 Sets the attributes of Node to Attributes.
2060 See also: copy_attrs/2, get_attrs/1.
2062 set_pos(Node::syntaxTree(), Pos::term()) -> syntaxTree()
2064 Sets the position information of Node to Pos.
2066 See also: copy_pos/2, get_pos/1.
2068 set_postcomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntax‐
2070 Tree()
2071 Sets the post-comments of Node to Comments. Comments should be a
2073 possibly empty list of abstract comments, in top-down textual
2074 order
2075 See also: add_postcomments/2, comment/2, copy_comments/2,
2077 get_postcomments/1, join_comments/2, remove_comments/1, set_pre‐
2078 comments/2.
2079 set_precomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntaxTree()
2081 Sets the pre-comments of Node to Comments. Comments should be a
2083 possibly empty list of abstract comments, in top-down textual
2084 order.
2085 See also: add_precomments/2, comment/2, copy_comments/2,
2087 get_precomments/1, join_comments/2, remove_comments/1, set_post‐
2088 comments/2.
2089 size_qualifier(Body::syntaxTree(), Size::syntaxTree()) -> syntaxTree()
2091 Creates an abstract size qualifier. The result represents
2093 "Body:Size".
2094 See also: size_qualifier_argument/1, size_qualifier_body/1.
2096 size_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
2098 Returns the argument subtree (the size) of a size_qualifier
2100 node.
2101 See also: size_qualifier/2.
2103 size_qualifier_body(Node::syntaxTree()) -> syntaxTree()
2105 Returns the body subtree of a size_qualifier node.
2107 See also: size_qualifier/2.
2109 string(String::string()) -> syntaxTree()
2111 Creates an abstract string literal. The result represents "Text"
2113 (including the surrounding double-quotes), where Text corre‐
2114 sponds to the sequence of characters in Value, but not repre‐
2115 senting a specific string literal.
2116 For example, the result of string("x\ny") represents any and all
2118 of "x\ny", "x\12y", "x\012y" and "x\^Jy"; see char/1.
2119 See also: char/1, is_string/2, string_literal/1, string_lit‐
2121 eral/2, string_value/1.
2122 string_literal(Node::syntaxTree()) -> nonempty_string()
2124 Returns the literal string represented by a string node. This
2126 includes surrounding double-quote characters. Characters beyond
2127 255 will be escaped.
2128 See also: string/1.
2130 string_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
2132 Returns the literal string represented by a string node. This
2134 includes surrounding double-quote characters. Depending on the
2135 encoding characters beyond 255 will be escaped (latin1) or
2136 copied as is (utf8).
2137 See also: string/1.
2139 string_value(Node::syntaxTree()) -> string()
2141 Returns the value represented by a string node.
2143 See also: string/1.
2145 subtrees(T::syntaxTree()) -> [[syntaxTree()]]
2147 Returns the grouped list of all subtrees of a syntax tree. If
2149 Node is a leaf node (see is_leaf/1), this is the empty list,
2150 otherwise the result is always a nonempty list, containing the
2151 lists of subtrees of Node, in left-to-right order as they occur
2152 in the printed program text, and grouped by category. Often,
2153 each group contains only a single subtree.
2154 Depending on the type of Node, the size of some groups may be
2156 variable (e.g., the group consisting of all the elements of a
2157 tuple), while others always contain the same number of elements
2158 - usually exactly one (e.g., the group containing the argument
2159 expression of a case-expression). Note, however, that the exact
2160 structure of the returned list (for a given node type) should in
2161 general not be depended upon, since it might be subject to
2162 change without notice.
2163 The function subtrees/1 and the constructor functions
2165 make_tree/2 and update_tree/2 can be a great help if one wants
2166 to traverse a syntax tree, visiting all its subtrees, but treat
2167 nodes of the tree in a uniform way in most or all cases. Using
2168 these functions makes this simple, and also assures that your
2169 code is not overly sensitive to extensions of the syntax tree
2170 data type, because any node types not explicitly handled by your
2171 code can be left to a default case.
2172 For example:
2174 postorder(F, Tree) ->
2176 F(case subtrees(Tree) of
2177 [] -> Tree;
2178 List -> update_tree(Tree,
2179 [[postorder(F, Subtree)
2180 || Subtree <- Group]
2181 || Group <- List])
2182 end).
2183 maps the function F on Tree and all its subtrees, doing a post-
2185 order traversal of the syntax tree. (Note the use of
2186 update_tree/2 to preserve node attributes.) For a simple func‐
2187 tion like:
2188 f(Node) ->
2190 case type(Node) of
2191 atom -> atom("a_" ++ atom_name(Node));
2192 _ -> Node
2193 end.
2194 the call postorder(fun f/1, Tree) will yield a new representa‐
2196 tion of Tree in which all atom names have been extended with the
2197 prefix "a_", but nothing else (including comments, annotations
2198 and line numbers) has been changed.
2199 See also: copy_attrs/2, is_leaf/1, make_tree/2, type/1.
2201 text(String::string()) -> syntaxTree()
2203 Creates an abstract piece of source code text. The result repre‐
2205 sents exactly the sequence of characters in String. This is use‐
2206 ful in cases when one wants full control of the resulting out‐
2207 put, e.g., for the appearance of floating-point numbers or macro
2208 definitions.
2209 See also: text_string/1.
2211 text_string(Node::syntaxTree()) -> string()
2213 Returns the character sequence represented by a text node.
2215 See also: text/1.
2217 tree(Type::atom()) -> tree()
2219 Equivalent to tree(Type, []).
2221 tree(Type::atom(), Data::term()) -> tree()
2223 For special purposes only. Creates an abstract syntax tree node
2225 with type tag Type and associated data Data.
2226 This function and the related is_tree/1 and data/1 provide a
2228 uniform way to extend the set of erl_parse node types. The asso‐
2229 ciated data is any term, whose format may depend on the type
2230 tag.
2231 Notes:
2233 * Any nodes created outside of this module must have type tags
2235 distinct from those currently defined by this module; see
2236 type/1 for a complete list.
2237 * The type tag of a syntax tree node may also be used as a
2239 primary tag by the erl_parse representation; in that case,
2240 the selector functions for that node type must handle both
2241 the abstract syntax tree and the erl_parse form. The func‐
2242 tion type(T) should return the correct type tag regardless
2243 of the representation of T, so that the user sees no differ‐
2244 ence between erl_syntax and erl_parse nodes.
2245 See also: data/1, is_tree/1, type/1.
2247 try_after_expr(Body::[syntaxTree()], After::[syntaxTree()]) -> syntax‐
2249 Tree()
2250 Equivalent to try_expr(Body, [], [], After).
2252 try_expr(Body::[syntaxTree()], Handlers::[syntaxTree()]) -> syntax‐
2254 Tree()
2255 Equivalent to try_expr(Body, [], Handlers).
2257 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2259 taxTree()]) -> syntaxTree()
2260 Equivalent to try_expr(Body, Clauses, Handlers, []).
2262 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2264 taxTree()], After::[syntaxTree()]) -> syntaxTree()
2265 Creates an abstract try-expression. If Body is [B1, ..., Bn],
2267 Clauses is [C1, ..., Cj], Handlers is [H1, ..., Hk], and After
2268 is [A1, ..., Am], the result represents "try B1, ..., Bn of C1;
2269 ...; Cj catch H1; ...; Hk after A1, ..., Am end". More exactly,
2270 if each Ci represents "(CPi) CGi -> CBi", and each Hi represents
2271 "(HPi) HGi -> HBi", then the result represents "try B1, ..., Bn
2272 of CP1 CG1 -> CB1; ...; CPj CGj -> CBj catch HP1 HG1 -> HB1;
2273 ...; HPk HGk -> HBk after A1, ..., Am end"; see case_expr/2. If
2274 Clauses is the empty list, the of ... section is left out. If
2275 After is the empty list, the after ... section is left out. If
2276 Handlers is the empty list, and After is nonempty, the catch ...
2277 section is left out.
2278 See also: case_expr/2, class_qualifier/2, clause/3,
2280 try_after_expr/2, try_expr/2, try_expr/3, try_expr_after/1,
2281 try_expr_body/1, try_expr_clauses/1, try_expr_handlers/1.
2282 try_expr_after(Node::syntaxTree()) -> [syntaxTree()]
2284 Returns the list of "after" subtrees of a try_expr node.
2286 See also: try_expr/4.
2288 try_expr_body(Node::syntaxTree()) -> [syntaxTree()]
2290 Returns the list of body subtrees of a try_expr node.
2292 See also: try_expr/4.
2294 try_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
2296 Returns the list of case-clause subtrees of a try_expr node. If
2298 Node represents "try Body catch H1; ...; Hn end", the result is
2299 the empty list.
2300 See also: try_expr/4.
2302 try_expr_handlers(Node::syntaxTree()) -> [syntaxTree()]
2304 Returns the list of handler-clause subtrees of a try_expr node.
2306 See also: try_expr/4.
2308 tuple(List::[syntaxTree()]) -> syntaxTree()
2310 Creates an abstract tuple. If Elements is [X1, ..., Xn], the
2312 result represents "{X1, ..., Xn}".
2313 Note: The Erlang language has distinct 1-tuples, i.e., {X} is
2315 always distinct from X itself.
2316 See also: tuple_elements/1, tuple_size/1.
2318 tuple_elements(Node::syntaxTree()) -> [syntaxTree()]
2320 Returns the list of element subtrees of a tuple node.
2322 See also: tuple/1.
2324 tuple_size(Node::syntaxTree()) -> non_neg_integer()
2326 Returns the number of elements of a tuple node.
2328 Note: this is equivalent to length(tuple_elements(Node)), but
2330 potentially more efficient.
2331 See also: tuple/1, tuple_elements/1.
2333 tuple_type() -> term()
2335 Equivalent to tuple_type(any_size).
2337 tuple_type(Elements::any_size | [syntaxTree()]) -> syntaxTree()
2339 Creates an abstract type tuple. If Elements is [T1, ..., Tn],
2341 the result represents "{T1, ..., Tn}"; otherwise, if Elements is
2342 any_size, it represents "tuple()".
2343 See also: tuple_type_elements/1.
2345 tuple_type_elements(Node::syntaxTree()) -> any_size | [syntaxTree()]
2347 Returns the list of type element subtrees of a tuple_type node.
2349 If Node represents "tuple()", any_size is returned; otherwise,
2350 if Node represents "{T1, ..., Tn}", [T1, ..., Tn] is returned.
2351 See also: tuple_type/0, tuple_type/1.
2353 type(Tree::syntaxTree()) -> atom()
2355 Returns the type tag of Node. If Node does not represent a syn‐
2357 tax tree, evaluation fails with reason badarg. Node types cur‐
2358 rently defined by this module are:
2359 application annotated_type arity_qualifier atom
2361 attribute binary binary_field bitstring_type
2362 block_expr case_expr catch_expr char
2363 class_qualifier clause comment conjunction
2364 constrained_function_type constraint disjunction eof_marker
2365 error_marker float form_list fun_expr
2366 fun_type function function_type generator
2367 if_expr implicit_fun infix_expr integer
2368 integer_range_type list list_comp macro
2369 map_expr map_field_assoc map_field_exact map_type
2370 map_type_assoc map_type_exact match_expr module_qualifier
2371 named_fun_expr nil operator parentheses
2372 prefix_expr receive_expr record_access record_expr
2373 record_field record_index_expr record_type record_type_field
2374 size_qualifier string text try_expr
2375 tuple tuple_type typed_record_field type_application
2376 type_union underscore user_type_application variable
2377 warning_marker
2378 The user may (for special purposes) create additional nodes with
2381 other type tags, using the tree/2 function.
2382 Note: The primary constructor functions for a node type should
2384 always have the same name as the node type itself.
2385 See also: annotated_type/2, application/3, arity_qualifier/2,
2387 atom/1, attribute/2, binary/1, binary_field/2, bitstring_type/2,
2388 block_expr/1, case_expr/2, catch_expr/1, char/1, class_quali‐
2389 fier/2, clause/3, comment/2, conjunction/1, constrained_func‐
2390 tion_type/2, constraint/2, disjunction/1, eof_marker/0,
2391 error_marker/1, float/1, form_list/1, fun_expr/1, fun_type/0,
2392 function/2, function_type/1, function_type/2, generator/2,
2393 if_expr/1, implicit_fun/2, infix_expr/3, integer/1, inte‐
2394 ger_range_type/2, list/2, list_comp/2, macro/2, map_expr/2,
2395 map_field_assoc/2, map_field_exact/2, map_type/0, map_type/1,
2396 map_type_assoc/2, map_type_exact/2, match_expr/2, module_quali‐
2397 fier/2, named_fun_expr/2, nil/0, operator/1, parentheses/1, pre‐
2398 fix_expr/2, receive_expr/3, record_access/3, record_expr/2,
2399 record_field/2, record_index_expr/2, record_type/2,
2400 record_type_field/2, size_qualifier/2, string/1, text/1, tree/2,
2401 try_expr/3, tuple/1, tuple_type/0, tuple_type/1, type_applica‐
2402 tion/2, type_union/1, typed_record_field/2, underscore/0,
2403 user_type_application/2, variable/1, warning_marker/1.
2404 type_application(TypeName::syntaxTree(), Arguments::[syntaxTree()]) ->
2406 syntaxTree()
2407 Creates an abstract type application expression. If Arguments is
2409 [T1, ..., Tn], the result represents "TypeName(T1, ...Tn)".
2410 See also: type_application/3, type_application_arguments/1,
2412 type_application_name/1, user_type_application/2.
2413 type_application(Module::none | syntaxTree(), TypeName::syntaxTree(),
2415 Arguments::[syntaxTree()]) -> syntaxTree()
2416 Creates an abstract type application expression. If Module is
2418 none, this is call is equivalent to type_application(TypeName,
2419 Arguments), otherwise it is equivalent to type_application(mod‐
2420 ule_qualifier(Module, TypeName), Arguments).
2421 (This is a utility function.)
2423 See also: module_qualifier/2, type_application/2.
2425 type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2427 Returns the arguments subtrees of a type_application node.
2429 See also: type_application/2.
2431 type_application_name(Node::syntaxTree()) -> syntaxTree()
2433 Returns the type name subtree of a type_application node.
2435 See also: type_application/2.
2437 type_union(Types::[syntaxTree()]) -> syntaxTree()
2439 Creates an abstract type union. If Types is [T1, ..., Tn], the
2441 result represents "T1 | ... | Tn".
2442 See also: type_union_types/1.
2444 type_union_types(Node::syntaxTree()) -> [syntaxTree()]
2446 Returns the list of type subtrees of a type_union node.
2448 See also: type_union/1.
2450 typed_record_field(Field::syntaxTree(), Type::syntaxTree()) -> syntax‐
2452 Tree()
2453 Creates an abstract typed record field specification. The result
2455 represents "Field :: Type".
2456 See also: typed_record_field_body/1, typed_record_field_type/1.
2458 typed_record_field_body(Node::syntaxTree()) -> syntaxTree()
2460 Returns the field subtree of a typed_record_field node.
2462 See also: typed_record_field/2.
2464 typed_record_field_type(Node::syntaxTree()) -> syntaxTree()
2466 Returns the type subtree of a typed_record_field node.
2468 See also: typed_record_field/2.
2470 underscore() -> syntaxTree()
2472 Creates an abstract universal pattern ("_"). The lexical repre‐
2474 sentation is a single underscore character. Note that this is
2475 not a variable, lexically speaking.
2476 See also: variable/1.
2478 update_tree(Node::syntaxTree(), Groups::[[syntaxTree()]]) -> syntax‐
2480 Tree()
2481 Creates a syntax tree with the same type and attributes as the
2483 given tree. This is equivalent to copy_attrs(Node,
2484 make_tree(type(Node), Groups)).
2485 See also: copy_attrs/2, make_tree/2, type/1.
2487 user_type_application(TypeName::syntaxTree(), Arguments::[syntax‐
2489 Tree()]) -> syntaxTree()
2490 Creates an abstract user type. If Arguments is [T1, ..., Tn],
2492 the result represents "TypeName(T1, ...Tn)".
2493 See also: type_application/2, user_type_application_arguments/1,
2495 user_type_application_name/1.
2496 user_type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2498 Returns the arguments subtrees of a user_type_application node.
2500 See also: user_type_application/2.
2502 user_type_application_name(Node::syntaxTree()) -> syntaxTree()
2504 Returns the type name subtree of a user_type_application node.
2506 See also: user_type_application/2.
2508 variable(Name::atom() | string()) -> syntaxTree()
2510 Creates an abstract variable with the given name. Name may be
2512 any atom or string that represents a lexically valid variable
2513 name, but not a single underscore character; see underscore/0.
2514 Note: no checking is done whether the character sequence repre‐
2516 sents a proper variable name, i.e., whether or not its first
2517 character is an uppercase Erlang character, or whether it does
2518 not contain control characters, whitespace, etc.
2519 See also: underscore/0, variable_literal/1, variable_name/1.
2521 variable_literal(Node::syntaxTree()) -> string()
2523 Returns the name of a variable node as a string.
2525 See also: variable/1.
2527 variable_name(Node::syntaxTree()) -> atom()
2529 Returns the name of a variable node as an atom.
2531 See also: variable/1.
2533 warning_marker(Warning::term()) -> syntaxTree()
2535 Creates an abstract warning marker. The result represents an
2537 occurrence of a possible problem in the source code, with an
2538 associated Erlang I/O ErrorInfo structure given by Error (see
2539 module io(3) for details). Warning markers are regarded as
2540 source code forms, but have no defined lexical form.
2541 Note: this is supported only for backwards compatibility with
2543 existing parsers and tools.
2544 See also: eof_marker/0, error_marker/1, is_form/1, warn‐
2546 ing_marker_info/1.
2547 warning_marker_info(Node::syntaxTree()) -> term()
2549 Returns the ErrorInfo structure of a warning_marker node.
2551 See also: warning_marker/1.
2553
2555 Richard Carlsson <carlsson.richard@gmail.com>
2556 syntax_tools 2.5 erl_syntax(3)