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_expr(Fields::[syntaxTree()]) -> syntaxTree()
1500 Equivalent to map_expr(none, Fields).
1502 map_expr(Argument::none | syntaxTree(), Fields::[syntaxTree()]) -> syn‐
1504 taxTree()
1505 Creates an abstract map expression. If Fields is [F1, ..., Fn],
1507 then if Argument is none, the result represents "#{F1, ...,
1508 Fn}", otherwise it represents "Argument#{F1, ..., Fn}".
1509 See also: map_expr/1, map_expr_argument/1, map_expr_fields/1,
1511 map_field_assoc/2, map_field_exact/2.
1512 map_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1514 Returns the argument subtree of a map_expr node, if any. If Node
1516 represents "#{...}", none is returned. Otherwise, if Node repre‐
1517 sents "Argument#{...}", Argument is returned.
1518 See also: map_expr/2.
1520 map_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1522 Returns the list of field subtrees of a map_expr node.
1524 See also: map_expr/2.
1526 map_field_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1528 Tree()
1529 Creates an abstract map assoc field. The result represents "Name
1531 => Value".
1532 See also: map_expr/2, map_field_assoc_name/1, map_field_as‐
1534 soc_value/1.
1535 map_field_assoc_name(Node::syntaxTree()) -> syntaxTree()
1537 Returns the name subtree of a map_field_assoc node.
1539 See also: map_field_assoc/2.
1541 map_field_assoc_value(Node::syntaxTree()) -> syntaxTree()
1543 Returns the value subtree of a map_field_assoc node.
1545 See also: map_field_assoc/2.
1547 map_field_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1549 Tree()
1550 Creates an abstract map exact field. The result represents "Name
1552 := Value".
1553 See also: map_expr/2, map_field_exact_name/1, map_field_ex‐
1555 act_value/1.
1556 map_field_exact_name(Node::syntaxTree()) -> syntaxTree()
1558 Returns the name subtree of a map_field_exact node.
1560 See also: map_field_exact/2.
1562 map_field_exact_value(Node::syntaxTree()) -> syntaxTree()
1564 Returns the value subtree of a map_field_exact node.
1566 See also: map_field_exact/2.
1568 map_type() -> term()
1570 Equivalent to map_type(any_size).
1572 map_type(Fields::any_size | [syntaxTree()]) -> syntaxTree()
1574 Creates an abstract type map. If Fields is [F1, ..., Fn], the
1576 result represents "#{F1, ..., Fn}"; otherwise, if Fields is
1577 any_size, it represents "map()".
1578 See also: map_type_fields/1.
1580 map_type_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1582 Creates an abstract map type assoc field. The result represents
1584 "Name => Value".
1585 See also: map_type/1, map_type_assoc_name/1, map_type_as‐
1587 soc_value/1.
1588 map_type_assoc_name(Node::syntaxTree()) -> syntaxTree()
1590 Returns the name subtree of a map_type_assoc node.
1592 See also: map_type_assoc/2.
1594 map_type_assoc_value(Node::syntaxTree()) -> syntaxTree()
1596 Returns the value subtree of a map_type_assoc node.
1598 See also: map_type_assoc/2.
1600 map_type_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1602 Creates an abstract map type exact field. The result represents
1604 "Name := Value".
1605 See also: map_type/1, map_type_exact_name/1, map_type_ex‐
1607 act_value/1.
1608 map_type_exact_name(Node::syntaxTree()) -> syntaxTree()
1610 Returns the name subtree of a map_type_exact node.
1612 See also: map_type_exact/2.
1614 map_type_exact_value(Node::syntaxTree()) -> syntaxTree()
1616 Returns the value subtree of a map_type_exact node.
1618 See also: map_type_exact/2.
1620 map_type_fields(Node::syntaxTree()) -> any_size | [syntaxTree()]
1622 Returns the list of field subtrees of a map_type node. If Node
1624 represents "map()", any_size is returned; otherwise, if Node
1625 represents "#{F1, ..., Fn}", [F1, ..., Fn] is returned.
1626 See also: map_type/0, map_type/1.
1628 match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
1630 Creates an abstract match-expression. The result represents
1632 "Pattern = Body".
1633 See also: match_expr_body/1, match_expr_pattern/1.
1635 match_expr_body(Node::syntaxTree()) -> syntaxTree()
1637 Returns the body subtree of a match_expr node.
1639 See also: match_expr/2.
1641 match_expr_pattern(Node::syntaxTree()) -> syntaxTree()
1643 Returns the pattern subtree of a match_expr node.
1645 See also: match_expr/2.
1647 maybe_expr(Body::[syntaxTree()]) -> syntaxTree()
1649 Equivalent to maybe_expr(Body, none).
1651 maybe_expr(Body::[syntaxTree()], OptionalElse::none | syntaxTree()) ->
1653 syntaxTree()
1654 Creates an abstract maybe-expression. If Body is [B1, ..., Bn],
1656 and OptionalElse is none, the result represents "maybe B1, ...,
1657 Bn end". If Body is [B1, ..., Bn], and OptionalElse reprsents an
1658 else_expr node with clauses [C1, ..., Cn], the result represents
1659 "maybe B1, ..., Bn else C1; ..., Cn end".
1660 See clause for documentation on erl_parse clauses.
1662 See also: maybe_expr_body/1, maybe_expr_else/1.
1664 maybe_expr_body(Node::syntaxTree()) -> [syntaxTree()]
1666 Returns the list of body subtrees of a maybe_expr node.
1668 See also: maybe_expr/2.
1670 maybe_expr_else(Node::syntaxTree()) -> none | syntaxTree()
1672 Returns the else subtree of a maybe_expr node.
1674 See also: maybe_expr/2.
1676 maybe_match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> syntax‐
1678 Tree()
1679 Creates an abstract maybe-expression, as used in maybe blocks.
1681 The result represents "Pattern ?= Body".
1682 See also: maybe_expr/2, maybe_match_expr_body/1,
1684 maybe_match_expr_pattern/1.
1685 maybe_match_expr_body(Node::syntaxTree()) -> syntaxTree()
1687 Returns the body subtree of a maybe_expr node.
1689 See also: maybe_match_expr/2.
1691 maybe_match_expr_pattern(Node::syntaxTree()) -> syntaxTree()
1693 Returns the pattern subtree of a maybe_expr node.
1695 See also: maybe_match_expr/2.
1697 meta(T::syntaxTree()) -> syntaxTree()
1699 Creates a meta-representation of a syntax tree. The result rep‐
1701 resents an Erlang expression "MetaTree" which, if evaluated,
1702 will yield a new syntax tree representing the same source code
1703 text as Tree (although the actual data representation may be
1704 different). The expression represented by MetaTree is implemen‐
1705 tation independent with regard to the data structures used by
1706 the abstract syntax tree implementation. Comments attached to
1707 nodes of Tree will be preserved, but other attributes are lost.
1708 Any node in Tree whose node type is variable (see type/1), and
1710 whose list of annotations (see get_ann/1) contains the atom
1711 meta_var, will remain unchanged in the resulting tree, except
1712 that exactly one occurrence of meta_var is removed from its an‐
1713 notation list.
1714 The main use of the function meta/1 is to transform a data
1716 structure Tree, which represents a piece of program code, into a
1717 form that is representation independent when printed. E.g., sup‐
1718 pose Tree represents a variable named "V". Then (assuming a
1719 function print/1 for printing syntax trees), evaluating
1720 print(abstract(Tree)) - simply using abstract/1 to map the ac‐
1721 tual data structure onto a syntax tree representation - would
1722 output a string that might look something like "{tree, variable,
1723 ..., "V", ...}", which is obviously dependent on the implementa‐
1724 tion of the abstract syntax trees. This could e.g. be useful for
1725 caching a syntax tree in a file. However, in some situations
1726 like in a program generator generator (with two "generator"), it
1727 may be unacceptable. Using print(meta(Tree)) instead would out‐
1728 put a representation independent syntax tree generating expres‐
1729 sion; in the above case, something like "erl_syntax:vari‐
1730 able("V")".
1731 See also: abstract/1, get_ann/1, type/1.
1733 module_qualifier(Module::syntaxTree(), Body::syntaxTree()) -> syntax‐
1735 Tree()
1736 Creates an abstract module qualifier. The result represents
1738 "Module:Body".
1739 See also: module_qualifier_argument/1, module_qualifier_body/1.
1741 module_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
1743 Returns the argument (the module) subtree of a module_qualifier
1745 node.
1746 See also: module_qualifier/2.
1748 module_qualifier_body(Node::syntaxTree()) -> syntaxTree()
1750 Returns the body subtree of a module_qualifier node.
1752 See also: module_qualifier/2.
1754 named_fun_expr(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
1756 Tree()
1757 Creates an abstract named fun-expression. If Clauses is [C1,
1759 ..., Cn], the result represents "fun Name C1; ...; Name Cn end".
1760 More exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi",
1761 then the result represents "fun Name(P11, ..., P1m) G1 -> B1;
1762 ...; Name(Pn1, ..., Pnm) Gn -> Bn end".
1763 See also: named_fun_expr_arity/1, named_fun_expr_clauses/1,
1765 named_fun_expr_name/1.
1766 named_fun_expr_arity(Node::syntaxTree()) -> arity()
1768 Returns the arity of a named_fun_expr node. The result is the
1770 number of parameter patterns in the first clause of the named
1771 fun-expression; subsequent clauses are ignored.
1772 An exception is thrown if named_fun_expr_clauses(Node) returns
1774 an empty list, or if the first element of that list is not a
1775 syntax tree C of type clause such that clause_patterns(C) is a
1776 nonempty list.
1777 See also: clause/3, clause_patterns/1, named_fun_expr/2,
1779 named_fun_expr_clauses/1.
1780 named_fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1782 Returns the list of clause subtrees of a named_fun_expr node.
1784 See also: named_fun_expr/2.
1786 named_fun_expr_name(Node::syntaxTree()) -> syntaxTree()
1788 Returns the name subtree of a named_fun_expr node.
1790 See also: named_fun_expr/2.
1792 nil() -> syntaxTree()
1794 Creates an abstract empty list. The result represents "[]". The
1796 empty list is traditionally called "nil".
1797 See also: is_list_skeleton/1, list/2.
1799 normalize_list(Node::syntaxTree()) -> syntaxTree()
1801 Expands an abstract list skeleton to its most explicit form. If
1803 Node represents "[E1, ..., En | Tail]", the result represents
1804 "[E1 | ... [En | Tail1] ... ]", where Tail1 is the result of
1805 normalize_list(Tail). If Node represents "[E1, ..., En]", the
1806 result simply represents "[E1 | ... [En | []] ... ]". If Node
1807 does not represent a list skeleton, Node itself is returned.
1808 See also: compact_list/1, list/2.
1810 operator(Name::atom() | string()) -> syntaxTree()
1812 Creates an abstract operator. The name of the operator is the
1814 character sequence represented by Name. This is analogous to the
1815 print name of an atom, but an operator is never written within
1816 single-quotes; e.g., the result of operator('++') represents
1817 "++" rather than "'++'".
1818 See also: atom/1, operator_literal/1, operator_name/1.
1820 operator_literal(Node::syntaxTree()) -> string()
1822 Returns the literal string represented by an operator node. This
1824 is simply the operator name as a string.
1825 See also: operator/1.
1827 operator_name(Node::syntaxTree()) -> atom()
1829 Returns the name of an operator node. Note that the name is re‐
1831 turned as an atom.
1832 See also: operator/1.
1834 parentheses(Expr::syntaxTree()) -> syntaxTree()
1836 Creates an abstract parenthesised expression. The result repre‐
1838 sents "(Body)", independently of the context.
1839 See also: parentheses_body/1.
1841 parentheses_body(Node::syntaxTree()) -> syntaxTree()
1843 Returns the body subtree of a parentheses node.
1845 See also: parentheses/1.
1847 prefix_expr(Operator::syntaxTree(), Argument::syntaxTree()) -> syntax‐
1849 Tree()
1850 Creates an abstract prefix operator expression. The result rep‐
1852 resents "Operator Argument".
1853 See also: infix_expr/3, prefix_expr_argument/1, prefix_expr_op‐
1855 erator/1.
1856 prefix_expr_argument(Node::syntaxTree()) -> syntaxTree()
1858 Returns the argument subtree of a prefix_expr node.
1860 See also: prefix_expr/2.
1862 prefix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1864 Returns the operator subtree of a prefix_expr node.
1866 See also: prefix_expr/2.
1868 receive_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1870 Equivalent to receive_expr(Clauses, none, []).
1872 receive_expr(Clauses::[syntaxTree()], Timeout::none | syntaxTree(), Ac‐
1874 tion::[syntaxTree()]) -> syntaxTree()
1875 Creates an abstract receive-expression. If Timeout is none, the
1877 result represents "receive C1; ...; Cn end" (the Action argument
1878 is ignored). Otherwise, if Clauses is [C1, ..., Cn] and Action
1879 is [A1, ..., Am], the result represents "receive C1; ...; Cn af‐
1880 ter Timeout -> A1, ..., Am end". More exactly, if each Ci repre‐
1881 sents "(Pi) Gi -> Bi", then the result represents "receive P1 G1
1882 -> B1; ...; Pn Gn -> Bn ... end".
1883 Note that in Erlang, a receive-expression must have at least one
1885 clause if no timeout part is specified.
1886 See also: case_expr/2, clause/3, receive_expr/1, re‐
1888 ceive_expr_action/1, receive_expr_clauses/1, receive_expr_time‐
1889 out/1.
1890 receive_expr_action(Node::syntaxTree()) -> [syntaxTree()]
1892 Returns the list of action body subtrees of a receive_expr node.
1894 If Node represents "receive C1; ...; Cn end", this is the empty
1895 list.
1896 See also: receive_expr/3.
1898 receive_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1900 Returns the list of clause subtrees of a receive_expr node.
1902 See also: receive_expr/3.
1904 receive_expr_timeout(Node::syntaxTree()) -> none | syntaxTree()
1906 Returns the timeout subtree of a receive_expr node, if any. If
1908 Node represents "receive C1; ...; Cn end", none is returned.
1909 Otherwise, if Node represents "receive C1; ...; Cn after Timeout
1910 -> ... end", Timeout is returned.
1911 See also: receive_expr/3.
1913 record_access(Argument::syntaxTree(), Type::syntaxTree(), Field::syn‐
1915 taxTree()) -> syntaxTree()
1916 Creates an abstract record field access expression. The result
1918 represents "Argument#Type.Field".
1919 See also: record_access_argument/1, record_access_field/1,
1921 record_access_type/1, record_expr/3.
1922 record_access_argument(Node::syntaxTree()) -> syntaxTree()
1924 Returns the argument subtree of a record_access node.
1926 See also: record_access/3.
1928 record_access_field(Node::syntaxTree()) -> syntaxTree()
1930 Returns the field subtree of a record_access node.
1932 See also: record_access/3.
1934 record_access_type(Node::syntaxTree()) -> syntaxTree()
1936 Returns the type subtree of a record_access node.
1938 See also: record_access/3.
1940 record_expr(Type::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1942 Equivalent to record_expr(none, Type, Fields).
1944 record_expr(Argument::none | syntaxTree(), Type::syntaxTree(),
1946 Fields::[syntaxTree()]) -> syntaxTree()
1947 Creates an abstract record expression. If Fields is [F1, ...,
1949 Fn], then if Argument is none, the result represents "#Type{F1,
1950 ..., Fn}", otherwise it represents "Argument#Type{F1, ..., Fn}".
1951 See also: record_access/3, record_expr/2, record_expr_argu‐
1953 ment/1, record_expr_fields/1, record_expr_type/1,
1954 record_field/2, record_index_expr/2.
1955 record_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1957 Returns the argument subtree of a record_expr node, if any. If
1959 Node represents "#Type{...}", none is returned. Otherwise, if
1960 Node represents "Argument#Type{...}", Argument is returned.
1961 See also: record_expr/3.
1963 record_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1965 Returns the list of field subtrees of a record_expr node.
1967 See also: record_expr/3.
1969 record_expr_type(Node::syntaxTree()) -> syntaxTree()
1971 Returns the type subtree of a record_expr node.
1973 See also: record_expr/3.
1975 record_field(Name::syntaxTree()) -> syntaxTree()
1977 Equivalent to record_field(Name, none).
1979 record_field(Name::syntaxTree(), Value::none | syntaxTree()) -> syntax‐
1981 Tree()
1982 Creates an abstract record field specification. If Value is
1984 none, the result represents simply "Name", otherwise it repre‐
1985 sents "Name = Value".
1986 See also: record_expr/3, record_field_name/1,
1988 record_field_value/1.
1989 record_field_name(Node::syntaxTree()) -> syntaxTree()
1991 Returns the name subtree of a record_field node.
1993 See also: record_field/2.
1995 record_field_value(Node::syntaxTree()) -> none | syntaxTree()
1997 Returns the value subtree of a record_field node, if any. If
1999 Node represents "Name", none is returned. Otherwise, if Node
2000 represents "Name = Value", Value is returned.
2001 See also: record_field/2.
2003 record_index_expr(Type::syntaxTree(), Field::syntaxTree()) -> syntax‐
2005 Tree()
2006 Creates an abstract record field index expression. The result
2008 represents "#Type.Field".
2009 (Note: the function name record_index/2 is reserved by the Er‐
2011 lang compiler, which is why that name could not be used for this
2012 constructor.)
2013 See also: record_expr/3, record_index_expr_field/1, record_in‐
2015 dex_expr_type/1.
2016 record_index_expr_field(Node::syntaxTree()) -> syntaxTree()
2018 Returns the field subtree of a record_index_expr node.
2020 See also: record_index_expr/2.
2022 record_index_expr_type(Node::syntaxTree()) -> syntaxTree()
2024 Returns the type subtree of a record_index_expr node.
2026 See also: record_index_expr/2.
2028 record_type(Name::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
2030 Creates an abstract record type. If Fields is [F1, ..., Fn], the
2032 result represents "#Name{F1, ..., Fn}".
2033 See also: record_type_fields/1, record_type_name/1.
2035 record_type_field(Name::syntaxTree(), Type::syntaxTree()) -> syntax‐
2037 Tree()
2038 Creates an abstract record type field. The result represents
2040 "Name :: Type".
2041 See also: record_type_field_name/1, record_type_field_type/1.
2043 record_type_field_name(Node::syntaxTree()) -> syntaxTree()
2045 Returns the name subtree of a record_type_field node.
2047 See also: record_type_field/2.
2049 record_type_field_type(Node::syntaxTree()) -> syntaxTree()
2051 Returns the type subtree of a record_type_field node.
2053 See also: record_type_field/2.
2055 record_type_fields(Node::syntaxTree()) -> [syntaxTree()]
2057 Returns the fields subtree of a record_type node.
2059 See also: record_type/2.
2061 record_type_name(Node::syntaxTree()) -> syntaxTree()
2063 Returns the name subtree of a record_type node.
2065 See also: record_type/2.
2067 remove_comments(Node::syntaxTree()) -> syntaxTree()
2069 Clears the associated comments of Node.
2071 Note: This is equivalent to set_precomments(set_postcom‐
2073 ments(Node, []), []), but potentially more efficient.
2074 See also: set_postcomments/2, set_precomments/2.
2076 revert(Node::syntaxTree()) -> syntaxTree()
2078 Returns an erl_parse-compatible representation of a syntax tree,
2080 if possible. If Tree represents a well-formed Erlang program or
2081 expression, the conversion should work without problems. Typi‐
2082 cally, is_tree/1 yields true if conversion failed (i.e., the re‐
2083 sult is still an abstract syntax tree), and false otherwise.
2084 The is_tree/1 test is not completely foolproof. For a few spe‐
2086 cial node types (e.g. arity_qualifier), if such a node occurs in
2087 a context where it is not expected, it will be left unchanged as
2088 a non-reverted subtree of the result. This can only happen if
2089 Tree does not actually represent legal Erlang code.
2090 See also: erl_parse(3), revert_forms/1.
2092 revert_forms(Forms::forms()) -> [erl_parse()]
2094 Reverts a sequence of Erlang source code forms. The sequence can
2096 be given either as a form_list syntax tree (possibly nested), or
2097 as a list of "program form" syntax trees. If successful, the
2098 corresponding flat list of erl_parse-compatible syntax trees is
2099 returned (see revert/1). If some program form could not be re‐
2100 verted, {error, Form} is thrown. Standalone comments in the form
2101 sequence are discarded.
2102 See also: form_list/1, is_form/1, revert/1.
2104 set_ann(Node::syntaxTree(), As::[term()]) -> syntaxTree()
2106 Sets the list of user annotations of Node to Annotations.
2108 See also: add_ann/2, copy_ann/2, get_ann/1.
2110 set_attrs(Node::syntaxTree(), Attr::syntaxTreeAttributes()) -> syntax‐
2112 Tree()
2113 Sets the attributes of Node to Attributes.
2115 See also: copy_attrs/2, get_attrs/1.
2117 set_pos(Node::syntaxTree(), Pos::annotation_or_location()) -> syntax‐
2119 Tree()
2120 Sets the position information of Node to Pos.
2122 See also: copy_pos/2, get_pos/1.
2124 set_postcomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntax‐
2126 Tree()
2127 Sets the post-comments of Node to Comments. Comments should be a
2129 possibly empty list of abstract comments, in top-down textual
2130 order
2131 See also: add_postcomments/2, comment/2, copy_comments/2,
2133 get_postcomments/1, join_comments/2, remove_comments/1, set_pre‐
2134 comments/2.
2135 set_precomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntaxTree()
2137 Sets the pre-comments of Node to Comments. Comments should be a
2139 possibly empty list of abstract comments, in top-down textual
2140 order.
2141 See also: add_precomments/2, comment/2, copy_comments/2,
2143 get_precomments/1, join_comments/2, remove_comments/1, set_post‐
2144 comments/2.
2145 size_qualifier(Body::syntaxTree(), Size::syntaxTree()) -> syntaxTree()
2147 Creates an abstract size qualifier. The result represents
2149 "Body:Size".
2150 See also: size_qualifier_argument/1, size_qualifier_body/1.
2152 size_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
2154 Returns the argument subtree (the size) of a size_qualifier
2156 node.
2157 See also: size_qualifier/2.
2159 size_qualifier_body(Node::syntaxTree()) -> syntaxTree()
2161 Returns the body subtree of a size_qualifier node.
2163 See also: size_qualifier/2.
2165 string(String::string()) -> syntaxTree()
2167 Creates an abstract string literal. The result represents "Text"
2169 (including the surrounding double-quotes), where Text corre‐
2170 sponds to the sequence of characters in Value, but not repre‐
2171 senting a specific string literal.
2172 For example, the result of string("x\ny") represents any and all
2174 of "x\ny", "x\12y", "x\012y" and "x\^Jy"; see char/1.
2175 See also: char/1, is_string/2, string_literal/1, string_lit‐
2177 eral/2, string_value/1.
2178 string_literal(Node::syntaxTree()) -> nonempty_string()
2180 Returns the literal string represented by a string node. This
2182 includes surrounding double-quote characters. Characters beyond
2183 255 will be escaped.
2184 See also: string/1.
2186 string_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
2188 Returns the literal string represented by a string node. This
2190 includes surrounding double-quote characters. Depending on the
2191 encoding characters beyond 255 will be escaped (latin1) or
2192 copied as is (utf8).
2193 See also: string/1.
2195 string_value(Node::syntaxTree()) -> string()
2197 Returns the value represented by a string node.
2199 See also: string/1.
2201 subtrees(T::syntaxTree()) -> [[syntaxTree()]]
2203 Returns the grouped list of all subtrees of a syntax tree. If
2205 Node is a leaf node (see is_leaf/1), this is the empty list,
2206 otherwise the result is always a nonempty list, containing the
2207 lists of subtrees of Node, in left-to-right order as they occur
2208 in the printed program text, and grouped by category. Often,
2209 each group contains only a single subtree.
2210 Depending on the type of Node, the size of some groups may be
2212 variable (e.g., the group consisting of all the elements of a
2213 tuple), while others always contain the same number of elements
2214 - usually exactly one (e.g., the group containing the argument
2215 expression of a case-expression). Note, however, that the exact
2216 structure of the returned list (for a given node type) should in
2217 general not be depended upon, since it might be subject to
2218 change without notice.
2219 The function subtrees/1 and the constructor functions
2221 make_tree/2 and update_tree/2 can be a great help if one wants
2222 to traverse a syntax tree, visiting all its subtrees, but treat
2223 nodes of the tree in a uniform way in most or all cases. Using
2224 these functions makes this simple, and also assures that your
2225 code is not overly sensitive to extensions of the syntax tree
2226 data type, because any node types not explicitly handled by your
2227 code can be left to a default case.
2228 For example:
2230 postorder(F, Tree) ->
2232 F(case subtrees(Tree) of
2233 [] -> Tree;
2234 List -> update_tree(Tree,
2235 [[postorder(F, Subtree)
2236 || Subtree <- Group]
2237 || Group <- List])
2238 end).
2239 maps the function F on Tree and all its subtrees, doing a post-
2241 order traversal of the syntax tree. (Note the use of up‐
2242 date_tree/2 to preserve node attributes.) For a simple function
2243 like:
2244 f(Node) ->
2246 case type(Node) of
2247 atom -> atom("a_" ++ atom_name(Node));
2248 _ -> Node
2249 end.
2250 the call postorder(fun f/1, Tree) will yield a new representa‐
2252 tion of Tree in which all atom names have been extended with the
2253 prefix "a_", but nothing else (including comments, annotations
2254 and line numbers) has been changed.
2255 See also: copy_attrs/2, is_leaf/1, make_tree/2, type/1.
2257 text(String::string()) -> syntaxTree()
2259 Creates an abstract piece of source code text. The result repre‐
2261 sents exactly the sequence of characters in String. This is use‐
2262 ful in cases when one wants full control of the resulting out‐
2263 put, e.g., for the appearance of floating-point numbers or macro
2264 definitions.
2265 See also: text_string/1.
2267 text_string(Node::syntaxTree()) -> string()
2269 Returns the character sequence represented by a text node.
2271 See also: text/1.
2273 tree(Type::atom()) -> tree()
2275 Equivalent to tree(Type, []).
2277 tree(Type::atom(), Data::term()) -> tree()
2279 For special purposes only. Creates an abstract syntax tree node
2281 with type tag Type and associated data Data.
2282 This function and the related is_tree/1 and data/1 provide a
2284 uniform way to extend the set of erl_parse node types. The asso‐
2285 ciated data is any term, whose format may depend on the type
2286 tag.
2287 Notes:
2289 * Any nodes created outside of this module must have type tags
2291 distinct from those currently defined by this module; see
2292 type/1 for a complete list.
2293 * The type tag of a syntax tree node may also be used as a
2295 primary tag by the erl_parse representation; in that case,
2296 the selector functions for that node type must handle both
2297 the abstract syntax tree and the erl_parse form. The func‐
2298 tion type(T) should return the correct type tag regardless
2299 of the representation of T, so that the user sees no differ‐
2300 ence between erl_syntax and erl_parse nodes.
2301 See also: data/1, is_tree/1, type/1.
2303 try_after_expr(Body::[syntaxTree()], After::[syntaxTree()]) -> syntax‐
2305 Tree()
2306 Equivalent to try_expr(Body, [], [], After).
2308 try_expr(Body::[syntaxTree()], Handlers::[syntaxTree()]) -> syntax‐
2310 Tree()
2311 Equivalent to try_expr(Body, [], Handlers).
2313 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2315 taxTree()]) -> syntaxTree()
2316 Equivalent to try_expr(Body, Clauses, Handlers, []).
2318 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2320 taxTree()], After::[syntaxTree()]) -> syntaxTree()
2321 Creates an abstract try-expression. If Body is [B1, ..., Bn],
2323 Clauses is [C1, ..., Cj], Handlers is [H1, ..., Hk], and After
2324 is [A1, ..., Am], the result represents "try B1, ..., Bn of C1;
2325 ...; Cj catch H1; ...; Hk after A1, ..., Am end". More exactly,
2326 if each Ci represents "(CPi) CGi -> CBi", and each Hi represents
2327 "(HPi) HGi -> HBi", then the result represents "try B1, ..., Bn
2328 of CP1 CG1 -> CB1; ...; CPj CGj -> CBj catch HP1 HG1 -> HB1;
2329 ...; HPk HGk -> HBk after A1, ..., Am end"; see case_expr/2. If
2330 Clauses is the empty list, the of ... section is left out. If
2331 After is the empty list, the after ... section is left out. If
2332 Handlers is the empty list, and After is nonempty, the catch ...
2333 section is left out.
2334 See also: case_expr/2, class_qualifier/2, clause/3, try_af‐
2336 ter_expr/2, try_expr/2, try_expr/3, try_expr_after/1,
2337 try_expr_body/1, try_expr_clauses/1, try_expr_handlers/1.
2338 try_expr_after(Node::syntaxTree()) -> [syntaxTree()]
2340 Returns the list of "after" subtrees of a try_expr node.
2342 See also: try_expr/4.
2344 try_expr_body(Node::syntaxTree()) -> [syntaxTree()]
2346 Returns the list of body subtrees of a try_expr node.
2348 See also: try_expr/4.
2350 try_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
2352 Returns the list of case-clause subtrees of a try_expr node. If
2354 Node represents "try Body catch H1; ...; Hn end", the result is
2355 the empty list.
2356 See also: try_expr/4.
2358 try_expr_handlers(Node::syntaxTree()) -> [syntaxTree()]
2360 Returns the list of handler-clause subtrees of a try_expr node.
2362 See also: try_expr/4.
2364 tuple(List::[syntaxTree()]) -> syntaxTree()
2366 Creates an abstract tuple. If Elements is [X1, ..., Xn], the re‐
2368 sult represents "{X1, ..., Xn}".
2369 Note: The Erlang language has distinct 1-tuples, i.e., {X} is
2371 always distinct from X itself.
2372 See also: tuple_elements/1, tuple_size/1.
2374 tuple_elements(Node::syntaxTree()) -> [syntaxTree()]
2376 Returns the list of element subtrees of a tuple node.
2378 See also: tuple/1.
2380 tuple_size(Node::syntaxTree()) -> non_neg_integer()
2382 Returns the number of elements of a tuple node.
2384 Note: this is equivalent to length(tuple_elements(Node)), but
2386 potentially more efficient.
2387 See also: tuple/1, tuple_elements/1.
2389 tuple_type() -> term()
2391 Equivalent to tuple_type(any_size).
2393 tuple_type(Elements::any_size | [syntaxTree()]) -> syntaxTree()
2395 Creates an abstract type tuple. If Elements is [T1, ..., Tn],
2397 the result represents "{T1, ..., Tn}"; otherwise, if Elements is
2398 any_size, it represents "tuple()".
2399 See also: tuple_type_elements/1.
2401 tuple_type_elements(Node::syntaxTree()) -> any_size | [syntaxTree()]
2403 Returns the list of type element subtrees of a tuple_type node.
2405 If Node represents "tuple()", any_size is returned; otherwise,
2406 if Node represents "{T1, ..., Tn}", [T1, ..., Tn] is returned.
2407 See also: tuple_type/0, tuple_type/1.
2409 type(Tree::syntaxTree()) -> atom()
2411 Returns the type tag of Node. If Node does not represent a syn‐
2413 tax tree, evaluation fails with reason badarg. Node types cur‐
2414 rently defined by this module are:
2415 application annotated_type arity_qualifier atom
2417 attribute binary binary_field bitstring_type
2418 block_expr case_expr catch_expr char
2419 class_qualifier clause comment conjunction
2420 constrained_function_type constraint disjunction
2421 else_expr eof_marker error_marker
2422 float form_list fun_expr fun_type function function_type genera‐
2423 tor
2424 if_expr implicit_fun infix_expr integer
2425 integer_range_type list list_comp macro
2426 map_expr map_field_assoc map_field_exact map_type
2427 map_type_assoc map_type_exact match_expr
2428 maybe_expr maybe_match_expr module_qualifier
2429 named_fun_expr nil operator parentheses
2430 prefix_expr receive_expr record_access record_expr
2431 record_field record_index_expr record_type record_type_field
2432 size_qualifier string text try_expr
2433 tuple tuple_type typed_record_field type_application
2434 type_union underscore user_type_application variable
2435 warning_marker
2436 The user may (for special purposes) create additional nodes with
2439 other type tags, using the tree/2 function.
2440 Note: The primary constructor functions for a node type should
2442 always have the same name as the node type itself.
2443 See also: annotated_type/2, application/3, arity_qualifier/2,
2445 atom/1, attribute/2, binary/1, binary_field/2, bitstring_type/2,
2446 block_expr/1, case_expr/2, catch_expr/1, char/1, class_quali‐
2447 fier/2, clause/3, comment/2, conjunction/1, constrained_func‐
2448 tion_type/2, constraint/2, disjunction/1, else_expr/1,
2449 eof_marker/0, error_marker/1, float/1, form_list/1, fun_expr/1,
2450 fun_type/0, function/2, function_type/1, function_type/2, gener‐
2451 ator/2, if_expr/1, implicit_fun/2, infix_expr/3, integer/1, in‐
2452 teger_range_type/2, list/2, list_comp/2, macro/2, map_expr/2,
2453 map_field_assoc/2, map_field_exact/2, map_type/0, map_type/1,
2454 map_type_assoc/2, map_type_exact/2, match_expr/2, maybe_expr/1,
2455 maybe_expr/2, maybe_match_expr/2, module_qualifier/2,
2456 named_fun_expr/2, nil/0, operator/1, parentheses/1, pre‐
2457 fix_expr/2, receive_expr/3, record_access/3, record_expr/2,
2458 record_field/2, record_index_expr/2, record_type/2,
2459 record_type_field/2, size_qualifier/2, string/1, text/1, tree/2,
2460 try_expr/3, tuple/1, tuple_type/0, tuple_type/1, type_applica‐
2461 tion/2, type_union/1, typed_record_field/2, underscore/0,
2462 user_type_application/2, variable/1, warning_marker/1.
2463 type_application(TypeName::syntaxTree(), Arguments::[syntaxTree()]) ->
2465 syntaxTree()
2466 Creates an abstract type application expression. If Arguments is
2468 [T1, ..., Tn], the result represents "TypeName(T1, ...Tn)".
2469 See also: type_application/3, type_application_arguments/1,
2471 type_application_name/1, user_type_application/2.
2472 type_application(Module::none | syntaxTree(), TypeName::syntaxTree(),
2474 Arguments::[syntaxTree()]) -> syntaxTree()
2475 Creates an abstract type application expression. If Module is
2477 none, this is call is equivalent to type_application(TypeName,
2478 Arguments), otherwise it is equivalent to type_application(mod‐
2479 ule_qualifier(Module, TypeName), Arguments).
2480 (This is a utility function.)
2482 See also: module_qualifier/2, type_application/2.
2484 type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2486 Returns the arguments subtrees of a type_application node.
2488 See also: type_application/2.
2490 type_application_name(Node::syntaxTree()) -> syntaxTree()
2492 Returns the type name subtree of a type_application node.
2494 See also: type_application/2.
2496 type_union(Types::[syntaxTree()]) -> syntaxTree()
2498 Creates an abstract type union. If Types is [T1, ..., Tn], the
2500 result represents "T1 | ... | Tn".
2501 See also: type_union_types/1.
2503 type_union_types(Node::syntaxTree()) -> [syntaxTree()]
2505 Returns the list of type subtrees of a type_union node.
2507 See also: type_union/1.
2509 typed_record_field(Field::syntaxTree(), Type::syntaxTree()) -> syntax‐
2511 Tree()
2512 Creates an abstract typed record field specification. The result
2514 represents "Field :: Type".
2515 See also: typed_record_field_body/1, typed_record_field_type/1.
2517 typed_record_field_body(Node::syntaxTree()) -> syntaxTree()
2519 Returns the field subtree of a typed_record_field node.
2521 See also: typed_record_field/2.
2523 typed_record_field_type(Node::syntaxTree()) -> syntaxTree()
2525 Returns the type subtree of a typed_record_field node.
2527 See also: typed_record_field/2.
2529 underscore() -> syntaxTree()
2531 Creates an abstract universal pattern ("_"). The lexical repre‐
2533 sentation is a single underscore character. Note that this is
2534 not a variable, lexically speaking.
2535 See also: variable/1.
2537 update_tree(Node::syntaxTree(), Groups::[[syntaxTree()]]) -> syntax‐
2539 Tree()
2540 Creates a syntax tree with the same type and attributes as the
2542 given tree. This is equivalent to copy_attrs(Node,
2543 make_tree(type(Node), Groups)).
2544 See also: copy_attrs/2, make_tree/2, type/1.
2546 user_type_application(TypeName::syntaxTree(), Arguments::[syntax‐
2548 Tree()]) -> syntaxTree()
2549 Creates an abstract user type. If Arguments is [T1, ..., Tn],
2551 the result represents "TypeName(T1, ...Tn)".
2552 See also: type_application/2, user_type_application_arguments/1,
2554 user_type_application_name/1.
2555 user_type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2557 Returns the arguments subtrees of a user_type_application node.
2559 See also: user_type_application/2.
2561 user_type_application_name(Node::syntaxTree()) -> syntaxTree()
2563 Returns the type name subtree of a user_type_application node.
2565 See also: user_type_application/2.
2567 variable(Name::atom() | string()) -> syntaxTree()
2569 Creates an abstract variable with the given name. Name may be
2571 any atom or string that represents a lexically valid variable
2572 name, but not a single underscore character; see underscore/0.
2573 Note: no checking is done whether the character sequence repre‐
2575 sents a proper variable name, i.e., whether or not its first
2576 character is an uppercase Erlang character, or whether it does
2577 not contain control characters, whitespace, etc.
2578 See also: underscore/0, variable_literal/1, variable_name/1.
2580 variable_literal(Node::syntaxTree()) -> string()
2582 Returns the name of a variable node as a string.
2584 See also: variable/1.
2586 variable_name(Node::syntaxTree()) -> atom()
2588 Returns the name of a variable node as an atom.
2590 See also: variable/1.
2592 warning_marker(Warning::term()) -> syntaxTree()
2594 Creates an abstract warning marker. The result represents an oc‐
2596 currence of a possible problem in the source code, with an asso‐
2597 ciated Erlang I/O ErrorInfo structure given by Error (see module
2598 io(3) for details). Warning markers are regarded as source code
2599 forms, but have no defined lexical form.
2600 Note: this is supported only for backwards compatibility with
2602 existing parsers and tools.
2603 See also: eof_marker/0, error_marker/1, is_form/1, warn‐
2605 ing_marker_info/1.
2606 warning_marker_info(Node::syntaxTree()) -> term()
2608 Returns the ErrorInfo structure of a warning_marker node.
2610 See also: warning_marker/1.
2612
2614 Richard Carlsson <carlsson.richard@gmail.com>
2615 syntax_tools 3.0 erl_syntax(3)