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 eof_marker() -> syntaxTree()
774 Creates an abstract end-of-file marker. This represents the end
776 of input when reading a sequence of source code forms. An end-
777 of-file marker is itself regarded as a source code form (namely,
778 the last in any sequence in which it occurs). It has no defined
779 lexical form.
780 Note: this is retained only for backwards compatibility with ex‐
782 isting parsers and tools.
783 See also: error_marker/1, is_form/1, warning_marker/1.
785 error_marker(Error::term()) -> syntaxTree()
787 Creates an abstract error marker. The result represents an oc‐
789 currence of an error in the source code, with an associated Er‐
790 lang I/O ErrorInfo structure given by Error (see module io(3)
791 for details). Error markers are regarded as source code forms,
792 but have no defined lexical form.
793 Note: this is supported only for backwards compatibility with
795 existing parsers and tools.
796 See also: eof_marker/0, error_marker_info/1, is_form/1, warn‐
798 ing_marker/1.
799 error_marker_info(Node::syntaxTree()) -> term()
801 Returns the ErrorInfo structure of an error_marker node.
803 See also: error_marker/1.
805 flatten_form_list(Node::syntaxTree()) -> syntaxTree()
807 Flattens sublists of a form_list node. Returns Node with all
809 subtrees of type form_list recursively expanded, yielding a sin‐
810 gle "flat" abstract form sequence.
811 See also: form_list/1.
813 float(Value::float()) -> syntaxTree()
815 Creates an abstract floating-point literal. The lexical repre‐
817 sentation is the decimal floating-point numeral of Value.
818 See also: float_literal/1, float_value/1.
820 float_literal(Node::syntaxTree()) -> string()
822 Returns the numeral string represented by a float node.
824 See also: float/1.
826 float_value(Node::syntaxTree()) -> float()
828 Returns the value represented by a float node. Note that float‐
830 ing-point values should usually not be compared for equality.
831 See also: float/1.
833 form_list(Forms::[syntaxTree()]) -> syntaxTree()
835 Creates an abstract sequence of "source code forms". If Forms is
837 [F1, ..., Fn], where each Fi is a form (see is_form/1, the re‐
838 sult represents
839 F1
841 ...
842 Fn
843 where the Fi are separated by one or more line breaks. A node of
845 type form_list is itself regarded as a source code form; see
846 flatten_form_list/1.
847 Note: this is simply a way of grouping source code forms as a
849 single syntax tree, usually in order to form an Erlang module
850 definition.
851 See also: flatten_form_list/1, form_list_elements/1, is_form/1.
853 form_list_elements(Node::syntaxTree()) -> [syntaxTree()]
855 Returns the list of subnodes of a form_list node.
857 See also: form_list/1.
859 fun_expr(Clauses::[syntaxTree()]) -> syntaxTree()
861 Creates an abstract fun-expression. If Clauses is [C1, ..., Cn],
863 the result represents "fun C1; ...; Cn end". More exactly, if
864 each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then the result
865 represents "fun (P11, ..., P1m) G1 -> B1; ...; (Pn1, ..., Pnm)
866 Gn -> Bn end".
867 See also: fun_expr_arity/1, fun_expr_clauses/1.
869 fun_expr_arity(Node::syntaxTree()) -> arity()
871 Returns the arity of a fun_expr node. The result is the number
873 of parameter patterns in the first clause of the fun-expression;
874 subsequent clauses are ignored.
875 An exception is thrown if fun_expr_clauses(Node) returns an
877 empty list, or if the first element of that list is not a syntax
878 tree C of type clause such that clause_patterns(C) is a nonempty
879 list.
880 See also: clause/3, clause_patterns/1, fun_expr/1,
882 fun_expr_clauses/1.
883 fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
885 Returns the list of clause subtrees of a fun_expr node.
887 See also: fun_expr/1.
889 fun_type() -> syntaxTree()
891 Creates an abstract fun of any type. The result represents
893 "fun()".
894 function(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntaxTree()
896 Creates an abstract function definition. If Clauses is [C1, ...,
898 Cn], the result represents "Name C1; ...; Name Cn.". More ex‐
899 actly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then
900 the result represents "Name(P11, ..., P1m) G1 -> B1; ...;
901 Name(Pn1, ..., Pnm) Gn -> Bn.". Function definitions are source
902 code forms.
903 See also: function_arity/1, function_clauses/1, function_name/1,
905 is_form/1.
906 function_arity(Node::syntaxTree()) -> arity()
908 Returns the arity of a function node. The result is the number
910 of parameter patterns in the first clause of the function; sub‐
911 sequent clauses are ignored.
912 An exception is thrown if function_clauses(Node) returns an
914 empty list, or if the first element of that list is not a syntax
915 tree C of type clause such that clause_patterns(C) is a nonempty
916 list.
917 See also: clause/3, clause_patterns/1, function/2, func‐
919 tion_clauses/1.
920 function_clauses(Node::syntaxTree()) -> [syntaxTree()]
922 Returns the list of clause subtrees of a function node.
924 See also: function/2.
926 function_name(Node::syntaxTree()) -> syntaxTree()
928 Returns the name subtree of a function node.
930 See also: function/2.
932 function_type(Type) -> term()
934 Equivalent to function_type(any_arity, Type).
936 function_type(Arguments::any_arity | [syntaxTree()], Return::syntax‐
938 Tree()) -> syntaxTree()
939 Creates an abstract function type. If Arguments is [T1, ...,
941 Tn], then if it occurs within a function specification, the re‐
942 sult represents "(T1, ...Tn) -> Return"; otherwise it represents
943 "fun((T1, ...Tn) -> Return)". If Arguments is any_arity, it rep‐
944 resents "fun((...) -> Return)".
945 Note that the erl_parse representation is identical for "Func‐
947 tionType" and "fun(FunctionType)".
948 See also: function_type_arguments/1, function_type_return/1.
950 function_type_arguments(Node::syntaxTree()) -> any_arity | [syntax‐
952 Tree()]
953 Returns the argument types subtrees of a function_type node. If
955 Node represents "fun((...) -> Return)", any_arity is returned;
956 otherwise, if Node represents "(T1, ...Tn) -> Return" or
957 "fun((T1, ...Tn) -> Return)", [T1, ..., Tn] is returned.
958 See also: function_type/1, function_type/2.
960 function_type_return(Node::syntaxTree()) -> syntaxTree()
962 Returns the return type subtrees of a function_type node.
964 See also: function_type/1, function_type/2.
966 generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
968 Creates an abstract generator. The result represents "Pattern <-
970 Body".
971 See also: binary_comp/2, generator_body/1, generator_pattern/1,
973 list_comp/2.
974 generator_body(Node::syntaxTree()) -> syntaxTree()
976 Returns the body subtree of a generator node.
978 See also: generator/2.
980 generator_pattern(Node::syntaxTree()) -> syntaxTree()
982 Returns the pattern subtree of a generator node.
984 See also: generator/2.
986 get_ann(Tree::syntaxTree()) -> [term()]
988 Returns the list of user annotations associated with a syntax
990 tree node. For a newly created node, this is the empty list. The
991 annotations may be any terms.
992 See also: get_attrs/1, set_ann/2.
994 get_attrs(Tree::syntaxTree()) -> syntaxTreeAttributes()
996 Returns a representation of the attributes associated with a
998 syntax tree node. The attributes are all the extra information
999 that can be attached to a node. Currently, this includes posi‐
1000 tion information, source code comments, and user annotations.
1001 The result of this function cannot be inspected directly; only
1002 attached to another node (see set_attrs/2).
1003 For accessing individual attributes, see get_pos/1, get_ann/1,
1005 get_precomments/1 and get_postcomments/1.
1006 See also: get_ann/1, get_pos/1, get_postcomments/1, get_precom‐
1008 ments/1, set_attrs/2.
1009 get_pos(Tree::syntaxTree()) -> annotation_or_location()
1011 Returns the annotation (see erl_anno(3)) associated with Node.
1013 By default, all new tree nodes have their associated position
1014 information set to the integer zero. Use erl_anno:location/1 or
1015 erl_anno:line/1 to get the position information.
1016 See also: get_attrs/1, set_pos/2.
1018 get_postcomments(Tree::syntaxTree()) -> [syntaxTree()]
1020 Returns the associated post-comments of a node. This is a possi‐
1022 bly empty list of abstract comments, in top-down textual order.
1023 When the code is formatted, post-comments are typically dis‐
1024 played to the right of and/or below the node. For example:
1025 {foo, X, Y} % Post-comment of tuple
1027 If possible, the comment should be moved past any following sep‐
1029 arator characters on the same line, rather than placing the sep‐
1030 arators on the following line. E.g.:
1031 foo([X | Xs], Y) ->
1033 foo(Xs, bar(X)); % Post-comment of 'bar(X)' node
1034 ...
1035 (where the comment is moved past the rightmost ")" and the ";").
1037 See also: comment/2, get_attrs/1, get_precomments/1, set_post‐
1039 comments/2.
1040 get_precomments(Tree::syntaxTree()) -> [syntaxTree()]
1042 Returns the associated pre-comments of a node. This is a possi‐
1044 bly empty list of abstract comments, in top-down textual order.
1045 When the code is formatted, pre-comments are typically displayed
1046 directly above the node. For example:
1047 % Pre-comment of function
1049 foo(X) -> {bar, X}.
1050 If possible, the comment should be moved before any preceding
1052 separator characters on the same line. E.g.:
1053 foo([X | Xs]) ->
1055 % Pre-comment of 'bar(X)' node
1056 [bar(X) | foo(Xs)];
1057 ...
1058 (where the comment is moved before the "[").
1060 See also: comment/2, get_attrs/1, get_postcomments/1, set_pre‐
1062 comments/2.
1063 has_comments(Tree::syntaxTree()) -> boolean()
1065 Yields false if the node has no associated comments, and true
1067 otherwise.
1068 Note: This is equivalent to (get_precomments(Node) == []) and
1070 (get_postcomments(Node) == []), but potentially more efficient.
1071 See also: get_postcomments/1, get_precomments/1, remove_com‐
1073 ments/1.
1074 if_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1076 Creates an abstract if-expression. If Clauses is [C1, ..., Cn],
1078 the result represents "if C1; ...; Cn end". More exactly, if
1079 each Ci represents "() Gi -> Bi", then the result represents "if
1080 G1 -> B1; ...; Gn -> Bn end".
1081 See also: case_expr/2, clause/3, if_expr_clauses/1.
1083 if_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1085 Returns the list of clause subtrees of an if_expr node.
1087 See also: if_expr/1.
1089 implicit_fun(Name::syntaxTree()) -> syntaxTree()
1091 Creates an abstract "implicit fun" expression. The result repre‐
1093 sents "fun Name". Name should represent either F/A or M:F/A
1094 See also: arity_qualifier/2, implicit_fun/2, implicit_fun/3, im‐
1096 plicit_fun_name/1, module_qualifier/2.
1097 implicit_fun(Name::syntaxTree(), Arity::none | syntaxTree()) -> syntax‐
1099 Tree()
1100 Creates an abstract "implicit fun" expression. If Arity is none,
1102 this is equivalent to implicit_fun(Name), otherwise it is equiv‐
1103 alent to implicit_fun(arity_qualifier(Name, Arity)).
1104 (This is a utility function.)
1106 See also: implicit_fun/1, implicit_fun/3.
1108 implicit_fun(Module::none | syntaxTree(), Name::syntaxTree(), Ar‐
1110 ity::syntaxTree()) -> syntaxTree()
1111 Creates an abstract module-qualified "implicit fun" expression.
1113 If Module is none, this is equivalent to implicit_fun(Name, Ar‐
1114 ity), otherwise it is equivalent to implicit_fun(module_quali‐
1115 fier(Module, arity_qualifier(Name, Arity)).
1116 (This is a utility function.)
1118 See also: implicit_fun/1, implicit_fun/2.
1120 implicit_fun_name(Node::syntaxTree()) -> syntaxTree()
1122 Returns the name subtree of an implicit_fun node.
1124 Note: if Node represents "fun N/A" or "fun M:N/A", then the re‐
1126 sult is the subtree representing "N/A" or "M:N/A", respectively.
1127 See also: arity_qualifier/2, implicit_fun/1, module_qualifier/2.
1129 infix_expr(Left::syntaxTree(), Operator::syntaxTree(), Right::syntax‐
1131 Tree()) -> syntaxTree()
1132 Creates an abstract infix operator expression. The result repre‐
1134 sents "Left Operator Right".
1135 See also: infix_expr_left/1, infix_expr_operator/1, in‐
1137 fix_expr_right/1, prefix_expr/2.
1138 infix_expr_left(Node::syntaxTree()) -> syntaxTree()
1140 Returns the left argument subtree of an infix_expr node.
1142 See also: infix_expr/3.
1144 infix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1146 Returns the operator subtree of an infix_expr node.
1148 See also: infix_expr/3.
1150 infix_expr_right(Node::syntaxTree()) -> syntaxTree()
1152 Returns the right argument subtree of an infix_expr node.
1154 See also: infix_expr/3.
1156 integer(Value::integer()) -> syntaxTree()
1158 Creates an abstract integer literal. The lexical representation
1160 is the canonical decimal numeral of Value.
1161 See also: integer_literal/1, integer_value/1, is_integer/2.
1163 integer_literal(Node::syntaxTree()) -> string()
1165 Returns the numeral string represented by an integer node.
1167 See also: integer/1.
1169 integer_range_type(Low::syntaxTree(), High::syntaxTree()) -> syntax‐
1171 Tree()
1172 Creates an abstract range type. The result represents "Low ..
1174 High".
1175 See also: integer_range_type_high/1, integer_range_type_low/1.
1177 integer_range_type_high(Node::syntaxTree()) -> syntaxTree()
1179 Returns the high limit of an integer_range_type node.
1181 See also: integer_range_type/2.
1183 integer_range_type_low(Node::syntaxTree()) -> syntaxTree()
1185 Returns the low limit of an integer_range_type node.
1187 See also: integer_range_type/2.
1189 integer_value(Node::syntaxTree()) -> integer()
1191 Returns the value represented by an integer node.
1193 See also: integer/1.
1195 is_atom(Node::syntaxTree(), Value::atom()) -> boolean()
1197 Returns true if Node has type atom and represents Value, other‐
1199 wise false.
1200 See also: atom/1.
1202 is_char(Node::syntaxTree(), Value::char()) -> boolean()
1204 Returns true if Node has type char and represents Value, other‐
1206 wise false.
1207 See also: char/1.
1209 is_form(Node::syntaxTree()) -> boolean()
1211 Returns true if Node is a syntax tree representing a so-called
1213 "source code form", otherwise false. Forms are the Erlang source
1214 code units which, placed in sequence, constitute an Erlang pro‐
1215 gram. Current form types are:
1216 attribute comment error_marker eof_marker
1218 form_list function warning_marker text
1219 See also: attribute/2, comment/2, eof_marker/0, error_marker/1,
1222 form_list/1, function/2, type/1, warning_marker/1.
1223 is_integer(Node::syntaxTree(), Value::integer()) -> boolean()
1225 Returns true if Node has type integer and represents Value, oth‐
1227 erwise false.
1228 See also: integer/1.
1230 is_leaf(Node::syntaxTree()) -> boolean()
1232 Returns true if Node is a leaf node, otherwise false. The cur‐
1234 rently recognised leaf node types are:
1235 atom char comment eof_marker error_marker
1237 float fun_type integer nil operator string
1238 text underscore variable warning_marker
1239 A node of type map_expr is a leaf node if and only if it has no
1242 argument and no fields. A node of type map_type is a leaf node
1243 if and only if it has no fields (any_size). A node of type tuple
1244 is a leaf node if and only if its arity is zero. A node of type
1245 tuple_type is a leaf node if and only if it has no elements
1246 (any_size).
1247 Note: not all literals are leaf nodes, and vice versa. E.g., tu‐
1249 ples with nonzero arity and nonempty lists may be literals, but
1250 are not leaf nodes. Variables, on the other hand, are leaf nodes
1251 but not literals.
1252 See also: is_literal/1, type/1.
1254 is_list_skeleton(Node::syntaxTree()) -> boolean()
1256 Returns true if Node has type list or nil, otherwise false.
1258 See also: list/2, nil/0.
1260 is_literal(T::syntaxTree()) -> boolean()
1262 Returns true if Node represents a literal term, otherwise false.
1264 This function returns true if and only if the value of con‐
1265 crete(Node) is defined.
1266 See also: abstract/1, concrete/1.
1268 is_proper_list(Node::syntaxTree()) -> boolean()
1270 Returns true if Node represents a proper list, and false other‐
1272 wise. A proper list is a list skeleton either on the form "[]"
1273 or "[E1, ..., En]", or "[... | Tail]" where recursively Tail
1274 also represents a proper list.
1275 Note: Since Node is a syntax tree, the actual run-time values
1277 corresponding to its subtrees may often be partially or com‐
1278 pletely unknown. Thus, if Node represents e.g. "[... | Ns]"
1279 (where Ns is a variable), then the function will return false,
1280 because it is not known whether Ns will be bound to a list at
1281 run-time. If Node instead represents e.g. "[1, 2, 3]" or "[A |
1282 []]", then the function will return true.
1283 See also: list/2.
1285 is_string(Node::syntaxTree(), Value::string()) -> boolean()
1287 Returns true if Node has type string and represents Value, oth‐
1289 erwise false.
1290 See also: string/1.
1292 is_tree(Tree::syntaxTree()) -> boolean()
1294 For special purposes only. Returns true if Tree is an abstract
1296 syntax tree and false otherwise.
1297 Note: this function yields false for all "old-style" erl_parse-
1299 compatible "parse trees".
1300 See also: tree/2.
1302 join_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
1304 Tree()
1305 Appends the comments of Source to the current comments of Tar‐
1307 get.
1308 Note: This is equivalent to add_postcomments(get_postcom‐
1310 ments(Source), add_precomments(get_precomments(Source), Tar‐
1311 get)), but potentially more efficient.
1312 See also: add_postcomments/2, add_precomments/2, comment/2,
1314 get_postcomments/1, get_precomments/1.
1315 list(List::[syntaxTree()]) -> syntaxTree()
1317 Equivalent to list(List, none).
1319 list(Elements::[syntaxTree()], Tail::none | syntaxTree()) -> syntax‐
1321 Tree()
1322 Constructs an abstract list skeleton. The result has type list
1324 or nil. If List is a nonempty list [E1, ..., En], the result has
1325 type list and represents either "[E1, ..., En]", if Tail is
1326 none, or otherwise "[E1, ..., En | Tail]". If List is the empty
1327 list, Tail must be none, and in that case the result has type
1328 nil and represents "[]" (see nil/0).
1329 The difference between lists as semantic objects (built up of
1331 individual "cons" and "nil" terms) and the various syntactic
1332 forms for denoting lists may be bewildering at first. This mod‐
1333 ule provides functions both for exact control of the syntactic
1334 representation as well as for the simple composition and decon‐
1335 struction in terms of cons and head/tail operations.
1336 Note: in list(Elements, none), the "nil" list terminator is im‐
1338 plicit and has no associated information (see get_attrs/1),
1339 while in the seemingly equivalent list(Elements, Tail) when Tail
1340 has type nil, the list terminator subtree Tail may have attached
1341 attributes such as position, comments, and annotations, which
1342 will be preserved in the result.
1343 See also: compact_list/1, cons/2, get_attrs/1, is_list_skele‐
1345 ton/1, is_proper_list/1, list/1, list_elements/1, list_head/1,
1346 list_length/1, list_prefix/1, list_suffix/1, list_tail/1, nil/0,
1347 normalize_list/1.
1348 list_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntaxTree()
1350 Creates an abstract list comprehension. If Body is [E1, ...,
1352 En], the result represents "[Template || E1, ..., En]".
1353 See also: generator/2, list_comp_body/1, list_comp_template/1.
1355 list_comp_body(Node::syntaxTree()) -> [syntaxTree()]
1357 Returns the list of body subtrees of a list_comp node.
1359 See also: list_comp/2.
1361 list_comp_template(Node::syntaxTree()) -> syntaxTree()
1363 Returns the template subtree of a list_comp node.
1365 See also: list_comp/2.
1367 list_elements(Node::syntaxTree()) -> [syntaxTree()]
1369 Returns the list of element subtrees of a list skeleton. Node
1371 must represent a proper list. E.g., if Node represents "[X1, X2
1372 | [X3, X4 | []]", then list_elements(Node) yields the list [X1,
1373 X2, X3, X4].
1374 See also: is_proper_list/1, list/2.
1376 list_head(Node::syntaxTree()) -> syntaxTree()
1378 Returns the head element subtree of a list node. If Node repre‐
1380 sents "[Head ...]", the result will represent "Head".
1381 See also: cons/2, list/2, list_tail/1.
1383 list_length(Node::syntaxTree()) -> non_neg_integer()
1385 Returns the number of element subtrees of a list skeleton. Node
1387 must represent a proper list. E.g., if Node represents "[X1 |
1388 [X2, X3 | [X4, X5, X6]]]", then list_length(Node) returns the
1389 integer 6.
1390 Note: this is equivalent to length(list_elements(Node)), but po‐
1392 tentially more efficient.
1393 See also: is_proper_list/1, list/2, list_elements/1.
1395 list_prefix(Node::syntaxTree()) -> [syntaxTree()]
1397 Returns the prefix element subtrees of a list node. If Node rep‐
1399 resents "[E1, ..., En]" or "[E1, ..., En | Tail]", the returned
1400 value is [E1, ..., En].
1401 See also: list/2.
1403 list_suffix(Node::syntaxTree()) -> none | syntaxTree()
1405 Returns the suffix subtree of a list node, if one exists. If
1407 Node represents "[E1, ..., En | Tail]", the returned value is
1408 Tail, otherwise, i.e., if Node represents "[E1, ..., En]", none
1409 is returned.
1410 Note that even if this function returns some Tail that is not
1412 none, the type of Tail can be nil, if the tail has been given
1413 explicitly, and the list skeleton has not been compacted (see
1414 compact_list/1).
1415 See also: compact_list/1, list/2, nil/0.
1417 list_tail(Node::syntaxTree()) -> syntaxTree()
1419 Returns the tail of a list node. If Node represents a single-el‐
1421 ement list "[E]", then the result has type nil, representing
1422 "[]". If Node represents "[E1, E2 ...]", the result will repre‐
1423 sent "[E2 ...]", and if Node represents "[Head | Tail]", the re‐
1424 sult will represent "Tail".
1425 See also: cons/2, list/2, list_head/1.
1427 macro(Name::syntaxTree()) -> syntaxTree()
1429 Equivalent to macro(Name, none).
1431 macro(Name::syntaxTree(), Arguments::none | [syntaxTree()]) -> syntax‐
1433 Tree()
1434 Creates an abstract macro application. If Arguments is none, the
1436 result represents "?Name", otherwise, if Arguments is [A1, ...,
1437 An], the result represents "?Name(A1, ..., An)".
1438 Notes: if Arguments is the empty list, the result will thus rep‐
1440 resent "?Name()", including a pair of matching parentheses.
1441 The only syntactical limitation imposed by the preprocessor on
1443 the arguments to a macro application (viewed as sequences of to‐
1444 kens) is that they must be balanced with respect to parentheses,
1445 brackets, begin ... end, case ... end, etc. The text node type
1446 can be used to represent arguments which are not regular Erlang
1447 constructs.
1448 See also: macro/1, macro_arguments/1, macro_name/1, text/1.
1450 macro_arguments(Node::syntaxTree()) -> none | [syntaxTree()]
1452 Returns the list of argument subtrees of a macro node, if any.
1454 If Node represents "?Name", none is returned. Otherwise, if Node
1455 represents "?Name(A1, ..., An)", [A1, ..., An] is returned.
1456 See also: macro/2.
1458 macro_name(Node::syntaxTree()) -> syntaxTree()
1460 Returns the name subtree of a macro node.
1462 See also: macro/2.
1464 make_tree(X1::atom(), X2::[[syntaxTree()]]) -> syntaxTree()
1466 Creates a syntax tree with the given type and subtrees. Type
1468 must be a node type name (see type/1) that does not denote a
1469 leaf node type (see is_leaf/1). Groups must be a nonempty list
1470 of groups of syntax trees, representing the subtrees of a node
1471 of the given type, in left-to-right order as they would occur in
1472 the printed program text, grouped by category as done by sub‐
1473 trees/1.
1474 The result of copy_attrs(Node, make_tree(type(Node), sub‐
1476 trees(Node))) (see update_tree/2) represents the same source
1477 code text as the original Node, assuming that subtrees(Node)
1478 yields a nonempty list. However, it does not necessarily have
1479 the same data representation as Node.
1480 See also: copy_attrs/2, is_leaf/1, subtrees/1, type/1, up‐
1482 date_tree/2.
1483 map_expr(Fields::[syntaxTree()]) -> syntaxTree()
1485 Equivalent to map_expr(none, Fields).
1487 map_expr(Argument::none | syntaxTree(), Fields::[syntaxTree()]) -> syn‐
1489 taxTree()
1490 Creates an abstract map expression. If Fields is [F1, ..., Fn],
1492 then if Argument is none, the result represents "#{F1, ...,
1493 Fn}", otherwise it represents "Argument#{F1, ..., Fn}".
1494 See also: map_expr/1, map_expr_argument/1, map_expr_fields/1,
1496 map_field_assoc/2, map_field_exact/2.
1497 map_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1499 Returns the argument subtree of a map_expr node, if any. If Node
1501 represents "#{...}", none is returned. Otherwise, if Node repre‐
1502 sents "Argument#{...}", Argument is returned.
1503 See also: map_expr/2.
1505 map_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1507 Returns the list of field subtrees of a map_expr node.
1509 See also: map_expr/2.
1511 map_field_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1513 Tree()
1514 Creates an abstract map assoc field. The result represents "Name
1516 => Value".
1517 See also: map_expr/2, map_field_assoc_name/1, map_field_as‐
1519 soc_value/1.
1520 map_field_assoc_name(Node::syntaxTree()) -> syntaxTree()
1522 Returns the name subtree of a map_field_assoc node.
1524 See also: map_field_assoc/2.
1526 map_field_assoc_value(Node::syntaxTree()) -> syntaxTree()
1528 Returns the value subtree of a map_field_assoc node.
1530 See also: map_field_assoc/2.
1532 map_field_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1534 Tree()
1535 Creates an abstract map exact field. The result represents "Name
1537 := Value".
1538 See also: map_expr/2, map_field_exact_name/1, map_field_ex‐
1540 act_value/1.
1541 map_field_exact_name(Node::syntaxTree()) -> syntaxTree()
1543 Returns the name subtree of a map_field_exact node.
1545 See also: map_field_exact/2.
1547 map_field_exact_value(Node::syntaxTree()) -> syntaxTree()
1549 Returns the value subtree of a map_field_exact node.
1551 See also: map_field_exact/2.
1553 map_type() -> term()
1555 Equivalent to map_type(any_size).
1557 map_type(Fields::any_size | [syntaxTree()]) -> syntaxTree()
1559 Creates an abstract type map. If Fields is [F1, ..., Fn], the
1561 result represents "#{F1, ..., Fn}"; otherwise, if Fields is
1562 any_size, it represents "map()".
1563 See also: map_type_fields/1.
1565 map_type_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1567 Creates an abstract map type assoc field. The result represents
1569 "Name => Value".
1570 See also: map_type/1, map_type_assoc_name/1, map_type_as‐
1572 soc_value/1.
1573 map_type_assoc_name(Node::syntaxTree()) -> syntaxTree()
1575 Returns the name subtree of a map_type_assoc node.
1577 See also: map_type_assoc/2.
1579 map_type_assoc_value(Node::syntaxTree()) -> syntaxTree()
1581 Returns the value subtree of a map_type_assoc node.
1583 See also: map_type_assoc/2.
1585 map_type_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1587 Creates an abstract map type exact field. The result represents
1589 "Name := Value".
1590 See also: map_type/1, map_type_exact_name/1, map_type_ex‐
1592 act_value/1.
1593 map_type_exact_name(Node::syntaxTree()) -> syntaxTree()
1595 Returns the name subtree of a map_type_exact node.
1597 See also: map_type_exact/2.
1599 map_type_exact_value(Node::syntaxTree()) -> syntaxTree()
1601 Returns the value subtree of a map_type_exact node.
1603 See also: map_type_exact/2.
1605 map_type_fields(Node::syntaxTree()) -> any_size | [syntaxTree()]
1607 Returns the list of field subtrees of a map_type node. If Node
1609 represents "map()", any_size is returned; otherwise, if Node
1610 represents "#{F1, ..., Fn}", [F1, ..., Fn] is returned.
1611 See also: map_type/0, map_type/1.
1613 match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
1615 Creates an abstract match-expression. The result represents
1617 "Pattern = Body".
1618 See also: match_expr_body/1, match_expr_pattern/1.
1620 match_expr_body(Node::syntaxTree()) -> syntaxTree()
1622 Returns the body subtree of a match_expr node.
1624 See also: match_expr/2.
1626 match_expr_pattern(Node::syntaxTree()) -> syntaxTree()
1628 Returns the pattern subtree of a match_expr node.
1630 See also: match_expr/2.
1632 meta(T::syntaxTree()) -> syntaxTree()
1634 Creates a meta-representation of a syntax tree. The result rep‐
1636 resents an Erlang expression "MetaTree" which, if evaluated,
1637 will yield a new syntax tree representing the same source code
1638 text as Tree (although the actual data representation may be
1639 different). The expression represented by MetaTree is implemen‐
1640 tation independent with regard to the data structures used by
1641 the abstract syntax tree implementation. Comments attached to
1642 nodes of Tree will be preserved, but other attributes are lost.
1643 Any node in Tree whose node type is variable (see type/1), and
1645 whose list of annotations (see get_ann/1) contains the atom
1646 meta_var, will remain unchanged in the resulting tree, except
1647 that exactly one occurrence of meta_var is removed from its an‐
1648 notation list.
1649 The main use of the function meta/1 is to transform a data
1651 structure Tree, which represents a piece of program code, into a
1652 form that is representation independent when printed. E.g., sup‐
1653 pose Tree represents a variable named "V". Then (assuming a
1654 function print/1 for printing syntax trees), evaluating
1655 print(abstract(Tree)) - simply using abstract/1 to map the ac‐
1656 tual data structure onto a syntax tree representation - would
1657 output a string that might look something like "{tree, variable,
1658 ..., "V", ...}", which is obviously dependent on the implementa‐
1659 tion of the abstract syntax trees. This could e.g. be useful for
1660 caching a syntax tree in a file. However, in some situations
1661 like in a program generator generator (with two "generator"), it
1662 may be unacceptable. Using print(meta(Tree)) instead would out‐
1663 put a representation independent syntax tree generating expres‐
1664 sion; in the above case, something like "erl_syntax:vari‐
1665 able("V")".
1666 See also: abstract/1, get_ann/1, type/1.
1668 module_qualifier(Module::syntaxTree(), Body::syntaxTree()) -> syntax‐
1670 Tree()
1671 Creates an abstract module qualifier. The result represents
1673 "Module:Body".
1674 See also: module_qualifier_argument/1, module_qualifier_body/1.
1676 module_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
1678 Returns the argument (the module) subtree of a module_qualifier
1680 node.
1681 See also: module_qualifier/2.
1683 module_qualifier_body(Node::syntaxTree()) -> syntaxTree()
1685 Returns the body subtree of a module_qualifier node.
1687 See also: module_qualifier/2.
1689 named_fun_expr(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
1691 Tree()
1692 Creates an abstract named fun-expression. If Clauses is [C1,
1694 ..., Cn], the result represents "fun Name C1; ...; Name Cn end".
1695 More exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi",
1696 then the result represents "fun Name(P11, ..., P1m) G1 -> B1;
1697 ...; Name(Pn1, ..., Pnm) Gn -> Bn end".
1698 See also: named_fun_expr_arity/1, named_fun_expr_clauses/1,
1700 named_fun_expr_name/1.
1701 named_fun_expr_arity(Node::syntaxTree()) -> arity()
1703 Returns the arity of a named_fun_expr node. The result is the
1705 number of parameter patterns in the first clause of the named
1706 fun-expression; subsequent clauses are ignored.
1707 An exception is thrown if named_fun_expr_clauses(Node) returns
1709 an empty list, or if the first element of that list is not a
1710 syntax tree C of type clause such that clause_patterns(C) is a
1711 nonempty list.
1712 See also: clause/3, clause_patterns/1, named_fun_expr/2,
1714 named_fun_expr_clauses/1.
1715 named_fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1717 Returns the list of clause subtrees of a named_fun_expr node.
1719 See also: named_fun_expr/2.
1721 named_fun_expr_name(Node::syntaxTree()) -> syntaxTree()
1723 Returns the name subtree of a named_fun_expr node.
1725 See also: named_fun_expr/2.
1727 nil() -> syntaxTree()
1729 Creates an abstract empty list. The result represents "[]". The
1731 empty list is traditionally called "nil".
1732 See also: is_list_skeleton/1, list/2.
1734 normalize_list(Node::syntaxTree()) -> syntaxTree()
1736 Expands an abstract list skeleton to its most explicit form. If
1738 Node represents "[E1, ..., En | Tail]", the result represents
1739 "[E1 | ... [En | Tail1] ... ]", where Tail1 is the result of
1740 normalize_list(Tail). If Node represents "[E1, ..., En]", the
1741 result simply represents "[E1 | ... [En | []] ... ]". If Node
1742 does not represent a list skeleton, Node itself is returned.
1743 See also: compact_list/1, list/2.
1745 operator(Name::atom() | string()) -> syntaxTree()
1747 Creates an abstract operator. The name of the operator is the
1749 character sequence represented by Name. This is analogous to the
1750 print name of an atom, but an operator is never written within
1751 single-quotes; e.g., the result of operator('++') represents
1752 "++" rather than "'++'".
1753 See also: atom/1, operator_literal/1, operator_name/1.
1755 operator_literal(Node::syntaxTree()) -> string()
1757 Returns the literal string represented by an operator node. This
1759 is simply the operator name as a string.
1760 See also: operator/1.
1762 operator_name(Node::syntaxTree()) -> atom()
1764 Returns the name of an operator node. Note that the name is re‐
1766 turned as an atom.
1767 See also: operator/1.
1769 parentheses(Expr::syntaxTree()) -> syntaxTree()
1771 Creates an abstract parenthesised expression. The result repre‐
1773 sents "(Body)", independently of the context.
1774 See also: parentheses_body/1.
1776 parentheses_body(Node::syntaxTree()) -> syntaxTree()
1778 Returns the body subtree of a parentheses node.
1780 See also: parentheses/1.
1782 prefix_expr(Operator::syntaxTree(), Argument::syntaxTree()) -> syntax‐
1784 Tree()
1785 Creates an abstract prefix operator expression. The result rep‐
1787 resents "Operator Argument".
1788 See also: infix_expr/3, prefix_expr_argument/1, prefix_expr_op‐
1790 erator/1.
1791 prefix_expr_argument(Node::syntaxTree()) -> syntaxTree()
1793 Returns the argument subtree of a prefix_expr node.
1795 See also: prefix_expr/2.
1797 prefix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1799 Returns the operator subtree of a prefix_expr node.
1801 See also: prefix_expr/2.
1803 receive_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1805 Equivalent to receive_expr(Clauses, none, []).
1807 receive_expr(Clauses::[syntaxTree()], Timeout::none | syntaxTree(), Ac‐
1809 tion::[syntaxTree()]) -> syntaxTree()
1810 Creates an abstract receive-expression. If Timeout is none, the
1812 result represents "receive C1; ...; Cn end" (the Action argument
1813 is ignored). Otherwise, if Clauses is [C1, ..., Cn] and Action
1814 is [A1, ..., Am], the result represents "receive C1; ...; Cn af‐
1815 ter Timeout -> A1, ..., Am end". More exactly, if each Ci repre‐
1816 sents "(Pi) Gi -> Bi", then the result represents "receive P1 G1
1817 -> B1; ...; Pn Gn -> Bn ... end".
1818 Note that in Erlang, a receive-expression must have at least one
1820 clause if no timeout part is specified.
1821 See also: case_expr/2, clause/3, receive_expr/1, re‐
1823 ceive_expr_action/1, receive_expr_clauses/1, receive_expr_time‐
1824 out/1.
1825 receive_expr_action(Node::syntaxTree()) -> [syntaxTree()]
1827 Returns the list of action body subtrees of a receive_expr node.
1829 If Node represents "receive C1; ...; Cn end", this is the empty
1830 list.
1831 See also: receive_expr/3.
1833 receive_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1835 Returns the list of clause subtrees of a receive_expr node.
1837 See also: receive_expr/3.
1839 receive_expr_timeout(Node::syntaxTree()) -> none | syntaxTree()
1841 Returns the timeout subtree of a receive_expr node, if any. If
1843 Node represents "receive C1; ...; Cn end", none is returned.
1844 Otherwise, if Node represents "receive C1; ...; Cn after Timeout
1845 -> ... end", Timeout is returned.
1846 See also: receive_expr/3.
1848 record_access(Argument::syntaxTree(), Type::syntaxTree(), Field::syn‐
1850 taxTree()) -> syntaxTree()
1851 Creates an abstract record field access expression. The result
1853 represents "Argument#Type.Field".
1854 See also: record_access_argument/1, record_access_field/1,
1856 record_access_type/1, record_expr/3.
1857 record_access_argument(Node::syntaxTree()) -> syntaxTree()
1859 Returns the argument subtree of a record_access node.
1861 See also: record_access/3.
1863 record_access_field(Node::syntaxTree()) -> syntaxTree()
1865 Returns the field subtree of a record_access node.
1867 See also: record_access/3.
1869 record_access_type(Node::syntaxTree()) -> syntaxTree()
1871 Returns the type subtree of a record_access node.
1873 See also: record_access/3.
1875 record_expr(Type::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1877 Equivalent to record_expr(none, Type, Fields).
1879 record_expr(Argument::none | syntaxTree(), Type::syntaxTree(),
1881 Fields::[syntaxTree()]) -> syntaxTree()
1882 Creates an abstract record expression. If Fields is [F1, ...,
1884 Fn], then if Argument is none, the result represents "#Type{F1,
1885 ..., Fn}", otherwise it represents "Argument#Type{F1, ..., Fn}".
1886 See also: record_access/3, record_expr/2, record_expr_argu‐
1888 ment/1, record_expr_fields/1, record_expr_type/1,
1889 record_field/2, record_index_expr/2.
1890 record_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1892 Returns the argument subtree of a record_expr node, if any. If
1894 Node represents "#Type{...}", none is returned. Otherwise, if
1895 Node represents "Argument#Type{...}", Argument is returned.
1896 See also: record_expr/3.
1898 record_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1900 Returns the list of field subtrees of a record_expr node.
1902 See also: record_expr/3.
1904 record_expr_type(Node::syntaxTree()) -> syntaxTree()
1906 Returns the type subtree of a record_expr node.
1908 See also: record_expr/3.
1910 record_field(Name::syntaxTree()) -> syntaxTree()
1912 Equivalent to record_field(Name, none).
1914 record_field(Name::syntaxTree(), Value::none | syntaxTree()) -> syntax‐
1916 Tree()
1917 Creates an abstract record field specification. If Value is
1919 none, the result represents simply "Name", otherwise it repre‐
1920 sents "Name = Value".
1921 See also: record_expr/3, record_field_name/1,
1923 record_field_value/1.
1924 record_field_name(Node::syntaxTree()) -> syntaxTree()
1926 Returns the name subtree of a record_field node.
1928 See also: record_field/2.
1930 record_field_value(Node::syntaxTree()) -> none | syntaxTree()
1932 Returns the value subtree of a record_field node, if any. If
1934 Node represents "Name", none is returned. Otherwise, if Node
1935 represents "Name = Value", Value is returned.
1936 See also: record_field/2.
1938 record_index_expr(Type::syntaxTree(), Field::syntaxTree()) -> syntax‐
1940 Tree()
1941 Creates an abstract record field index expression. The result
1943 represents "#Type.Field".
1944 (Note: the function name record_index/2 is reserved by the Er‐
1946 lang compiler, which is why that name could not be used for this
1947 constructor.)
1948 See also: record_expr/3, record_index_expr_field/1, record_in‐
1950 dex_expr_type/1.
1951 record_index_expr_field(Node::syntaxTree()) -> syntaxTree()
1953 Returns the field subtree of a record_index_expr node.
1955 See also: record_index_expr/2.
1957 record_index_expr_type(Node::syntaxTree()) -> syntaxTree()
1959 Returns the type subtree of a record_index_expr node.
1961 See also: record_index_expr/2.
1963 record_type(Name::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1965 Creates an abstract record type. If Fields is [F1, ..., Fn], the
1967 result represents "#Name{F1, ..., Fn}".
1968 See also: record_type_fields/1, record_type_name/1.
1970 record_type_field(Name::syntaxTree(), Type::syntaxTree()) -> syntax‐
1972 Tree()
1973 Creates an abstract record type field. The result represents
1975 "Name :: Type".
1976 See also: record_type_field_name/1, record_type_field_type/1.
1978 record_type_field_name(Node::syntaxTree()) -> syntaxTree()
1980 Returns the name subtree of a record_type_field node.
1982 See also: record_type_field/2.
1984 record_type_field_type(Node::syntaxTree()) -> syntaxTree()
1986 Returns the type subtree of a record_type_field node.
1988 See also: record_type_field/2.
1990 record_type_fields(Node::syntaxTree()) -> [syntaxTree()]
1992 Returns the fields subtree of a record_type node.
1994 See also: record_type/2.
1996 record_type_name(Node::syntaxTree()) -> syntaxTree()
1998 Returns the name subtree of a record_type node.
2000 See also: record_type/2.
2002 remove_comments(Node::syntaxTree()) -> syntaxTree()
2004 Clears the associated comments of Node.
2006 Note: This is equivalent to set_precomments(set_postcom‐
2008 ments(Node, []), []), but potentially more efficient.
2009 See also: set_postcomments/2, set_precomments/2.
2011 revert(Node::syntaxTree()) -> syntaxTree()
2013 Returns an erl_parse-compatible representation of a syntax tree,
2015 if possible. If Tree represents a well-formed Erlang program or
2016 expression, the conversion should work without problems. Typi‐
2017 cally, is_tree/1 yields true if conversion failed (i.e., the re‐
2018 sult is still an abstract syntax tree), and false otherwise.
2019 The is_tree/1 test is not completely foolproof. For a few spe‐
2021 cial node types (e.g. arity_qualifier), if such a node occurs in
2022 a context where it is not expected, it will be left unchanged as
2023 a non-reverted subtree of the result. This can only happen if
2024 Tree does not actually represent legal Erlang code.
2025 See also: erl_parse(3), revert_forms/1.
2027 revert_forms(Forms::forms()) -> [erl_parse()]
2029 Reverts a sequence of Erlang source code forms. The sequence can
2031 be given either as a form_list syntax tree (possibly nested), or
2032 as a list of "program form" syntax trees. If successful, the
2033 corresponding flat list of erl_parse-compatible syntax trees is
2034 returned (see revert/1). If some program form could not be re‐
2035 verted, {error, Form} is thrown. Standalone comments in the form
2036 sequence are discarded.
2037 See also: form_list/1, is_form/1, revert/1.
2039 set_ann(Node::syntaxTree(), As::[term()]) -> syntaxTree()
2041 Sets the list of user annotations of Node to Annotations.
2043 See also: add_ann/2, copy_ann/2, get_ann/1.
2045 set_attrs(Node::syntaxTree(), Attr::syntaxTreeAttributes()) -> syntax‐
2047 Tree()
2048 Sets the attributes of Node to Attributes.
2050 See also: copy_attrs/2, get_attrs/1.
2052 set_pos(Node::syntaxTree(), Pos::annotation_or_location()) -> syntax‐
2054 Tree()
2055 Sets the position information of Node to Pos.
2057 See also: copy_pos/2, get_pos/1.
2059 set_postcomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntax‐
2061 Tree()
2062 Sets the post-comments of Node to Comments. Comments should be a
2064 possibly empty list of abstract comments, in top-down textual
2065 order
2066 See also: add_postcomments/2, comment/2, copy_comments/2,
2068 get_postcomments/1, join_comments/2, remove_comments/1, set_pre‐
2069 comments/2.
2070 set_precomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntaxTree()
2072 Sets the pre-comments of Node to Comments. Comments should be a
2074 possibly empty list of abstract comments, in top-down textual
2075 order.
2076 See also: add_precomments/2, comment/2, copy_comments/2,
2078 get_precomments/1, join_comments/2, remove_comments/1, set_post‐
2079 comments/2.
2080 size_qualifier(Body::syntaxTree(), Size::syntaxTree()) -> syntaxTree()
2082 Creates an abstract size qualifier. The result represents
2084 "Body:Size".
2085 See also: size_qualifier_argument/1, size_qualifier_body/1.
2087 size_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
2089 Returns the argument subtree (the size) of a size_qualifier
2091 node.
2092 See also: size_qualifier/2.
2094 size_qualifier_body(Node::syntaxTree()) -> syntaxTree()
2096 Returns the body subtree of a size_qualifier node.
2098 See also: size_qualifier/2.
2100 string(String::string()) -> syntaxTree()
2102 Creates an abstract string literal. The result represents "Text"
2104 (including the surrounding double-quotes), where Text corre‐
2105 sponds to the sequence of characters in Value, but not repre‐
2106 senting a specific string literal.
2107 For example, the result of string("x\ny") represents any and all
2109 of "x\ny", "x\12y", "x\012y" and "x\^Jy"; see char/1.
2110 See also: char/1, is_string/2, string_literal/1, string_lit‐
2112 eral/2, string_value/1.
2113 string_literal(Node::syntaxTree()) -> nonempty_string()
2115 Returns the literal string represented by a string node. This
2117 includes surrounding double-quote characters. Characters beyond
2118 255 will be escaped.
2119 See also: string/1.
2121 string_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
2123 Returns the literal string represented by a string node. This
2125 includes surrounding double-quote characters. Depending on the
2126 encoding characters beyond 255 will be escaped (latin1) or
2127 copied as is (utf8).
2128 See also: string/1.
2130 string_value(Node::syntaxTree()) -> string()
2132 Returns the value represented by a string node.
2134 See also: string/1.
2136 subtrees(T::syntaxTree()) -> [[syntaxTree()]]
2138 Returns the grouped list of all subtrees of a syntax tree. If
2140 Node is a leaf node (see is_leaf/1), this is the empty list,
2141 otherwise the result is always a nonempty list, containing the
2142 lists of subtrees of Node, in left-to-right order as they occur
2143 in the printed program text, and grouped by category. Often,
2144 each group contains only a single subtree.
2145 Depending on the type of Node, the size of some groups may be
2147 variable (e.g., the group consisting of all the elements of a
2148 tuple), while others always contain the same number of elements
2149 - usually exactly one (e.g., the group containing the argument
2150 expression of a case-expression). Note, however, that the exact
2151 structure of the returned list (for a given node type) should in
2152 general not be depended upon, since it might be subject to
2153 change without notice.
2154 The function subtrees/1 and the constructor functions
2156 make_tree/2 and update_tree/2 can be a great help if one wants
2157 to traverse a syntax tree, visiting all its subtrees, but treat
2158 nodes of the tree in a uniform way in most or all cases. Using
2159 these functions makes this simple, and also assures that your
2160 code is not overly sensitive to extensions of the syntax tree
2161 data type, because any node types not explicitly handled by your
2162 code can be left to a default case.
2163 For example:
2165 postorder(F, Tree) ->
2167 F(case subtrees(Tree) of
2168 [] -> Tree;
2169 List -> update_tree(Tree,
2170 [[postorder(F, Subtree)
2171 || Subtree <- Group]
2172 || Group <- List])
2173 end).
2174 maps the function F on Tree and all its subtrees, doing a post-
2176 order traversal of the syntax tree. (Note the use of up‐
2177 date_tree/2 to preserve node attributes.) For a simple function
2178 like:
2179 f(Node) ->
2181 case type(Node) of
2182 atom -> atom("a_" ++ atom_name(Node));
2183 _ -> Node
2184 end.
2185 the call postorder(fun f/1, Tree) will yield a new representa‐
2187 tion of Tree in which all atom names have been extended with the
2188 prefix "a_", but nothing else (including comments, annotations
2189 and line numbers) has been changed.
2190 See also: copy_attrs/2, is_leaf/1, make_tree/2, type/1.
2192 text(String::string()) -> syntaxTree()
2194 Creates an abstract piece of source code text. The result repre‐
2196 sents exactly the sequence of characters in String. This is use‐
2197 ful in cases when one wants full control of the resulting out‐
2198 put, e.g., for the appearance of floating-point numbers or macro
2199 definitions.
2200 See also: text_string/1.
2202 text_string(Node::syntaxTree()) -> string()
2204 Returns the character sequence represented by a text node.
2206 See also: text/1.
2208 tree(Type::atom()) -> tree()
2210 Equivalent to tree(Type, []).
2212 tree(Type::atom(), Data::term()) -> tree()
2214 For special purposes only. Creates an abstract syntax tree node
2216 with type tag Type and associated data Data.
2217 This function and the related is_tree/1 and data/1 provide a
2219 uniform way to extend the set of erl_parse node types. The asso‐
2220 ciated data is any term, whose format may depend on the type
2221 tag.
2222 Notes:
2224 * Any nodes created outside of this module must have type tags
2226 distinct from those currently defined by this module; see
2227 type/1 for a complete list.
2228 * The type tag of a syntax tree node may also be used as a
2230 primary tag by the erl_parse representation; in that case,
2231 the selector functions for that node type must handle both
2232 the abstract syntax tree and the erl_parse form. The func‐
2233 tion type(T) should return the correct type tag regardless
2234 of the representation of T, so that the user sees no differ‐
2235 ence between erl_syntax and erl_parse nodes.
2236 See also: data/1, is_tree/1, type/1.
2238 try_after_expr(Body::[syntaxTree()], After::[syntaxTree()]) -> syntax‐
2240 Tree()
2241 Equivalent to try_expr(Body, [], [], After).
2243 try_expr(Body::[syntaxTree()], Handlers::[syntaxTree()]) -> syntax‐
2245 Tree()
2246 Equivalent to try_expr(Body, [], Handlers).
2248 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2250 taxTree()]) -> syntaxTree()
2251 Equivalent to try_expr(Body, Clauses, Handlers, []).
2253 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2255 taxTree()], After::[syntaxTree()]) -> syntaxTree()
2256 Creates an abstract try-expression. If Body is [B1, ..., Bn],
2258 Clauses is [C1, ..., Cj], Handlers is [H1, ..., Hk], and After
2259 is [A1, ..., Am], the result represents "try B1, ..., Bn of C1;
2260 ...; Cj catch H1; ...; Hk after A1, ..., Am end". More exactly,
2261 if each Ci represents "(CPi) CGi -> CBi", and each Hi represents
2262 "(HPi) HGi -> HBi", then the result represents "try B1, ..., Bn
2263 of CP1 CG1 -> CB1; ...; CPj CGj -> CBj catch HP1 HG1 -> HB1;
2264 ...; HPk HGk -> HBk after A1, ..., Am end"; see case_expr/2. If
2265 Clauses is the empty list, the of ... section is left out. If
2266 After is the empty list, the after ... section is left out. If
2267 Handlers is the empty list, and After is nonempty, the catch ...
2268 section is left out.
2269 See also: case_expr/2, class_qualifier/2, clause/3, try_af‐
2271 ter_expr/2, try_expr/2, try_expr/3, try_expr_after/1,
2272 try_expr_body/1, try_expr_clauses/1, try_expr_handlers/1.
2273 try_expr_after(Node::syntaxTree()) -> [syntaxTree()]
2275 Returns the list of "after" subtrees of a try_expr node.
2277 See also: try_expr/4.
2279 try_expr_body(Node::syntaxTree()) -> [syntaxTree()]
2281 Returns the list of body subtrees of a try_expr node.
2283 See also: try_expr/4.
2285 try_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
2287 Returns the list of case-clause subtrees of a try_expr node. If
2289 Node represents "try Body catch H1; ...; Hn end", the result is
2290 the empty list.
2291 See also: try_expr/4.
2293 try_expr_handlers(Node::syntaxTree()) -> [syntaxTree()]
2295 Returns the list of handler-clause subtrees of a try_expr node.
2297 See also: try_expr/4.
2299 tuple(List::[syntaxTree()]) -> syntaxTree()
2301 Creates an abstract tuple. If Elements is [X1, ..., Xn], the re‐
2303 sult represents "{X1, ..., Xn}".
2304 Note: The Erlang language has distinct 1-tuples, i.e., {X} is
2306 always distinct from X itself.
2307 See also: tuple_elements/1, tuple_size/1.
2309 tuple_elements(Node::syntaxTree()) -> [syntaxTree()]
2311 Returns the list of element subtrees of a tuple node.
2313 See also: tuple/1.
2315 tuple_size(Node::syntaxTree()) -> non_neg_integer()
2317 Returns the number of elements of a tuple node.
2319 Note: this is equivalent to length(tuple_elements(Node)), but
2321 potentially more efficient.
2322 See also: tuple/1, tuple_elements/1.
2324 tuple_type() -> term()
2326 Equivalent to tuple_type(any_size).
2328 tuple_type(Elements::any_size | [syntaxTree()]) -> syntaxTree()
2330 Creates an abstract type tuple. If Elements is [T1, ..., Tn],
2332 the result represents "{T1, ..., Tn}"; otherwise, if Elements is
2333 any_size, it represents "tuple()".
2334 See also: tuple_type_elements/1.
2336 tuple_type_elements(Node::syntaxTree()) -> any_size | [syntaxTree()]
2338 Returns the list of type element subtrees of a tuple_type node.
2340 If Node represents "tuple()", any_size is returned; otherwise,
2341 if Node represents "{T1, ..., Tn}", [T1, ..., Tn] is returned.
2342 See also: tuple_type/0, tuple_type/1.
2344 type(Tree::syntaxTree()) -> atom()
2346 Returns the type tag of Node. If Node does not represent a syn‐
2348 tax tree, evaluation fails with reason badarg. Node types cur‐
2349 rently defined by this module are:
2350 application annotated_type arity_qualifier atom
2352 attribute binary binary_field bitstring_type
2353 block_expr case_expr catch_expr char
2354 class_qualifier clause comment conjunction
2355 constrained_function_type constraint disjunction eof_marker
2356 error_marker float form_list fun_expr
2357 fun_type function function_type generator
2358 if_expr implicit_fun infix_expr integer
2359 integer_range_type list list_comp macro
2360 map_expr map_field_assoc map_field_exact map_type
2361 map_type_assoc map_type_exact match_expr module_qualifier
2362 named_fun_expr nil operator parentheses
2363 prefix_expr receive_expr record_access record_expr
2364 record_field record_index_expr record_type record_type_field
2365 size_qualifier string text try_expr
2366 tuple tuple_type typed_record_field type_application
2367 type_union underscore user_type_application variable
2368 warning_marker
2369 The user may (for special purposes) create additional nodes with
2372 other type tags, using the tree/2 function.
2373 Note: The primary constructor functions for a node type should
2375 always have the same name as the node type itself.
2376 See also: annotated_type/2, application/3, arity_qualifier/2,
2378 atom/1, attribute/2, binary/1, binary_field/2, bitstring_type/2,
2379 block_expr/1, case_expr/2, catch_expr/1, char/1, class_quali‐
2380 fier/2, clause/3, comment/2, conjunction/1, constrained_func‐
2381 tion_type/2, constraint/2, disjunction/1, eof_marker/0, er‐
2382 ror_marker/1, float/1, form_list/1, fun_expr/1, fun_type/0,
2383 function/2, function_type/1, function_type/2, generator/2,
2384 if_expr/1, implicit_fun/2, infix_expr/3, integer/1, inte‐
2385 ger_range_type/2, list/2, list_comp/2, macro/2, map_expr/2,
2386 map_field_assoc/2, map_field_exact/2, map_type/0, map_type/1,
2387 map_type_assoc/2, map_type_exact/2, match_expr/2, module_quali‐
2388 fier/2, named_fun_expr/2, nil/0, operator/1, parentheses/1, pre‐
2389 fix_expr/2, receive_expr/3, record_access/3, record_expr/2,
2390 record_field/2, record_index_expr/2, record_type/2,
2391 record_type_field/2, size_qualifier/2, string/1, text/1, tree/2,
2392 try_expr/3, tuple/1, tuple_type/0, tuple_type/1, type_applica‐
2393 tion/2, type_union/1, typed_record_field/2, underscore/0,
2394 user_type_application/2, variable/1, warning_marker/1.
2395 type_application(TypeName::syntaxTree(), Arguments::[syntaxTree()]) ->
2397 syntaxTree()
2398 Creates an abstract type application expression. If Arguments is
2400 [T1, ..., Tn], the result represents "TypeName(T1, ...Tn)".
2401 See also: type_application/3, type_application_arguments/1,
2403 type_application_name/1, user_type_application/2.
2404 type_application(Module::none | syntaxTree(), TypeName::syntaxTree(),
2406 Arguments::[syntaxTree()]) -> syntaxTree()
2407 Creates an abstract type application expression. If Module is
2409 none, this is call is equivalent to type_application(TypeName,
2410 Arguments), otherwise it is equivalent to type_application(mod‐
2411 ule_qualifier(Module, TypeName), Arguments).
2412 (This is a utility function.)
2414 See also: module_qualifier/2, type_application/2.
2416 type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2418 Returns the arguments subtrees of a type_application node.
2420 See also: type_application/2.
2422 type_application_name(Node::syntaxTree()) -> syntaxTree()
2424 Returns the type name subtree of a type_application node.
2426 See also: type_application/2.
2428 type_union(Types::[syntaxTree()]) -> syntaxTree()
2430 Creates an abstract type union. If Types is [T1, ..., Tn], the
2432 result represents "T1 | ... | Tn".
2433 See also: type_union_types/1.
2435 type_union_types(Node::syntaxTree()) -> [syntaxTree()]
2437 Returns the list of type subtrees of a type_union node.
2439 See also: type_union/1.
2441 typed_record_field(Field::syntaxTree(), Type::syntaxTree()) -> syntax‐
2443 Tree()
2444 Creates an abstract typed record field specification. The result
2446 represents "Field :: Type".
2447 See also: typed_record_field_body/1, typed_record_field_type/1.
2449 typed_record_field_body(Node::syntaxTree()) -> syntaxTree()
2451 Returns the field subtree of a typed_record_field node.
2453 See also: typed_record_field/2.
2455 typed_record_field_type(Node::syntaxTree()) -> syntaxTree()
2457 Returns the type subtree of a typed_record_field node.
2459 See also: typed_record_field/2.
2461 underscore() -> syntaxTree()
2463 Creates an abstract universal pattern ("_"). The lexical repre‐
2465 sentation is a single underscore character. Note that this is
2466 not a variable, lexically speaking.
2467 See also: variable/1.
2469 update_tree(Node::syntaxTree(), Groups::[[syntaxTree()]]) -> syntax‐
2471 Tree()
2472 Creates a syntax tree with the same type and attributes as the
2474 given tree. This is equivalent to copy_attrs(Node,
2475 make_tree(type(Node), Groups)).
2476 See also: copy_attrs/2, make_tree/2, type/1.
2478 user_type_application(TypeName::syntaxTree(), Arguments::[syntax‐
2480 Tree()]) -> syntaxTree()
2481 Creates an abstract user type. If Arguments is [T1, ..., Tn],
2483 the result represents "TypeName(T1, ...Tn)".
2484 See also: type_application/2, user_type_application_arguments/1,
2486 user_type_application_name/1.
2487 user_type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2489 Returns the arguments subtrees of a user_type_application node.
2491 See also: user_type_application/2.
2493 user_type_application_name(Node::syntaxTree()) -> syntaxTree()
2495 Returns the type name subtree of a user_type_application node.
2497 See also: user_type_application/2.
2499 variable(Name::atom() | string()) -> syntaxTree()
2501 Creates an abstract variable with the given name. Name may be
2503 any atom or string that represents a lexically valid variable
2504 name, but not a single underscore character; see underscore/0.
2505 Note: no checking is done whether the character sequence repre‐
2507 sents a proper variable name, i.e., whether or not its first
2508 character is an uppercase Erlang character, or whether it does
2509 not contain control characters, whitespace, etc.
2510 See also: underscore/0, variable_literal/1, variable_name/1.
2512 variable_literal(Node::syntaxTree()) -> string()
2514 Returns the name of a variable node as a string.
2516 See also: variable/1.
2518 variable_name(Node::syntaxTree()) -> atom()
2520 Returns the name of a variable node as an atom.
2522 See also: variable/1.
2524 warning_marker(Warning::term()) -> syntaxTree()
2526 Creates an abstract warning marker. The result represents an oc‐
2528 currence of a possible problem in the source code, with an asso‐
2529 ciated Erlang I/O ErrorInfo structure given by Error (see module
2530 io(3) for details). Warning markers are regarded as source code
2531 forms, but have no defined lexical form.
2532 Note: this is supported only for backwards compatibility with
2534 existing parsers and tools.
2535 See also: eof_marker/0, error_marker/1, is_form/1, warn‐
2537 ing_marker_info/1.
2538 warning_marker_info(Node::syntaxTree()) -> term()
2540 Returns the ErrorInfo structure of a warning_marker node.
2542 See also: warning_marker/1.
2544
2546 Richard Carlsson <carlsson.richard@gmail.com>
2547 syntax_tools 2.6 erl_syntax(3)