1erl_syntax(3) Erlang Module Definition erl_syntax(3)
2
6 erl_syntax - Abstract Erlang syntax trees.
7
9 Abstract Erlang syntax trees.
10 This module defines an abstract data type for representing Erlang
12 source code as syntax trees, in a way that is backwards compatible with
13 the data structures created by the Erlang standard library parser mod‐
14 ule erl_parse (often referred to as "parse trees", which is a bit of a
15 misnomer). This means that all erl_parse trees are valid abstract syn‐
16 tax trees, but the reverse is not true: abstract syntax trees can in
17 general not be used as input to functions expecting an erl_parse tree.
18 However, as long as an abstract syntax tree represents a correct Erlang
19 program, the function revert/1 should be able to transform it to the
20 corresponding erl_parse representation.
21 A recommended starting point for the first-time user is the documenta‐
23 tion of the syntaxTree() data type, and the function type/1.
24 NOTES:
26 This module deals with the composition and decomposition of syntactic
28 entities (as opposed to semantic ones); its purpose is to hide all
29 direct references to the data structures used to represent these enti‐
30 ties. With few exceptions, the functions in this module perform no
31 semantic interpretation of their inputs, and in general, the user is
32 assumed to pass type-correct arguments - if this is not done, the
33 effects are not defined.
34 With the exception of the erl_parse() data structures, the internal
36 representations of abstract syntax trees are subject to change without
37 notice, and should not be documented outside this module. Furthermore,
38 we do not give any guarantees on how an abstract syntax tree may or may
39 not be represented, with the following exceptions: no syntax tree is
40 represented by a single atom, such as none, by a list constructor [X |
41 Y], or by the empty list []. This can be relied on when writing func‐
42 tions that operate on syntax trees.
43
45 encoding() = utf8 | unicode | latin1:
46 erl_parse() = erl_parse:abstract_clause() | erl_parse:abstract_expr()
49 | erl_parse:abstract_form() | erl_parse:abstract_type() |
50 erl_parse:form_info() | {bin_element, term(), term(), term(),
51 term()}:
52 forms() = syntaxTree() | [syntaxTree()]:
55 guard() = none | syntaxTree() | [syntaxTree()] | [[syntaxTree()]]:
58 padding() = none | integer():
61 syntaxTree():
64 An abstract syntax tree. The erl_parse() "parse tree" representa‐
67 tion is a proper subset of the syntaxTree() representation.
68 Every abstract syntax tree node has a type, given by the function
70 type/1. Each node also has associated attributes; see get_attrs/1
71 for details. The functions make_tree/2 and subtrees/1 are generic
72 constructor/decomposition functions for abstract syntax trees. The
73 functions abstract/1 and concrete/1 convert between constant Erlang
74 terms and their syntactic representations. The set of syntax tree
75 nodes is extensible through the tree/2 function.
76 A syntax tree can be transformed to the erl_parse() representation
78 with the revert/1 function.
79 syntaxTreeAttributes():
81 This is an abstract representation of syntax tree node attributes;
84 see the function get_attrs/1.
85
87 abstract(T::term()) -> syntaxTree()
88 Returns the syntax tree corresponding to an Erlang term. Term
90 must be a literal term, i.e., one that can be represented as a
91 source code literal. Thus, it may not contain a process identi‐
92 fier, port, reference, binary or function value as a subterm.
93 The function recognises printable strings, in order to get a
94 compact and readable representation. Evaluation fails with rea‐
95 son badarg if Term is not a literal term.
96 See also: concrete/1, is_literal/1.
98 add_ann(A::term(), Node::syntaxTree()) -> syntaxTree()
100 Appends the term Annotation to the list of user annotations of
102 Node.
103 Note: this is equivalent to set_ann(Node, [Annotation |
105 get_ann(Node)]), but potentially more efficient.
106 See also: get_ann/1, set_ann/2.
108 add_postcomments(Cs::[syntaxTree()], Node::syntaxTree()) -> syntax‐
110 Tree()
111 Appends Comments to the post-comments of Node.
113 Note: This is equivalent to set_postcomments(Node, get_postcom‐
115 ments(Node) ++ Comments), but potentially more efficient.
116 See also: add_precomments/2, comment/2, get_postcomments/1,
118 join_comments/2, set_postcomments/2.
119 add_precomments(Cs::[syntaxTree()], Node::syntaxTree()) -> syntaxTree()
121 Appends Comments to the pre-comments of Node.
123 Note: This is equivalent to set_precomments(Node, get_precom‐
125 ments(Node) ++ Comments), but potentially more efficient.
126 See also: add_postcomments/2, comment/2, get_precomments/1,
128 join_comments/2, set_precomments/2.
129 annotated_type(Name::syntaxTree(), Type::syntaxTree()) -> syntaxTree()
131 Creates an abstract annotated type expression. The result repre‐
133 sents "Name :: Type".
134 See also: annotated_type_body/1, annotated_type_name/1.
136 annotated_type_body(Node::syntaxTree()) -> syntaxTree()
138 Returns the type subtrees of an annotated_type node.
140 See also: annotated_type/2.
142 annotated_type_name(Node::syntaxTree()) -> syntaxTree()
144 Returns the name subtree of an annotated_type node.
146 See also: annotated_type/2.
148 application(Operator::syntaxTree(), Arguments::[syntaxTree()]) -> syn‐
150 taxTree()
151 Creates an abstract function application expression. If Argu‐
153 ments is [A1, ..., An], the result represents "Operator(A1, ...,
154 An)".
155 See also: application/3, application_arguments/1, applica‐
157 tion_operator/1.
158 application(Module::none | syntaxTree(), Name::syntaxTree(), Argu‐
160 ments::[syntaxTree()]) -> syntaxTree()
161 Creates an abstract function application expression. If Module
163 is none, this is call is equivalent to application(Function,
164 Arguments), otherwise it is equivalent to application(mod‐
165 ule_qualifier(Module, Function), Arguments).
166 (This is a utility function.)
168 See also: application/2, module_qualifier/2.
170 application_arguments(Node::syntaxTree()) -> [syntaxTree()]
172 Returns the list of argument subtrees of an application node.
174 See also: application/2.
176 application_operator(Node::syntaxTree()) -> syntaxTree()
178 Returns the operator subtree of an application node.
180 Note: if Node represents "M:F(...)", then the result is the sub‐
182 tree representing "M:F".
183 See also: application/2, module_qualifier/2.
185 arity_qualifier(Body::syntaxTree(), Arity::syntaxTree()) -> syntax‐
187 Tree()
188 Creates an abstract arity qualifier. The result represents
190 "Body/Arity".
191 See also: arity_qualifier_argument/1, arity_qualifier_body/1.
193 arity_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
195 Returns the argument (the arity) subtree of an arity_qualifier
197 node.
198 See also: arity_qualifier/2.
200 arity_qualifier_body(Node::syntaxTree()) -> syntaxTree()
202 Returns the body subtree of an arity_qualifier node.
204 See also: arity_qualifier/2.
206 atom(Name::atom() | string()) -> syntaxTree()
208 Creates an abstract atom literal. The print name of the atom is
210 the character sequence represented by Name.
211 See also: atom_literal/1, atom_literal/2, atom_name/1,
213 atom_value/1, is_atom/2.
214 atom_literal(Node::syntaxTree()) -> string()
216 Returns the literal string represented by an atom node. This
218 includes surrounding single-quote characters if necessary. Char‐
219 acters beyond 255 will be escaped.
220 Note that e.g. the result of atom("x\ny") represents any and all
222 of `x\ny'', `x\12y'', `x\012y'' and `x\^Jy\''; see string/1.
223 See also: atom/1, string/1.
225 atom_literal(Node, X2) -> term()
227 Returns the literal string represented by an atom node. This
229 includes surrounding single-quote characters if necessary.
230 Depending on the encoding a character beyond 255 will be escaped
231 (latin1) or copied as is (utf8).
232 See also: atom/1, atom_literal/1, string/1.
234 atom_name(Node::syntaxTree()) -> string()
236 Returns the printname of an atom node.
238 See also: atom/1.
240 atom_value(Node::syntaxTree()) -> atom()
242 Returns the value represented by an atom node.
244 See also: atom/1.
246 attribute(Name::syntaxTree()) -> syntaxTree()
248 Equivalent to attribute(Name, none).
250 attribute(Name::syntaxTree(), Args::none | [syntaxTree()]) -> syntax‐
252 Tree()
253 Creates an abstract program attribute. If Arguments is [A1, ...,
255 An], the result represents "-Name(A1, ..., An).". Otherwise, if
256 Arguments is none, the result represents "-Name.". The latter
257 form makes it possible to represent preprocessor directives such
258 as "-endif.". Attributes are source code forms.
259 Note: The preprocessor macro definition directive "-define(Name,
261 Body)." has relatively few requirements on the syntactical form
262 of Body (viewed as a sequence of tokens). The text node type can
263 be used for a Body that is not a normal Erlang construct.
264 See also: attribute/1, attribute_arguments/1, attribute_name/1,
266 is_form/1, text/1.
267 attribute_arguments(Node::syntaxTree()) -> none | [syntaxTree()]
269 Returns the list of argument subtrees of an attribute node, if
271 any. If Node represents "-Name.", the result is none. Otherwise,
272 if Node represents "-Name(E1, ..., En).", [E1, ..., E1] is
273 returned.
274 See also: attribute/1.
276 attribute_name(Node::syntaxTree()) -> syntaxTree()
278 Returns the name subtree of an attribute node.
280 See also: attribute/1.
282 binary(List::[syntaxTree()]) -> syntaxTree()
284 Creates an abstract binary-object template. If Fields is [F1,
286 ..., Fn], the result represents "<<F1, ..., Fn>>".
287 See also: binary_field/2, binary_fields/1.
289 binary_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntax‐
291 Tree()
292 Creates an abstract binary comprehension. If Body is [E1, ...,
294 En], the result represents "<<Template || E1, ..., En>>".
295 See also: binary_comp_body/1, binary_comp_template/1, genera‐
297 tor/2.
298 binary_comp_body(Node::syntaxTree()) -> [syntaxTree()]
300 Returns the list of body subtrees of a binary_comp node.
302 See also: binary_comp/2.
304 binary_comp_template(Node::syntaxTree()) -> syntaxTree()
306 Returns the template subtree of a binary_comp node.
308 See also: binary_comp/2.
310 binary_field(Body::syntaxTree()) -> syntaxTree()
312 Equivalent to binary_field(Body, []).
314 binary_field(Body::syntaxTree(), Types::[syntaxTree()]) -> syntaxTree()
316 Creates an abstract binary template field. If Types is the empty
318 list, the result simply represents "Body", otherwise, if Types
319 is [T1, ..., Tn], the result represents "Body/T1-...-Tn".
320 See also: binary/1, binary_field/1, binary_field/3,
322 binary_field_body/1, binary_field_size/1, binary_field_types/1.
323 binary_field(Body::syntaxTree(), Size::none | syntaxTree(),
325 Types::[syntaxTree()]) -> syntaxTree()
326 Creates an abstract binary template field. If Size is none, this
328 is equivalent to "binary_field(Body, Types)", otherwise it is
329 equivalent to "binary_field(size_qualifier(Body, Size), Types)".
330 (This is a utility function.)
332 See also: binary/1, binary_field/2, size_qualifier/2.
334 binary_field_body(Node::syntaxTree()) -> syntaxTree()
336 Returns the body subtree of a binary_field.
338 See also: binary_field/2.
340 binary_field_size(Node::syntaxTree()) -> none | syntaxTree()
342 Returns the size specifier subtree of a binary_field node, if
344 any. If Node represents "Body:Size" or "Body:Size/T1, ..., Tn",
345 the result is Size, otherwise none is returned.
346 (This is a utility function.)
348 See also: binary_field/2, binary_field/3.
350 binary_field_types(Node::syntaxTree()) -> [syntaxTree()]
352 Returns the list of type-specifier subtrees of a binary_field
354 node. If Node represents ".../T1, ..., Tn", the result is [T1,
355 ..., Tn], otherwise the result is the empty list.
356 See also: binary_field/2.
358 binary_fields(Node::syntaxTree()) -> [syntaxTree()]
360 Returns the list of field subtrees of a binary node.
362 See also: binary/1, binary_field/2.
364 binary_generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntax‐
366 Tree()
367 Creates an abstract binary_generator. The result represents
369 "Pattern <- Body".
370 See also: binary_comp/2, binary_generator_body/1, binary_genera‐
372 tor_pattern/1, list_comp/2.
373 binary_generator_body(Node::syntaxTree()) -> syntaxTree()
375 Returns the body subtree of a generator node.
377 See also: binary_generator/2.
379 binary_generator_pattern(Node::syntaxTree()) -> syntaxTree()
381 Returns the pattern subtree of a generator node.
383 See also: binary_generator/2.
385 bitstring_type(M::syntaxTree(), N::syntaxTree()) -> syntaxTree()
387 Creates an abstract bitstring type. The result represents
389 "<<_:M, _:_*N>>".
390 See also: bitstring_type_m/1, bitstring_type_n/1.
392 bitstring_type_m(Node::syntaxTree()) -> syntaxTree()
394 Returns the number of start bits, M, of a bitstring_type node.
396 See also: bitstring_type/2.
398 bitstring_type_n(Node::syntaxTree()) -> syntaxTree()
400 Returns the segment size, N, of a bitstring_type node.
402 See also: bitstring_type/2.
404 block_expr(Body::[syntaxTree()]) -> syntaxTree()
406 Creates an abstract block expression. If Body is [B1, ..., Bn],
408 the result represents "begin B1, ..., Bn end".
409 See also: block_expr_body/1.
411 block_expr_body(Node::syntaxTree()) -> [syntaxTree()]
413 Returns the list of body subtrees of a block_expr node.
415 See also: block_expr/1.
417 case_expr(Argument::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
419 Tree()
420 Creates an abstract case-expression. If Clauses is [C1, ...,
422 Cn], the result represents "case Argument of C1; ...; Cn end".
423 More exactly, if each Ci represents "(Pi) Gi -> Bi", then the
424 result represents "case Argument of P1 G1 -> B1; ...; Pn Gn ->
425 Bn end".
426 See also: case_expr_argument/1, case_expr_clauses/1, clause/3,
428 cond_expr/1, if_expr/1.
429 case_expr_argument(Node::syntaxTree()) -> syntaxTree()
431 Returns the argument subtree of a case_expr node.
433 See also: case_expr/2.
435 case_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
437 Returns the list of clause subtrees of a case_expr node.
439 See also: case_expr/2.
441 catch_expr(Expr::syntaxTree()) -> syntaxTree()
443 Creates an abstract catch-expression. The result represents
445 "catch Expr".
446 See also: catch_expr_body/1.
448 catch_expr_body(Node::syntaxTree()) -> syntaxTree()
450 Returns the body subtree of a catch_expr node.
452 See also: catch_expr/1.
454 char(Char::char()) -> syntaxTree()
456 Creates an abstract character literal. The result represents
458 "$Name", where Name corresponds to Value.
459 Note: the literal corresponding to a particular character value
461 is not uniquely defined. E.g., the character "a" can be written
462 both as "$a" and "$\141", and a Tab character can be written as
463 "$\11", "$\011" or "$\t".
464 See also: char_literal/1, char_literal/2, char_value/1,
466 is_char/2.
467 char_literal(Node::syntaxTree()) -> nonempty_string()
469 Returns the literal string represented by a char node. This
471 includes the leading "$" character. Characters beyond 255 will
472 be escaped.
473 See also: char/1.
475 char_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
477 Returns the literal string represented by a char node. This
479 includes the leading "$" character. Depending on the encoding a
480 character beyond 255 will be escaped (latin1) or copied as is
481 (utf8).
482 See also: char/1.
484 char_value(Node::syntaxTree()) -> char()
486 Returns the value represented by a char node.
488 See also: char/1.
490 class_qualifier(Class::syntaxTree(), Body::syntaxTree()) -> syntax‐
492 Tree()
493 Creates an abstract class qualifier. The result represents
495 "Class:Body".
496 See also: class_qualifier_argument/1, class_qualifier_body/1,
498 try_expr/4.
499 class_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
501 Returns the argument (the class) subtree of a class_qualifier
503 node.
504 See also: class_qualifier/2.
506 class_qualifier_body(Node::syntaxTree()) -> syntaxTree()
508 Returns the body subtree of a class_qualifier node.
510 See also: class_qualifier/2.
512 clause(Guard::guard(), Body::[syntaxTree()]) -> syntaxTree()
514 Equivalent to clause([], Guard, Body).
516 clause(Patterns::[syntaxTree()], Guard::guard(), Body::[syntaxTree()])
518 -> syntaxTree()
519 Creates an abstract clause. If Patterns is [P1, ..., Pn] and
521 Body is [B1, ..., Bm], then if Guard is none, the result repre‐
522 sents "(P1, ..., Pn) -> B1, ..., Bm", otherwise, unless Guard is
523 a list, the result represents "(P1, ..., Pn) when Guard -> B1,
524 ..., Bm".
525 For simplicity, the Guard argument may also be any of the fol‐
527 lowing:
528 * An empty list []. This is equivalent to passing none.
530 * A nonempty list [E1, ..., Ej] of syntax trees. This is
532 equivalent to passing conjunction([E1, ..., Ej]).
533 * A nonempty list of lists of syntax trees [[E1_1, ...,
535 E1_k1], ..., [Ej_1, ..., Ej_kj]], which is equivalent to
536 passing disjunction([conjunction([E1_1, ..., E1_k1]), ...,
537 conjunction([Ej_1, ..., Ej_kj])]).
538 See also: clause/2, clause_body/1, clause_guard/1, clause_pat‐
540 terns/1.
541 clause_body(Node::syntaxTree()) -> [syntaxTree()]
543 Return the list of body subtrees of a clause node.
545 See also: clause/3.
547 clause_guard(Node::syntaxTree()) -> none | syntaxTree()
549 Returns the guard subtree of a clause node, if any. If Node rep‐
551 resents "(P1, ..., Pn) when Guard -> B1, ..., Bm", Guard is
552 returned. Otherwise, the result is none.
553 See also: clause/3.
555 clause_patterns(Node::syntaxTree()) -> [syntaxTree()]
557 Returns the list of pattern subtrees of a clause node.
559 See also: clause/3.
561 comment(Strings::[string()]) -> syntaxTree()
563 Equivalent to comment(none, Strings).
565 comment(Pad::padding(), Strings::[string()]) -> syntaxTree()
567 Creates an abstract comment with the given padding and text. If
569 Strings is a (possibly empty) list ["Txt1", ..., "TxtN"], the
570 result represents the source code text
571 %Txt1
573 ...
574 %TxtN
575 Padding states the number of empty character positions to the
577 left of the comment separating it horizontally from source code
578 on the same line (if any). If Padding is none, a default posi‐
579 tive number is used. If Padding is an integer less than 1, there
580 should be no separating space. Comments are in themselves
581 regarded as source program forms.
582 See also: comment/1, is_form/1.
584 comment_padding(Node::syntaxTree()) -> padding()
586 Returns the amount of padding before the comment, or none. The
588 latter means that a default padding may be used.
589 See also: comment/2.
591 comment_text(Node::syntaxTree()) -> [string()]
593 Returns the lines of text of the abstract comment.
595 See also: comment/2.
597 compact_list(Node::syntaxTree()) -> syntaxTree()
599 Yields the most compact form for an abstract list skeleton. The
601 result either represents "[E1, ..., En | Tail]", where Tail is
602 not a list skeleton, or otherwise simply "[E1, ..., En]". Anno‐
603 tations on subtrees of Node that represent list skeletons may be
604 lost, but comments will be propagated to the result. Returns
605 Node itself if Node does not represent a list skeleton.
606 See also: list/2, normalize_list/1.
608 concrete(Node::syntaxTree()) -> term()
610 Returns the Erlang term represented by a syntax tree. Evaluation
612 fails with reason badarg if Node does not represent a literal
613 term.
614 Note: Currently, the set of syntax trees which have a concrete
616 representation is larger than the set of trees which can be
617 built using the function abstract/1. An abstract character will
618 be concretised as an integer, while abstract/1 does not at
619 present yield an abstract character for any input. (Use the
620 char/1 function to explicitly create an abstract character.)
621 Note: arity_qualifier nodes are recognized. This is to follow
623 The Erlang Parser when it comes to wild attributes: both {F, A}
624 and F/A are recognized, which makes it possible to turn wild
625 attributes into recognized attributes without at the same time
626 making it impossible to compile files using the new syntax with
627 the old version of the Erlang Compiler.
628 See also: abstract/1, char/1, is_literal/1.
630 cond_expr(Clauses::[syntaxTree()]) -> syntaxTree()
632 Creates an abstract cond-expression. If Clauses is [C1, ...,
634 Cn], the result represents "cond C1; ...; Cn end". More exactly,
635 if each Ci represents "() Ei -> Bi", then the result represents
636 "cond E1 -> B1; ...; En -> Bn end".
637 See also: case_expr/2, clause/3, cond_expr_clauses/1.
639 cond_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
641 Returns the list of clause subtrees of a cond_expr node.
643 See also: cond_expr/1.
645 conjunction(Tests::[syntaxTree()]) -> syntaxTree()
647 Creates an abstract conjunction. If List is [E1, ..., En], the
649 result represents "E1, ..., En".
650 See also: conjunction_body/1, disjunction/1.
652 conjunction_body(Node::syntaxTree()) -> [syntaxTree()]
654 Returns the list of body subtrees of a conjunction node.
656 See also: conjunction/1.
658 cons(Head::syntaxTree(), Tail::syntaxTree()) -> syntaxTree()
660 "Optimising" list skeleton cons operation. Creates an abstract
662 list skeleton whose first element is Head and whose tail corre‐
663 sponds to Tail. This is similar to list([Head], Tail), except
664 that Tail may not be none, and that the result does not neces‐
665 sarily represent exactly "[Head | Tail]", but may depend on the
666 Tail subtree. E.g., if Tail represents [X, Y], the result may
667 represent "[Head, X, Y]", rather than "[Head | [X, Y]]". Annota‐
668 tions on Tail itself may be lost if Tail represents a list
669 skeleton, but comments on Tail are propagated to the result.
670 See also: list/2, list_head/1, list_tail/1.
672 constrained_function_type(FunctionType::syntaxTree(), FunctionCon‐
674 straint::[syntaxTree()]) -> syntaxTree()
675 Creates an abstract constrained function type. If FunctionCon‐
677 straint is [C1, ..., Cn], the result represents "FunctionType
678 when C1, ...Cn".
679 See also: constrained_function_type_argument/1, con‐
681 strained_function_type_body/1.
682 constrained_function_type_argument(Node::syntaxTree()) -> syntaxTree()
684 Returns the function constraint subtree of a constrained_func‐
686 tion_type node.
687 See also: constrained_function_type/2.
689 constrained_function_type_body(Node::syntaxTree()) -> syntaxTree()
691 Returns the function type subtree of a constrained_function_type
693 node.
694 See also: constrained_function_type/2.
696 constraint(Name::syntaxTree(), Types::[syntaxTree()]) -> syntaxTree()
698 Creates an abstract (subtype) constraint. The result represents
700 "Name :: Type".
701 See also: constraint_argument/1, constraint_body/1.
703 constraint_argument(Node::syntaxTree()) -> syntaxTree()
705 Returns the name subtree of a constraint node.
707 See also: constraint/2.
709 constraint_body(Node::syntaxTree()) -> [syntaxTree()]
711 Returns the type subtree of a constraint node.
713 See also: constraint/2.
715 copy_ann(Source::syntaxTree(), Target::syntaxTree()) -> syntaxTree()
717 Copies the list of user annotations from Source to Target.
719 Note: this is equivalent to set_ann(Target, get_ann(Source)),
721 but potentially more efficient.
722 See also: get_ann/1, set_ann/2.
724 copy_attrs(S::syntaxTree(), T::syntaxTree()) -> syntaxTree()
726 Copies the attributes from Source to Target.
728 Note: this is equivalent to set_attrs(Target,
730 get_attrs(Source)), but potentially more efficient.
731 See also: get_attrs/1, set_attrs/2.
733 copy_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
735 Tree()
736 Copies the pre- and postcomments from Source to Target.
738 Note: This is equivalent to set_postcomments(set_precom‐
740 ments(Target, get_precomments(Source)), get_postcom‐
741 ments(Source)), but potentially more efficient.
742 See also: comment/2, get_postcomments/1, get_precomments/1,
744 set_postcomments/2, set_precomments/2.
745 copy_pos(Source::syntaxTree(), Target::syntaxTree()) -> syntaxTree()
747 Copies the position information from Source to Target.
749 This is equivalent to set_pos(Target, get_pos(Source)), but
751 potentially more efficient.
752 See also: get_pos/1, set_pos/2.
754 data(Tree::syntaxTree()) -> term()
756 For special purposes only. Returns the associated data of a syn‐
758 tax tree node. Evaluation fails with reason badarg if
759 is_tree(Node) does not yield true.
760 See also: tree/2.
762 disjunction(Tests::[syntaxTree()]) -> syntaxTree()
764 Creates an abstract disjunction. If List is [E1, ..., En], the
766 result represents "E1; ...; En".
767 See also: conjunction/1, disjunction_body/1.
769 disjunction_body(Node::syntaxTree()) -> [syntaxTree()]
771 Returns the list of body subtrees of a disjunction node.
773 See also: disjunction/1.
775 eof_marker() -> syntaxTree()
777 Creates an abstract end-of-file marker. This represents the end
779 of input when reading a sequence of source code forms. An end-
780 of-file marker is itself regarded as a source code form (namely,
781 the last in any sequence in which it occurs). It has no defined
782 lexical form.
783 Note: this is retained only for backwards compatibility with
785 existing parsers and tools.
786 See also: error_marker/1, is_form/1, warning_marker/1.
788 error_marker(Error::term()) -> syntaxTree()
790 Creates an abstract error marker. The result represents an
792 occurrence of an error in the source code, with an associated
793 Erlang I/O ErrorInfo structure given by Error (see module io(3)
794 for details). Error markers are regarded as source code forms,
795 but have no defined lexical form.
796 Note: this is supported only for backwards compatibility with
798 existing parsers and tools.
799 See also: eof_marker/0, error_marker_info/1, is_form/1, warn‐
801 ing_marker/1.
802 error_marker_info(Node::syntaxTree()) -> term()
804 Returns the ErrorInfo structure of an error_marker node.
806 See also: error_marker/1.
808 flatten_form_list(Node::syntaxTree()) -> syntaxTree()
810 Flattens sublists of a form_list node. Returns Node with all
812 subtrees of type form_list recursively expanded, yielding a sin‐
813 gle "flat" abstract form sequence.
814 See also: form_list/1.
816 float(Value::float()) -> syntaxTree()
818 Creates an abstract floating-point literal. The lexical repre‐
820 sentation is the decimal floating-point numeral of Value.
821 See also: float_literal/1, float_value/1.
823 float_literal(Node::syntaxTree()) -> string()
825 Returns the numeral string represented by a float node.
827 See also: float/1.
829 float_value(Node::syntaxTree()) -> float()
831 Returns the value represented by a float node. Note that float‐
833 ing-point values should usually not be compared for equality.
834 See also: float/1.
836 form_list(Forms::[syntaxTree()]) -> syntaxTree()
838 Creates an abstract sequence of "source code forms". If Forms is
840 [F1, ..., Fn], where each Fi is a form (see is_form/1, the
841 result represents
842 F1
844 ...
845 Fn
846 where the Fi are separated by one or more line breaks. A node of
848 type form_list is itself regarded as a source code form; see
849 flatten_form_list/1.
850 Note: this is simply a way of grouping source code forms as a
852 single syntax tree, usually in order to form an Erlang module
853 definition.
854 See also: flatten_form_list/1, form_list_elements/1, is_form/1.
856 form_list_elements(Node::syntaxTree()) -> [syntaxTree()]
858 Returns the list of subnodes of a form_list node.
860 See also: form_list/1.
862 fun_expr(Clauses::[syntaxTree()]) -> syntaxTree()
864 Creates an abstract fun-expression. If Clauses is [C1, ..., Cn],
866 the result represents "fun C1; ...; Cn end". More exactly, if
867 each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then the result
868 represents "fun (P11, ..., P1m) G1 -> B1; ...; (Pn1, ..., Pnm)
869 Gn -> Bn end".
870 See also: fun_expr_arity/1, fun_expr_clauses/1.
872 fun_expr_arity(Node::syntaxTree()) -> arity()
874 Returns the arity of a fun_expr node. The result is the number
876 of parameter patterns in the first clause of the fun-expression;
877 subsequent clauses are ignored.
878 An exception is thrown if fun_expr_clauses(Node) returns an
880 empty list, or if the first element of that list is not a syntax
881 tree C of type clause such that clause_patterns(C) is a nonempty
882 list.
883 See also: clause/3, clause_patterns/1, fun_expr/1,
885 fun_expr_clauses/1.
886 fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
888 Returns the list of clause subtrees of a fun_expr node.
890 See also: fun_expr/1.
892 fun_type() -> syntaxTree()
894 Creates an abstract fun of any type. The result represents
896 "fun()".
897 function(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntaxTree()
899 Creates an abstract function definition. If Clauses is [C1, ...,
901 Cn], the result represents "Name C1; ...; Name Cn.". More
902 exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then
903 the result represents "Name(P11, ..., P1m) G1 -> B1; ...;
904 Name(Pn1, ..., Pnm) Gn -> Bn.". Function definitions are source
905 code forms.
906 See also: function_arity/1, function_clauses/1, function_name/1,
908 is_form/1.
909 function_arity(Node::syntaxTree()) -> arity()
911 Returns the arity of a function node. The result is the number
913 of parameter patterns in the first clause of the function; sub‐
914 sequent clauses are ignored.
915 An exception is thrown if function_clauses(Node) returns an
917 empty list, or if the first element of that list is not a syntax
918 tree C of type clause such that clause_patterns(C) is a nonempty
919 list.
920 See also: clause/3, clause_patterns/1, function/2, func‐
922 tion_clauses/1.
923 function_clauses(Node::syntaxTree()) -> [syntaxTree()]
925 Returns the list of clause subtrees of a function node.
927 See also: function/2.
929 function_name(Node::syntaxTree()) -> syntaxTree()
931 Returns the name subtree of a function node.
933 See also: function/2.
935 function_type(Type) -> term()
937 Equivalent to function_type(any_arity, Type).
939 function_type(Arguments::any_arity | syntaxTree(), Return::syntax‐
941 Tree()) -> syntaxTree()
942 Creates an abstract function type. If Arguments is [T1, ...,
944 Tn], then if it occurs within a function specification, the
945 result represents "(T1, ...Tn) -> Return"; otherwise it repre‐
946 sents "fun((T1, ...Tn) -> Return)". If Arguments is any_arity,
947 it represents "fun((...) -> Return)".
948 Note that the erl_parse representation is identical for "Func‐
950 tionType" and "fun(FunctionType)".
951 See also: function_type_arguments/1, function_type_return/1.
953 function_type_arguments(Node::syntaxTree()) -> any_arity | [syntax‐
955 Tree()]
956 Returns the argument types subtrees of a function_type node. If
958 Node represents "fun((...) -> Return)", any_arity is returned;
959 otherwise, if Node represents "(T1, ...Tn) -> Return" or
960 "fun((T1, ...Tn) -> Return)", [T1, ..., Tn] is returned.
961 See also: function_type/1, function_type/2.
963 function_type_return(Node::syntaxTree()) -> syntaxTree()
965 Returns the return type subtrees of a function_type node.
967 See also: function_type/1, function_type/2.
969 generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
971 Creates an abstract generator. The result represents "Pattern <-
973 Body".
974 See also: binary_comp/2, generator_body/1, generator_pattern/1,
976 list_comp/2.
977 generator_body(Node::syntaxTree()) -> syntaxTree()
979 Returns the body subtree of a generator node.
981 See also: generator/2.
983 generator_pattern(Node::syntaxTree()) -> syntaxTree()
985 Returns the pattern subtree of a generator node.
987 See also: generator/2.
989 get_ann(Tree::syntaxTree()) -> [term()]
991 Returns the list of user annotations associated with a syntax
993 tree node. For a newly created node, this is the empty list. The
994 annotations may be any terms.
995 See also: get_attrs/1, set_ann/2.
997 get_attrs(Tree::syntaxTree()) -> syntaxTreeAttributes()
999 Returns a representation of the attributes associated with a
1001 syntax tree node. The attributes are all the extra information
1002 that can be attached to a node. Currently, this includes posi‐
1003 tion information, source code comments, and user annotations.
1004 The result of this function cannot be inspected directly; only
1005 attached to another node (see set_attrs/2).
1006 For accessing individual attributes, see get_pos/1, get_ann/1,
1008 get_precomments/1 and get_postcomments/1.
1009 See also: get_ann/1, get_pos/1, get_postcomments/1, get_precom‐
1011 ments/1, set_attrs/2.
1012 get_pos(Tree::syntaxTree()) -> term()
1014 Returns the position information associated with Node. This is
1016 usually a nonnegative integer (indicating the source code line
1017 number), but may be any term. By default, all new tree nodes
1018 have their associated position information set to the integer
1019 zero.
1020 See also: get_attrs/1, set_pos/2.
1022 get_postcomments(Tree::syntaxTree()) -> [syntaxTree()]
1024 Returns the associated post-comments of a node. This is a possi‐
1026 bly empty list of abstract comments, in top-down textual order.
1027 When the code is formatted, post-comments are typically dis‐
1028 played to the right of and/or below the node. For example:
1029 {foo, X, Y} % Post-comment of tuple
1031 If possible, the comment should be moved past any following sep‐
1033 arator characters on the same line, rather than placing the sep‐
1034 arators on the following line. E.g.:
1035 foo([X | Xs], Y) ->
1037 foo(Xs, bar(X)); % Post-comment of 'bar(X)' node
1038 ...
1039 (where the comment is moved past the rightmost ")" and the ";").
1041 See also: comment/2, get_attrs/1, get_precomments/1, set_post‐
1043 comments/2.
1044 get_precomments(Tree::syntaxTree()) -> [syntaxTree()]
1046 Returns the associated pre-comments of a node. This is a possi‐
1048 bly empty list of abstract comments, in top-down textual order.
1049 When the code is formatted, pre-comments are typically displayed
1050 directly above the node. For example:
1051 % Pre-comment of function
1053 foo(X) -> {bar, X}.
1054 If possible, the comment should be moved before any preceding
1056 separator characters on the same line. E.g.:
1057 foo([X | Xs]) ->
1059 % Pre-comment of 'bar(X)' node
1060 [bar(X) | foo(Xs)];
1061 ...
1062 (where the comment is moved before the "[").
1064 See also: comment/2, get_attrs/1, get_postcomments/1, set_pre‐
1066 comments/2.
1067 has_comments(Tree::syntaxTree()) -> boolean()
1069 Yields false if the node has no associated comments, and true
1071 otherwise.
1072 Note: This is equivalent to (get_precomments(Node) == []) and
1074 (get_postcomments(Node) == []), but potentially more efficient.
1075 See also: get_postcomments/1, get_precomments/1, remove_com‐
1077 ments/1.
1078 if_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1080 Creates an abstract if-expression. If Clauses is [C1, ..., Cn],
1082 the result represents "if C1; ...; Cn end". More exactly, if
1083 each Ci represents "() Gi -> Bi", then the result represents "if
1084 G1 -> B1; ...; Gn -> Bn end".
1085 See also: case_expr/2, clause/3, if_expr_clauses/1.
1087 if_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1089 Returns the list of clause subtrees of an if_expr node.
1091 See also: if_expr/1.
1093 implicit_fun(Name::syntaxTree()) -> syntaxTree()
1095 Creates an abstract "implicit fun" expression. The result repre‐
1097 sents "fun Name". Name should represent either F/A or M:F/A
1098 See also: arity_qualifier/2, implicit_fun/2, implicit_fun/3,
1100 implicit_fun_name/1, module_qualifier/2.
1101 implicit_fun(Name::syntaxTree(), Arity::none | syntaxTree()) -> syntax‐
1103 Tree()
1104 Creates an abstract "implicit fun" expression. If Arity is none,
1106 this is equivalent to implicit_fun(Name), otherwise it is equiv‐
1107 alent to implicit_fun(arity_qualifier(Name, Arity)).
1108 (This is a utility function.)
1110 See also: implicit_fun/1, implicit_fun/3.
1112 implicit_fun(Module::none | syntaxTree(), Name::syntaxTree(),
1114 Arity::syntaxTree()) -> syntaxTree()
1115 Creates an abstract module-qualified "implicit fun" expression.
1117 If Module is none, this is equivalent to implicit_fun(Name,
1118 Arity), otherwise it is equivalent to implicit_fun(module_quali‐
1119 fier(Module, arity_qualifier(Name, Arity)).
1120 (This is a utility function.)
1122 See also: implicit_fun/1, implicit_fun/2.
1124 implicit_fun_name(Node::syntaxTree()) -> syntaxTree()
1126 Returns the name subtree of an implicit_fun node.
1128 Note: if Node represents "fun N/A" or "fun M:N/A", then the
1130 result is the subtree representing "N/A" or "M:N/A", respec‐
1131 tively.
1132 See also: arity_qualifier/2, implicit_fun/1, module_qualifier/2.
1134 infix_expr(Left::syntaxTree(), Operator::syntaxTree(), Right::syntax‐
1136 Tree()) -> syntaxTree()
1137 Creates an abstract infix operator expression. The result repre‐
1139 sents "Left Operator Right".
1140 See also: infix_expr_left/1, infix_expr_operator/1,
1142 infix_expr_right/1, prefix_expr/2.
1143 infix_expr_left(Node::syntaxTree()) -> syntaxTree()
1145 Returns the left argument subtree of an infix_expr node.
1147 See also: infix_expr/3.
1149 infix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1151 Returns the operator subtree of an infix_expr node.
1153 See also: infix_expr/3.
1155 infix_expr_right(Node::syntaxTree()) -> syntaxTree()
1157 Returns the right argument subtree of an infix_expr node.
1159 See also: infix_expr/3.
1161 integer(Value::integer()) -> syntaxTree()
1163 Creates an abstract integer literal. The lexical representation
1165 is the canonical decimal numeral of Value.
1166 See also: integer_literal/1, integer_value/1, is_integer/2.
1168 integer_literal(Node::syntaxTree()) -> string()
1170 Returns the numeral string represented by an integer node.
1172 See also: integer/1.
1174 integer_range_type(Low::syntaxTree(), High::syntaxTree()) -> syntax‐
1176 Tree()
1177 Creates an abstract range type. The result represents "Low ..
1179 High".
1180 See also: integer_range_type_high/1, integer_range_type_low/1.
1182 integer_range_type_high(Node::syntaxTree()) -> syntaxTree()
1184 Returns the high limit of an integer_range_type node.
1186 See also: integer_range_type/2.
1188 integer_range_type_low(Node::syntaxTree()) -> syntaxTree()
1190 Returns the low limit of an integer_range_type node.
1192 See also: integer_range_type/2.
1194 integer_value(Node::syntaxTree()) -> integer()
1196 Returns the value represented by an integer node.
1198 See also: integer/1.
1200 is_atom(Node::syntaxTree(), Value::atom()) -> boolean()
1202 Returns true if Node has type atom and represents Value, other‐
1204 wise false.
1205 See also: atom/1.
1207 is_char(Node::syntaxTree(), Value::char()) -> boolean()
1209 Returns true if Node has type char and represents Value, other‐
1211 wise false.
1212 See also: char/1.
1214 is_form(Node::syntaxTree()) -> boolean()
1216 Returns true if Node is a syntax tree representing a so-called
1218 "source code form", otherwise false. Forms are the Erlang source
1219 code units which, placed in sequence, constitute an Erlang pro‐
1220 gram. Current form types are:
1221 attribute comment error_marker eof_marker
1223 form_list function warning_marker text
1224 See also: attribute/2, comment/2, eof_marker/0, error_marker/1,
1227 form_list/1, function/2, type/1, warning_marker/1.
1228 is_integer(Node::syntaxTree(), Value::integer()) -> boolean()
1230 Returns true if Node has type integer and represents Value, oth‐
1232 erwise false.
1233 See also: integer/1.
1235 is_leaf(Node::syntaxTree()) -> boolean()
1237 Returns true if Node is a leaf node, otherwise false. The cur‐
1239 rently recognised leaf node types are:
1240 atom char comment eof_marker error_marker
1242 float fun_type integer nil operator string
1243 text underscore variable warning_marker
1244 A node of type map_expr is a leaf node if and only if it has no
1247 argument and no fields. A node of type map_type is a leaf node
1248 if and only if it has no fields (any_size). A node of type tuple
1249 is a leaf node if and only if its arity is zero. A node of type
1250 tuple_type is a leaf node if and only if it has no elements
1251 (any_size).
1252 Note: not all literals are leaf nodes, and vice versa. E.g.,
1254 tuples with nonzero arity and nonempty lists may be literals,
1255 but are not leaf nodes. Variables, on the other hand, are leaf
1256 nodes but not literals.
1257 See also: is_literal/1, type/1.
1259 is_list_skeleton(Node::syntaxTree()) -> boolean()
1261 Returns true if Node has type list or nil, otherwise false.
1263 See also: list/2, nil/0.
1265 is_literal(T::syntaxTree()) -> boolean()
1267 Returns true if Node represents a literal term, otherwise false.
1269 This function returns true if and only if the value of con‐
1270 crete(Node) is defined.
1271 See also: abstract/1, concrete/1.
1273 is_proper_list(Node::syntaxTree()) -> boolean()
1275 Returns true if Node represents a proper list, and false other‐
1277 wise. A proper list is a list skeleton either on the form "[]"
1278 or "[E1, ..., En]", or "[... | Tail]" where recursively Tail
1279 also represents a proper list.
1280 Note: Since Node is a syntax tree, the actual run-time values
1282 corresponding to its subtrees may often be partially or com‐
1283 pletely unknown. Thus, if Node represents e.g. "[... | Ns]"
1284 (where Ns is a variable), then the function will return false,
1285 because it is not known whether Ns will be bound to a list at
1286 run-time. If Node instead represents e.g. "[1, 2, 3]" or "[A |
1287 []]", then the function will return true.
1288 See also: list/2.
1290 is_string(Node::syntaxTree(), Value::string()) -> boolean()
1292 Returns true if Node has type string and represents Value, oth‐
1294 erwise false.
1295 See also: string/1.
1297 is_tree(Tree::syntaxTree()) -> boolean()
1299 For special purposes only. Returns true if Tree is an abstract
1301 syntax tree and false otherwise.
1302 Note: this function yields false for all "old-style" erl_parse-
1304 compatible "parse trees".
1305 See also: tree/2.
1307 join_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
1309 Tree()
1310 Appends the comments of Source to the current comments of Tar‐
1312 get.
1313 Note: This is equivalent to add_postcomments(get_postcom‐
1315 ments(Source), add_precomments(get_precomments(Source), Tar‐
1316 get)), but potentially more efficient.
1317 See also: add_postcomments/2, add_precomments/2, comment/2,
1319 get_postcomments/1, get_precomments/1.
1320 list(List::[syntaxTree()]) -> syntaxTree()
1322 Equivalent to list(List, none).
1324 list(Elements::[syntaxTree()], Tail::none | syntaxTree()) -> syntax‐
1326 Tree()
1327 Constructs an abstract list skeleton. The result has type list
1329 or nil. If List is a nonempty list [E1, ..., En], the result has
1330 type list and represents either "[E1, ..., En]", if Tail is
1331 none, or otherwise "[E1, ..., En | Tail]". If List is the empty
1332 list, Tail must be none, and in that case the result has type
1333 nil and represents "[]" (see nil/0).
1334 The difference between lists as semantic objects (built up of
1336 individual "cons" and "nil" terms) and the various syntactic
1337 forms for denoting lists may be bewildering at first. This mod‐
1338 ule provides functions both for exact control of the syntactic
1339 representation as well as for the simple composition and decon‐
1340 struction in terms of cons and head/tail operations.
1341 Note: in list(Elements, none), the "nil" list terminator is
1343 implicit and has no associated information (see get_attrs/1),
1344 while in the seemingly equivalent list(Elements, Tail) when Tail
1345 has type nil, the list terminator subtree Tail may have attached
1346 attributes such as position, comments, and annotations, which
1347 will be preserved in the result.
1348 See also: compact_list/1, cons/2, get_attrs/1, is_list_skele‐
1350 ton/1, is_proper_list/1, list/1, list_elements/1, list_head/1,
1351 list_length/1, list_prefix/1, list_suffix/1, list_tail/1, nil/0,
1352 normalize_list/1.
1353 list_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntaxTree()
1355 Creates an abstract list comprehension. If Body is [E1, ...,
1357 En], the result represents "[Template || E1, ..., En]".
1358 See also: generator/2, list_comp_body/1, list_comp_template/1.
1360 list_comp_body(Node::syntaxTree()) -> [syntaxTree()]
1362 Returns the list of body subtrees of a list_comp node.
1364 See also: list_comp/2.
1366 list_comp_template(Node::syntaxTree()) -> syntaxTree()
1368 Returns the template subtree of a list_comp node.
1370 See also: list_comp/2.
1372 list_elements(Node::syntaxTree()) -> [syntaxTree()]
1374 Returns the list of element subtrees of a list skeleton. Node
1376 must represent a proper list. E.g., if Node represents "[X1, X2
1377 | [X3, X4 | []]", then list_elements(Node) yields the list [X1,
1378 X2, X3, X4].
1379 See also: is_proper_list/1, list/2.
1381 list_head(Node::syntaxTree()) -> syntaxTree()
1383 Returns the head element subtree of a list node. If Node repre‐
1385 sents "[Head ...]", the result will represent "Head".
1386 See also: cons/2, list/2, list_tail/1.
1388 list_length(Node::syntaxTree()) -> non_neg_integer()
1390 Returns the number of element subtrees of a list skeleton. Node
1392 must represent a proper list. E.g., if Node represents "[X1 |
1393 [X2, X3 | [X4, X5, X6]]]", then list_length(Node) returns the
1394 integer 6.
1395 Note: this is equivalent to length(list_elements(Node)), but
1397 potentially more efficient.
1398 See also: is_proper_list/1, list/2, list_elements/1.
1400 list_prefix(Node::syntaxTree()) -> [syntaxTree()]
1402 Returns the prefix element subtrees of a list node. If Node rep‐
1404 resents "[E1, ..., En]" or "[E1, ..., En | Tail]", the returned
1405 value is [E1, ..., En].
1406 See also: list/2.
1408 list_suffix(Node::syntaxTree()) -> none | syntaxTree()
1410 Returns the suffix subtree of a list node, if one exists. If
1412 Node represents "[E1, ..., En | Tail]", the returned value is
1413 Tail, otherwise, i.e., if Node represents "[E1, ..., En]", none
1414 is returned.
1415 Note that even if this function returns some Tail that is not
1417 none, the type of Tail can be nil, if the tail has been given
1418 explicitly, and the list skeleton has not been compacted (see
1419 compact_list/1).
1420 See also: compact_list/1, list/2, nil/0.
1422 list_tail(Node::syntaxTree()) -> syntaxTree()
1424 Returns the tail of a list node. If Node represents a single-
1426 element list "[E]", then the result has type nil, representing
1427 "[]". If Node represents "[E1, E2 ...]", the result will repre‐
1428 sent "[E2 ...]", and if Node represents "[Head | Tail]", the
1429 result will represent "Tail".
1430 See also: cons/2, list/2, list_head/1.
1432 macro(Name::syntaxTree()) -> syntaxTree()
1434 Equivalent to macro(Name, none).
1436 macro(Name::syntaxTree(), Arguments::none | [syntaxTree()]) -> syntax‐
1438 Tree()
1439 Creates an abstract macro application. If Arguments is none, the
1441 result represents "?Name", otherwise, if Arguments is [A1, ...,
1442 An], the result represents "?Name(A1, ..., An)".
1443 Notes: if Arguments is the empty list, the result will thus rep‐
1445 resent "?Name()", including a pair of matching parentheses.
1446 The only syntactical limitation imposed by the preprocessor on
1448 the arguments to a macro application (viewed as sequences of
1449 tokens) is that they must be balanced with respect to parenthe‐
1450 ses, brackets, begin ... end, case ... end, etc. The text node
1451 type can be used to represent arguments which are not regular
1452 Erlang constructs.
1453 See also: macro/1, macro_arguments/1, macro_name/1, text/1.
1455 macro_arguments(Node::syntaxTree()) -> none | [syntaxTree()]
1457 Returns the list of argument subtrees of a macro node, if any.
1459 If Node represents "?Name", none is returned. Otherwise, if Node
1460 represents "?Name(A1, ..., An)", [A1, ..., An] is returned.
1461 See also: macro/2.
1463 macro_name(Node::syntaxTree()) -> syntaxTree()
1465 Returns the name subtree of a macro node.
1467 See also: macro/2.
1469 make_tree(X1::atom(), X2::[[syntaxTree()]]) -> syntaxTree()
1471 Creates a syntax tree with the given type and subtrees. Type
1473 must be a node type name (see type/1) that does not denote a
1474 leaf node type (see is_leaf/1). Groups must be a nonempty list
1475 of groups of syntax trees, representing the subtrees of a node
1476 of the given type, in left-to-right order as they would occur in
1477 the printed program text, grouped by category as done by sub‐
1478 trees/1.
1479 The result of copy_attrs(Node, make_tree(type(Node), sub‐
1481 trees(Node))) (see update_tree/2) represents the same source
1482 code text as the original Node, assuming that subtrees(Node)
1483 yields a nonempty list. However, it does not necessarily have
1484 the same data representation as Node.
1485 See also: copy_attrs/2, is_leaf/1, subtrees/1, type/1,
1487 update_tree/2.
1488 map_expr(Fields::[syntaxTree()]) -> syntaxTree()
1490 Equivalent to map_expr(none, Fields).
1492 map_expr(Argument::none | syntaxTree(), Fields::[syntaxTree()]) -> syn‐
1494 taxTree()
1495 Creates an abstract map expression. If Fields is [F1, ..., Fn],
1497 then if Argument is none, the result represents "#{F1, ...,
1498 Fn}", otherwise it represents "Argument#{F1, ..., Fn}".
1499 See also: map_expr/1, map_expr_argument/1, map_expr_fields/1,
1501 map_field_assoc/2, map_field_exact/2.
1502 map_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1504 Returns the argument subtree of a map_expr node, if any. If Node
1506 represents "#{...}", none is returned. Otherwise, if Node repre‐
1507 sents "Argument#{...}", Argument is returned.
1508 See also: map_expr/2.
1510 map_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1512 Returns the list of field subtrees of a map_expr node.
1514 See also: map_expr/2.
1516 map_field_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1518 Tree()
1519 Creates an abstract map assoc field. The result represents "Name
1521 => Value".
1522 See also: map_expr/2, map_field_assoc_name/1,
1524 map_field_assoc_value/1.
1525 map_field_assoc_name(Node::syntaxTree()) -> syntaxTree()
1527 Returns the name subtree of a map_field_assoc node.
1529 See also: map_field_assoc/2.
1531 map_field_assoc_value(Node::syntaxTree()) -> syntaxTree()
1533 Returns the value subtree of a map_field_assoc node.
1535 See also: map_field_assoc/2.
1537 map_field_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1539 Tree()
1540 Creates an abstract map exact field. The result represents "Name
1542 := Value".
1543 See also: map_expr/2, map_field_exact_name/1,
1545 map_field_exact_value/1.
1546 map_field_exact_name(Node::syntaxTree()) -> syntaxTree()
1548 Returns the name subtree of a map_field_exact node.
1550 See also: map_field_exact/2.
1552 map_field_exact_value(Node::syntaxTree()) -> syntaxTree()
1554 Returns the value subtree of a map_field_exact node.
1556 See also: map_field_exact/2.
1558 map_type() -> term()
1560 Equivalent to map_type(any_size).
1562 map_type(Fields::any_size | [syntaxTree()]) -> syntaxTree()
1564 Creates an abstract type map. If Fields is [F1, ..., Fn], the
1566 result represents "#{F1, ..., Fn}"; otherwise, if Fields is
1567 any_size, it represents "map()".
1568 See also: map_type_fields/1.
1570 map_type_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1572 Creates an abstract map type assoc field. The result represents
1574 "Name => Value".
1575 See also: map_type/1, map_type_assoc_name/1,
1577 map_type_assoc_value/1.
1578 map_type_assoc_name(Node::syntaxTree()) -> syntaxTree()
1580 Returns the name subtree of a map_type_assoc node.
1582 See also: map_type_assoc/2.
1584 map_type_assoc_value(Node::syntaxTree()) -> syntaxTree()
1586 Returns the value subtree of a map_type_assoc node.
1588 See also: map_type_assoc/2.
1590 map_type_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1592 Creates an abstract map type exact field. The result represents
1594 "Name := Value".
1595 See also: map_type/1, map_type_exact_name/1,
1597 map_type_exact_value/1.
1598 map_type_exact_name(Node::syntaxTree()) -> syntaxTree()
1600 Returns the name subtree of a map_type_exact node.
1602 See also: map_type_exact/2.
1604 map_type_exact_value(Node::syntaxTree()) -> syntaxTree()
1606 Returns the value subtree of a map_type_exact node.
1608 See also: map_type_exact/2.
1610 map_type_fields(Node::syntaxTree()) -> any_size | [syntaxTree()]
1612 Returns the list of field subtrees of a map_type node. If Node
1614 represents "map()", any_size is returned; otherwise, if Node
1615 represents "#{F1, ..., Fn}", [F1, ..., Fn] is returned.
1616 See also: map_type/0, map_type/1.
1618 match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
1620 Creates an abstract match-expression. The result represents
1622 "Pattern = Body".
1623 See also: match_expr_body/1, match_expr_pattern/1.
1625 match_expr_body(Node::syntaxTree()) -> syntaxTree()
1627 Returns the body subtree of a match_expr node.
1629 See also: match_expr/2.
1631 match_expr_pattern(Node::syntaxTree()) -> syntaxTree()
1633 Returns the pattern subtree of a match_expr node.
1635 See also: match_expr/2.
1637 meta(T::syntaxTree()) -> syntaxTree()
1639 Creates a meta-representation of a syntax tree. The result rep‐
1641 resents an Erlang expression "MetaTree" which, if evaluated,
1642 will yield a new syntax tree representing the same source code
1643 text as Tree (although the actual data representation may be
1644 different). The expression represented by MetaTree is implemen‐
1645 tation independent with regard to the data structures used by
1646 the abstract syntax tree implementation. Comments attached to
1647 nodes of Tree will be preserved, but other attributes are lost.
1648 Any node in Tree whose node type is variable (see type/1), and
1650 whose list of annotations (see get_ann/1) contains the atom
1651 meta_var, will remain unchanged in the resulting tree, except
1652 that exactly one occurrence of meta_var is removed from its
1653 annotation list.
1654 The main use of the function meta/1 is to transform a data
1656 structure Tree, which represents a piece of program code, into a
1657 form that is representation independent when printed. E.g., sup‐
1658 pose Tree represents a variable named "V". Then (assuming a
1659 function print/1 for printing syntax trees), evaluating
1660 print(abstract(Tree)) - simply using abstract/1 to map the
1661 actual data structure onto a syntax tree representation - would
1662 output a string that might look something like "{tree, variable,
1663 ..., "V", ...}", which is obviously dependent on the implementa‐
1664 tion of the abstract syntax trees. This could e.g. be useful for
1665 caching a syntax tree in a file. However, in some situations
1666 like in a program generator generator (with two "generator"), it
1667 may be unacceptable. Using print(meta(Tree)) instead would out‐
1668 put a representation independent syntax tree generating expres‐
1669 sion; in the above case, something like "erl_syntax:vari‐
1670 able("V")".
1671 See also: abstract/1, get_ann/1, type/1.
1673 module_qualifier(Module::syntaxTree(), Body::syntaxTree()) -> syntax‐
1675 Tree()
1676 Creates an abstract module qualifier. The result represents
1678 "Module:Body".
1679 See also: module_qualifier_argument/1, module_qualifier_body/1.
1681 module_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
1683 Returns the argument (the module) subtree of a module_qualifier
1685 node.
1686 See also: module_qualifier/2.
1688 module_qualifier_body(Node::syntaxTree()) -> syntaxTree()
1690 Returns the body subtree of a module_qualifier node.
1692 See also: module_qualifier/2.
1694 named_fun_expr(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
1696 Tree()
1697 Creates an abstract named fun-expression. If Clauses is [C1,
1699 ..., Cn], the result represents "fun Name C1; ...; Name Cn end".
1700 More exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi",
1701 then the result represents "fun Name(P11, ..., P1m) G1 -> B1;
1702 ...; Name(Pn1, ..., Pnm) Gn -> Bn end".
1703 See also: named_fun_expr_arity/1, named_fun_expr_clauses/1,
1705 named_fun_expr_name/1.
1706 named_fun_expr_arity(Node::syntaxTree()) -> arity()
1708 Returns the arity of a named_fun_expr node. The result is the
1710 number of parameter patterns in the first clause of the named
1711 fun-expression; subsequent clauses are ignored.
1712 An exception is thrown if named_fun_expr_clauses(Node) returns
1714 an empty list, or if the first element of that list is not a
1715 syntax tree C of type clause such that clause_patterns(C) is a
1716 nonempty list.
1717 See also: clause/3, clause_patterns/1, named_fun_expr/2,
1719 named_fun_expr_clauses/1.
1720 named_fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1722 Returns the list of clause subtrees of a named_fun_expr node.
1724 See also: named_fun_expr/2.
1726 named_fun_expr_name(Node::syntaxTree()) -> syntaxTree()
1728 Returns the name subtree of a named_fun_expr node.
1730 See also: named_fun_expr/2.
1732 nil() -> syntaxTree()
1734 Creates an abstract empty list. The result represents "[]". The
1736 empty list is traditionally called "nil".
1737 See also: is_list_skeleton/1, list/2.
1739 normalize_list(Node::syntaxTree()) -> syntaxTree()
1741 Expands an abstract list skeleton to its most explicit form. If
1743 Node represents "[E1, ..., En | Tail]", the result represents
1744 "[E1 | ... [En | Tail1] ... ]", where Tail1 is the result of
1745 normalize_list(Tail). If Node represents "[E1, ..., En]", the
1746 result simply represents "[E1 | ... [En | []] ... ]". If Node
1747 does not represent a list skeleton, Node itself is returned.
1748 See also: compact_list/1, list/2.
1750 operator(Name::atom() | string()) -> syntaxTree()
1752 Creates an abstract operator. The name of the operator is the
1754 character sequence represented by Name. This is analogous to the
1755 print name of an atom, but an operator is never written within
1756 single-quotes; e.g., the result of operator(++')' represents
1757 "++" rather than "`++''".
1758 See also: atom/1, operator_literal/1, operator_name/1.
1760 operator_literal(Node::syntaxTree()) -> string()
1762 Returns the literal string represented by an operator node. This
1764 is simply the operator name as a string.
1765 See also: operator/1.
1767 operator_name(Node::syntaxTree()) -> atom()
1769 Returns the name of an operator node. Note that the name is
1771 returned as an atom.
1772 See also: operator/1.
1774 parentheses(Expr::syntaxTree()) -> syntaxTree()
1776 Creates an abstract parenthesised expression. The result repre‐
1778 sents "(Body)", independently of the context.
1779 See also: parentheses_body/1.
1781 parentheses_body(Node::syntaxTree()) -> syntaxTree()
1783 Returns the body subtree of a parentheses node.
1785 See also: parentheses/1.
1787 prefix_expr(Operator::syntaxTree(), Argument::syntaxTree()) -> syntax‐
1789 Tree()
1790 Creates an abstract prefix operator expression. The result rep‐
1792 resents "Operator Argument".
1793 See also: infix_expr/3, prefix_expr_argument/1, pre‐
1795 fix_expr_operator/1.
1796 prefix_expr_argument(Node::syntaxTree()) -> syntaxTree()
1798 Returns the argument subtree of a prefix_expr node.
1800 See also: prefix_expr/2.
1802 prefix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1804 Returns the operator subtree of a prefix_expr node.
1806 See also: prefix_expr/2.
1808 receive_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1810 Equivalent to receive_expr(Clauses, none, []).
1812 receive_expr(Clauses::[syntaxTree()], Timeout::none | syntaxTree(),
1814 Action::[syntaxTree()]) -> syntaxTree()
1815 Creates an abstract receive-expression. If Timeout is none, the
1817 result represents "receive C1; ...; Cn end" (the Action argument
1818 is ignored). Otherwise, if Clauses is [C1, ..., Cn] and Action
1819 is [A1, ..., Am], the result represents "receive C1; ...; Cn
1820 after Timeout -> A1, ..., Am end". More exactly, if each Ci rep‐
1821 resents "(Pi) Gi -> Bi", then the result represents "receive P1
1822 G1 -> B1; ...; Pn Gn -> Bn ... end".
1823 Note that in Erlang, a receive-expression must have at least one
1825 clause if no timeout part is specified.
1826 See also: case_expr/2, clause/3, receive_expr/1,
1828 receive_expr_action/1, receive_expr_clauses/1,
1829 receive_expr_timeout/1.
1830 receive_expr_action(Node::syntaxTree()) -> [syntaxTree()]
1832 Returns the list of action body subtrees of a receive_expr node.
1834 If Node represents "receive C1; ...; Cn end", this is the empty
1835 list.
1836 See also: receive_expr/3.
1838 receive_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1840 Returns the list of clause subtrees of a receive_expr node.
1842 See also: receive_expr/3.
1844 receive_expr_timeout(Node::syntaxTree()) -> none | syntaxTree()
1846 Returns the timeout subtree of a receive_expr node, if any. If
1848 Node represents "receive C1; ...; Cn end", none is returned.
1849 Otherwise, if Node represents "receive C1; ...; Cn after Timeout
1850 -> ... end", Timeout is returned.
1851 See also: receive_expr/3.
1853 record_access(Argument::syntaxTree(), Type::syntaxTree(), Field::syn‐
1855 taxTree()) -> syntaxTree()
1856 Creates an abstract record field access expression. The result
1858 represents "Argument#Type.Field".
1859 See also: record_access_argument/1, record_access_field/1,
1861 record_access_type/1, record_expr/3.
1862 record_access_argument(Node::syntaxTree()) -> syntaxTree()
1864 Returns the argument subtree of a record_access node.
1866 See also: record_access/3.
1868 record_access_field(Node::syntaxTree()) -> syntaxTree()
1870 Returns the field subtree of a record_access node.
1872 See also: record_access/3.
1874 record_access_type(Node::syntaxTree()) -> syntaxTree()
1876 Returns the type subtree of a record_access node.
1878 See also: record_access/3.
1880 record_expr(Type::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1882 Equivalent to record_expr(none, Type, Fields).
1884 record_expr(Argument::none | syntaxTree(), Type::syntaxTree(),
1886 Fields::[syntaxTree()]) -> syntaxTree()
1887 Creates an abstract record expression. If Fields is [F1, ...,
1889 Fn], then if Argument is none, the result represents "#Type{F1,
1890 ..., Fn}", otherwise it represents "Argument#Type{F1, ..., Fn}".
1891 See also: record_access/3, record_expr/2, record_expr_argu‐
1893 ment/1, record_expr_fields/1, record_expr_type/1,
1894 record_field/2, record_index_expr/2.
1895 record_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1897 Returns the argument subtree of a record_expr node, if any. If
1899 Node represents "#Type{...}", none is returned. Otherwise, if
1900 Node represents "Argument#Type{...}", Argument is returned.
1901 See also: record_expr/3.
1903 record_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1905 Returns the list of field subtrees of a record_expr node.
1907 See also: record_expr/3.
1909 record_expr_type(Node::syntaxTree()) -> syntaxTree()
1911 Returns the type subtree of a record_expr node.
1913 See also: record_expr/3.
1915 record_field(Name::syntaxTree()) -> syntaxTree()
1917 Equivalent to record_field(Name, none).
1919 record_field(Name::syntaxTree(), Value::none | syntaxTree()) -> syntax‐
1921 Tree()
1922 Creates an abstract record field specification. If Value is
1924 none, the result represents simply "Name", otherwise it repre‐
1925 sents "Name = Value".
1926 See also: record_expr/3, record_field_name/1,
1928 record_field_value/1.
1929 record_field_name(Node::syntaxTree()) -> syntaxTree()
1931 Returns the name subtree of a record_field node.
1933 See also: record_field/2.
1935 record_field_value(Node::syntaxTree()) -> none | syntaxTree()
1937 Returns the value subtree of a record_field node, if any. If
1939 Node represents "Name", none is returned. Otherwise, if Node
1940 represents "Name = Value", Value is returned.
1941 See also: record_field/2.
1943 record_index_expr(Type::syntaxTree(), Field::syntaxTree()) -> syntax‐
1945 Tree()
1946 Creates an abstract record field index expression. The result
1948 represents "#Type.Field".
1949 (Note: the function name record_index/2 is reserved by the
1951 Erlang compiler, which is why that name could not be used for
1952 this constructor.)
1953 See also: record_expr/3, record_index_expr_field/1,
1955 record_index_expr_type/1.
1956 record_index_expr_field(Node::syntaxTree()) -> syntaxTree()
1958 Returns the field subtree of a record_index_expr node.
1960 See also: record_index_expr/2.
1962 record_index_expr_type(Node::syntaxTree()) -> syntaxTree()
1964 Returns the type subtree of a record_index_expr node.
1966 See also: record_index_expr/2.
1968 record_type(Name::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1970 Creates an abstract record type. If Fields is [F1, ..., Fn], the
1972 result represents "#Name{F1, ..., Fn}".
1973 See also: record_type_fields/1, record_type_name/1.
1975 record_type_field(Name::syntaxTree(), Type::syntaxTree()) -> syntax‐
1977 Tree()
1978 Creates an abstract record type field. The result represents
1980 "Name :: Type".
1981 See also: record_type_field_name/1, record_type_field_type/1.
1983 record_type_field_name(Node::syntaxTree()) -> syntaxTree()
1985 Returns the name subtree of a record_type_field node.
1987 See also: record_type_field/2.
1989 record_type_field_type(Node::syntaxTree()) -> syntaxTree()
1991 Returns the type subtree of a record_type_field node.
1993 See also: record_type_field/2.
1995 record_type_fields(Node::syntaxTree()) -> [syntaxTree()]
1997 Returns the fields subtree of a record_type node.
1999 See also: record_type/2.
2001 record_type_name(Node::syntaxTree()) -> syntaxTree()
2003 Returns the name subtree of a record_type node.
2005 See also: record_type/2.
2007 remove_comments(Node::syntaxTree()) -> syntaxTree()
2009 Clears the associated comments of Node.
2011 Note: This is equivalent to set_precomments(set_postcom‐
2013 ments(Node, []), []), but potentially more efficient.
2014 See also: set_postcomments/2, set_precomments/2.
2016 revert(Node::syntaxTree()) -> syntaxTree()
2018 Returns an erl_parse-compatible representation of a syntax tree,
2020 if possible. If Tree represents a well-formed Erlang program or
2021 expression, the conversion should work without problems. Typi‐
2022 cally, is_tree/1 yields true if conversion failed (i.e., the
2023 result is still an abstract syntax tree), and false otherwise.
2024 The is_tree/1 test is not completely foolproof. For a few spe‐
2026 cial node types (e.g. arity_qualifier), if such a node occurs in
2027 a context where it is not expected, it will be left unchanged as
2028 a non-reverted subtree of the result. This can only happen if
2029 Tree does not actually represent legal Erlang code.
2030 See also: erl_parse(3), revert_forms/1.
2032 revert_forms(Forms::forms()) -> [erl_parse()]
2034 Reverts a sequence of Erlang source code forms. The sequence can
2036 be given either as a form_list syntax tree (possibly nested), or
2037 as a list of "program form" syntax trees. If successful, the
2038 corresponding flat list of erl_parse-compatible syntax trees is
2039 returned (see revert/1). If some program form could not be
2040 reverted, {error, Form} is thrown. Standalone comments in the
2041 form sequence are discarded.
2042 See also: form_list/1, is_form/1, revert/1.
2044 set_ann(Node::syntaxTree(), As::[term()]) -> syntaxTree()
2046 Sets the list of user annotations of Node to Annotations.
2048 See also: add_ann/2, copy_ann/2, get_ann/1.
2050 set_attrs(Node::syntaxTree(), Attr::syntaxTreeAttributes()) -> syntax‐
2052 Tree()
2053 Sets the attributes of Node to Attributes.
2055 See also: copy_attrs/2, get_attrs/1.
2057 set_pos(Node::syntaxTree(), Pos::term()) -> syntaxTree()
2059 Sets the position information of Node to Pos.
2061 See also: copy_pos/2, get_pos/1.
2063 set_postcomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntax‐
2065 Tree()
2066 Sets the post-comments of Node to Comments. Comments should be a
2068 possibly empty list of abstract comments, in top-down textual
2069 order
2070 See also: add_postcomments/2, comment/2, copy_comments/2,
2072 get_postcomments/1, join_comments/2, remove_comments/1, set_pre‐
2073 comments/2.
2074 set_precomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntaxTree()
2076 Sets the pre-comments of Node to Comments. Comments should be a
2078 possibly empty list of abstract comments, in top-down textual
2079 order.
2080 See also: add_precomments/2, comment/2, copy_comments/2,
2082 get_precomments/1, join_comments/2, remove_comments/1, set_post‐
2083 comments/2.
2084 size_qualifier(Body::syntaxTree(), Size::syntaxTree()) -> syntaxTree()
2086 Creates an abstract size qualifier. The result represents
2088 "Body:Size".
2089 See also: size_qualifier_argument/1, size_qualifier_body/1.
2091 size_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
2093 Returns the argument subtree (the size) of a size_qualifier
2095 node.
2096 See also: size_qualifier/2.
2098 size_qualifier_body(Node::syntaxTree()) -> syntaxTree()
2100 Returns the body subtree of a size_qualifier node.
2102 See also: size_qualifier/2.
2104 string(String::string()) -> syntaxTree()
2106 Creates an abstract string literal. The result represents "Text"
2108 (including the surrounding double-quotes), where Text corre‐
2109 sponds to the sequence of characters in Value, but not repre‐
2110 senting a specific string literal.
2111 For example, the result of string("x\ny") represents any and all
2113 of "x\ny", "x\12y", "x\012y" and "x\^Jy"; see char/1.
2114 See also: char/1, is_string/2, string_literal/1, string_lit‐
2116 eral/2, string_value/1.
2117 string_literal(Node::syntaxTree()) -> nonempty_string()
2119 Returns the literal string represented by a string node. This
2121 includes surrounding double-quote characters. Characters beyond
2122 255 will be escaped.
2123 See also: string/1.
2125 string_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
2127 Returns the literal string represented by a string node. This
2129 includes surrounding double-quote characters. Depending on the
2130 encoding characters beyond 255 will be escaped (latin1) or
2131 copied as is (utf8).
2132 See also: string/1.
2134 string_value(Node::syntaxTree()) -> string()
2136 Returns the value represented by a string node.
2138 See also: string/1.
2140 subtrees(T::syntaxTree()) -> [[syntaxTree()]]
2142 Returns the grouped list of all subtrees of a syntax tree. If
2144 Node is a leaf node (see is_leaf/1), this is the empty list,
2145 otherwise the result is always a nonempty list, containing the
2146 lists of subtrees of Node, in left-to-right order as they occur
2147 in the printed program text, and grouped by category. Often,
2148 each group contains only a single subtree.
2149 Depending on the type of Node, the size of some groups may be
2151 variable (e.g., the group consisting of all the elements of a
2152 tuple), while others always contain the same number of elements
2153 - usually exactly one (e.g., the group containing the argument
2154 expression of a case-expression). Note, however, that the exact
2155 structure of the returned list (for a given node type) should in
2156 general not be depended upon, since it might be subject to
2157 change without notice.
2158 The function subtrees/1 and the constructor functions
2160 make_tree/2 and update_tree/2 can be a great help if one wants
2161 to traverse a syntax tree, visiting all its subtrees, but treat
2162 nodes of the tree in a uniform way in most or all cases. Using
2163 these functions makes this simple, and also assures that your
2164 code is not overly sensitive to extensions of the syntax tree
2165 data type, because any node types not explicitly handled by your
2166 code can be left to a default case.
2167 For example:
2169 postorder(F, Tree) ->
2171 F(case subtrees(Tree) of
2172 [] -> Tree;
2173 List -> update_tree(Tree,
2174 [[postorder(F, Subtree)
2175 || Subtree <- Group]
2176 || Group <- List])
2177 end).
2178 maps the function F on Tree and all its subtrees, doing a post-
2180 order traversal of the syntax tree. (Note the use of
2181 update_tree/2 to preserve node attributes.) For a simple func‐
2182 tion like:
2183 f(Node) ->
2185 case type(Node) of
2186 atom -> atom("a_" ++ atom_name(Node));
2187 _ -> Node
2188 end.
2189 the call postorder(fun f/1, Tree) will yield a new representa‐
2191 tion of Tree in which all atom names have been extended with the
2192 prefix "a_", but nothing else (including comments, annotations
2193 and line numbers) has been changed.
2194 See also: copy_attrs/2, is_leaf/1, make_tree/2, type/1.
2196 text(String::string()) -> syntaxTree()
2198 Creates an abstract piece of source code text. The result repre‐
2200 sents exactly the sequence of characters in String. This is use‐
2201 ful in cases when one wants full control of the resulting out‐
2202 put, e.g., for the appearance of floating-point numbers or macro
2203 definitions.
2204 See also: text_string/1.
2206 text_string(Node::syntaxTree()) -> string()
2208 Returns the character sequence represented by a text node.
2210 See also: text/1.
2212 tree(Type::atom()) -> #tree{type=atom(), attr=#attr{pos=term(),
2214 ann=[term()], com=none | #com{pre=[syntaxTree()], post=[syntax‐
2215 Tree()]}}, data=term()}
2216 Equivalent to tree(Type, []).
2218 tree(Type::atom(), Data::term()) -> #tree{type=atom(),
2220 attr=#attr{pos=term(), ann=[term()], com=none | #com{pre=[syntax‐
2221 Tree()], post=[syntaxTree()]}}, data=term()}
2222 For special purposes only. Creates an abstract syntax tree node
2224 with type tag Type and associated data Data.
2225 This function and the related is_tree/1 and data/1 provide a
2227 uniform way to extend the set of erl_parse node types. The asso‐
2228 ciated data is any term, whose format may depend on the type
2229 tag.
2230 Notes:
2232 * Any nodes created outside of this module must have type tags
2234 distinct from those currently defined by this module; see
2235 type/1 for a complete list.
2236 * The type tag of a syntax tree node may also be used as a
2238 primary tag by the erl_parse representation; in that case,
2239 the selector functions for that node type must handle both
2240 the abstract syntax tree and the erl_parse form. The func‐
2241 tion type(T) should return the correct type tag regardless
2242 of the representation of T, so that the user sees no differ‐
2243 ence between erl_syntax and erl_parse nodes.
2244 See also: data/1, is_tree/1, type/1.
2246 try_after_expr(Body::[syntaxTree()], After::[syntaxTree()]) -> syntax‐
2248 Tree()
2249 Equivalent to try_expr(Body, [], [], After).
2251 try_expr(Body::[syntaxTree()], Handlers::[syntaxTree()]) -> syntax‐
2253 Tree()
2254 Equivalent to try_expr(Body, [], Handlers).
2256 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2258 taxTree()]) -> syntaxTree()
2259 Equivalent to try_expr(Body, Clauses, Handlers, []).
2261 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2263 taxTree()], After::[syntaxTree()]) -> syntaxTree()
2264 Creates an abstract try-expression. If Body is [B1, ..., Bn],
2266 Clauses is [C1, ..., Cj], Handlers is [H1, ..., Hk], and After
2267 is [A1, ..., Am], the result represents "try B1, ..., Bn of C1;
2268 ...; Cj catch H1; ...; Hk after A1, ..., Am end". More exactly,
2269 if each Ci represents "(CPi) CGi -> CBi", and each Hi represents
2270 "(HPi) HGi -> HBi", then the result represents "try B1, ..., Bn
2271 of CP1 CG1 -> CB1; ...; CPj CGj -> CBj catch HP1 HG1 -> HB1;
2272 ...; HPk HGk -> HBk after A1, ..., Am end"; see case_expr/2. If
2273 Clauses is the empty list, the of ... section is left out. If
2274 After is the empty list, the after ... section is left out. If
2275 Handlers is the empty list, and After is nonempty, the catch ...
2276 section is left out.
2277 See also: case_expr/2, class_qualifier/2, clause/3,
2279 try_after_expr/2, try_expr/2, try_expr/3, try_expr_after/1,
2280 try_expr_body/1, try_expr_clauses/1, try_expr_handlers/1.
2281 try_expr_after(Node::syntaxTree()) -> [syntaxTree()]
2283 Returns the list of "after" subtrees of a try_expr node.
2285 See also: try_expr/4.
2287 try_expr_body(Node::syntaxTree()) -> [syntaxTree()]
2289 Returns the list of body subtrees of a try_expr node.
2291 See also: try_expr/4.
2293 try_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
2295 Returns the list of case-clause subtrees of a try_expr node. If
2297 Node represents "try Body catch H1; ...; Hn end", the result is
2298 the empty list.
2299 See also: try_expr/4.
2301 try_expr_handlers(Node::syntaxTree()) -> [syntaxTree()]
2303 Returns the list of handler-clause subtrees of a try_expr node.
2305 See also: try_expr/4.
2307 tuple(List::[syntaxTree()]) -> syntaxTree()
2309 Creates an abstract tuple. If Elements is [X1, ..., Xn], the
2311 result represents "{X1, ..., Xn}".
2312 Note: The Erlang language has distinct 1-tuples, i.e., {X} is
2314 always distinct from X itself.
2315 See also: tuple_elements/1, tuple_size/1.
2317 tuple_elements(Node::syntaxTree()) -> [syntaxTree()]
2319 Returns the list of element subtrees of a tuple node.
2321 See also: tuple/1.
2323 tuple_size(Node::syntaxTree()) -> non_neg_integer()
2325 Returns the number of elements of a tuple node.
2327 Note: this is equivalent to length(tuple_elements(Node)), but
2329 potentially more efficient.
2330 See also: tuple/1, tuple_elements/1.
2332 tuple_type() -> term()
2334 Equivalent to tuple_type(any_size).
2336 tuple_type(Elements::any_size | [syntaxTree()]) -> syntaxTree()
2338 Creates an abstract type tuple. If Elements is [T1, ..., Tn],
2340 the result represents "{T1, ..., Tn}"; otherwise, if Elements is
2341 any_size, it represents "tuple()".
2342 See also: tuple_type_elements/1.
2344 tuple_type_elements(Node::syntaxTree()) -> any_size | [syntaxTree()]
2346 Returns the list of type element subtrees of a tuple_type node.
2348 If Node represents "tuple()", any_size is returned; otherwise,
2349 if Node represents "{T1, ..., Tn}", [T1, ..., Tn] is returned.
2350 See also: tuple_type/0, tuple_type/1.
2352 type(Tree::syntaxTree()) -> atom()
2354 Returns the type tag of Node. If Node does not represent a syn‐
2356 tax tree, evaluation fails with reason badarg. Node types cur‐
2357 rently defined by this module are:
2358 application annotated_type arity_qualifier atom
2360 attribute binary binary_field bitstring_type
2361 block_expr case_expr catch_expr char
2362 class_qualifier clause comment cond_expr
2363 conjunction constrained_function_type constraint disjunction
2364 eof_marker error_marker float form_list
2365 fun_expr fun_type function function_type
2366 generator if_expr implicit_fun infix_expr
2367 integer integer_range_type list list_comp
2368 macro map_expr map_field_assoc map_field_exact
2369 map_type map_type_assoc map_type_exact match_expr module_quali‐
2370 fier
2371 named_fun_expr nil operator parentheses
2372 prefix_expr receive_expr record_access record_expr
2373 record_field record_index_expr record_type record_type_field
2374 size_qualifier string text try_expr
2375 tuple tuple_type typed_record_field type_application type_union
2376 underscore user_type_application variable
2377 warning_marker
2378 The user may (for special purposes) create additional nodes with
2381 other type tags, using the tree/2 function.
2382 Note: The primary constructor functions for a node type should
2384 always have the same name as the node type itself.
2385 See also: annotated_type/2, application/3, arity_qualifier/2,
2387 atom/1, attribute/2, binary/1, binary_field/2, bitstring_type/2,
2388 block_expr/1, case_expr/2, catch_expr/1, char/1, class_quali‐
2389 fier/2, clause/3, comment/2, cond_expr/1, conjunction/1, con‐
2390 strained_function_type/2, constraint/2, disjunction/1,
2391 eof_marker/0, error_marker/1, float/1, form_list/1, fun_expr/1,
2392 fun_type/0, function/2, function_type/1, function_type/2, gener‐
2393 ator/2, if_expr/1, implicit_fun/2, infix_expr/3, integer/1,
2394 integer_range_type/2, list/2, list_comp/2, macro/2, map_expr/2,
2395 map_field_assoc/2, map_field_exact/2, map_type/0, map_type/1,
2396 map_type_assoc/2, map_type_exact/2, match_expr/2, module_quali‐
2397 fier/2, named_fun_expr/2, nil/0, operator/1, parentheses/1, pre‐
2398 fix_expr/2, receive_expr/3, record_access/3, record_expr/2,
2399 record_field/2, record_index_expr/2, record_type/2,
2400 record_type_field/2, size_qualifier/2, string/1, text/1, tree/2,
2401 try_expr/3, tuple/1, tuple_type/0, tuple_type/1, type_applica‐
2402 tion/2, type_union/1, typed_record_field/2, underscore/0,
2403 user_type_application/2, variable/1, warning_marker/1.
2404 type_application(TypeName::syntaxTree(), Arguments::[syntaxTree()]) ->
2406 syntaxTree()
2407 Creates an abstract type application expression. If Arguments is
2409 [T1, ..., Tn], the result represents "TypeName(T1, ...Tn)".
2410 See also: type_application/3, type_application_arguments/1,
2412 type_application_name/1, user_type_application/2.
2413 type_application(Module::none | syntaxTree(), TypeName::syntaxTree(),
2415 Arguments::[syntaxTree()]) -> syntaxTree()
2416 Creates an abstract type application expression. If Module is
2418 none, this is call is equivalent to type_application(TypeName,
2419 Arguments), otherwise it is equivalent to type_application(mod‐
2420 ule_qualifier(Module, TypeName), Arguments).
2421 (This is a utility function.)
2423 See also: module_qualifier/2, type_application/2.
2425 type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2427 Returns the arguments subtrees of a type_application node.
2429 See also: type_application/2.
2431 type_application_name(Node::syntaxTree()) -> syntaxTree()
2433 Returns the type name subtree of a type_application node.
2435 See also: type_application/2.
2437 type_union(Types::[syntaxTree()]) -> syntaxTree()
2439 Creates an abstract type union. If Types is [T1, ..., Tn], the
2441 result represents "T1 | ... | Tn".
2442 See also: type_union_types/1.
2444 type_union_types(Node::syntaxTree()) -> [syntaxTree()]
2446 Returns the list of type subtrees of a type_union node.
2448 See also: type_union/1.
2450 typed_record_field(Field::syntaxTree(), Type::syntaxTree()) -> syntax‐
2452 Tree()
2453 Creates an abstract typed record field specification. The result
2455 represents "Field :: Type".
2456 See also: typed_record_field_body/1, typed_record_field_type/1.
2458 typed_record_field_body(Node::syntaxTree()) -> syntaxTree()
2460 Returns the field subtree of a typed_record_field node.
2462 See also: typed_record_field/2.
2464 typed_record_field_type(Node::syntaxTree()) -> syntaxTree()
2466 Returns the type subtree of a typed_record_field node.
2468 See also: typed_record_field/2.
2470 underscore() -> syntaxTree()
2472 Creates an abstract universal pattern ("_"). The lexical repre‐
2474 sentation is a single underscore character. Note that this is
2475 not a variable, lexically speaking.
2476 See also: variable/1.
2478 update_tree(Node::syntaxTree(), Groups::[[syntaxTree()]]) -> syntax‐
2480 Tree()
2481 Creates a syntax tree with the same type and attributes as the
2483 given tree. This is equivalent to copy_attrs(Node,
2484 make_tree(type(Node), Groups)).
2485 See also: copy_attrs/2, make_tree/2, type/1.
2487 user_type_application(TypeName::syntaxTree(), Arguments::[syntax‐
2489 Tree()]) -> syntaxTree()
2490 Creates an abstract user type. If Arguments is [T1, ..., Tn],
2492 the result represents "TypeName(T1, ...Tn)".
2493 See also: type_application/2, user_type_application_arguments/1,
2495 user_type_application_name/1.
2496 user_type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2498 Returns the arguments subtrees of a user_type_application node.
2500 See also: user_type_application/2.
2502 user_type_application_name(Node::syntaxTree()) -> syntaxTree()
2504 Returns the type name subtree of a user_type_application node.
2506 See also: user_type_application/2.
2508 variable(Name::atom() | string()) -> syntaxTree()
2510 Creates an abstract variable with the given name. Name may be
2512 any atom or string that represents a lexically valid variable
2513 name, but not a single underscore character; see underscore/0.
2514 Note: no checking is done whether the character sequence repre‐
2516 sents a proper variable name, i.e., whether or not its first
2517 character is an uppercase Erlang character, or whether it does
2518 not contain control characters, whitespace, etc.
2519 See also: underscore/0, variable_literal/1, variable_name/1.
2521 variable_literal(Node::syntaxTree()) -> string()
2523 Returns the name of a variable node as a string.
2525 See also: variable/1.
2527 variable_name(Node::syntaxTree()) -> atom()
2529 Returns the name of a variable node as an atom.
2531 See also: variable/1.
2533 warning_marker(Warning::term()) -> syntaxTree()
2535 Creates an abstract warning marker. The result represents an
2537 occurrence of a possible problem in the source code, with an
2538 associated Erlang I/O ErrorInfo structure given by Error (see
2539 module io(3) for details). Warning markers are regarded as
2540 source code forms, but have no defined lexical form.
2541 Note: this is supported only for backwards compatibility with
2543 existing parsers and tools.
2544 See also: eof_marker/0, error_marker/1, is_form/1, warn‐
2546 ing_marker_info/1.
2547 warning_marker_info(Node::syntaxTree()) -> term()
2549 Returns the ErrorInfo structure of a warning_marker node.
2551 See also: warning_marker/1.
2553
2555 Richard Carlsson <carlsson.richard@gmail.com>
2556 syntax_tools 2.1.4.1 erl_syntax(3)