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 di‐
29 rect references to the data structures used to represent these enti‐
30 ties. With few exceptions, the functions in this module perform no se‐
31 mantic interpretation of their inputs, and in general, the user is as‐
32 sumed to pass type-correct arguments - if this is not done, the effects
33 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 annotation_or_location() = erl_anno:anno() | erl_anno:location():
46 encoding() = utf8 | unicode | latin1:
49 erl_parse() = erl_parse:abstract_clause() | erl_parse:abstract_expr()
52 | erl_parse:abstract_form() | erl_parse:abstract_type() |
53 erl_parse:form_info() | erl_parse:af_binelement(term()) |
54 erl_parse:af_generator() | erl_parse:af_remote_function():
55 forms() = syntaxTree() | [syntaxTree()]:
58 guard() = none | syntaxTree() | [syntaxTree()] | [[syntaxTree()]]:
61 padding() = none | integer():
64 syntaxTree() = tree() | wrapper() | erl_parse():
67 syntaxTreeAttributes() = #attr{pos=term(), ann=[term()], com=none |
70 #com{pre=[syntaxTree()], post=[syntaxTree()]}}:
71 tree() = #tree{type=atom(), attr=#attr{pos=term(), ann=[term()],
74 com=none | #com{pre=[syntaxTree()], post=[syntaxTree()]}},
75 data=term()}:
76 wrapper() = #wrapper{type=atom(), attr=#attr{pos=term(),
79 ann=[term()], com=none | #com{pre=[syntaxTree()], post=[syntax‐
80 Tree()]}}, tree=erl_parse()}:
81
84 abstract(T::term()) -> syntaxTree()
85 Returns the syntax tree corresponding to an Erlang term. Term
87 must be a literal term, i.e., one that can be represented as a
88 source code literal. Thus, it may not contain a process identi‐
89 fier, port, reference or function value as a subterm. The func‐
90 tion recognises printable strings, in order to get a compact and
91 readable representation. Evaluation fails with reason badarg if
92 Term is not a literal term.
93 See also: concrete/1, is_literal/1.
95 add_ann(A::term(), Node::syntaxTree()) -> syntaxTree()
97 Appends the term Annotation to the list of user annotations of
99 Node.
100 Note: this is equivalent to set_ann(Node, [Annotation |
102 get_ann(Node)]), but potentially more efficient.
103 See also: get_ann/1, set_ann/2.
105 add_postcomments(Cs::[syntaxTree()], Node::syntaxTree()) -> syntax‐
107 Tree()
108 Appends Comments to the post-comments of Node.
110 Note: This is equivalent to set_postcomments(Node, get_postcom‐
112 ments(Node) ++ Comments), but potentially more efficient.
113 See also: add_precomments/2, comment/2, get_postcomments/1,
115 join_comments/2, set_postcomments/2.
116 add_precomments(Cs::[syntaxTree()], Node::syntaxTree()) -> syntaxTree()
118 Appends Comments to the pre-comments of Node.
120 Note: This is equivalent to set_precomments(Node, get_precom‐
122 ments(Node) ++ Comments), but potentially more efficient.
123 See also: add_postcomments/2, comment/2, get_precomments/1,
125 join_comments/2, set_precomments/2.
126 annotated_type(Name::syntaxTree(), Type::syntaxTree()) -> syntaxTree()
128 Creates an abstract annotated type expression. The result repre‐
130 sents "Name :: Type".
131 See also: annotated_type_body/1, annotated_type_name/1.
133 annotated_type_body(Node::syntaxTree()) -> syntaxTree()
135 Returns the type subtrees of an annotated_type node.
137 See also: annotated_type/2.
139 annotated_type_name(Node::syntaxTree()) -> syntaxTree()
141 Returns the name subtree of an annotated_type node.
143 See also: annotated_type/2.
145 application(Operator::syntaxTree(), Arguments::[syntaxTree()]) -> syn‐
147 taxTree()
148 Creates an abstract function application expression. If Argu‐
150 ments is [A1, ..., An], the result represents "Operator(A1, ...,
151 An)".
152 See also: application/3, application_arguments/1, applica‐
154 tion_operator/1.
155 application(Module::none | syntaxTree(), Name::syntaxTree(), Argu‐
157 ments::[syntaxTree()]) -> syntaxTree()
158 Creates an abstract function application expression. If Module
160 is none, this is call is equivalent to application(Function, Ar‐
161 guments), otherwise it is equivalent to application(module_qual‐
162 ifier(Module, Function), Arguments).
163 (This is a utility function.)
165 See also: application/2, module_qualifier/2.
167 application_arguments(Node::syntaxTree()) -> [syntaxTree()]
169 Returns the list of argument subtrees of an application node.
171 See also: application/2.
173 application_operator(Node::syntaxTree()) -> syntaxTree()
175 Returns the operator subtree of an application node.
177 Note: if Node represents "M:F(...)", then the result is the sub‐
179 tree representing "M:F".
180 See also: application/2, module_qualifier/2.
182 arity_qualifier(Body::syntaxTree(), Arity::syntaxTree()) -> syntax‐
184 Tree()
185 Creates an abstract arity qualifier. The result represents
187 "Body/Arity".
188 See also: arity_qualifier_argument/1, arity_qualifier_body/1.
190 arity_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
192 Returns the argument (the arity) subtree of an arity_qualifier
194 node.
195 See also: arity_qualifier/2.
197 arity_qualifier_body(Node::syntaxTree()) -> syntaxTree()
199 Returns the body subtree of an arity_qualifier node.
201 See also: arity_qualifier/2.
203 atom(Name::atom() | string()) -> syntaxTree()
205 Creates an abstract atom literal. The print name of the atom is
207 the character sequence represented by Name.
208 See also: atom_literal/1, atom_literal/2, atom_name/1,
210 atom_value/1, is_atom/2.
211 atom_literal(Node::syntaxTree()) -> string()
213 Returns the literal string represented by an atom node. This in‐
215 cludes surrounding single-quote characters if necessary. Charac‐
216 ters beyond 255 will be escaped.
217 Note that e.g. the result of atom("x\ny") represents any and all
219 of `x\ny'', `x\12y'', `x\012y'' and `x\^Jy\''; see string/1.
220 See also: atom/1, string/1.
222 atom_literal(Node, X2) -> term()
224 Returns the literal string represented by an atom node. This in‐
226 cludes surrounding single-quote characters if necessary. Depend‐
227 ing on the encoding a character beyond 255 will be escaped
228 (latin1) or copied as is (utf8).
229 See also: atom/1, atom_literal/1, string/1.
231 atom_name(Node::syntaxTree()) -> string()
233 Returns the printname of an atom node.
235 See also: atom/1.
237 atom_value(Node::syntaxTree()) -> atom()
239 Returns the value represented by an atom node.
241 See also: atom/1.
243 attribute(Name::syntaxTree()) -> syntaxTree()
245 Equivalent to attribute(Name, none).
247 attribute(Name::syntaxTree(), Args::none | [syntaxTree()]) -> syntax‐
249 Tree()
250 Creates an abstract program attribute. If Arguments is [A1, ...,
252 An], the result represents "-Name(A1, ..., An).". Otherwise, if
253 Arguments is none, the result represents "-Name.". The latter
254 form makes it possible to represent preprocessor directives such
255 as "-endif.". Attributes are source code forms.
256 Note: The preprocessor macro definition directive "-define(Name,
258 Body)." has relatively few requirements on the syntactical form
259 of Body (viewed as a sequence of tokens). The text node type can
260 be used for a Body that is not a normal Erlang construct.
261 See also: attribute/1, attribute_arguments/1, attribute_name/1,
263 is_form/1, text/1.
264 attribute_arguments(Node::syntaxTree()) -> none | [syntaxTree()]
266 Returns the list of argument subtrees of an attribute node, if
268 any. If Node represents "-Name.", the result is none. Otherwise,
269 if Node represents "-Name(E1, ..., En).", [E1, ..., E1] is re‐
270 turned.
271 See also: attribute/1.
273 attribute_name(Node::syntaxTree()) -> syntaxTree()
275 Returns the name subtree of an attribute node.
277 See also: attribute/1.
279 binary(List::[syntaxTree()]) -> syntaxTree()
281 Creates an abstract binary-object template. If Fields is [F1,
283 ..., Fn], the result represents "<<F1, ..., Fn>>".
284 See also: binary_field/2, binary_fields/1.
286 binary_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntax‐
288 Tree()
289 Creates an abstract binary comprehension. If Body is [E1, ...,
291 En], the result represents "<<Template || E1, ..., En>>".
292 See also: binary_comp_body/1, binary_comp_template/1, genera‐
294 tor/2.
295 binary_comp_body(Node::syntaxTree()) -> [syntaxTree()]
297 Returns the list of body subtrees of a binary_comp node.
299 See also: binary_comp/2.
301 binary_comp_template(Node::syntaxTree()) -> syntaxTree()
303 Returns the template subtree of a binary_comp node.
305 See also: binary_comp/2.
307 binary_field(Body::syntaxTree()) -> syntaxTree()
309 Equivalent to binary_field(Body, []).
311 binary_field(Body::syntaxTree(), Types::[syntaxTree()]) -> syntaxTree()
313 Creates an abstract binary template field. If Types is the empty
315 list, the result simply represents "Body", otherwise, if Types
316 is [T1, ..., Tn], the result represents "Body/T1-...-Tn".
317 See also: binary/1, binary_field/1, binary_field/3, bi‐
319 nary_field_body/1, binary_field_size/1, binary_field_types/1.
320 binary_field(Body::syntaxTree(), Size::none | syntaxTree(),
322 Types::[syntaxTree()]) -> syntaxTree()
323 Creates an abstract binary template field. If Size is none, this
325 is equivalent to "binary_field(Body, Types)", otherwise it is
326 equivalent to "binary_field(size_qualifier(Body, Size), Types)".
327 (This is a utility function.)
329 See also: binary/1, binary_field/2, size_qualifier/2.
331 binary_field_body(Node::syntaxTree()) -> syntaxTree()
333 Returns the body subtree of a binary_field.
335 See also: binary_field/2.
337 binary_field_size(Node::syntaxTree()) -> none | syntaxTree()
339 Returns the size specifier subtree of a binary_field node, if
341 any. If Node represents "Body:Size" or "Body:Size/T1, ..., Tn",
342 the result is Size, otherwise none is returned.
343 (This is a utility function.)
345 See also: binary_field/2, binary_field/3.
347 binary_field_types(Node::syntaxTree()) -> [syntaxTree()]
349 Returns the list of type-specifier subtrees of a binary_field
351 node. If Node represents ".../T1, ..., Tn", the result is [T1,
352 ..., Tn], otherwise the result is the empty list.
353 See also: binary_field/2.
355 binary_fields(Node::syntaxTree()) -> [syntaxTree()]
357 Returns the list of field subtrees of a binary node.
359 See also: binary/1, binary_field/2.
361 binary_generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntax‐
363 Tree()
364 Creates an abstract binary_generator. The result represents
366 "Pattern <- Body".
367 See also: binary_comp/2, binary_generator_body/1, binary_genera‐
369 tor_pattern/1, list_comp/2.
370 binary_generator_body(Node::syntaxTree()) -> syntaxTree()
372 Returns the body subtree of a generator node.
374 See also: binary_generator/2.
376 binary_generator_pattern(Node::syntaxTree()) -> syntaxTree()
378 Returns the pattern subtree of a generator node.
380 See also: binary_generator/2.
382 bitstring_type(M::syntaxTree(), N::syntaxTree()) -> syntaxTree()
384 Creates an abstract bitstring type. The result represents
386 "<<_:M, _:_*N>>".
387 See also: bitstring_type_m/1, bitstring_type_n/1.
389 bitstring_type_m(Node::syntaxTree()) -> syntaxTree()
391 Returns the number of start bits, M, of a bitstring_type node.
393 See also: bitstring_type/2.
395 bitstring_type_n(Node::syntaxTree()) -> syntaxTree()
397 Returns the segment size, N, of a bitstring_type node.
399 See also: bitstring_type/2.
401 block_expr(Body::[syntaxTree()]) -> syntaxTree()
403 Creates an abstract block expression. If Body is [B1, ..., Bn],
405 the result represents "begin B1, ..., Bn end".
406 See also: block_expr_body/1.
408 block_expr_body(Node::syntaxTree()) -> [syntaxTree()]
410 Returns the list of body subtrees of a block_expr node.
412 See also: block_expr/1.
414 case_expr(Argument::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
416 Tree()
417 Creates an abstract case-expression. If Clauses is [C1, ...,
419 Cn], the result represents "case Argument of C1; ...; Cn end".
420 More exactly, if each Ci represents "(Pi) Gi -> Bi", then the
421 result represents "case Argument of P1 G1 -> B1; ...; Pn Gn ->
422 Bn end".
423 See also: case_expr_argument/1, case_expr_clauses/1, clause/3,
425 if_expr/1.
426 case_expr_argument(Node::syntaxTree()) -> syntaxTree()
428 Returns the argument subtree of a case_expr node.
430 See also: case_expr/2.
432 case_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
434 Returns the list of clause subtrees of a case_expr node.
436 See also: case_expr/2.
438 catch_expr(Expr::syntaxTree()) -> syntaxTree()
440 Creates an abstract catch-expression. The result represents
442 "catch Expr".
443 See also: catch_expr_body/1.
445 catch_expr_body(Node::syntaxTree()) -> syntaxTree()
447 Returns the body subtree of a catch_expr node.
449 See also: catch_expr/1.
451 char(Char::char()) -> syntaxTree()
453 Creates an abstract character literal. The result represents
455 "$Name", where Name corresponds to Value.
456 Note: the literal corresponding to a particular character value
458 is not uniquely defined. E.g., the character "a" can be written
459 both as "$a" and "$\141", and a Tab character can be written as
460 "$\11", "$\011" or "$\t".
461 See also: char_literal/1, char_literal/2, char_value/1,
463 is_char/2.
464 char_literal(Node::syntaxTree()) -> nonempty_string()
466 Returns the literal string represented by a char node. This in‐
468 cludes the leading "$" character. Characters beyond 255 will be
469 escaped.
470 See also: char/1.
472 char_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
474 Returns the literal string represented by a char node. This in‐
476 cludes the leading "$" character. Depending on the encoding a
477 character beyond 255 will be escaped (latin1) or copied as is
478 (utf8).
479 See also: char/1.
481 char_value(Node::syntaxTree()) -> char()
483 Returns the value represented by a char node.
485 See also: char/1.
487 class_qualifier(Class::syntaxTree(), Body::syntaxTree()) -> syntax‐
489 Tree()
490 Creates an abstract class qualifier. The result represents
492 "Class:Body".
493 See also: class_qualifier_argument/1, class_qualifier_body/1,
495 class_qualifier_stacktrace/1, try_expr/4.
496 class_qualifier(Class::syntaxTree(), Body::syntaxTree(), Stack‐
498 trace::syntaxTree()) -> syntaxTree()
499 Creates an abstract class qualifier. The result represents
501 "Class:Body:Stacktrace".
502 See also: class_qualifier_argument/1, class_qualifier_body/1,
504 try_expr/4.
505 class_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
507 Returns the argument (the class) subtree of a class_qualifier
509 node.
510 See also: class_qualifier/2.
512 class_qualifier_body(Node::syntaxTree()) -> syntaxTree()
514 Returns the body subtree of a class_qualifier node.
516 See also: class_qualifier/2.
518 class_qualifier_stacktrace(Node::syntaxTree()) -> syntaxTree()
520 Returns the stacktrace subtree of a class_qualifier node.
522 See also: class_qualifier/2.
524 clause(Guard::guard(), Body::[syntaxTree()]) -> syntaxTree()
526 Equivalent to clause([], Guard, Body).
528 clause(Patterns::[syntaxTree()], Guard::guard(), Body::[syntaxTree()])
530 -> syntaxTree()
531 Creates an abstract clause. If Patterns is [P1, ..., Pn] and
533 Body is [B1, ..., Bm], then if Guard is none, the result repre‐
534 sents "(P1, ..., Pn) -> B1, ..., Bm", otherwise, unless Guard is
535 a list, the result represents "(P1, ..., Pn) when Guard -> B1,
536 ..., Bm".
537 For simplicity, the Guard argument may also be any of the fol‐
539 lowing:
540 * An empty list []. This is equivalent to passing none.
542 * A nonempty list [E1, ..., Ej] of syntax trees. This is
544 equivalent to passing conjunction([E1, ..., Ej]).
545 * A nonempty list of lists of syntax trees [[E1_1, ...,
547 E1_k1], ..., [Ej_1, ..., Ej_kj]], which is equivalent to
548 passing disjunction([conjunction([E1_1, ..., E1_k1]), ...,
549 conjunction([Ej_1, ..., Ej_kj])]).
550 See also: clause/2, clause_body/1, clause_guard/1, clause_pat‐
552 terns/1.
553 clause_body(Node::syntaxTree()) -> [syntaxTree()]
555 Return the list of body subtrees of a clause node.
557 See also: clause/3.
559 clause_guard(Node::syntaxTree()) -> none | syntaxTree()
561 Returns the guard subtree of a clause node, if any. If Node rep‐
563 resents "(P1, ..., Pn) when Guard -> B1, ..., Bm", Guard is re‐
564 turned. Otherwise, the result is none.
565 See also: clause/3.
567 clause_patterns(Node::syntaxTree()) -> [syntaxTree()]
569 Returns the list of pattern subtrees of a clause node.
571 See also: clause/3.
573 comment(Strings::[string()]) -> syntaxTree()
575 Equivalent to comment(none, Strings).
577 comment(Pad::padding(), Strings::[string()]) -> syntaxTree()
579 Creates an abstract comment with the given padding and text. If
581 Strings is a (possibly empty) list ["Txt1", ..., "TxtN"], the
582 result represents the source code text
583 %Txt1
585 ...
586 %TxtN
587 Padding states the number of empty character positions to the
589 left of the comment separating it horizontally from source code
590 on the same line (if any). If Padding is none, a default posi‐
591 tive number is used. If Padding is an integer less than 1, there
592 should be no separating space. Comments are in themselves re‐
593 garded as source program forms.
594 See also: comment/1, is_form/1.
596 comment_padding(Node::syntaxTree()) -> padding()
598 Returns the amount of padding before the comment, or none. The
600 latter means that a default padding may be used.
601 See also: comment/2.
603 comment_text(Node::syntaxTree()) -> [string()]
605 Returns the lines of text of the abstract comment.
607 See also: comment/2.
609 compact_list(Node::syntaxTree()) -> syntaxTree()
611 Yields the most compact form for an abstract list skeleton. The
613 result either represents "[E1, ..., En | Tail]", where Tail is
614 not a list skeleton, or otherwise simply "[E1, ..., En]". Anno‐
615 tations on subtrees of Node that represent list skeletons may be
616 lost, but comments will be propagated to the result. Returns
617 Node itself if Node does not represent a list skeleton.
618 See also: list/2, normalize_list/1.
620 concrete(Node::syntaxTree()) -> term()
622 Returns the Erlang term represented by a syntax tree. Evaluation
624 fails with reason badarg if Node does not represent a literal
625 term.
626 Note: Currently, the set of syntax trees which have a concrete
628 representation is larger than the set of trees which can be
629 built using the function abstract/1. An abstract character will
630 be concretised as an integer, while abstract/1 does not at
631 present yield an abstract character for any input. (Use the
632 char/1 function to explicitly create an abstract character.)
633 Note: arity_qualifier nodes are recognized. This is to follow
635 The Erlang Parser when it comes to wild attributes: both {F, A}
636 and F/A are recognized, which makes it possible to turn wild at‐
637 tributes into recognized attributes without at the same time
638 making it impossible to compile files using the new syntax with
639 the old version of the Erlang Compiler.
640 See also: abstract/1, char/1, is_literal/1.
642 conjunction(Tests::[syntaxTree()]) -> syntaxTree()
644 Creates an abstract conjunction. If List is [E1, ..., En], the
646 result represents "E1, ..., En".
647 See also: conjunction_body/1, disjunction/1.
649 conjunction_body(Node::syntaxTree()) -> [syntaxTree()]
651 Returns the list of body subtrees of a conjunction node.
653 See also: conjunction/1.
655 cons(Head::syntaxTree(), Tail::syntaxTree()) -> syntaxTree()
657 "Optimising" list skeleton cons operation. Creates an abstract
659 list skeleton whose first element is Head and whose tail corre‐
660 sponds to Tail. This is similar to list([Head], Tail), except
661 that Tail may not be none, and that the result does not neces‐
662 sarily represent exactly "[Head | Tail]", but may depend on the
663 Tail subtree. E.g., if Tail represents [X, Y], the result may
664 represent "[Head, X, Y]", rather than "[Head | [X, Y]]". Annota‐
665 tions on Tail itself may be lost if Tail represents a list
666 skeleton, but comments on Tail are propagated to the result.
667 See also: list/2, list_head/1, list_tail/1.
669 constrained_function_type(FunctionType::syntaxTree(), FunctionCon‐
671 straint::[syntaxTree()]) -> syntaxTree()
672 Creates an abstract constrained function type. If FunctionCon‐
674 straint is [C1, ..., Cn], the result represents "FunctionType
675 when C1, ...Cn".
676 See also: constrained_function_type_argument/1, con‐
678 strained_function_type_body/1.
679 constrained_function_type_argument(Node::syntaxTree()) -> syntaxTree()
681 Returns the function constraint subtree of a constrained_func‐
683 tion_type node.
684 See also: constrained_function_type/2.
686 constrained_function_type_body(Node::syntaxTree()) -> syntaxTree()
688 Returns the function type subtree of a constrained_function_type
690 node.
691 See also: constrained_function_type/2.
693 constraint(Name::syntaxTree(), Types::[syntaxTree()]) -> syntaxTree()
695 Creates an abstract (subtype) constraint. The result represents
697 "Name :: Type".
698 See also: constraint_argument/1, constraint_body/1.
700 constraint_argument(Node::syntaxTree()) -> syntaxTree()
702 Returns the name subtree of a constraint node.
704 See also: constraint/2.
706 constraint_body(Node::syntaxTree()) -> [syntaxTree()]
708 Returns the type subtree of a constraint node.
710 See also: constraint/2.
712 copy_ann(Source::syntaxTree(), Target::syntaxTree()) -> syntaxTree()
714 Copies the list of user annotations from Source to Target.
716 Note: this is equivalent to set_ann(Target, get_ann(Source)),
718 but potentially more efficient.
719 See also: get_ann/1, set_ann/2.
721 copy_attrs(S::syntaxTree(), T::syntaxTree()) -> syntaxTree()
723 Copies the attributes from Source to Target.
725 Note: this is equivalent to set_attrs(Target, get_at‐
727 trs(Source)), but potentially more efficient.
728 See also: get_attrs/1, set_attrs/2.
730 copy_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
732 Tree()
733 Copies the pre- and postcomments from Source to Target.
735 Note: This is equivalent to set_postcomments(set_precom‐
737 ments(Target, get_precomments(Source)), get_postcom‐
738 ments(Source)), but potentially more efficient.
739 See also: comment/2, get_postcomments/1, get_precomments/1,
741 set_postcomments/2, set_precomments/2.
742 copy_pos(Source::syntaxTree(), Target::syntaxTree()) -> syntaxTree()
744 Copies the annotation from Source to Target.
746 This is equivalent to set_pos(Target, get_pos(Source)), but po‐
748 tentially more efficient.
749 See also: get_pos/1, set_pos/2.
751 data(Tree::syntaxTree()) -> term()
753 For special purposes only. Returns the associated data of a syn‐
755 tax tree node. Evaluation fails with reason badarg if
756 is_tree(Node) does not yield true.
757 See also: tree/2.
759 disjunction(Tests::[syntaxTree()]) -> syntaxTree()
761 Creates an abstract disjunction. If List is [E1, ..., En], the
763 result represents "E1; ...; En".
764 See also: conjunction/1, disjunction_body/1.
766 disjunction_body(Node::syntaxTree()) -> [syntaxTree()]
768 Returns the list of body subtrees of a disjunction node.
770 See also: disjunction/1.
772 else_expr(Clauses) -> term()
774 Creates an abstract else-expression. If Clauses is [C1, ...,
776 Cn], the result represents "else C1; ...; Cn end". More exactly,
777 if each Ci represents "(Pi) Gi -> Bi", then the result repre‐
778 sents "else G1 -> B1; ...; Pn Gn -> Bn end".
779 See also: clause/3, else_expr_clauses/1, maybe_expr/2.
781 else_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
783 Returns the list of clause subtrees of an else_expr node.
785 See also: else_expr/1.
787 eof_marker() -> syntaxTree()
789 Creates an abstract end-of-file marker. This represents the end
791 of input when reading a sequence of source code forms. An end-
792 of-file marker is itself regarded as a source code form (namely,
793 the last in any sequence in which it occurs). It has no defined
794 lexical form.
795 Note: this is retained only for backwards compatibility with ex‐
797 isting parsers and tools.
798 See also: error_marker/1, is_form/1, warning_marker/1.
800 error_marker(Error::term()) -> syntaxTree()
802 Creates an abstract error marker. The result represents an oc‐
804 currence of an error in the source code, with an associated Er‐
805 lang I/O ErrorInfo structure given by Error (see module io(3)
806 for details). Error markers are regarded as source code forms,
807 but have no defined lexical form.
808 Note: this is supported only for backwards compatibility with
810 existing parsers and tools.
811 See also: eof_marker/0, error_marker_info/1, is_form/1, warn‐
813 ing_marker/1.
814 error_marker_info(Node::syntaxTree()) -> term()
816 Returns the ErrorInfo structure of an error_marker node.
818 See also: error_marker/1.
820 flatten_form_list(Node::syntaxTree()) -> syntaxTree()
822 Flattens sublists of a form_list node. Returns Node with all
824 subtrees of type form_list recursively expanded, yielding a sin‐
825 gle "flat" abstract form sequence.
826 See also: form_list/1.
828 float(Value::float()) -> syntaxTree()
830 Creates an abstract floating-point literal. The lexical repre‐
832 sentation is the decimal floating-point numeral of Value.
833 See also: float_literal/1, float_value/1.
835 float_literal(Node::syntaxTree()) -> string()
837 Returns the numeral string represented by a float node.
839 See also: float/1.
841 float_value(Node::syntaxTree()) -> float()
843 Returns the value represented by a float node. Note that float‐
845 ing-point values should usually not be compared for equality.
846 See also: float/1.
848 form_list(Forms::[syntaxTree()]) -> syntaxTree()
850 Creates an abstract sequence of "source code forms". If Forms is
852 [F1, ..., Fn], where each Fi is a form (see is_form/1, the re‐
853 sult represents
854 F1
856 ...
857 Fn
858 where the Fi are separated by one or more line breaks. A node of
860 type form_list is itself regarded as a source code form; see
861 flatten_form_list/1.
862 Note: this is simply a way of grouping source code forms as a
864 single syntax tree, usually in order to form an Erlang module
865 definition.
866 See also: flatten_form_list/1, form_list_elements/1, is_form/1.
868 form_list_elements(Node::syntaxTree()) -> [syntaxTree()]
870 Returns the list of subnodes of a form_list node.
872 See also: form_list/1.
874 fun_expr(Clauses::[syntaxTree()]) -> syntaxTree()
876 Creates an abstract fun-expression. If Clauses is [C1, ..., Cn],
878 the result represents "fun C1; ...; Cn end". More exactly, if
879 each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then the result
880 represents "fun (P11, ..., P1m) G1 -> B1; ...; (Pn1, ..., Pnm)
881 Gn -> Bn end".
882 See also: fun_expr_arity/1, fun_expr_clauses/1.
884 fun_expr_arity(Node::syntaxTree()) -> arity()
886 Returns the arity of a fun_expr node. The result is the number
888 of parameter patterns in the first clause of the fun-expression;
889 subsequent clauses are ignored.
890 An exception is thrown if fun_expr_clauses(Node) returns an
892 empty list, or if the first element of that list is not a syntax
893 tree C of type clause such that clause_patterns(C) is a nonempty
894 list.
895 See also: clause/3, clause_patterns/1, fun_expr/1,
897 fun_expr_clauses/1.
898 fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
900 Returns the list of clause subtrees of a fun_expr node.
902 See also: fun_expr/1.
904 fun_type() -> syntaxTree()
906 Creates an abstract fun of any type. The result represents
908 "fun()".
909 function(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntaxTree()
911 Creates an abstract function definition. If Clauses is [C1, ...,
913 Cn], the result represents "Name C1; ...; Name Cn.". More ex‐
914 actly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then
915 the result represents "Name(P11, ..., P1m) G1 -> B1; ...;
916 Name(Pn1, ..., Pnm) Gn -> Bn.". Function definitions are source
917 code forms.
918 See also: function_arity/1, function_clauses/1, function_name/1,
920 is_form/1.
921 function_arity(Node::syntaxTree()) -> arity()
923 Returns the arity of a function node. The result is the number
925 of parameter patterns in the first clause of the function; sub‐
926 sequent clauses are ignored.
927 An exception is thrown if function_clauses(Node) returns an
929 empty list, or if the first element of that list is not a syntax
930 tree C of type clause such that clause_patterns(C) is a nonempty
931 list.
932 See also: clause/3, clause_patterns/1, function/2, func‐
934 tion_clauses/1.
935 function_clauses(Node::syntaxTree()) -> [syntaxTree()]
937 Returns the list of clause subtrees of a function node.
939 See also: function/2.
941 function_name(Node::syntaxTree()) -> syntaxTree()
943 Returns the name subtree of a function node.
945 See also: function/2.
947 function_type(Type) -> term()
949 Equivalent to function_type(any_arity, Type).
951 function_type(Arguments::any_arity | [syntaxTree()], Return::syntax‐
953 Tree()) -> syntaxTree()
954 Creates an abstract function type. If Arguments is [T1, ...,
956 Tn], then if it occurs within a function specification, the re‐
957 sult represents "(T1, ...Tn) -> Return"; otherwise it represents
958 "fun((T1, ...Tn) -> Return)". If Arguments is any_arity, it rep‐
959 resents "fun((...) -> Return)".
960 Note that the erl_parse representation is identical for "Func‐
962 tionType" and "fun(FunctionType)".
963 See also: function_type_arguments/1, function_type_return/1.
965 function_type_arguments(Node::syntaxTree()) -> any_arity | [syntax‐
967 Tree()]
968 Returns the argument types subtrees of a function_type node. If
970 Node represents "fun((...) -> Return)", any_arity is returned;
971 otherwise, if Node represents "(T1, ...Tn) -> Return" or
972 "fun((T1, ...Tn) -> Return)", [T1, ..., Tn] is returned.
973 See also: function_type/1, function_type/2.
975 function_type_return(Node::syntaxTree()) -> syntaxTree()
977 Returns the return type subtrees of a function_type node.
979 See also: function_type/1, function_type/2.
981 generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
983 Creates an abstract generator. The result represents "Pattern <-
985 Body".
986 See also: binary_comp/2, generator_body/1, generator_pattern/1,
988 list_comp/2.
989 generator_body(Node::syntaxTree()) -> syntaxTree()
991 Returns the body subtree of a generator node.
993 See also: generator/2.
995 generator_pattern(Node::syntaxTree()) -> syntaxTree()
997 Returns the pattern subtree of a generator node.
999 See also: generator/2.
1001 get_ann(Tree::syntaxTree()) -> [term()]
1003 Returns the list of user annotations associated with a syntax
1005 tree node. For a newly created node, this is the empty list. The
1006 annotations may be any terms.
1007 See also: get_attrs/1, set_ann/2.
1009 get_attrs(Tree::syntaxTree()) -> syntaxTreeAttributes()
1011 Returns a representation of the attributes associated with a
1013 syntax tree node. The attributes are all the extra information
1014 that can be attached to a node. Currently, this includes posi‐
1015 tion information, source code comments, and user annotations.
1016 The result of this function cannot be inspected directly; only
1017 attached to another node (see set_attrs/2).
1018 For accessing individual attributes, see get_pos/1, get_ann/1,
1020 get_precomments/1 and get_postcomments/1.
1021 See also: get_ann/1, get_pos/1, get_postcomments/1, get_precom‐
1023 ments/1, set_attrs/2.
1024 get_pos(Tree::syntaxTree()) -> annotation_or_location()
1026 Returns the annotation (see erl_anno(3)) associated with Node.
1028 By default, all new tree nodes have their associated position
1029 information set to the integer zero. Use erl_anno:location/1 or
1030 erl_anno:line/1 to get the position information.
1031 See also: get_attrs/1, set_pos/2.
1033 get_postcomments(Tree::syntaxTree()) -> [syntaxTree()]
1035 Returns the associated post-comments of a node. This is a possi‐
1037 bly empty list of abstract comments, in top-down textual order.
1038 When the code is formatted, post-comments are typically dis‐
1039 played to the right of and/or below the node. For example:
1040 {foo, X, Y} % Post-comment of tuple
1042 If possible, the comment should be moved past any following sep‐
1044 arator characters on the same line, rather than placing the sep‐
1045 arators on the following line. E.g.:
1046 foo([X | Xs], Y) ->
1048 foo(Xs, bar(X)); % Post-comment of 'bar(X)' node
1049 ...
1050 (where the comment is moved past the rightmost ")" and the ";").
1052 See also: comment/2, get_attrs/1, get_precomments/1, set_post‐
1054 comments/2.
1055 get_precomments(Tree::syntaxTree()) -> [syntaxTree()]
1057 Returns the associated pre-comments of a node. This is a possi‐
1059 bly empty list of abstract comments, in top-down textual order.
1060 When the code is formatted, pre-comments are typically displayed
1061 directly above the node. For example:
1062 % Pre-comment of function
1064 foo(X) -> {bar, X}.
1065 If possible, the comment should be moved before any preceding
1067 separator characters on the same line. E.g.:
1068 foo([X | Xs]) ->
1070 % Pre-comment of 'bar(X)' node
1071 [bar(X) | foo(Xs)];
1072 ...
1073 (where the comment is moved before the "[").
1075 See also: comment/2, get_attrs/1, get_postcomments/1, set_pre‐
1077 comments/2.
1078 has_comments(Tree::syntaxTree()) -> boolean()
1080 Yields false if the node has no associated comments, and true
1082 otherwise.
1083 Note: This is equivalent to (get_precomments(Node) == []) and
1085 (get_postcomments(Node) == []), but potentially more efficient.
1086 See also: get_postcomments/1, get_precomments/1, remove_com‐
1088 ments/1.
1089 if_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1091 Creates an abstract if-expression. If Clauses is [C1, ..., Cn],
1093 the result represents "if C1; ...; Cn end". More exactly, if
1094 each Ci represents "() Gi -> Bi", then the result represents "if
1095 G1 -> B1; ...; Gn -> Bn end".
1096 See also: case_expr/2, clause/3, if_expr_clauses/1.
1098 if_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1100 Returns the list of clause subtrees of an if_expr node.
1102 See also: if_expr/1.
1104 implicit_fun(Name::syntaxTree()) -> syntaxTree()
1106 Creates an abstract "implicit fun" expression. The result repre‐
1108 sents "fun Name". Name should represent either F/A or M:F/A
1109 See also: arity_qualifier/2, implicit_fun/2, implicit_fun/3, im‐
1111 plicit_fun_name/1, module_qualifier/2.
1112 implicit_fun(Name::syntaxTree(), Arity::none | syntaxTree()) -> syntax‐
1114 Tree()
1115 Creates an abstract "implicit fun" expression. If Arity is none,
1117 this is equivalent to implicit_fun(Name), otherwise it is equiv‐
1118 alent to implicit_fun(arity_qualifier(Name, Arity)).
1119 (This is a utility function.)
1121 See also: implicit_fun/1, implicit_fun/3.
1123 implicit_fun(Module::none | syntaxTree(), Name::syntaxTree(), Ar‐
1125 ity::syntaxTree()) -> syntaxTree()
1126 Creates an abstract module-qualified "implicit fun" expression.
1128 If Module is none, this is equivalent to implicit_fun(Name, Ar‐
1129 ity), otherwise it is equivalent to implicit_fun(module_quali‐
1130 fier(Module, arity_qualifier(Name, Arity)).
1131 (This is a utility function.)
1133 See also: implicit_fun/1, implicit_fun/2.
1135 implicit_fun_name(Node::syntaxTree()) -> syntaxTree()
1137 Returns the name subtree of an implicit_fun node.
1139 Note: if Node represents "fun N/A" or "fun M:N/A", then the re‐
1141 sult is the subtree representing "N/A" or "M:N/A", respectively.
1142 See also: arity_qualifier/2, implicit_fun/1, module_qualifier/2.
1144 infix_expr(Left::syntaxTree(), Operator::syntaxTree(), Right::syntax‐
1146 Tree()) -> syntaxTree()
1147 Creates an abstract infix operator expression. The result repre‐
1149 sents "Left Operator Right".
1150 See also: infix_expr_left/1, infix_expr_operator/1, in‐
1152 fix_expr_right/1, prefix_expr/2.
1153 infix_expr_left(Node::syntaxTree()) -> syntaxTree()
1155 Returns the left argument subtree of an infix_expr node.
1157 See also: infix_expr/3.
1159 infix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1161 Returns the operator subtree of an infix_expr node.
1163 See also: infix_expr/3.
1165 infix_expr_right(Node::syntaxTree()) -> syntaxTree()
1167 Returns the right argument subtree of an infix_expr node.
1169 See also: infix_expr/3.
1171 integer(Value::integer()) -> syntaxTree()
1173 Creates an abstract integer literal. The lexical representation
1175 is the canonical decimal numeral of Value.
1176 See also: integer_literal/1, integer_value/1, is_integer/2.
1178 integer_literal(Node::syntaxTree()) -> string()
1180 Returns the numeral string represented by an integer node.
1182 See also: integer/1.
1184 integer_range_type(Low::syntaxTree(), High::syntaxTree()) -> syntax‐
1186 Tree()
1187 Creates an abstract range type. The result represents "Low ..
1189 High".
1190 See also: integer_range_type_high/1, integer_range_type_low/1.
1192 integer_range_type_high(Node::syntaxTree()) -> syntaxTree()
1194 Returns the high limit of an integer_range_type node.
1196 See also: integer_range_type/2.
1198 integer_range_type_low(Node::syntaxTree()) -> syntaxTree()
1200 Returns the low limit of an integer_range_type node.
1202 See also: integer_range_type/2.
1204 integer_value(Node::syntaxTree()) -> integer()
1206 Returns the value represented by an integer node.
1208 See also: integer/1.
1210 is_atom(Node::syntaxTree(), Value::atom()) -> boolean()
1212 Returns true if Node has type atom and represents Value, other‐
1214 wise false.
1215 See also: atom/1.
1217 is_char(Node::syntaxTree(), Value::char()) -> boolean()
1219 Returns true if Node has type char and represents Value, other‐
1221 wise false.
1222 See also: char/1.
1224 is_form(Node::syntaxTree()) -> boolean()
1226 Returns true if Node is a syntax tree representing a so-called
1228 "source code form", otherwise false. Forms are the Erlang source
1229 code units which, placed in sequence, constitute an Erlang pro‐
1230 gram. Current form types are:
1231 attribute comment error_marker eof_marker
1233 form_list function warning_marker text
1234 See also: attribute/2, comment/2, eof_marker/0, error_marker/1,
1237 form_list/1, function/2, type/1, warning_marker/1.
1238 is_integer(Node::syntaxTree(), Value::integer()) -> boolean()
1240 Returns true if Node has type integer and represents Value, oth‐
1242 erwise false.
1243 See also: integer/1.
1245 is_leaf(Node::syntaxTree()) -> boolean()
1247 Returns true if Node is a leaf node, otherwise false. The cur‐
1249 rently recognised leaf node types are:
1250 atom char comment eof_marker error_marker
1252 float fun_type integer nil operator string
1253 text underscore variable warning_marker
1254 A node of type map_expr is a leaf node if and only if it has no
1257 argument and no fields. A node of type map_type is a leaf node
1258 if and only if it has no fields (any_size). A node of type tuple
1259 is a leaf node if and only if its arity is zero. A node of type
1260 tuple_type is a leaf node if and only if it has no elements
1261 (any_size).
1262 Note: not all literals are leaf nodes, and vice versa. E.g., tu‐
1264 ples with nonzero arity and nonempty lists may be literals, but
1265 are not leaf nodes. Variables, on the other hand, are leaf nodes
1266 but not literals.
1267 See also: is_literal/1, type/1.
1269 is_list_skeleton(Node::syntaxTree()) -> boolean()
1271 Returns true if Node has type list or nil, otherwise false.
1273 See also: list/2, nil/0.
1275 is_literal(T::syntaxTree()) -> boolean()
1277 Returns true if Node represents a literal term, otherwise false.
1279 This function returns true if and only if the value of con‐
1280 crete(Node) is defined.
1281 See also: abstract/1, concrete/1.
1283 is_proper_list(Node::syntaxTree()) -> boolean()
1285 Returns true if Node represents a proper list, and false other‐
1287 wise. A proper list is a list skeleton either on the form "[]"
1288 or "[E1, ..., En]", or "[... | Tail]" where recursively Tail
1289 also represents a proper list.
1290 Note: Since Node is a syntax tree, the actual run-time values
1292 corresponding to its subtrees may often be partially or com‐
1293 pletely unknown. Thus, if Node represents e.g. "[... | Ns]"
1294 (where Ns is a variable), then the function will return false,
1295 because it is not known whether Ns will be bound to a list at
1296 run-time. If Node instead represents e.g. "[1, 2, 3]" or "[A |
1297 []]", then the function will return true.
1298 See also: list/2.
1300 is_string(Node::syntaxTree(), Value::string()) -> boolean()
1302 Returns true if Node has type string and represents Value, oth‐
1304 erwise false.
1305 See also: string/1.
1307 is_tree(Tree::syntaxTree()) -> boolean()
1309 For special purposes only. Returns true if Tree is an abstract
1311 syntax tree and false otherwise.
1312 Note: this function yields false for all "old-style" erl_parse-
1314 compatible "parse trees".
1315 See also: tree/2.
1317 join_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
1319 Tree()
1320 Appends the comments of Source to the current comments of Tar‐
1322 get.
1323 Note: This is equivalent to add_postcomments(get_postcom‐
1325 ments(Source), add_precomments(get_precomments(Source), Tar‐
1326 get)), but potentially more efficient.
1327 See also: add_postcomments/2, add_precomments/2, comment/2,
1329 get_postcomments/1, get_precomments/1.
1330 list(List::[syntaxTree()]) -> syntaxTree()
1332 Equivalent to list(List, none).
1334 list(Elements::[syntaxTree()], Tail::none | syntaxTree()) -> syntax‐
1336 Tree()
1337 Constructs an abstract list skeleton. The result has type list
1339 or nil. If List is a nonempty list [E1, ..., En], the result has
1340 type list and represents either "[E1, ..., En]", if Tail is
1341 none, or otherwise "[E1, ..., En | Tail]". If List is the empty
1342 list, Tail must be none, and in that case the result has type
1343 nil and represents "[]" (see nil/0).
1344 The difference between lists as semantic objects (built up of
1346 individual "cons" and "nil" terms) and the various syntactic
1347 forms for denoting lists may be bewildering at first. This mod‐
1348 ule provides functions both for exact control of the syntactic
1349 representation as well as for the simple composition and decon‐
1350 struction in terms of cons and head/tail operations.
1351 Note: in list(Elements, none), the "nil" list terminator is im‐
1353 plicit and has no associated information (see get_attrs/1),
1354 while in the seemingly equivalent list(Elements, Tail) when Tail
1355 has type nil, the list terminator subtree Tail may have attached
1356 attributes such as position, comments, and annotations, which
1357 will be preserved in the result.
1358 See also: compact_list/1, cons/2, get_attrs/1, is_list_skele‐
1360 ton/1, is_proper_list/1, list/1, list_elements/1, list_head/1,
1361 list_length/1, list_prefix/1, list_suffix/1, list_tail/1, nil/0,
1362 normalize_list/1.
1363 list_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntaxTree()
1365 Creates an abstract list comprehension. If Body is [E1, ...,
1367 En], the result represents "[Template || E1, ..., En]".
1368 See also: generator/2, list_comp_body/1, list_comp_template/1.
1370 list_comp_body(Node::syntaxTree()) -> [syntaxTree()]
1372 Returns the list of body subtrees of a list_comp node.
1374 See also: list_comp/2.
1376 list_comp_template(Node::syntaxTree()) -> syntaxTree()
1378 Returns the template subtree of a list_comp node.
1380 See also: list_comp/2.
1382 list_elements(Node::syntaxTree()) -> [syntaxTree()]
1384 Returns the list of element subtrees of a list skeleton. Node
1386 must represent a proper list. E.g., if Node represents "[X1, X2
1387 | [X3, X4 | []]", then list_elements(Node) yields the list [X1,
1388 X2, X3, X4].
1389 See also: is_proper_list/1, list/2.
1391 list_head(Node::syntaxTree()) -> syntaxTree()
1393 Returns the head element subtree of a list node. If Node repre‐
1395 sents "[Head ...]", the result will represent "Head".
1396 See also: cons/2, list/2, list_tail/1.
1398 list_length(Node::syntaxTree()) -> non_neg_integer()
1400 Returns the number of element subtrees of a list skeleton. Node
1402 must represent a proper list. E.g., if Node represents "[X1 |
1403 [X2, X3 | [X4, X5, X6]]]", then list_length(Node) returns the
1404 integer 6.
1405 Note: this is equivalent to length(list_elements(Node)), but po‐
1407 tentially more efficient.
1408 See also: is_proper_list/1, list/2, list_elements/1.
1410 list_prefix(Node::syntaxTree()) -> [syntaxTree()]
1412 Returns the prefix element subtrees of a list node. If Node rep‐
1414 resents "[E1, ..., En]" or "[E1, ..., En | Tail]", the returned
1415 value is [E1, ..., En].
1416 See also: list/2.
1418 list_suffix(Node::syntaxTree()) -> none | syntaxTree()
1420 Returns the suffix subtree of a list node, if one exists. If
1422 Node represents "[E1, ..., En | Tail]", the returned value is
1423 Tail, otherwise, i.e., if Node represents "[E1, ..., En]", none
1424 is returned.
1425 Note that even if this function returns some Tail that is not
1427 none, the type of Tail can be nil, if the tail has been given
1428 explicitly, and the list skeleton has not been compacted (see
1429 compact_list/1).
1430 See also: compact_list/1, list/2, nil/0.
1432 list_tail(Node::syntaxTree()) -> syntaxTree()
1434 Returns the tail of a list node. If Node represents a single-el‐
1436 ement list "[E]", then the result has type nil, representing
1437 "[]". If Node represents "[E1, E2 ...]", the result will repre‐
1438 sent "[E2 ...]", and if Node represents "[Head | Tail]", the re‐
1439 sult will represent "Tail".
1440 See also: cons/2, list/2, list_head/1.
1442 macro(Name::syntaxTree()) -> syntaxTree()
1444 Equivalent to macro(Name, none).
1446 macro(Name::syntaxTree(), Arguments::none | [syntaxTree()]) -> syntax‐
1448 Tree()
1449 Creates an abstract macro application. If Arguments is none, the
1451 result represents "?Name", otherwise, if Arguments is [A1, ...,
1452 An], the result represents "?Name(A1, ..., An)".
1453 Notes: if Arguments is the empty list, the result will thus rep‐
1455 resent "?Name()", including a pair of matching parentheses.
1456 The only syntactical limitation imposed by the preprocessor on
1458 the arguments to a macro application (viewed as sequences of to‐
1459 kens) is that they must be balanced with respect to parentheses,
1460 brackets, begin ... end, case ... end, etc. The text node type
1461 can be used to represent arguments which are not regular Erlang
1462 constructs.
1463 See also: macro/1, macro_arguments/1, macro_name/1, text/1.
1465 macro_arguments(Node::syntaxTree()) -> none | [syntaxTree()]
1467 Returns the list of argument subtrees of a macro node, if any.
1469 If Node represents "?Name", none is returned. Otherwise, if Node
1470 represents "?Name(A1, ..., An)", [A1, ..., An] is returned.
1471 See also: macro/2.
1473 macro_name(Node::syntaxTree()) -> syntaxTree()
1475 Returns the name subtree of a macro node.
1477 See also: macro/2.
1479 make_tree(X1::atom(), X2::[[syntaxTree()]]) -> syntaxTree()
1481 Creates a syntax tree with the given type and subtrees. Type
1483 must be a node type name (see type/1) that does not denote a
1484 leaf node type (see is_leaf/1). Groups must be a nonempty list
1485 of groups of syntax trees, representing the subtrees of a node
1486 of the given type, in left-to-right order as they would occur in
1487 the printed program text, grouped by category as done by sub‐
1488 trees/1.
1489 The result of copy_attrs(Node, make_tree(type(Node), sub‐
1491 trees(Node))) (see update_tree/2) represents the same source
1492 code text as the original Node, assuming that subtrees(Node)
1493 yields a nonempty list. However, it does not necessarily have
1494 the same data representation as Node.
1495 See also: copy_attrs/2, is_leaf/1, subtrees/1, type/1, up‐
1497 date_tree/2.
1498 map_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntaxTree()
1500 Creates an abstract map comprehension. If Body is [E1, ..., En],
1502 the result represents "#{Template || E1, ..., En}".
1503 See also: generator/2, map_comp_body/1, map_comp_template/1.
1505 map_comp_body(Node::syntaxTree()) -> [syntaxTree()]
1507 Returns the list of body subtrees of a map_comp node.
1509 See also: map_comp/2.
1511 map_comp_template(Node::syntaxTree()) -> syntaxTree()
1513 Returns the template subtree of a map_comp node.
1515 See also: map_comp/2.
1517 map_expr(Fields::[syntaxTree()]) -> syntaxTree()
1519 Equivalent to map_expr(none, Fields).
1521 map_expr(Argument::none | syntaxTree(), Fields::[syntaxTree()]) -> syn‐
1523 taxTree()
1524 Creates an abstract map expression. If Fields is [F1, ..., Fn],
1526 then if Argument is none, the result represents "#{F1, ...,
1527 Fn}", otherwise it represents "Argument#{F1, ..., Fn}".
1528 See also: map_expr/1, map_expr_argument/1, map_expr_fields/1,
1530 map_field_assoc/2, map_field_exact/2.
1531 map_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1533 Returns the argument subtree of a map_expr node, if any. If Node
1535 represents "#{...}", none is returned. Otherwise, if Node repre‐
1536 sents "Argument#{...}", Argument is returned.
1537 See also: map_expr/2.
1539 map_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1541 Returns the list of field subtrees of a map_expr node.
1543 See also: map_expr/2.
1545 map_field_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1547 Tree()
1548 Creates an abstract map assoc field. The result represents "Name
1550 => Value".
1551 See also: map_expr/2, map_field_assoc_name/1, map_field_as‐
1553 soc_value/1.
1554 map_field_assoc_name(Node::syntaxTree()) -> syntaxTree()
1556 Returns the name subtree of a map_field_assoc node.
1558 See also: map_field_assoc/2.
1560 map_field_assoc_value(Node::syntaxTree()) -> syntaxTree()
1562 Returns the value subtree of a map_field_assoc node.
1564 See also: map_field_assoc/2.
1566 map_field_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1568 Tree()
1569 Creates an abstract map exact field. The result represents "Name
1571 := Value".
1572 See also: map_expr/2, map_field_exact_name/1, map_field_ex‐
1574 act_value/1.
1575 map_field_exact_name(Node::syntaxTree()) -> syntaxTree()
1577 Returns the name subtree of a map_field_exact node.
1579 See also: map_field_exact/2.
1581 map_field_exact_value(Node::syntaxTree()) -> syntaxTree()
1583 Returns the value subtree of a map_field_exact node.
1585 See also: map_field_exact/2.
1587 map_generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntax‐
1589 Tree()
1590 Creates an abstract map_generator. The result represents "Pat‐
1592 tern <- Body".
1593 See also: list_comp/2, map_comp/2, map_generator_body/1,
1595 map_generator_pattern/1.
1596 map_generator_body(Node::syntaxTree()) -> syntaxTree()
1598 Returns the body subtree of a generator node.
1600 See also: map_generator/2.
1602 map_generator_pattern(Node::syntaxTree()) -> syntaxTree()
1604 Returns the pattern subtree of a generator node.
1606 See also: map_generator/2.
1608 map_type() -> term()
1610 Equivalent to map_type(any_size).
1612 map_type(Fields::any_size | [syntaxTree()]) -> syntaxTree()
1614 Creates an abstract type map. If Fields is [F1, ..., Fn], the
1616 result represents "#{F1, ..., Fn}"; otherwise, if Fields is
1617 any_size, it represents "map()".
1618 See also: map_type_fields/1.
1620 map_type_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1622 Creates an abstract map type assoc field. The result represents
1624 "Name => Value".
1625 See also: map_type/1, map_type_assoc_name/1, map_type_as‐
1627 soc_value/1.
1628 map_type_assoc_name(Node::syntaxTree()) -> syntaxTree()
1630 Returns the name subtree of a map_type_assoc node.
1632 See also: map_type_assoc/2.
1634 map_type_assoc_value(Node::syntaxTree()) -> syntaxTree()
1636 Returns the value subtree of a map_type_assoc node.
1638 See also: map_type_assoc/2.
1640 map_type_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1642 Creates an abstract map type exact field. The result represents
1644 "Name := Value".
1645 See also: map_type/1, map_type_exact_name/1, map_type_ex‐
1647 act_value/1.
1648 map_type_exact_name(Node::syntaxTree()) -> syntaxTree()
1650 Returns the name subtree of a map_type_exact node.
1652 See also: map_type_exact/2.
1654 map_type_exact_value(Node::syntaxTree()) -> syntaxTree()
1656 Returns the value subtree of a map_type_exact node.
1658 See also: map_type_exact/2.
1660 map_type_fields(Node::syntaxTree()) -> any_size | [syntaxTree()]
1662 Returns the list of field subtrees of a map_type node. If Node
1664 represents "map()", any_size is returned; otherwise, if Node
1665 represents "#{F1, ..., Fn}", [F1, ..., Fn] is returned.
1666 See also: map_type/0, map_type/1.
1668 match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
1670 Creates an abstract match-expression. The result represents
1672 "Pattern = Body".
1673 See also: match_expr_body/1, match_expr_pattern/1.
1675 match_expr_body(Node::syntaxTree()) -> syntaxTree()
1677 Returns the body subtree of a match_expr node.
1679 See also: match_expr/2.
1681 match_expr_pattern(Node::syntaxTree()) -> syntaxTree()
1683 Returns the pattern subtree of a match_expr node.
1685 See also: match_expr/2.
1687 maybe_expr(Body::[syntaxTree()]) -> syntaxTree()
1689 Equivalent to maybe_expr(Body, none).
1691 maybe_expr(Body::[syntaxTree()], OptionalElse::none | syntaxTree()) ->
1693 syntaxTree()
1694 Creates an abstract maybe-expression. If Body is [B1, ..., Bn],
1696 and OptionalElse is none, the result represents "maybe B1, ...,
1697 Bn end". If Body is [B1, ..., Bn], and OptionalElse reprsents an
1698 else_expr node with clauses [C1, ..., Cn], the result represents
1699 "maybe B1, ..., Bn else C1; ..., Cn end".
1700 See clause for documentation on erl_parse clauses.
1702 See also: maybe_expr_body/1, maybe_expr_else/1.
1704 maybe_expr_body(Node::syntaxTree()) -> [syntaxTree()]
1706 Returns the list of body subtrees of a maybe_expr node.
1708 See also: maybe_expr/2.
1710 maybe_expr_else(Node::syntaxTree()) -> none | syntaxTree()
1712 Returns the else subtree of a maybe_expr node.
1714 See also: maybe_expr/2.
1716 maybe_match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> syntax‐
1718 Tree()
1719 Creates an abstract maybe-expression, as used in maybe blocks.
1721 The result represents "Pattern ?= Body".
1722 See also: maybe_expr/2, maybe_match_expr_body/1,
1724 maybe_match_expr_pattern/1.
1725 maybe_match_expr_body(Node::syntaxTree()) -> syntaxTree()
1727 Returns the body subtree of a maybe_expr node.
1729 See also: maybe_match_expr/2.
1731 maybe_match_expr_pattern(Node::syntaxTree()) -> syntaxTree()
1733 Returns the pattern subtree of a maybe_expr node.
1735 See also: maybe_match_expr/2.
1737 meta(T::syntaxTree()) -> syntaxTree()
1739 Creates a meta-representation of a syntax tree. The result rep‐
1741 resents an Erlang expression "MetaTree" which, if evaluated,
1742 will yield a new syntax tree representing the same source code
1743 text as Tree (although the actual data representation may be
1744 different). The expression represented by MetaTree is implemen‐
1745 tation independent with regard to the data structures used by
1746 the abstract syntax tree implementation. Comments attached to
1747 nodes of Tree will be preserved, but other attributes are lost.
1748 Any node in Tree whose node type is variable (see type/1), and
1750 whose list of annotations (see get_ann/1) contains the atom
1751 meta_var, will remain unchanged in the resulting tree, except
1752 that exactly one occurrence of meta_var is removed from its an‐
1753 notation list.
1754 The main use of the function meta/1 is to transform a data
1756 structure Tree, which represents a piece of program code, into a
1757 form that is representation independent when printed. E.g., sup‐
1758 pose Tree represents a variable named "V". Then (assuming a
1759 function print/1 for printing syntax trees), evaluating
1760 print(abstract(Tree)) - simply using abstract/1 to map the ac‐
1761 tual data structure onto a syntax tree representation - would
1762 output a string that might look something like "{tree, variable,
1763 ..., "V", ...}", which is obviously dependent on the implementa‐
1764 tion of the abstract syntax trees. This could e.g. be useful for
1765 caching a syntax tree in a file. However, in some situations
1766 like in a program generator generator (with two "generator"), it
1767 may be unacceptable. Using print(meta(Tree)) instead would out‐
1768 put a representation independent syntax tree generating expres‐
1769 sion; in the above case, something like "erl_syntax:vari‐
1770 able("V")".
1771 See also: abstract/1, get_ann/1, type/1.
1773 module_qualifier(Module::syntaxTree(), Body::syntaxTree()) -> syntax‐
1775 Tree()
1776 Creates an abstract module qualifier. The result represents
1778 "Module:Body".
1779 See also: module_qualifier_argument/1, module_qualifier_body/1.
1781 module_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
1783 Returns the argument (the module) subtree of a module_qualifier
1785 node.
1786 See also: module_qualifier/2.
1788 module_qualifier_body(Node::syntaxTree()) -> syntaxTree()
1790 Returns the body subtree of a module_qualifier node.
1792 See also: module_qualifier/2.
1794 named_fun_expr(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
1796 Tree()
1797 Creates an abstract named fun-expression. If Clauses is [C1,
1799 ..., Cn], the result represents "fun Name C1; ...; Name Cn end".
1800 More exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi",
1801 then the result represents "fun Name(P11, ..., P1m) G1 -> B1;
1802 ...; Name(Pn1, ..., Pnm) Gn -> Bn end".
1803 See also: named_fun_expr_arity/1, named_fun_expr_clauses/1,
1805 named_fun_expr_name/1.
1806 named_fun_expr_arity(Node::syntaxTree()) -> arity()
1808 Returns the arity of a named_fun_expr node. The result is the
1810 number of parameter patterns in the first clause of the named
1811 fun-expression; subsequent clauses are ignored.
1812 An exception is thrown if named_fun_expr_clauses(Node) returns
1814 an empty list, or if the first element of that list is not a
1815 syntax tree C of type clause such that clause_patterns(C) is a
1816 nonempty list.
1817 See also: clause/3, clause_patterns/1, named_fun_expr/2,
1819 named_fun_expr_clauses/1.
1820 named_fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1822 Returns the list of clause subtrees of a named_fun_expr node.
1824 See also: named_fun_expr/2.
1826 named_fun_expr_name(Node::syntaxTree()) -> syntaxTree()
1828 Returns the name subtree of a named_fun_expr node.
1830 See also: named_fun_expr/2.
1832 nil() -> syntaxTree()
1834 Creates an abstract empty list. The result represents "[]". The
1836 empty list is traditionally called "nil".
1837 See also: is_list_skeleton/1, list/2.
1839 normalize_list(Node::syntaxTree()) -> syntaxTree()
1841 Expands an abstract list skeleton to its most explicit form. If
1843 Node represents "[E1, ..., En | Tail]", the result represents
1844 "[E1 | ... [En | Tail1] ... ]", where Tail1 is the result of
1845 normalize_list(Tail). If Node represents "[E1, ..., En]", the
1846 result simply represents "[E1 | ... [En | []] ... ]". If Node
1847 does not represent a list skeleton, Node itself is returned.
1848 See also: compact_list/1, list/2.
1850 operator(Name::atom() | string()) -> syntaxTree()
1852 Creates an abstract operator. The name of the operator is the
1854 character sequence represented by Name. This is analogous to the
1855 print name of an atom, but an operator is never written within
1856 single-quotes; e.g., the result of operator('++') represents
1857 "++" rather than "'++'".
1858 See also: atom/1, operator_literal/1, operator_name/1.
1860 operator_literal(Node::syntaxTree()) -> string()
1862 Returns the literal string represented by an operator node. This
1864 is simply the operator name as a string.
1865 See also: operator/1.
1867 operator_name(Node::syntaxTree()) -> atom()
1869 Returns the name of an operator node. Note that the name is re‐
1871 turned as an atom.
1872 See also: operator/1.
1874 parentheses(Expr::syntaxTree()) -> syntaxTree()
1876 Creates an abstract parenthesised expression. The result repre‐
1878 sents "(Body)", independently of the context.
1879 See also: parentheses_body/1.
1881 parentheses_body(Node::syntaxTree()) -> syntaxTree()
1883 Returns the body subtree of a parentheses node.
1885 See also: parentheses/1.
1887 prefix_expr(Operator::syntaxTree(), Argument::syntaxTree()) -> syntax‐
1889 Tree()
1890 Creates an abstract prefix operator expression. The result rep‐
1892 resents "Operator Argument".
1893 See also: infix_expr/3, prefix_expr_argument/1, prefix_expr_op‐
1895 erator/1.
1896 prefix_expr_argument(Node::syntaxTree()) -> syntaxTree()
1898 Returns the argument subtree of a prefix_expr node.
1900 See also: prefix_expr/2.
1902 prefix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1904 Returns the operator subtree of a prefix_expr node.
1906 See also: prefix_expr/2.
1908 receive_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1910 Equivalent to receive_expr(Clauses, none, []).
1912 receive_expr(Clauses::[syntaxTree()], Timeout::none | syntaxTree(), Ac‐
1914 tion::[syntaxTree()]) -> syntaxTree()
1915 Creates an abstract receive-expression. If Timeout is none, the
1917 result represents "receive C1; ...; Cn end" (the Action argument
1918 is ignored). Otherwise, if Clauses is [C1, ..., Cn] and Action
1919 is [A1, ..., Am], the result represents "receive C1; ...; Cn af‐
1920 ter Timeout -> A1, ..., Am end". More exactly, if each Ci repre‐
1921 sents "(Pi) Gi -> Bi", then the result represents "receive P1 G1
1922 -> B1; ...; Pn Gn -> Bn ... end".
1923 Note that in Erlang, a receive-expression must have at least one
1925 clause if no timeout part is specified.
1926 See also: case_expr/2, clause/3, receive_expr/1, re‐
1928 ceive_expr_action/1, receive_expr_clauses/1, receive_expr_time‐
1929 out/1.
1930 receive_expr_action(Node::syntaxTree()) -> [syntaxTree()]
1932 Returns the list of action body subtrees of a receive_expr node.
1934 If Node represents "receive C1; ...; Cn end", this is the empty
1935 list.
1936 See also: receive_expr/3.
1938 receive_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1940 Returns the list of clause subtrees of a receive_expr node.
1942 See also: receive_expr/3.
1944 receive_expr_timeout(Node::syntaxTree()) -> none | syntaxTree()
1946 Returns the timeout subtree of a receive_expr node, if any. If
1948 Node represents "receive C1; ...; Cn end", none is returned.
1949 Otherwise, if Node represents "receive C1; ...; Cn after Timeout
1950 -> ... end", Timeout is returned.
1951 See also: receive_expr/3.
1953 record_access(Argument::syntaxTree(), Type::syntaxTree(), Field::syn‐
1955 taxTree()) -> syntaxTree()
1956 Creates an abstract record field access expression. The result
1958 represents "Argument#Type.Field".
1959 See also: record_access_argument/1, record_access_field/1,
1961 record_access_type/1, record_expr/3.
1962 record_access_argument(Node::syntaxTree()) -> syntaxTree()
1964 Returns the argument subtree of a record_access node.
1966 See also: record_access/3.
1968 record_access_field(Node::syntaxTree()) -> syntaxTree()
1970 Returns the field subtree of a record_access node.
1972 See also: record_access/3.
1974 record_access_type(Node::syntaxTree()) -> syntaxTree()
1976 Returns the type subtree of a record_access node.
1978 See also: record_access/3.
1980 record_expr(Type::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1982 Equivalent to record_expr(none, Type, Fields).
1984 record_expr(Argument::none | syntaxTree(), Type::syntaxTree(),
1986 Fields::[syntaxTree()]) -> syntaxTree()
1987 Creates an abstract record expression. If Fields is [F1, ...,
1989 Fn], then if Argument is none, the result represents "#Type{F1,
1990 ..., Fn}", otherwise it represents "Argument#Type{F1, ..., Fn}".
1991 See also: record_access/3, record_expr/2, record_expr_argu‐
1993 ment/1, record_expr_fields/1, record_expr_type/1,
1994 record_field/2, record_index_expr/2.
1995 record_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1997 Returns the argument subtree of a record_expr node, if any. If
1999 Node represents "#Type{...}", none is returned. Otherwise, if
2000 Node represents "Argument#Type{...}", Argument is returned.
2001 See also: record_expr/3.
2003 record_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
2005 Returns the list of field subtrees of a record_expr node.
2007 See also: record_expr/3.
2009 record_expr_type(Node::syntaxTree()) -> syntaxTree()
2011 Returns the type subtree of a record_expr node.
2013 See also: record_expr/3.
2015 record_field(Name::syntaxTree()) -> syntaxTree()
2017 Equivalent to record_field(Name, none).
2019 record_field(Name::syntaxTree(), Value::none | syntaxTree()) -> syntax‐
2021 Tree()
2022 Creates an abstract record field specification. If Value is
2024 none, the result represents simply "Name", otherwise it repre‐
2025 sents "Name = Value".
2026 See also: record_expr/3, record_field_name/1,
2028 record_field_value/1.
2029 record_field_name(Node::syntaxTree()) -> syntaxTree()
2031 Returns the name subtree of a record_field node.
2033 See also: record_field/2.
2035 record_field_value(Node::syntaxTree()) -> none | syntaxTree()
2037 Returns the value subtree of a record_field node, if any. If
2039 Node represents "Name", none is returned. Otherwise, if Node
2040 represents "Name = Value", Value is returned.
2041 See also: record_field/2.
2043 record_index_expr(Type::syntaxTree(), Field::syntaxTree()) -> syntax‐
2045 Tree()
2046 Creates an abstract record field index expression. The result
2048 represents "#Type.Field".
2049 (Note: the function name record_index/2 is reserved by the Er‐
2051 lang compiler, which is why that name could not be used for this
2052 constructor.)
2053 See also: record_expr/3, record_index_expr_field/1, record_in‐
2055 dex_expr_type/1.
2056 record_index_expr_field(Node::syntaxTree()) -> syntaxTree()
2058 Returns the field subtree of a record_index_expr node.
2060 See also: record_index_expr/2.
2062 record_index_expr_type(Node::syntaxTree()) -> syntaxTree()
2064 Returns the type subtree of a record_index_expr node.
2066 See also: record_index_expr/2.
2068 record_type(Name::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
2070 Creates an abstract record type. If Fields is [F1, ..., Fn], the
2072 result represents "#Name{F1, ..., Fn}".
2073 See also: record_type_fields/1, record_type_name/1.
2075 record_type_field(Name::syntaxTree(), Type::syntaxTree()) -> syntax‐
2077 Tree()
2078 Creates an abstract record type field. The result represents
2080 "Name :: Type".
2081 See also: record_type_field_name/1, record_type_field_type/1.
2083 record_type_field_name(Node::syntaxTree()) -> syntaxTree()
2085 Returns the name subtree of a record_type_field node.
2087 See also: record_type_field/2.
2089 record_type_field_type(Node::syntaxTree()) -> syntaxTree()
2091 Returns the type subtree of a record_type_field node.
2093 See also: record_type_field/2.
2095 record_type_fields(Node::syntaxTree()) -> [syntaxTree()]
2097 Returns the fields subtree of a record_type node.
2099 See also: record_type/2.
2101 record_type_name(Node::syntaxTree()) -> syntaxTree()
2103 Returns the name subtree of a record_type node.
2105 See also: record_type/2.
2107 remove_comments(Node::syntaxTree()) -> syntaxTree()
2109 Clears the associated comments of Node.
2111 Note: This is equivalent to set_precomments(set_postcom‐
2113 ments(Node, []), []), but potentially more efficient.
2114 See also: set_postcomments/2, set_precomments/2.
2116 revert(Node::syntaxTree()) -> syntaxTree()
2118 Returns an erl_parse-compatible representation of a syntax tree,
2120 if possible. If Tree represents a well-formed Erlang program or
2121 expression, the conversion should work without problems. Typi‐
2122 cally, is_tree/1 yields true if conversion failed (i.e., the re‐
2123 sult is still an abstract syntax tree), and false otherwise.
2124 The is_tree/1 test is not completely foolproof. For a few spe‐
2126 cial node types (e.g. arity_qualifier), if such a node occurs in
2127 a context where it is not expected, it will be left unchanged as
2128 a non-reverted subtree of the result. This can only happen if
2129 Tree does not actually represent legal Erlang code.
2130 See also: erl_parse(3), revert_forms/1.
2132 revert_forms(Forms::forms()) -> [erl_parse()]
2134 Reverts a sequence of Erlang source code forms. The sequence can
2136 be given either as a form_list syntax tree (possibly nested), or
2137 as a list of "program form" syntax trees. If successful, the
2138 corresponding flat list of erl_parse-compatible syntax trees is
2139 returned (see revert/1). If some program form could not be re‐
2140 verted, {error, Form} is thrown. Standalone comments in the form
2141 sequence are discarded.
2142 See also: form_list/1, is_form/1, revert/1.
2144 set_ann(Node::syntaxTree(), As::[term()]) -> syntaxTree()
2146 Sets the list of user annotations of Node to Annotations.
2148 See also: add_ann/2, copy_ann/2, get_ann/1.
2150 set_attrs(Node::syntaxTree(), Attr::syntaxTreeAttributes()) -> syntax‐
2152 Tree()
2153 Sets the attributes of Node to Attributes.
2155 See also: copy_attrs/2, get_attrs/1.
2157 set_pos(Node::syntaxTree(), Pos::annotation_or_location()) -> syntax‐
2159 Tree()
2160 Sets the position information of Node to Pos.
2162 See also: copy_pos/2, get_pos/1.
2164 set_postcomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntax‐
2166 Tree()
2167 Sets the post-comments of Node to Comments. Comments should be a
2169 possibly empty list of abstract comments, in top-down textual
2170 order
2171 See also: add_postcomments/2, comment/2, copy_comments/2,
2173 get_postcomments/1, join_comments/2, remove_comments/1, set_pre‐
2174 comments/2.
2175 set_precomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntaxTree()
2177 Sets the pre-comments of Node to Comments. Comments should be a
2179 possibly empty list of abstract comments, in top-down textual
2180 order.
2181 See also: add_precomments/2, comment/2, copy_comments/2,
2183 get_precomments/1, join_comments/2, remove_comments/1, set_post‐
2184 comments/2.
2185 size_qualifier(Body::syntaxTree(), Size::syntaxTree()) -> syntaxTree()
2187 Creates an abstract size qualifier. The result represents
2189 "Body:Size".
2190 See also: size_qualifier_argument/1, size_qualifier_body/1.
2192 size_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
2194 Returns the argument subtree (the size) of a size_qualifier
2196 node.
2197 See also: size_qualifier/2.
2199 size_qualifier_body(Node::syntaxTree()) -> syntaxTree()
2201 Returns the body subtree of a size_qualifier node.
2203 See also: size_qualifier/2.
2205 string(String::string()) -> syntaxTree()
2207 Creates an abstract string literal. The result represents "Text"
2209 (including the surrounding double-quotes), where Text corre‐
2210 sponds to the sequence of characters in Value, but not repre‐
2211 senting a specific string literal.
2212 For example, the result of string("x\ny") represents any and all
2214 of "x\ny", "x\12y", "x\012y" and "x\^Jy"; see char/1.
2215 See also: char/1, is_string/2, string_literal/1, string_lit‐
2217 eral/2, string_value/1.
2218 string_literal(Node::syntaxTree()) -> nonempty_string()
2220 Returns the literal string represented by a string node. This
2222 includes surrounding double-quote characters. Characters beyond
2223 255 will be escaped.
2224 See also: string/1.
2226 string_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
2228 Returns the literal string represented by a string node. This
2230 includes surrounding double-quote characters. Depending on the
2231 encoding characters beyond 255 will be escaped (latin1) or
2232 copied as is (utf8).
2233 See also: string/1.
2235 string_value(Node::syntaxTree()) -> string()
2237 Returns the value represented by a string node.
2239 See also: string/1.
2241 subtrees(T::syntaxTree()) -> [[syntaxTree()]]
2243 Returns the grouped list of all subtrees of a syntax tree. If
2245 Node is a leaf node (see is_leaf/1), this is the empty list,
2246 otherwise the result is always a nonempty list, containing the
2247 lists of subtrees of Node, in left-to-right order as they occur
2248 in the printed program text, and grouped by category. Often,
2249 each group contains only a single subtree.
2250 Depending on the type of Node, the size of some groups may be
2252 variable (e.g., the group consisting of all the elements of a
2253 tuple), while others always contain the same number of elements
2254 - usually exactly one (e.g., the group containing the argument
2255 expression of a case-expression). Note, however, that the exact
2256 structure of the returned list (for a given node type) should in
2257 general not be depended upon, since it might be subject to
2258 change without notice.
2259 The function subtrees/1 and the constructor functions
2261 make_tree/2 and update_tree/2 can be a great help if one wants
2262 to traverse a syntax tree, visiting all its subtrees, but treat
2263 nodes of the tree in a uniform way in most or all cases. Using
2264 these functions makes this simple, and also assures that your
2265 code is not overly sensitive to extensions of the syntax tree
2266 data type, because any node types not explicitly handled by your
2267 code can be left to a default case.
2268 For example:
2270 postorder(F, Tree) ->
2272 F(case subtrees(Tree) of
2273 [] -> Tree;
2274 List -> update_tree(Tree,
2275 [[postorder(F, Subtree)
2276 || Subtree <- Group]
2277 || Group <- List])
2278 end).
2279 maps the function F on Tree and all its subtrees, doing a post-
2281 order traversal of the syntax tree. (Note the use of up‐
2282 date_tree/2 to preserve node attributes.) For a simple function
2283 like:
2284 f(Node) ->
2286 case type(Node) of
2287 atom -> atom("a_" ++ atom_name(Node));
2288 _ -> Node
2289 end.
2290 the call postorder(fun f/1, Tree) will yield a new representa‐
2292 tion of Tree in which all atom names have been extended with the
2293 prefix "a_", but nothing else (including comments, annotations
2294 and line numbers) has been changed.
2295 See also: copy_attrs/2, is_leaf/1, make_tree/2, type/1.
2297 text(String::string()) -> syntaxTree()
2299 Creates an abstract piece of source code text. The result repre‐
2301 sents exactly the sequence of characters in String. This is use‐
2302 ful in cases when one wants full control of the resulting out‐
2303 put, e.g., for the appearance of floating-point numbers or macro
2304 definitions.
2305 See also: text_string/1.
2307 text_string(Node::syntaxTree()) -> string()
2309 Returns the character sequence represented by a text node.
2311 See also: text/1.
2313 tree(Type::atom()) -> tree()
2315 Equivalent to tree(Type, []).
2317 tree(Type::atom(), Data::term()) -> tree()
2319 For special purposes only. Creates an abstract syntax tree node
2321 with type tag Type and associated data Data.
2322 This function and the related is_tree/1 and data/1 provide a
2324 uniform way to extend the set of erl_parse node types. The asso‐
2325 ciated data is any term, whose format may depend on the type
2326 tag.
2327 Notes:
2329 * Any nodes created outside of this module must have type tags
2331 distinct from those currently defined by this module; see
2332 type/1 for a complete list.
2333 * The type tag of a syntax tree node may also be used as a
2335 primary tag by the erl_parse representation; in that case,
2336 the selector functions for that node type must handle both
2337 the abstract syntax tree and the erl_parse form. The func‐
2338 tion type(T) should return the correct type tag regardless
2339 of the representation of T, so that the user sees no differ‐
2340 ence between erl_syntax and erl_parse nodes.
2341 See also: data/1, is_tree/1, type/1.
2343 try_after_expr(Body::[syntaxTree()], After::[syntaxTree()]) -> syntax‐
2345 Tree()
2346 Equivalent to try_expr(Body, [], [], After).
2348 try_expr(Body::[syntaxTree()], Handlers::[syntaxTree()]) -> syntax‐
2350 Tree()
2351 Equivalent to try_expr(Body, [], Handlers).
2353 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2355 taxTree()]) -> syntaxTree()
2356 Equivalent to try_expr(Body, Clauses, Handlers, []).
2358 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2360 taxTree()], After::[syntaxTree()]) -> syntaxTree()
2361 Creates an abstract try-expression. If Body is [B1, ..., Bn],
2363 Clauses is [C1, ..., Cj], Handlers is [H1, ..., Hk], and After
2364 is [A1, ..., Am], the result represents "try B1, ..., Bn of C1;
2365 ...; Cj catch H1; ...; Hk after A1, ..., Am end". More exactly,
2366 if each Ci represents "(CPi) CGi -> CBi", and each Hi represents
2367 "(HPi) HGi -> HBi", then the result represents "try B1, ..., Bn
2368 of CP1 CG1 -> CB1; ...; CPj CGj -> CBj catch HP1 HG1 -> HB1;
2369 ...; HPk HGk -> HBk after A1, ..., Am end"; see case_expr/2. If
2370 Clauses is the empty list, the of ... section is left out. If
2371 After is the empty list, the after ... section is left out. If
2372 Handlers is the empty list, and After is nonempty, the catch ...
2373 section is left out.
2374 See also: case_expr/2, class_qualifier/2, clause/3, try_af‐
2376 ter_expr/2, try_expr/2, try_expr/3, try_expr_after/1,
2377 try_expr_body/1, try_expr_clauses/1, try_expr_handlers/1.
2378 try_expr_after(Node::syntaxTree()) -> [syntaxTree()]
2380 Returns the list of "after" subtrees of a try_expr node.
2382 See also: try_expr/4.
2384 try_expr_body(Node::syntaxTree()) -> [syntaxTree()]
2386 Returns the list of body subtrees of a try_expr node.
2388 See also: try_expr/4.
2390 try_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
2392 Returns the list of case-clause subtrees of a try_expr node. If
2394 Node represents "try Body catch H1; ...; Hn end", the result is
2395 the empty list.
2396 See also: try_expr/4.
2398 try_expr_handlers(Node::syntaxTree()) -> [syntaxTree()]
2400 Returns the list of handler-clause subtrees of a try_expr node.
2402 See also: try_expr/4.
2404 tuple(List::[syntaxTree()]) -> syntaxTree()
2406 Creates an abstract tuple. If Elements is [X1, ..., Xn], the re‐
2408 sult represents "{X1, ..., Xn}".
2409 Note: The Erlang language has distinct 1-tuples, i.e., {X} is
2411 always distinct from X itself.
2412 See also: tuple_elements/1, tuple_size/1.
2414 tuple_elements(Node::syntaxTree()) -> [syntaxTree()]
2416 Returns the list of element subtrees of a tuple node.
2418 See also: tuple/1.
2420 tuple_size(Node::syntaxTree()) -> non_neg_integer()
2422 Returns the number of elements of a tuple node.
2424 Note: this is equivalent to length(tuple_elements(Node)), but
2426 potentially more efficient.
2427 See also: tuple/1, tuple_elements/1.
2429 tuple_type() -> term()
2431 Equivalent to tuple_type(any_size).
2433 tuple_type(Elements::any_size | [syntaxTree()]) -> syntaxTree()
2435 Creates an abstract type tuple. If Elements is [T1, ..., Tn],
2437 the result represents "{T1, ..., Tn}"; otherwise, if Elements is
2438 any_size, it represents "tuple()".
2439 See also: tuple_type_elements/1.
2441 tuple_type_elements(Node::syntaxTree()) -> any_size | [syntaxTree()]
2443 Returns the list of type element subtrees of a tuple_type node.
2445 If Node represents "tuple()", any_size is returned; otherwise,
2446 if Node represents "{T1, ..., Tn}", [T1, ..., Tn] is returned.
2447 See also: tuple_type/0, tuple_type/1.
2449 type(Tree::syntaxTree()) -> atom()
2451 Returns the type tag of Node. If Node does not represent a syn‐
2453 tax tree, evaluation fails with reason badarg. Node types cur‐
2454 rently defined by this module are:
2455 application annotated_type arity_qualifier atom
2457 attribute binary binary_field bitstring_type
2458 block_expr case_expr catch_expr char
2459 class_qualifier clause comment conjunction
2460 constrained_function_type constraint disjunction
2461 else_expr eof_marker error_marker
2462 float form_list fun_expr fun_type function function_type genera‐
2463 tor
2464 if_expr implicit_fun infix_expr integer
2465 integer_range_type list list_comp macro
2466 map_expr map_field_assoc map_field_exact map_type
2467 map_type_assoc map_type_exact match_expr
2468 maybe_expr maybe_match_expr module_qualifier
2469 named_fun_expr nil operator parentheses
2470 prefix_expr receive_expr record_access record_expr
2471 record_field record_index_expr record_type record_type_field
2472 size_qualifier string text try_expr
2473 tuple tuple_type typed_record_field type_application
2474 type_union underscore user_type_application variable
2475 warning_marker
2476 The user may (for special purposes) create additional nodes with
2479 other type tags, using the tree/2 function.
2480 Note: The primary constructor functions for a node type should
2482 always have the same name as the node type itself.
2483 See also: annotated_type/2, application/3, arity_qualifier/2,
2485 atom/1, attribute/2, binary/1, binary_field/2, bitstring_type/2,
2486 block_expr/1, case_expr/2, catch_expr/1, char/1, class_quali‐
2487 fier/2, clause/3, comment/2, conjunction/1, constrained_func‐
2488 tion_type/2, constraint/2, disjunction/1, else_expr/1,
2489 eof_marker/0, error_marker/1, float/1, form_list/1, fun_expr/1,
2490 fun_type/0, function/2, function_type/1, function_type/2, gener‐
2491 ator/2, if_expr/1, implicit_fun/2, infix_expr/3, integer/1, in‐
2492 teger_range_type/2, list/2, list_comp/2, macro/2, map_expr/2,
2493 map_field_assoc/2, map_field_exact/2, map_type/0, map_type/1,
2494 map_type_assoc/2, map_type_exact/2, match_expr/2, maybe_expr/1,
2495 maybe_expr/2, maybe_match_expr/2, module_qualifier/2,
2496 named_fun_expr/2, nil/0, operator/1, parentheses/1, pre‐
2497 fix_expr/2, receive_expr/3, record_access/3, record_expr/2,
2498 record_field/2, record_index_expr/2, record_type/2,
2499 record_type_field/2, size_qualifier/2, string/1, text/1, tree/2,
2500 try_expr/3, tuple/1, tuple_type/0, tuple_type/1, type_applica‐
2501 tion/2, type_union/1, typed_record_field/2, underscore/0,
2502 user_type_application/2, variable/1, warning_marker/1.
2503 type_application(TypeName::syntaxTree(), Arguments::[syntaxTree()]) ->
2505 syntaxTree()
2506 Creates an abstract type application expression. If Arguments is
2508 [T1, ..., Tn], the result represents "TypeName(T1, ...Tn)".
2509 See also: type_application/3, type_application_arguments/1,
2511 type_application_name/1, user_type_application/2.
2512 type_application(Module::none | syntaxTree(), TypeName::syntaxTree(),
2514 Arguments::[syntaxTree()]) -> syntaxTree()
2515 Creates an abstract type application expression. If Module is
2517 none, this is call is equivalent to type_application(TypeName,
2518 Arguments), otherwise it is equivalent to type_application(mod‐
2519 ule_qualifier(Module, TypeName), Arguments).
2520 (This is a utility function.)
2522 See also: module_qualifier/2, type_application/2.
2524 type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2526 Returns the arguments subtrees of a type_application node.
2528 See also: type_application/2.
2530 type_application_name(Node::syntaxTree()) -> syntaxTree()
2532 Returns the type name subtree of a type_application node.
2534 See also: type_application/2.
2536 type_union(Types::[syntaxTree()]) -> syntaxTree()
2538 Creates an abstract type union. If Types is [T1, ..., Tn], the
2540 result represents "T1 | ... | Tn".
2541 See also: type_union_types/1.
2543 type_union_types(Node::syntaxTree()) -> [syntaxTree()]
2545 Returns the list of type subtrees of a type_union node.
2547 See also: type_union/1.
2549 typed_record_field(Field::syntaxTree(), Type::syntaxTree()) -> syntax‐
2551 Tree()
2552 Creates an abstract typed record field specification. The result
2554 represents "Field :: Type".
2555 See also: typed_record_field_body/1, typed_record_field_type/1.
2557 typed_record_field_body(Node::syntaxTree()) -> syntaxTree()
2559 Returns the field subtree of a typed_record_field node.
2561 See also: typed_record_field/2.
2563 typed_record_field_type(Node::syntaxTree()) -> syntaxTree()
2565 Returns the type subtree of a typed_record_field node.
2567 See also: typed_record_field/2.
2569 underscore() -> syntaxTree()
2571 Creates an abstract universal pattern ("_"). The lexical repre‐
2573 sentation is a single underscore character. Note that this is
2574 not a variable, lexically speaking.
2575 See also: variable/1.
2577 update_tree(Node::syntaxTree(), Groups::[[syntaxTree()]]) -> syntax‐
2579 Tree()
2580 Creates a syntax tree with the same type and attributes as the
2582 given tree. This is equivalent to copy_attrs(Node,
2583 make_tree(type(Node), Groups)).
2584 See also: copy_attrs/2, make_tree/2, type/1.
2586 user_type_application(TypeName::syntaxTree(), Arguments::[syntax‐
2588 Tree()]) -> syntaxTree()
2589 Creates an abstract user type. If Arguments is [T1, ..., Tn],
2591 the result represents "TypeName(T1, ...Tn)".
2592 See also: type_application/2, user_type_application_arguments/1,
2594 user_type_application_name/1.
2595 user_type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2597 Returns the arguments subtrees of a user_type_application node.
2599 See also: user_type_application/2.
2601 user_type_application_name(Node::syntaxTree()) -> syntaxTree()
2603 Returns the type name subtree of a user_type_application node.
2605 See also: user_type_application/2.
2607 variable(Name::atom() | string()) -> syntaxTree()
2609 Creates an abstract variable with the given name. Name may be
2611 any atom or string that represents a lexically valid variable
2612 name, but not a single underscore character; see underscore/0.
2613 Note: no checking is done whether the character sequence repre‐
2615 sents a proper variable name, i.e., whether or not its first
2616 character is an uppercase Erlang character, or whether it does
2617 not contain control characters, whitespace, etc.
2618 See also: underscore/0, variable_literal/1, variable_name/1.
2620 variable_literal(Node::syntaxTree()) -> string()
2622 Returns the name of a variable node as a string.
2624 See also: variable/1.
2626 variable_name(Node::syntaxTree()) -> atom()
2628 Returns the name of a variable node as an atom.
2630 See also: variable/1.
2632 warning_marker(Warning::term()) -> syntaxTree()
2634 Creates an abstract warning marker. The result represents an oc‐
2636 currence of a possible problem in the source code, with an asso‐
2637 ciated Erlang I/O ErrorInfo structure given by Error (see module
2638 io(3) for details). Warning markers are regarded as source code
2639 forms, but have no defined lexical form.
2640 Note: this is supported only for backwards compatibility with
2642 existing parsers and tools.
2643 See also: eof_marker/0, error_marker/1, is_form/1, warn‐
2645 ing_marker_info/1.
2646 warning_marker_info(Node::syntaxTree()) -> term()
2648 Returns the ErrorInfo structure of a warning_marker node.
2650 See also: warning_marker/1.
2652
2654 Richard Carlsson <carlsson.richard@gmail.com>
2655 syntax_tools 3.1 erl_syntax(3)