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 or function value as a subterm. The func‐
93 tion recognises printable strings, in order to get a compact and
94 readable representation. Evaluation fails with reason badarg if
95 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 class_qualifier_stacktrace/1, try_expr/4.
499 class_qualifier(Class::syntaxTree(), Body::syntaxTree(), Stack‐
501 trace::syntaxTree()) -> syntaxTree()
502 Creates an abstract class qualifier. The result represents
504 "Class:Body:Stacktrace".
505 See also: class_qualifier_argument/1, class_qualifier_body/1,
507 try_expr/4.
508 class_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
510 Returns the argument (the class) subtree of a class_qualifier
512 node.
513 See also: class_qualifier/2.
515 class_qualifier_body(Node::syntaxTree()) -> syntaxTree()
517 Returns the body subtree of a class_qualifier node.
519 See also: class_qualifier/2.
521 class_qualifier_stacktrace(Node::syntaxTree()) -> syntaxTree()
523 Returns the stacktrace subtree of a class_qualifier node.
525 See also: class_qualifier/2.
527 clause(Guard::guard(), Body::[syntaxTree()]) -> syntaxTree()
529 Equivalent to clause([], Guard, Body).
531 clause(Patterns::[syntaxTree()], Guard::guard(), Body::[syntaxTree()])
533 -> syntaxTree()
534 Creates an abstract clause. If Patterns is [P1, ..., Pn] and
536 Body is [B1, ..., Bm], then if Guard is none, the result repre‐
537 sents "(P1, ..., Pn) -> B1, ..., Bm", otherwise, unless Guard is
538 a list, the result represents "(P1, ..., Pn) when Guard -> B1,
539 ..., Bm".
540 For simplicity, the Guard argument may also be any of the fol‐
542 lowing:
543 * An empty list []. This is equivalent to passing none.
545 * A nonempty list [E1, ..., Ej] of syntax trees. This is
547 equivalent to passing conjunction([E1, ..., Ej]).
548 * A nonempty list of lists of syntax trees [[E1_1, ...,
550 E1_k1], ..., [Ej_1, ..., Ej_kj]], which is equivalent to
551 passing disjunction([conjunction([E1_1, ..., E1_k1]), ...,
552 conjunction([Ej_1, ..., Ej_kj])]).
553 See also: clause/2, clause_body/1, clause_guard/1, clause_pat‐
555 terns/1.
556 clause_body(Node::syntaxTree()) -> [syntaxTree()]
558 Return the list of body subtrees of a clause node.
560 See also: clause/3.
562 clause_guard(Node::syntaxTree()) -> none | syntaxTree()
564 Returns the guard subtree of a clause node, if any. If Node rep‐
566 resents "(P1, ..., Pn) when Guard -> B1, ..., Bm", Guard is
567 returned. Otherwise, the result is none.
568 See also: clause/3.
570 clause_patterns(Node::syntaxTree()) -> [syntaxTree()]
572 Returns the list of pattern subtrees of a clause node.
574 See also: clause/3.
576 comment(Strings::[string()]) -> syntaxTree()
578 Equivalent to comment(none, Strings).
580 comment(Pad::padding(), Strings::[string()]) -> syntaxTree()
582 Creates an abstract comment with the given padding and text. If
584 Strings is a (possibly empty) list ["Txt1", ..., "TxtN"], the
585 result represents the source code text
586 %Txt1
588 ...
589 %TxtN
590 Padding states the number of empty character positions to the
592 left of the comment separating it horizontally from source code
593 on the same line (if any). If Padding is none, a default posi‐
594 tive number is used. If Padding is an integer less than 1, there
595 should be no separating space. Comments are in themselves
596 regarded as source program forms.
597 See also: comment/1, is_form/1.
599 comment_padding(Node::syntaxTree()) -> padding()
601 Returns the amount of padding before the comment, or none. The
603 latter means that a default padding may be used.
604 See also: comment/2.
606 comment_text(Node::syntaxTree()) -> [string()]
608 Returns the lines of text of the abstract comment.
610 See also: comment/2.
612 compact_list(Node::syntaxTree()) -> syntaxTree()
614 Yields the most compact form for an abstract list skeleton. The
616 result either represents "[E1, ..., En | Tail]", where Tail is
617 not a list skeleton, or otherwise simply "[E1, ..., En]". Anno‐
618 tations on subtrees of Node that represent list skeletons may be
619 lost, but comments will be propagated to the result. Returns
620 Node itself if Node does not represent a list skeleton.
621 See also: list/2, normalize_list/1.
623 concrete(Node::syntaxTree()) -> term()
625 Returns the Erlang term represented by a syntax tree. Evaluation
627 fails with reason badarg if Node does not represent a literal
628 term.
629 Note: Currently, the set of syntax trees which have a concrete
631 representation is larger than the set of trees which can be
632 built using the function abstract/1. An abstract character will
633 be concretised as an integer, while abstract/1 does not at
634 present yield an abstract character for any input. (Use the
635 char/1 function to explicitly create an abstract character.)
636 Note: arity_qualifier nodes are recognized. This is to follow
638 The Erlang Parser when it comes to wild attributes: both {F, A}
639 and F/A are recognized, which makes it possible to turn wild
640 attributes into recognized attributes without at the same time
641 making it impossible to compile files using the new syntax with
642 the old version of the Erlang Compiler.
643 See also: abstract/1, char/1, is_literal/1.
645 cond_expr(Clauses::[syntaxTree()]) -> syntaxTree()
647 Creates an abstract cond-expression. If Clauses is [C1, ...,
649 Cn], the result represents "cond C1; ...; Cn end". More exactly,
650 if each Ci represents "() Ei -> Bi", then the result represents
651 "cond E1 -> B1; ...; En -> Bn end".
652 See also: case_expr/2, clause/3, cond_expr_clauses/1.
654 cond_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
656 Returns the list of clause subtrees of a cond_expr node.
658 See also: cond_expr/1.
660 conjunction(Tests::[syntaxTree()]) -> syntaxTree()
662 Creates an abstract conjunction. If List is [E1, ..., En], the
664 result represents "E1, ..., En".
665 See also: conjunction_body/1, disjunction/1.
667 conjunction_body(Node::syntaxTree()) -> [syntaxTree()]
669 Returns the list of body subtrees of a conjunction node.
671 See also: conjunction/1.
673 cons(Head::syntaxTree(), Tail::syntaxTree()) -> syntaxTree()
675 "Optimising" list skeleton cons operation. Creates an abstract
677 list skeleton whose first element is Head and whose tail corre‐
678 sponds to Tail. This is similar to list([Head], Tail), except
679 that Tail may not be none, and that the result does not neces‐
680 sarily represent exactly "[Head | Tail]", but may depend on the
681 Tail subtree. E.g., if Tail represents [X, Y], the result may
682 represent "[Head, X, Y]", rather than "[Head | [X, Y]]". Annota‐
683 tions on Tail itself may be lost if Tail represents a list
684 skeleton, but comments on Tail are propagated to the result.
685 See also: list/2, list_head/1, list_tail/1.
687 constrained_function_type(FunctionType::syntaxTree(), FunctionCon‐
689 straint::[syntaxTree()]) -> syntaxTree()
690 Creates an abstract constrained function type. If FunctionCon‐
692 straint is [C1, ..., Cn], the result represents "FunctionType
693 when C1, ...Cn".
694 See also: constrained_function_type_argument/1, con‐
696 strained_function_type_body/1.
697 constrained_function_type_argument(Node::syntaxTree()) -> syntaxTree()
699 Returns the function constraint subtree of a constrained_func‐
701 tion_type node.
702 See also: constrained_function_type/2.
704 constrained_function_type_body(Node::syntaxTree()) -> syntaxTree()
706 Returns the function type subtree of a constrained_function_type
708 node.
709 See also: constrained_function_type/2.
711 constraint(Name::syntaxTree(), Types::[syntaxTree()]) -> syntaxTree()
713 Creates an abstract (subtype) constraint. The result represents
715 "Name :: Type".
716 See also: constraint_argument/1, constraint_body/1.
718 constraint_argument(Node::syntaxTree()) -> syntaxTree()
720 Returns the name subtree of a constraint node.
722 See also: constraint/2.
724 constraint_body(Node::syntaxTree()) -> [syntaxTree()]
726 Returns the type subtree of a constraint node.
728 See also: constraint/2.
730 copy_ann(Source::syntaxTree(), Target::syntaxTree()) -> syntaxTree()
732 Copies the list of user annotations from Source to Target.
734 Note: this is equivalent to set_ann(Target, get_ann(Source)),
736 but potentially more efficient.
737 See also: get_ann/1, set_ann/2.
739 copy_attrs(S::syntaxTree(), T::syntaxTree()) -> syntaxTree()
741 Copies the attributes from Source to Target.
743 Note: this is equivalent to set_attrs(Target,
745 get_attrs(Source)), but potentially more efficient.
746 See also: get_attrs/1, set_attrs/2.
748 copy_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
750 Tree()
751 Copies the pre- and postcomments from Source to Target.
753 Note: This is equivalent to set_postcomments(set_precom‐
755 ments(Target, get_precomments(Source)), get_postcom‐
756 ments(Source)), but potentially more efficient.
757 See also: comment/2, get_postcomments/1, get_precomments/1,
759 set_postcomments/2, set_precomments/2.
760 copy_pos(Source::syntaxTree(), Target::syntaxTree()) -> syntaxTree()
762 Copies the position information from Source to Target.
764 This is equivalent to set_pos(Target, get_pos(Source)), but
766 potentially more efficient.
767 See also: get_pos/1, set_pos/2.
769 data(Tree::syntaxTree()) -> term()
771 For special purposes only. Returns the associated data of a syn‐
773 tax tree node. Evaluation fails with reason badarg if
774 is_tree(Node) does not yield true.
775 See also: tree/2.
777 disjunction(Tests::[syntaxTree()]) -> syntaxTree()
779 Creates an abstract disjunction. If List is [E1, ..., En], the
781 result represents "E1; ...; En".
782 See also: conjunction/1, disjunction_body/1.
784 disjunction_body(Node::syntaxTree()) -> [syntaxTree()]
786 Returns the list of body subtrees of a disjunction node.
788 See also: disjunction/1.
790 eof_marker() -> syntaxTree()
792 Creates an abstract end-of-file marker. This represents the end
794 of input when reading a sequence of source code forms. An end-
795 of-file marker is itself regarded as a source code form (namely,
796 the last in any sequence in which it occurs). It has no defined
797 lexical form.
798 Note: this is retained only for backwards compatibility with
800 existing parsers and tools.
801 See also: error_marker/1, is_form/1, warning_marker/1.
803 error_marker(Error::term()) -> syntaxTree()
805 Creates an abstract error marker. The result represents an
807 occurrence of an error in the source code, with an associated
808 Erlang I/O ErrorInfo structure given by Error (see module io(3)
809 for details). Error markers are regarded as source code forms,
810 but have no defined lexical form.
811 Note: this is supported only for backwards compatibility with
813 existing parsers and tools.
814 See also: eof_marker/0, error_marker_info/1, is_form/1, warn‐
816 ing_marker/1.
817 error_marker_info(Node::syntaxTree()) -> term()
819 Returns the ErrorInfo structure of an error_marker node.
821 See also: error_marker/1.
823 flatten_form_list(Node::syntaxTree()) -> syntaxTree()
825 Flattens sublists of a form_list node. Returns Node with all
827 subtrees of type form_list recursively expanded, yielding a sin‐
828 gle "flat" abstract form sequence.
829 See also: form_list/1.
831 float(Value::float()) -> syntaxTree()
833 Creates an abstract floating-point literal. The lexical repre‐
835 sentation is the decimal floating-point numeral of Value.
836 See also: float_literal/1, float_value/1.
838 float_literal(Node::syntaxTree()) -> string()
840 Returns the numeral string represented by a float node.
842 See also: float/1.
844 float_value(Node::syntaxTree()) -> float()
846 Returns the value represented by a float node. Note that float‐
848 ing-point values should usually not be compared for equality.
849 See also: float/1.
851 form_list(Forms::[syntaxTree()]) -> syntaxTree()
853 Creates an abstract sequence of "source code forms". If Forms is
855 [F1, ..., Fn], where each Fi is a form (see is_form/1, the
856 result represents
857 F1
859 ...
860 Fn
861 where the Fi are separated by one or more line breaks. A node of
863 type form_list is itself regarded as a source code form; see
864 flatten_form_list/1.
865 Note: this is simply a way of grouping source code forms as a
867 single syntax tree, usually in order to form an Erlang module
868 definition.
869 See also: flatten_form_list/1, form_list_elements/1, is_form/1.
871 form_list_elements(Node::syntaxTree()) -> [syntaxTree()]
873 Returns the list of subnodes of a form_list node.
875 See also: form_list/1.
877 fun_expr(Clauses::[syntaxTree()]) -> syntaxTree()
879 Creates an abstract fun-expression. If Clauses is [C1, ..., Cn],
881 the result represents "fun C1; ...; Cn end". More exactly, if
882 each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then the result
883 represents "fun (P11, ..., P1m) G1 -> B1; ...; (Pn1, ..., Pnm)
884 Gn -> Bn end".
885 See also: fun_expr_arity/1, fun_expr_clauses/1.
887 fun_expr_arity(Node::syntaxTree()) -> arity()
889 Returns the arity of a fun_expr node. The result is the number
891 of parameter patterns in the first clause of the fun-expression;
892 subsequent clauses are ignored.
893 An exception is thrown if fun_expr_clauses(Node) returns an
895 empty list, or if the first element of that list is not a syntax
896 tree C of type clause such that clause_patterns(C) is a nonempty
897 list.
898 See also: clause/3, clause_patterns/1, fun_expr/1,
900 fun_expr_clauses/1.
901 fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
903 Returns the list of clause subtrees of a fun_expr node.
905 See also: fun_expr/1.
907 fun_type() -> syntaxTree()
909 Creates an abstract fun of any type. The result represents
911 "fun()".
912 function(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntaxTree()
914 Creates an abstract function definition. If Clauses is [C1, ...,
916 Cn], the result represents "Name C1; ...; Name Cn.". More
917 exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi", then
918 the result represents "Name(P11, ..., P1m) G1 -> B1; ...;
919 Name(Pn1, ..., Pnm) Gn -> Bn.". Function definitions are source
920 code forms.
921 See also: function_arity/1, function_clauses/1, function_name/1,
923 is_form/1.
924 function_arity(Node::syntaxTree()) -> arity()
926 Returns the arity of a function node. The result is the number
928 of parameter patterns in the first clause of the function; sub‐
929 sequent clauses are ignored.
930 An exception is thrown if function_clauses(Node) returns an
932 empty list, or if the first element of that list is not a syntax
933 tree C of type clause such that clause_patterns(C) is a nonempty
934 list.
935 See also: clause/3, clause_patterns/1, function/2, func‐
937 tion_clauses/1.
938 function_clauses(Node::syntaxTree()) -> [syntaxTree()]
940 Returns the list of clause subtrees of a function node.
942 See also: function/2.
944 function_name(Node::syntaxTree()) -> syntaxTree()
946 Returns the name subtree of a function node.
948 See also: function/2.
950 function_type(Type) -> term()
952 Equivalent to function_type(any_arity, Type).
954 function_type(Arguments::any_arity | syntaxTree(), Return::syntax‐
956 Tree()) -> syntaxTree()
957 Creates an abstract function type. If Arguments is [T1, ...,
959 Tn], then if it occurs within a function specification, the
960 result represents "(T1, ...Tn) -> Return"; otherwise it repre‐
961 sents "fun((T1, ...Tn) -> Return)". If Arguments is any_arity,
962 it represents "fun((...) -> Return)".
963 Note that the erl_parse representation is identical for "Func‐
965 tionType" and "fun(FunctionType)".
966 See also: function_type_arguments/1, function_type_return/1.
968 function_type_arguments(Node::syntaxTree()) -> any_arity | [syntax‐
970 Tree()]
971 Returns the argument types subtrees of a function_type node. If
973 Node represents "fun((...) -> Return)", any_arity is returned;
974 otherwise, if Node represents "(T1, ...Tn) -> Return" or
975 "fun((T1, ...Tn) -> Return)", [T1, ..., Tn] is returned.
976 See also: function_type/1, function_type/2.
978 function_type_return(Node::syntaxTree()) -> syntaxTree()
980 Returns the return type subtrees of a function_type node.
982 See also: function_type/1, function_type/2.
984 generator(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
986 Creates an abstract generator. The result represents "Pattern <-
988 Body".
989 See also: binary_comp/2, generator_body/1, generator_pattern/1,
991 list_comp/2.
992 generator_body(Node::syntaxTree()) -> syntaxTree()
994 Returns the body subtree of a generator node.
996 See also: generator/2.
998 generator_pattern(Node::syntaxTree()) -> syntaxTree()
1000 Returns the pattern subtree of a generator node.
1002 See also: generator/2.
1004 get_ann(Tree::syntaxTree()) -> [term()]
1006 Returns the list of user annotations associated with a syntax
1008 tree node. For a newly created node, this is the empty list. The
1009 annotations may be any terms.
1010 See also: get_attrs/1, set_ann/2.
1012 get_attrs(Tree::syntaxTree()) -> syntaxTreeAttributes()
1014 Returns a representation of the attributes associated with a
1016 syntax tree node. The attributes are all the extra information
1017 that can be attached to a node. Currently, this includes posi‐
1018 tion information, source code comments, and user annotations.
1019 The result of this function cannot be inspected directly; only
1020 attached to another node (see set_attrs/2).
1021 For accessing individual attributes, see get_pos/1, get_ann/1,
1023 get_precomments/1 and get_postcomments/1.
1024 See also: get_ann/1, get_pos/1, get_postcomments/1, get_precom‐
1026 ments/1, set_attrs/2.
1027 get_pos(Tree::syntaxTree()) -> term()
1029 Returns the position information associated with Node. This is
1031 usually a nonnegative integer (indicating the source code line
1032 number), but may be any term. By default, all new tree nodes
1033 have their associated position information set to the integer
1034 zero.
1035 See also: get_attrs/1, set_pos/2.
1037 get_postcomments(Tree::syntaxTree()) -> [syntaxTree()]
1039 Returns the associated post-comments of a node. This is a possi‐
1041 bly empty list of abstract comments, in top-down textual order.
1042 When the code is formatted, post-comments are typically dis‐
1043 played to the right of and/or below the node. For example:
1044 {foo, X, Y} % Post-comment of tuple
1046 If possible, the comment should be moved past any following sep‐
1048 arator characters on the same line, rather than placing the sep‐
1049 arators on the following line. E.g.:
1050 foo([X | Xs], Y) ->
1052 foo(Xs, bar(X)); % Post-comment of 'bar(X)' node
1053 ...
1054 (where the comment is moved past the rightmost ")" and the ";").
1056 See also: comment/2, get_attrs/1, get_precomments/1, set_post‐
1058 comments/2.
1059 get_precomments(Tree::syntaxTree()) -> [syntaxTree()]
1061 Returns the associated pre-comments of a node. This is a possi‐
1063 bly empty list of abstract comments, in top-down textual order.
1064 When the code is formatted, pre-comments are typically displayed
1065 directly above the node. For example:
1066 % Pre-comment of function
1068 foo(X) -> {bar, X}.
1069 If possible, the comment should be moved before any preceding
1071 separator characters on the same line. E.g.:
1072 foo([X | Xs]) ->
1074 % Pre-comment of 'bar(X)' node
1075 [bar(X) | foo(Xs)];
1076 ...
1077 (where the comment is moved before the "[").
1079 See also: comment/2, get_attrs/1, get_postcomments/1, set_pre‐
1081 comments/2.
1082 has_comments(Tree::syntaxTree()) -> boolean()
1084 Yields false if the node has no associated comments, and true
1086 otherwise.
1087 Note: This is equivalent to (get_precomments(Node) == []) and
1089 (get_postcomments(Node) == []), but potentially more efficient.
1090 See also: get_postcomments/1, get_precomments/1, remove_com‐
1092 ments/1.
1093 if_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1095 Creates an abstract if-expression. If Clauses is [C1, ..., Cn],
1097 the result represents "if C1; ...; Cn end". More exactly, if
1098 each Ci represents "() Gi -> Bi", then the result represents "if
1099 G1 -> B1; ...; Gn -> Bn end".
1100 See also: case_expr/2, clause/3, if_expr_clauses/1.
1102 if_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1104 Returns the list of clause subtrees of an if_expr node.
1106 See also: if_expr/1.
1108 implicit_fun(Name::syntaxTree()) -> syntaxTree()
1110 Creates an abstract "implicit fun" expression. The result repre‐
1112 sents "fun Name". Name should represent either F/A or M:F/A
1113 See also: arity_qualifier/2, implicit_fun/2, implicit_fun/3,
1115 implicit_fun_name/1, module_qualifier/2.
1116 implicit_fun(Name::syntaxTree(), Arity::none | syntaxTree()) -> syntax‐
1118 Tree()
1119 Creates an abstract "implicit fun" expression. If Arity is none,
1121 this is equivalent to implicit_fun(Name), otherwise it is equiv‐
1122 alent to implicit_fun(arity_qualifier(Name, Arity)).
1123 (This is a utility function.)
1125 See also: implicit_fun/1, implicit_fun/3.
1127 implicit_fun(Module::none | syntaxTree(), Name::syntaxTree(),
1129 Arity::syntaxTree()) -> syntaxTree()
1130 Creates an abstract module-qualified "implicit fun" expression.
1132 If Module is none, this is equivalent to implicit_fun(Name,
1133 Arity), otherwise it is equivalent to implicit_fun(module_quali‐
1134 fier(Module, arity_qualifier(Name, Arity)).
1135 (This is a utility function.)
1137 See also: implicit_fun/1, implicit_fun/2.
1139 implicit_fun_name(Node::syntaxTree()) -> syntaxTree()
1141 Returns the name subtree of an implicit_fun node.
1143 Note: if Node represents "fun N/A" or "fun M:N/A", then the
1145 result is the subtree representing "N/A" or "M:N/A", respec‐
1146 tively.
1147 See also: arity_qualifier/2, implicit_fun/1, module_qualifier/2.
1149 infix_expr(Left::syntaxTree(), Operator::syntaxTree(), Right::syntax‐
1151 Tree()) -> syntaxTree()
1152 Creates an abstract infix operator expression. The result repre‐
1154 sents "Left Operator Right".
1155 See also: infix_expr_left/1, infix_expr_operator/1,
1157 infix_expr_right/1, prefix_expr/2.
1158 infix_expr_left(Node::syntaxTree()) -> syntaxTree()
1160 Returns the left argument subtree of an infix_expr node.
1162 See also: infix_expr/3.
1164 infix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1166 Returns the operator subtree of an infix_expr node.
1168 See also: infix_expr/3.
1170 infix_expr_right(Node::syntaxTree()) -> syntaxTree()
1172 Returns the right argument subtree of an infix_expr node.
1174 See also: infix_expr/3.
1176 integer(Value::integer()) -> syntaxTree()
1178 Creates an abstract integer literal. The lexical representation
1180 is the canonical decimal numeral of Value.
1181 See also: integer_literal/1, integer_value/1, is_integer/2.
1183 integer_literal(Node::syntaxTree()) -> string()
1185 Returns the numeral string represented by an integer node.
1187 See also: integer/1.
1189 integer_range_type(Low::syntaxTree(), High::syntaxTree()) -> syntax‐
1191 Tree()
1192 Creates an abstract range type. The result represents "Low ..
1194 High".
1195 See also: integer_range_type_high/1, integer_range_type_low/1.
1197 integer_range_type_high(Node::syntaxTree()) -> syntaxTree()
1199 Returns the high limit of an integer_range_type node.
1201 See also: integer_range_type/2.
1203 integer_range_type_low(Node::syntaxTree()) -> syntaxTree()
1205 Returns the low limit of an integer_range_type node.
1207 See also: integer_range_type/2.
1209 integer_value(Node::syntaxTree()) -> integer()
1211 Returns the value represented by an integer node.
1213 See also: integer/1.
1215 is_atom(Node::syntaxTree(), Value::atom()) -> boolean()
1217 Returns true if Node has type atom and represents Value, other‐
1219 wise false.
1220 See also: atom/1.
1222 is_char(Node::syntaxTree(), Value::char()) -> boolean()
1224 Returns true if Node has type char and represents Value, other‐
1226 wise false.
1227 See also: char/1.
1229 is_form(Node::syntaxTree()) -> boolean()
1231 Returns true if Node is a syntax tree representing a so-called
1233 "source code form", otherwise false. Forms are the Erlang source
1234 code units which, placed in sequence, constitute an Erlang pro‐
1235 gram. Current form types are:
1236 attribute comment error_marker eof_marker
1238 form_list function warning_marker text
1239 See also: attribute/2, comment/2, eof_marker/0, error_marker/1,
1242 form_list/1, function/2, type/1, warning_marker/1.
1243 is_integer(Node::syntaxTree(), Value::integer()) -> boolean()
1245 Returns true if Node has type integer and represents Value, oth‐
1247 erwise false.
1248 See also: integer/1.
1250 is_leaf(Node::syntaxTree()) -> boolean()
1252 Returns true if Node is a leaf node, otherwise false. The cur‐
1254 rently recognised leaf node types are:
1255 atom char comment eof_marker error_marker
1257 float fun_type integer nil operator string
1258 text underscore variable warning_marker
1259 A node of type map_expr is a leaf node if and only if it has no
1262 argument and no fields. A node of type map_type is a leaf node
1263 if and only if it has no fields (any_size). A node of type tuple
1264 is a leaf node if and only if its arity is zero. A node of type
1265 tuple_type is a leaf node if and only if it has no elements
1266 (any_size).
1267 Note: not all literals are leaf nodes, and vice versa. E.g.,
1269 tuples with nonzero arity and nonempty lists may be literals,
1270 but are not leaf nodes. Variables, on the other hand, are leaf
1271 nodes but not literals.
1272 See also: is_literal/1, type/1.
1274 is_list_skeleton(Node::syntaxTree()) -> boolean()
1276 Returns true if Node has type list or nil, otherwise false.
1278 See also: list/2, nil/0.
1280 is_literal(T::syntaxTree()) -> boolean()
1282 Returns true if Node represents a literal term, otherwise false.
1284 This function returns true if and only if the value of con‐
1285 crete(Node) is defined.
1286 See also: abstract/1, concrete/1.
1288 is_proper_list(Node::syntaxTree()) -> boolean()
1290 Returns true if Node represents a proper list, and false other‐
1292 wise. A proper list is a list skeleton either on the form "[]"
1293 or "[E1, ..., En]", or "[... | Tail]" where recursively Tail
1294 also represents a proper list.
1295 Note: Since Node is a syntax tree, the actual run-time values
1297 corresponding to its subtrees may often be partially or com‐
1298 pletely unknown. Thus, if Node represents e.g. "[... | Ns]"
1299 (where Ns is a variable), then the function will return false,
1300 because it is not known whether Ns will be bound to a list at
1301 run-time. If Node instead represents e.g. "[1, 2, 3]" or "[A |
1302 []]", then the function will return true.
1303 See also: list/2.
1305 is_string(Node::syntaxTree(), Value::string()) -> boolean()
1307 Returns true if Node has type string and represents Value, oth‐
1309 erwise false.
1310 See also: string/1.
1312 is_tree(Tree::syntaxTree()) -> boolean()
1314 For special purposes only. Returns true if Tree is an abstract
1316 syntax tree and false otherwise.
1317 Note: this function yields false for all "old-style" erl_parse-
1319 compatible "parse trees".
1320 See also: tree/2.
1322 join_comments(Source::syntaxTree(), Target::syntaxTree()) -> syntax‐
1324 Tree()
1325 Appends the comments of Source to the current comments of Tar‐
1327 get.
1328 Note: This is equivalent to add_postcomments(get_postcom‐
1330 ments(Source), add_precomments(get_precomments(Source), Tar‐
1331 get)), but potentially more efficient.
1332 See also: add_postcomments/2, add_precomments/2, comment/2,
1334 get_postcomments/1, get_precomments/1.
1335 list(List::[syntaxTree()]) -> syntaxTree()
1337 Equivalent to list(List, none).
1339 list(Elements::[syntaxTree()], Tail::none | syntaxTree()) -> syntax‐
1341 Tree()
1342 Constructs an abstract list skeleton. The result has type list
1344 or nil. If List is a nonempty list [E1, ..., En], the result has
1345 type list and represents either "[E1, ..., En]", if Tail is
1346 none, or otherwise "[E1, ..., En | Tail]". If List is the empty
1347 list, Tail must be none, and in that case the result has type
1348 nil and represents "[]" (see nil/0).
1349 The difference between lists as semantic objects (built up of
1351 individual "cons" and "nil" terms) and the various syntactic
1352 forms for denoting lists may be bewildering at first. This mod‐
1353 ule provides functions both for exact control of the syntactic
1354 representation as well as for the simple composition and decon‐
1355 struction in terms of cons and head/tail operations.
1356 Note: in list(Elements, none), the "nil" list terminator is
1358 implicit and has no associated information (see get_attrs/1),
1359 while in the seemingly equivalent list(Elements, Tail) when Tail
1360 has type nil, the list terminator subtree Tail may have attached
1361 attributes such as position, comments, and annotations, which
1362 will be preserved in the result.
1363 See also: compact_list/1, cons/2, get_attrs/1, is_list_skele‐
1365 ton/1, is_proper_list/1, list/1, list_elements/1, list_head/1,
1366 list_length/1, list_prefix/1, list_suffix/1, list_tail/1, nil/0,
1367 normalize_list/1.
1368 list_comp(Template::syntaxTree(), Body::[syntaxTree()]) -> syntaxTree()
1370 Creates an abstract list comprehension. If Body is [E1, ...,
1372 En], the result represents "[Template || E1, ..., En]".
1373 See also: generator/2, list_comp_body/1, list_comp_template/1.
1375 list_comp_body(Node::syntaxTree()) -> [syntaxTree()]
1377 Returns the list of body subtrees of a list_comp node.
1379 See also: list_comp/2.
1381 list_comp_template(Node::syntaxTree()) -> syntaxTree()
1383 Returns the template subtree of a list_comp node.
1385 See also: list_comp/2.
1387 list_elements(Node::syntaxTree()) -> [syntaxTree()]
1389 Returns the list of element subtrees of a list skeleton. Node
1391 must represent a proper list. E.g., if Node represents "[X1, X2
1392 | [X3, X4 | []]", then list_elements(Node) yields the list [X1,
1393 X2, X3, X4].
1394 See also: is_proper_list/1, list/2.
1396 list_head(Node::syntaxTree()) -> syntaxTree()
1398 Returns the head element subtree of a list node. If Node repre‐
1400 sents "[Head ...]", the result will represent "Head".
1401 See also: cons/2, list/2, list_tail/1.
1403 list_length(Node::syntaxTree()) -> non_neg_integer()
1405 Returns the number of element subtrees of a list skeleton. Node
1407 must represent a proper list. E.g., if Node represents "[X1 |
1408 [X2, X3 | [X4, X5, X6]]]", then list_length(Node) returns the
1409 integer 6.
1410 Note: this is equivalent to length(list_elements(Node)), but
1412 potentially more efficient.
1413 See also: is_proper_list/1, list/2, list_elements/1.
1415 list_prefix(Node::syntaxTree()) -> [syntaxTree()]
1417 Returns the prefix element subtrees of a list node. If Node rep‐
1419 resents "[E1, ..., En]" or "[E1, ..., En | Tail]", the returned
1420 value is [E1, ..., En].
1421 See also: list/2.
1423 list_suffix(Node::syntaxTree()) -> none | syntaxTree()
1425 Returns the suffix subtree of a list node, if one exists. If
1427 Node represents "[E1, ..., En | Tail]", the returned value is
1428 Tail, otherwise, i.e., if Node represents "[E1, ..., En]", none
1429 is returned.
1430 Note that even if this function returns some Tail that is not
1432 none, the type of Tail can be nil, if the tail has been given
1433 explicitly, and the list skeleton has not been compacted (see
1434 compact_list/1).
1435 See also: compact_list/1, list/2, nil/0.
1437 list_tail(Node::syntaxTree()) -> syntaxTree()
1439 Returns the tail of a list node. If Node represents a single-
1441 element list "[E]", then the result has type nil, representing
1442 "[]". If Node represents "[E1, E2 ...]", the result will repre‐
1443 sent "[E2 ...]", and if Node represents "[Head | Tail]", the
1444 result will represent "Tail".
1445 See also: cons/2, list/2, list_head/1.
1447 macro(Name::syntaxTree()) -> syntaxTree()
1449 Equivalent to macro(Name, none).
1451 macro(Name::syntaxTree(), Arguments::none | [syntaxTree()]) -> syntax‐
1453 Tree()
1454 Creates an abstract macro application. If Arguments is none, the
1456 result represents "?Name", otherwise, if Arguments is [A1, ...,
1457 An], the result represents "?Name(A1, ..., An)".
1458 Notes: if Arguments is the empty list, the result will thus rep‐
1460 resent "?Name()", including a pair of matching parentheses.
1461 The only syntactical limitation imposed by the preprocessor on
1463 the arguments to a macro application (viewed as sequences of
1464 tokens) is that they must be balanced with respect to parenthe‐
1465 ses, brackets, begin ... end, case ... end, etc. The text node
1466 type can be used to represent arguments which are not regular
1467 Erlang constructs.
1468 See also: macro/1, macro_arguments/1, macro_name/1, text/1.
1470 macro_arguments(Node::syntaxTree()) -> none | [syntaxTree()]
1472 Returns the list of argument subtrees of a macro node, if any.
1474 If Node represents "?Name", none is returned. Otherwise, if Node
1475 represents "?Name(A1, ..., An)", [A1, ..., An] is returned.
1476 See also: macro/2.
1478 macro_name(Node::syntaxTree()) -> syntaxTree()
1480 Returns the name subtree of a macro node.
1482 See also: macro/2.
1484 make_tree(X1::atom(), X2::[[syntaxTree()]]) -> syntaxTree()
1486 Creates a syntax tree with the given type and subtrees. Type
1488 must be a node type name (see type/1) that does not denote a
1489 leaf node type (see is_leaf/1). Groups must be a nonempty list
1490 of groups of syntax trees, representing the subtrees of a node
1491 of the given type, in left-to-right order as they would occur in
1492 the printed program text, grouped by category as done by sub‐
1493 trees/1.
1494 The result of copy_attrs(Node, make_tree(type(Node), sub‐
1496 trees(Node))) (see update_tree/2) represents the same source
1497 code text as the original Node, assuming that subtrees(Node)
1498 yields a nonempty list. However, it does not necessarily have
1499 the same data representation as Node.
1500 See also: copy_attrs/2, is_leaf/1, subtrees/1, type/1,
1502 update_tree/2.
1503 map_expr(Fields::[syntaxTree()]) -> syntaxTree()
1505 Equivalent to map_expr(none, Fields).
1507 map_expr(Argument::none | syntaxTree(), Fields::[syntaxTree()]) -> syn‐
1509 taxTree()
1510 Creates an abstract map expression. If Fields is [F1, ..., Fn],
1512 then if Argument is none, the result represents "#{F1, ...,
1513 Fn}", otherwise it represents "Argument#{F1, ..., Fn}".
1514 See also: map_expr/1, map_expr_argument/1, map_expr_fields/1,
1516 map_field_assoc/2, map_field_exact/2.
1517 map_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1519 Returns the argument subtree of a map_expr node, if any. If Node
1521 represents "#{...}", none is returned. Otherwise, if Node repre‐
1522 sents "Argument#{...}", Argument is returned.
1523 See also: map_expr/2.
1525 map_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1527 Returns the list of field subtrees of a map_expr node.
1529 See also: map_expr/2.
1531 map_field_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1533 Tree()
1534 Creates an abstract map assoc field. The result represents "Name
1536 => Value".
1537 See also: map_expr/2, map_field_assoc_name/1,
1539 map_field_assoc_value/1.
1540 map_field_assoc_name(Node::syntaxTree()) -> syntaxTree()
1542 Returns the name subtree of a map_field_assoc node.
1544 See also: map_field_assoc/2.
1546 map_field_assoc_value(Node::syntaxTree()) -> syntaxTree()
1548 Returns the value subtree of a map_field_assoc node.
1550 See also: map_field_assoc/2.
1552 map_field_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntax‐
1554 Tree()
1555 Creates an abstract map exact field. The result represents "Name
1557 := Value".
1558 See also: map_expr/2, map_field_exact_name/1,
1560 map_field_exact_value/1.
1561 map_field_exact_name(Node::syntaxTree()) -> syntaxTree()
1563 Returns the name subtree of a map_field_exact node.
1565 See also: map_field_exact/2.
1567 map_field_exact_value(Node::syntaxTree()) -> syntaxTree()
1569 Returns the value subtree of a map_field_exact node.
1571 See also: map_field_exact/2.
1573 map_type() -> term()
1575 Equivalent to map_type(any_size).
1577 map_type(Fields::any_size | [syntaxTree()]) -> syntaxTree()
1579 Creates an abstract type map. If Fields is [F1, ..., Fn], the
1581 result represents "#{F1, ..., Fn}"; otherwise, if Fields is
1582 any_size, it represents "map()".
1583 See also: map_type_fields/1.
1585 map_type_assoc(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1587 Creates an abstract map type assoc field. The result represents
1589 "Name => Value".
1590 See also: map_type/1, map_type_assoc_name/1,
1592 map_type_assoc_value/1.
1593 map_type_assoc_name(Node::syntaxTree()) -> syntaxTree()
1595 Returns the name subtree of a map_type_assoc node.
1597 See also: map_type_assoc/2.
1599 map_type_assoc_value(Node::syntaxTree()) -> syntaxTree()
1601 Returns the value subtree of a map_type_assoc node.
1603 See also: map_type_assoc/2.
1605 map_type_exact(Name::syntaxTree(), Value::syntaxTree()) -> syntaxTree()
1607 Creates an abstract map type exact field. The result represents
1609 "Name := Value".
1610 See also: map_type/1, map_type_exact_name/1,
1612 map_type_exact_value/1.
1613 map_type_exact_name(Node::syntaxTree()) -> syntaxTree()
1615 Returns the name subtree of a map_type_exact node.
1617 See also: map_type_exact/2.
1619 map_type_exact_value(Node::syntaxTree()) -> syntaxTree()
1621 Returns the value subtree of a map_type_exact node.
1623 See also: map_type_exact/2.
1625 map_type_fields(Node::syntaxTree()) -> any_size | [syntaxTree()]
1627 Returns the list of field subtrees of a map_type node. If Node
1629 represents "map()", any_size is returned; otherwise, if Node
1630 represents "#{F1, ..., Fn}", [F1, ..., Fn] is returned.
1631 See also: map_type/0, map_type/1.
1633 match_expr(Pattern::syntaxTree(), Body::syntaxTree()) -> syntaxTree()
1635 Creates an abstract match-expression. The result represents
1637 "Pattern = Body".
1638 See also: match_expr_body/1, match_expr_pattern/1.
1640 match_expr_body(Node::syntaxTree()) -> syntaxTree()
1642 Returns the body subtree of a match_expr node.
1644 See also: match_expr/2.
1646 match_expr_pattern(Node::syntaxTree()) -> syntaxTree()
1648 Returns the pattern subtree of a match_expr node.
1650 See also: match_expr/2.
1652 meta(T::syntaxTree()) -> syntaxTree()
1654 Creates a meta-representation of a syntax tree. The result rep‐
1656 resents an Erlang expression "MetaTree" which, if evaluated,
1657 will yield a new syntax tree representing the same source code
1658 text as Tree (although the actual data representation may be
1659 different). The expression represented by MetaTree is implemen‐
1660 tation independent with regard to the data structures used by
1661 the abstract syntax tree implementation. Comments attached to
1662 nodes of Tree will be preserved, but other attributes are lost.
1663 Any node in Tree whose node type is variable (see type/1), and
1665 whose list of annotations (see get_ann/1) contains the atom
1666 meta_var, will remain unchanged in the resulting tree, except
1667 that exactly one occurrence of meta_var is removed from its
1668 annotation list.
1669 The main use of the function meta/1 is to transform a data
1671 structure Tree, which represents a piece of program code, into a
1672 form that is representation independent when printed. E.g., sup‐
1673 pose Tree represents a variable named "V". Then (assuming a
1674 function print/1 for printing syntax trees), evaluating
1675 print(abstract(Tree)) - simply using abstract/1 to map the
1676 actual data structure onto a syntax tree representation - would
1677 output a string that might look something like "{tree, variable,
1678 ..., "V", ...}", which is obviously dependent on the implementa‐
1679 tion of the abstract syntax trees. This could e.g. be useful for
1680 caching a syntax tree in a file. However, in some situations
1681 like in a program generator generator (with two "generator"), it
1682 may be unacceptable. Using print(meta(Tree)) instead would out‐
1683 put a representation independent syntax tree generating expres‐
1684 sion; in the above case, something like "erl_syntax:vari‐
1685 able("V")".
1686 See also: abstract/1, get_ann/1, type/1.
1688 module_qualifier(Module::syntaxTree(), Body::syntaxTree()) -> syntax‐
1690 Tree()
1691 Creates an abstract module qualifier. The result represents
1693 "Module:Body".
1694 See also: module_qualifier_argument/1, module_qualifier_body/1.
1696 module_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
1698 Returns the argument (the module) subtree of a module_qualifier
1700 node.
1701 See also: module_qualifier/2.
1703 module_qualifier_body(Node::syntaxTree()) -> syntaxTree()
1705 Returns the body subtree of a module_qualifier node.
1707 See also: module_qualifier/2.
1709 named_fun_expr(Name::syntaxTree(), Clauses::[syntaxTree()]) -> syntax‐
1711 Tree()
1712 Creates an abstract named fun-expression. If Clauses is [C1,
1714 ..., Cn], the result represents "fun Name C1; ...; Name Cn end".
1715 More exactly, if each Ci represents "(Pi1, ..., Pim) Gi -> Bi",
1716 then the result represents "fun Name(P11, ..., P1m) G1 -> B1;
1717 ...; Name(Pn1, ..., Pnm) Gn -> Bn end".
1718 See also: named_fun_expr_arity/1, named_fun_expr_clauses/1,
1720 named_fun_expr_name/1.
1721 named_fun_expr_arity(Node::syntaxTree()) -> arity()
1723 Returns the arity of a named_fun_expr node. The result is the
1725 number of parameter patterns in the first clause of the named
1726 fun-expression; subsequent clauses are ignored.
1727 An exception is thrown if named_fun_expr_clauses(Node) returns
1729 an empty list, or if the first element of that list is not a
1730 syntax tree C of type clause such that clause_patterns(C) is a
1731 nonempty list.
1732 See also: clause/3, clause_patterns/1, named_fun_expr/2,
1734 named_fun_expr_clauses/1.
1735 named_fun_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1737 Returns the list of clause subtrees of a named_fun_expr node.
1739 See also: named_fun_expr/2.
1741 named_fun_expr_name(Node::syntaxTree()) -> syntaxTree()
1743 Returns the name subtree of a named_fun_expr node.
1745 See also: named_fun_expr/2.
1747 nil() -> syntaxTree()
1749 Creates an abstract empty list. The result represents "[]". The
1751 empty list is traditionally called "nil".
1752 See also: is_list_skeleton/1, list/2.
1754 normalize_list(Node::syntaxTree()) -> syntaxTree()
1756 Expands an abstract list skeleton to its most explicit form. If
1758 Node represents "[E1, ..., En | Tail]", the result represents
1759 "[E1 | ... [En | Tail1] ... ]", where Tail1 is the result of
1760 normalize_list(Tail). If Node represents "[E1, ..., En]", the
1761 result simply represents "[E1 | ... [En | []] ... ]". If Node
1762 does not represent a list skeleton, Node itself is returned.
1763 See also: compact_list/1, list/2.
1765 operator(Name::atom() | string()) -> syntaxTree()
1767 Creates an abstract operator. The name of the operator is the
1769 character sequence represented by Name. This is analogous to the
1770 print name of an atom, but an operator is never written within
1771 single-quotes; e.g., the result of operator(++')' represents
1772 "++" rather than "`++''".
1773 See also: atom/1, operator_literal/1, operator_name/1.
1775 operator_literal(Node::syntaxTree()) -> string()
1777 Returns the literal string represented by an operator node. This
1779 is simply the operator name as a string.
1780 See also: operator/1.
1782 operator_name(Node::syntaxTree()) -> atom()
1784 Returns the name of an operator node. Note that the name is
1786 returned as an atom.
1787 See also: operator/1.
1789 parentheses(Expr::syntaxTree()) -> syntaxTree()
1791 Creates an abstract parenthesised expression. The result repre‐
1793 sents "(Body)", independently of the context.
1794 See also: parentheses_body/1.
1796 parentheses_body(Node::syntaxTree()) -> syntaxTree()
1798 Returns the body subtree of a parentheses node.
1800 See also: parentheses/1.
1802 prefix_expr(Operator::syntaxTree(), Argument::syntaxTree()) -> syntax‐
1804 Tree()
1805 Creates an abstract prefix operator expression. The result rep‐
1807 resents "Operator Argument".
1808 See also: infix_expr/3, prefix_expr_argument/1, pre‐
1810 fix_expr_operator/1.
1811 prefix_expr_argument(Node::syntaxTree()) -> syntaxTree()
1813 Returns the argument subtree of a prefix_expr node.
1815 See also: prefix_expr/2.
1817 prefix_expr_operator(Node::syntaxTree()) -> syntaxTree()
1819 Returns the operator subtree of a prefix_expr node.
1821 See also: prefix_expr/2.
1823 receive_expr(Clauses::[syntaxTree()]) -> syntaxTree()
1825 Equivalent to receive_expr(Clauses, none, []).
1827 receive_expr(Clauses::[syntaxTree()], Timeout::none | syntaxTree(),
1829 Action::[syntaxTree()]) -> syntaxTree()
1830 Creates an abstract receive-expression. If Timeout is none, the
1832 result represents "receive C1; ...; Cn end" (the Action argument
1833 is ignored). Otherwise, if Clauses is [C1, ..., Cn] and Action
1834 is [A1, ..., Am], the result represents "receive C1; ...; Cn
1835 after Timeout -> A1, ..., Am end". More exactly, if each Ci rep‐
1836 resents "(Pi) Gi -> Bi", then the result represents "receive P1
1837 G1 -> B1; ...; Pn Gn -> Bn ... end".
1838 Note that in Erlang, a receive-expression must have at least one
1840 clause if no timeout part is specified.
1841 See also: case_expr/2, clause/3, receive_expr/1,
1843 receive_expr_action/1, receive_expr_clauses/1,
1844 receive_expr_timeout/1.
1845 receive_expr_action(Node::syntaxTree()) -> [syntaxTree()]
1847 Returns the list of action body subtrees of a receive_expr node.
1849 If Node represents "receive C1; ...; Cn end", this is the empty
1850 list.
1851 See also: receive_expr/3.
1853 receive_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
1855 Returns the list of clause subtrees of a receive_expr node.
1857 See also: receive_expr/3.
1859 receive_expr_timeout(Node::syntaxTree()) -> none | syntaxTree()
1861 Returns the timeout subtree of a receive_expr node, if any. If
1863 Node represents "receive C1; ...; Cn end", none is returned.
1864 Otherwise, if Node represents "receive C1; ...; Cn after Timeout
1865 -> ... end", Timeout is returned.
1866 See also: receive_expr/3.
1868 record_access(Argument::syntaxTree(), Type::syntaxTree(), Field::syn‐
1870 taxTree()) -> syntaxTree()
1871 Creates an abstract record field access expression. The result
1873 represents "Argument#Type.Field".
1874 See also: record_access_argument/1, record_access_field/1,
1876 record_access_type/1, record_expr/3.
1877 record_access_argument(Node::syntaxTree()) -> syntaxTree()
1879 Returns the argument subtree of a record_access node.
1881 See also: record_access/3.
1883 record_access_field(Node::syntaxTree()) -> syntaxTree()
1885 Returns the field subtree of a record_access node.
1887 See also: record_access/3.
1889 record_access_type(Node::syntaxTree()) -> syntaxTree()
1891 Returns the type subtree of a record_access node.
1893 See also: record_access/3.
1895 record_expr(Type::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1897 Equivalent to record_expr(none, Type, Fields).
1899 record_expr(Argument::none | syntaxTree(), Type::syntaxTree(),
1901 Fields::[syntaxTree()]) -> syntaxTree()
1902 Creates an abstract record expression. If Fields is [F1, ...,
1904 Fn], then if Argument is none, the result represents "#Type{F1,
1905 ..., Fn}", otherwise it represents "Argument#Type{F1, ..., Fn}".
1906 See also: record_access/3, record_expr/2, record_expr_argu‐
1908 ment/1, record_expr_fields/1, record_expr_type/1,
1909 record_field/2, record_index_expr/2.
1910 record_expr_argument(Node::syntaxTree()) -> none | syntaxTree()
1912 Returns the argument subtree of a record_expr node, if any. If
1914 Node represents "#Type{...}", none is returned. Otherwise, if
1915 Node represents "Argument#Type{...}", Argument is returned.
1916 See also: record_expr/3.
1918 record_expr_fields(Node::syntaxTree()) -> [syntaxTree()]
1920 Returns the list of field subtrees of a record_expr node.
1922 See also: record_expr/3.
1924 record_expr_type(Node::syntaxTree()) -> syntaxTree()
1926 Returns the type subtree of a record_expr node.
1928 See also: record_expr/3.
1930 record_field(Name::syntaxTree()) -> syntaxTree()
1932 Equivalent to record_field(Name, none).
1934 record_field(Name::syntaxTree(), Value::none | syntaxTree()) -> syntax‐
1936 Tree()
1937 Creates an abstract record field specification. If Value is
1939 none, the result represents simply "Name", otherwise it repre‐
1940 sents "Name = Value".
1941 See also: record_expr/3, record_field_name/1,
1943 record_field_value/1.
1944 record_field_name(Node::syntaxTree()) -> syntaxTree()
1946 Returns the name subtree of a record_field node.
1948 See also: record_field/2.
1950 record_field_value(Node::syntaxTree()) -> none | syntaxTree()
1952 Returns the value subtree of a record_field node, if any. If
1954 Node represents "Name", none is returned. Otherwise, if Node
1955 represents "Name = Value", Value is returned.
1956 See also: record_field/2.
1958 record_index_expr(Type::syntaxTree(), Field::syntaxTree()) -> syntax‐
1960 Tree()
1961 Creates an abstract record field index expression. The result
1963 represents "#Type.Field".
1964 (Note: the function name record_index/2 is reserved by the
1966 Erlang compiler, which is why that name could not be used for
1967 this constructor.)
1968 See also: record_expr/3, record_index_expr_field/1,
1970 record_index_expr_type/1.
1971 record_index_expr_field(Node::syntaxTree()) -> syntaxTree()
1973 Returns the field subtree of a record_index_expr node.
1975 See also: record_index_expr/2.
1977 record_index_expr_type(Node::syntaxTree()) -> syntaxTree()
1979 Returns the type subtree of a record_index_expr node.
1981 See also: record_index_expr/2.
1983 record_type(Name::syntaxTree(), Fields::[syntaxTree()]) -> syntaxTree()
1985 Creates an abstract record type. If Fields is [F1, ..., Fn], the
1987 result represents "#Name{F1, ..., Fn}".
1988 See also: record_type_fields/1, record_type_name/1.
1990 record_type_field(Name::syntaxTree(), Type::syntaxTree()) -> syntax‐
1992 Tree()
1993 Creates an abstract record type field. The result represents
1995 "Name :: Type".
1996 See also: record_type_field_name/1, record_type_field_type/1.
1998 record_type_field_name(Node::syntaxTree()) -> syntaxTree()
2000 Returns the name subtree of a record_type_field node.
2002 See also: record_type_field/2.
2004 record_type_field_type(Node::syntaxTree()) -> syntaxTree()
2006 Returns the type subtree of a record_type_field node.
2008 See also: record_type_field/2.
2010 record_type_fields(Node::syntaxTree()) -> [syntaxTree()]
2012 Returns the fields subtree of a record_type node.
2014 See also: record_type/2.
2016 record_type_name(Node::syntaxTree()) -> syntaxTree()
2018 Returns the name subtree of a record_type node.
2020 See also: record_type/2.
2022 remove_comments(Node::syntaxTree()) -> syntaxTree()
2024 Clears the associated comments of Node.
2026 Note: This is equivalent to set_precomments(set_postcom‐
2028 ments(Node, []), []), but potentially more efficient.
2029 See also: set_postcomments/2, set_precomments/2.
2031 revert(Node::syntaxTree()) -> syntaxTree()
2033 Returns an erl_parse-compatible representation of a syntax tree,
2035 if possible. If Tree represents a well-formed Erlang program or
2036 expression, the conversion should work without problems. Typi‐
2037 cally, is_tree/1 yields true if conversion failed (i.e., the
2038 result is still an abstract syntax tree), and false otherwise.
2039 The is_tree/1 test is not completely foolproof. For a few spe‐
2041 cial node types (e.g. arity_qualifier), if such a node occurs in
2042 a context where it is not expected, it will be left unchanged as
2043 a non-reverted subtree of the result. This can only happen if
2044 Tree does not actually represent legal Erlang code.
2045 See also: erl_parse(3), revert_forms/1.
2047 revert_forms(Forms::forms()) -> [erl_parse()]
2049 Reverts a sequence of Erlang source code forms. The sequence can
2051 be given either as a form_list syntax tree (possibly nested), or
2052 as a list of "program form" syntax trees. If successful, the
2053 corresponding flat list of erl_parse-compatible syntax trees is
2054 returned (see revert/1). If some program form could not be
2055 reverted, {error, Form} is thrown. Standalone comments in the
2056 form sequence are discarded.
2057 See also: form_list/1, is_form/1, revert/1.
2059 set_ann(Node::syntaxTree(), As::[term()]) -> syntaxTree()
2061 Sets the list of user annotations of Node to Annotations.
2063 See also: add_ann/2, copy_ann/2, get_ann/1.
2065 set_attrs(Node::syntaxTree(), Attr::syntaxTreeAttributes()) -> syntax‐
2067 Tree()
2068 Sets the attributes of Node to Attributes.
2070 See also: copy_attrs/2, get_attrs/1.
2072 set_pos(Node::syntaxTree(), Pos::term()) -> syntaxTree()
2074 Sets the position information of Node to Pos.
2076 See also: copy_pos/2, get_pos/1.
2078 set_postcomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntax‐
2080 Tree()
2081 Sets the post-comments of Node to Comments. Comments should be a
2083 possibly empty list of abstract comments, in top-down textual
2084 order
2085 See also: add_postcomments/2, comment/2, copy_comments/2,
2087 get_postcomments/1, join_comments/2, remove_comments/1, set_pre‐
2088 comments/2.
2089 set_precomments(Node::syntaxTree(), Cs::[syntaxTree()]) -> syntaxTree()
2091 Sets the pre-comments of Node to Comments. Comments should be a
2093 possibly empty list of abstract comments, in top-down textual
2094 order.
2095 See also: add_precomments/2, comment/2, copy_comments/2,
2097 get_precomments/1, join_comments/2, remove_comments/1, set_post‐
2098 comments/2.
2099 size_qualifier(Body::syntaxTree(), Size::syntaxTree()) -> syntaxTree()
2101 Creates an abstract size qualifier. The result represents
2103 "Body:Size".
2104 See also: size_qualifier_argument/1, size_qualifier_body/1.
2106 size_qualifier_argument(Node::syntaxTree()) -> syntaxTree()
2108 Returns the argument subtree (the size) of a size_qualifier
2110 node.
2111 See also: size_qualifier/2.
2113 size_qualifier_body(Node::syntaxTree()) -> syntaxTree()
2115 Returns the body subtree of a size_qualifier node.
2117 See also: size_qualifier/2.
2119 string(String::string()) -> syntaxTree()
2121 Creates an abstract string literal. The result represents "Text"
2123 (including the surrounding double-quotes), where Text corre‐
2124 sponds to the sequence of characters in Value, but not repre‐
2125 senting a specific string literal.
2126 For example, the result of string("x\ny") represents any and all
2128 of "x\ny", "x\12y", "x\012y" and "x\^Jy"; see char/1.
2129 See also: char/1, is_string/2, string_literal/1, string_lit‐
2131 eral/2, string_value/1.
2132 string_literal(Node::syntaxTree()) -> nonempty_string()
2134 Returns the literal string represented by a string node. This
2136 includes surrounding double-quote characters. Characters beyond
2137 255 will be escaped.
2138 See also: string/1.
2140 string_literal(Node::syntaxTree(), X2::encoding()) -> nonempty_string()
2142 Returns the literal string represented by a string node. This
2144 includes surrounding double-quote characters. Depending on the
2145 encoding characters beyond 255 will be escaped (latin1) or
2146 copied as is (utf8).
2147 See also: string/1.
2149 string_value(Node::syntaxTree()) -> string()
2151 Returns the value represented by a string node.
2153 See also: string/1.
2155 subtrees(T::syntaxTree()) -> [[syntaxTree()]]
2157 Returns the grouped list of all subtrees of a syntax tree. If
2159 Node is a leaf node (see is_leaf/1), this is the empty list,
2160 otherwise the result is always a nonempty list, containing the
2161 lists of subtrees of Node, in left-to-right order as they occur
2162 in the printed program text, and grouped by category. Often,
2163 each group contains only a single subtree.
2164 Depending on the type of Node, the size of some groups may be
2166 variable (e.g., the group consisting of all the elements of a
2167 tuple), while others always contain the same number of elements
2168 - usually exactly one (e.g., the group containing the argument
2169 expression of a case-expression). Note, however, that the exact
2170 structure of the returned list (for a given node type) should in
2171 general not be depended upon, since it might be subject to
2172 change without notice.
2173 The function subtrees/1 and the constructor functions
2175 make_tree/2 and update_tree/2 can be a great help if one wants
2176 to traverse a syntax tree, visiting all its subtrees, but treat
2177 nodes of the tree in a uniform way in most or all cases. Using
2178 these functions makes this simple, and also assures that your
2179 code is not overly sensitive to extensions of the syntax tree
2180 data type, because any node types not explicitly handled by your
2181 code can be left to a default case.
2182 For example:
2184 postorder(F, Tree) ->
2186 F(case subtrees(Tree) of
2187 [] -> Tree;
2188 List -> update_tree(Tree,
2189 [[postorder(F, Subtree)
2190 || Subtree <- Group]
2191 || Group <- List])
2192 end).
2193 maps the function F on Tree and all its subtrees, doing a post-
2195 order traversal of the syntax tree. (Note the use of
2196 update_tree/2 to preserve node attributes.) For a simple func‐
2197 tion like:
2198 f(Node) ->
2200 case type(Node) of
2201 atom -> atom("a_" ++ atom_name(Node));
2202 _ -> Node
2203 end.
2204 the call postorder(fun f/1, Tree) will yield a new representa‐
2206 tion of Tree in which all atom names have been extended with the
2207 prefix "a_", but nothing else (including comments, annotations
2208 and line numbers) has been changed.
2209 See also: copy_attrs/2, is_leaf/1, make_tree/2, type/1.
2211 text(String::string()) -> syntaxTree()
2213 Creates an abstract piece of source code text. The result repre‐
2215 sents exactly the sequence of characters in String. This is use‐
2216 ful in cases when one wants full control of the resulting out‐
2217 put, e.g., for the appearance of floating-point numbers or macro
2218 definitions.
2219 See also: text_string/1.
2221 text_string(Node::syntaxTree()) -> string()
2223 Returns the character sequence represented by a text node.
2225 See also: text/1.
2227 tree(Type::atom()) -> #tree{type=atom(), attr=#attr{pos=term(),
2229 ann=[term()], com=none | #com{pre=[syntaxTree()], post=[syntax‐
2230 Tree()]}}, data=term()}
2231 Equivalent to tree(Type, []).
2233 tree(Type::atom(), Data::term()) -> #tree{type=atom(),
2235 attr=#attr{pos=term(), ann=[term()], com=none | #com{pre=[syntax‐
2236 Tree()], post=[syntaxTree()]}}, data=term()}
2237 For special purposes only. Creates an abstract syntax tree node
2239 with type tag Type and associated data Data.
2240 This function and the related is_tree/1 and data/1 provide a
2242 uniform way to extend the set of erl_parse node types. The asso‐
2243 ciated data is any term, whose format may depend on the type
2244 tag.
2245 Notes:
2247 * Any nodes created outside of this module must have type tags
2249 distinct from those currently defined by this module; see
2250 type/1 for a complete list.
2251 * The type tag of a syntax tree node may also be used as a
2253 primary tag by the erl_parse representation; in that case,
2254 the selector functions for that node type must handle both
2255 the abstract syntax tree and the erl_parse form. The func‐
2256 tion type(T) should return the correct type tag regardless
2257 of the representation of T, so that the user sees no differ‐
2258 ence between erl_syntax and erl_parse nodes.
2259 See also: data/1, is_tree/1, type/1.
2261 try_after_expr(Body::[syntaxTree()], After::[syntaxTree()]) -> syntax‐
2263 Tree()
2264 Equivalent to try_expr(Body, [], [], After).
2266 try_expr(Body::[syntaxTree()], Handlers::[syntaxTree()]) -> syntax‐
2268 Tree()
2269 Equivalent to try_expr(Body, [], Handlers).
2271 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2273 taxTree()]) -> syntaxTree()
2274 Equivalent to try_expr(Body, Clauses, Handlers, []).
2276 try_expr(Body::[syntaxTree()], Clauses::[syntaxTree()], Handlers::[syn‐
2278 taxTree()], After::[syntaxTree()]) -> syntaxTree()
2279 Creates an abstract try-expression. If Body is [B1, ..., Bn],
2281 Clauses is [C1, ..., Cj], Handlers is [H1, ..., Hk], and After
2282 is [A1, ..., Am], the result represents "try B1, ..., Bn of C1;
2283 ...; Cj catch H1; ...; Hk after A1, ..., Am end". More exactly,
2284 if each Ci represents "(CPi) CGi -> CBi", and each Hi represents
2285 "(HPi) HGi -> HBi", then the result represents "try B1, ..., Bn
2286 of CP1 CG1 -> CB1; ...; CPj CGj -> CBj catch HP1 HG1 -> HB1;
2287 ...; HPk HGk -> HBk after A1, ..., Am end"; see case_expr/2. If
2288 Clauses is the empty list, the of ... section is left out. If
2289 After is the empty list, the after ... section is left out. If
2290 Handlers is the empty list, and After is nonempty, the catch ...
2291 section is left out.
2292 See also: case_expr/2, class_qualifier/2, clause/3,
2294 try_after_expr/2, try_expr/2, try_expr/3, try_expr_after/1,
2295 try_expr_body/1, try_expr_clauses/1, try_expr_handlers/1.
2296 try_expr_after(Node::syntaxTree()) -> [syntaxTree()]
2298 Returns the list of "after" subtrees of a try_expr node.
2300 See also: try_expr/4.
2302 try_expr_body(Node::syntaxTree()) -> [syntaxTree()]
2304 Returns the list of body subtrees of a try_expr node.
2306 See also: try_expr/4.
2308 try_expr_clauses(Node::syntaxTree()) -> [syntaxTree()]
2310 Returns the list of case-clause subtrees of a try_expr node. If
2312 Node represents "try Body catch H1; ...; Hn end", the result is
2313 the empty list.
2314 See also: try_expr/4.
2316 try_expr_handlers(Node::syntaxTree()) -> [syntaxTree()]
2318 Returns the list of handler-clause subtrees of a try_expr node.
2320 See also: try_expr/4.
2322 tuple(List::[syntaxTree()]) -> syntaxTree()
2324 Creates an abstract tuple. If Elements is [X1, ..., Xn], the
2326 result represents "{X1, ..., Xn}".
2327 Note: The Erlang language has distinct 1-tuples, i.e., {X} is
2329 always distinct from X itself.
2330 See also: tuple_elements/1, tuple_size/1.
2332 tuple_elements(Node::syntaxTree()) -> [syntaxTree()]
2334 Returns the list of element subtrees of a tuple node.
2336 See also: tuple/1.
2338 tuple_size(Node::syntaxTree()) -> non_neg_integer()
2340 Returns the number of elements of a tuple node.
2342 Note: this is equivalent to length(tuple_elements(Node)), but
2344 potentially more efficient.
2345 See also: tuple/1, tuple_elements/1.
2347 tuple_type() -> term()
2349 Equivalent to tuple_type(any_size).
2351 tuple_type(Elements::any_size | [syntaxTree()]) -> syntaxTree()
2353 Creates an abstract type tuple. If Elements is [T1, ..., Tn],
2355 the result represents "{T1, ..., Tn}"; otherwise, if Elements is
2356 any_size, it represents "tuple()".
2357 See also: tuple_type_elements/1.
2359 tuple_type_elements(Node::syntaxTree()) -> any_size | [syntaxTree()]
2361 Returns the list of type element subtrees of a tuple_type node.
2363 If Node represents "tuple()", any_size is returned; otherwise,
2364 if Node represents "{T1, ..., Tn}", [T1, ..., Tn] is returned.
2365 See also: tuple_type/0, tuple_type/1.
2367 type(Tree::syntaxTree()) -> atom()
2369 Returns the type tag of Node. If Node does not represent a syn‐
2371 tax tree, evaluation fails with reason badarg. Node types cur‐
2372 rently defined by this module are:
2373 application annotated_type arity_qualifier atom
2375 attribute binary binary_field bitstring_type
2376 block_expr case_expr catch_expr char
2377 class_qualifier clause comment cond_expr
2378 conjunction constrained_function_type constraint disjunction
2379 eof_marker error_marker float form_list
2380 fun_expr fun_type function function_type
2381 generator if_expr implicit_fun infix_expr
2382 integer integer_range_type list list_comp
2383 macro map_expr map_field_assoc map_field_exact
2384 map_type map_type_assoc map_type_exact match_expr module_quali‐
2385 fier
2386 named_fun_expr nil operator parentheses
2387 prefix_expr receive_expr record_access record_expr
2388 record_field record_index_expr record_type record_type_field
2389 size_qualifier string text try_expr
2390 tuple tuple_type typed_record_field type_application type_union
2391 underscore user_type_application variable
2392 warning_marker
2393 The user may (for special purposes) create additional nodes with
2396 other type tags, using the tree/2 function.
2397 Note: The primary constructor functions for a node type should
2399 always have the same name as the node type itself.
2400 See also: annotated_type/2, application/3, arity_qualifier/2,
2402 atom/1, attribute/2, binary/1, binary_field/2, bitstring_type/2,
2403 block_expr/1, case_expr/2, catch_expr/1, char/1, class_quali‐
2404 fier/2, clause/3, comment/2, cond_expr/1, conjunction/1, con‐
2405 strained_function_type/2, constraint/2, disjunction/1,
2406 eof_marker/0, error_marker/1, float/1, form_list/1, fun_expr/1,
2407 fun_type/0, function/2, function_type/1, function_type/2, gener‐
2408 ator/2, if_expr/1, implicit_fun/2, infix_expr/3, integer/1,
2409 integer_range_type/2, list/2, list_comp/2, macro/2, map_expr/2,
2410 map_field_assoc/2, map_field_exact/2, map_type/0, map_type/1,
2411 map_type_assoc/2, map_type_exact/2, match_expr/2, module_quali‐
2412 fier/2, named_fun_expr/2, nil/0, operator/1, parentheses/1, pre‐
2413 fix_expr/2, receive_expr/3, record_access/3, record_expr/2,
2414 record_field/2, record_index_expr/2, record_type/2,
2415 record_type_field/2, size_qualifier/2, string/1, text/1, tree/2,
2416 try_expr/3, tuple/1, tuple_type/0, tuple_type/1, type_applica‐
2417 tion/2, type_union/1, typed_record_field/2, underscore/0,
2418 user_type_application/2, variable/1, warning_marker/1.
2419 type_application(TypeName::syntaxTree(), Arguments::[syntaxTree()]) ->
2421 syntaxTree()
2422 Creates an abstract type application expression. If Arguments is
2424 [T1, ..., Tn], the result represents "TypeName(T1, ...Tn)".
2425 See also: type_application/3, type_application_arguments/1,
2427 type_application_name/1, user_type_application/2.
2428 type_application(Module::none | syntaxTree(), TypeName::syntaxTree(),
2430 Arguments::[syntaxTree()]) -> syntaxTree()
2431 Creates an abstract type application expression. If Module is
2433 none, this is call is equivalent to type_application(TypeName,
2434 Arguments), otherwise it is equivalent to type_application(mod‐
2435 ule_qualifier(Module, TypeName), Arguments).
2436 (This is a utility function.)
2438 See also: module_qualifier/2, type_application/2.
2440 type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2442 Returns the arguments subtrees of a type_application node.
2444 See also: type_application/2.
2446 type_application_name(Node::syntaxTree()) -> syntaxTree()
2448 Returns the type name subtree of a type_application node.
2450 See also: type_application/2.
2452 type_union(Types::[syntaxTree()]) -> syntaxTree()
2454 Creates an abstract type union. If Types is [T1, ..., Tn], the
2456 result represents "T1 | ... | Tn".
2457 See also: type_union_types/1.
2459 type_union_types(Node::syntaxTree()) -> [syntaxTree()]
2461 Returns the list of type subtrees of a type_union node.
2463 See also: type_union/1.
2465 typed_record_field(Field::syntaxTree(), Type::syntaxTree()) -> syntax‐
2467 Tree()
2468 Creates an abstract typed record field specification. The result
2470 represents "Field :: Type".
2471 See also: typed_record_field_body/1, typed_record_field_type/1.
2473 typed_record_field_body(Node::syntaxTree()) -> syntaxTree()
2475 Returns the field subtree of a typed_record_field node.
2477 See also: typed_record_field/2.
2479 typed_record_field_type(Node::syntaxTree()) -> syntaxTree()
2481 Returns the type subtree of a typed_record_field node.
2483 See also: typed_record_field/2.
2485 underscore() -> syntaxTree()
2487 Creates an abstract universal pattern ("_"). The lexical repre‐
2489 sentation is a single underscore character. Note that this is
2490 not a variable, lexically speaking.
2491 See also: variable/1.
2493 update_tree(Node::syntaxTree(), Groups::[[syntaxTree()]]) -> syntax‐
2495 Tree()
2496 Creates a syntax tree with the same type and attributes as the
2498 given tree. This is equivalent to copy_attrs(Node,
2499 make_tree(type(Node), Groups)).
2500 See also: copy_attrs/2, make_tree/2, type/1.
2502 user_type_application(TypeName::syntaxTree(), Arguments::[syntax‐
2504 Tree()]) -> syntaxTree()
2505 Creates an abstract user type. If Arguments is [T1, ..., Tn],
2507 the result represents "TypeName(T1, ...Tn)".
2508 See also: type_application/2, user_type_application_arguments/1,
2510 user_type_application_name/1.
2511 user_type_application_arguments(Node::syntaxTree()) -> [syntaxTree()]
2513 Returns the arguments subtrees of a user_type_application node.
2515 See also: user_type_application/2.
2517 user_type_application_name(Node::syntaxTree()) -> syntaxTree()
2519 Returns the type name subtree of a user_type_application node.
2521 See also: user_type_application/2.
2523 variable(Name::atom() | string()) -> syntaxTree()
2525 Creates an abstract variable with the given name. Name may be
2527 any atom or string that represents a lexically valid variable
2528 name, but not a single underscore character; see underscore/0.
2529 Note: no checking is done whether the character sequence repre‐
2531 sents a proper variable name, i.e., whether or not its first
2532 character is an uppercase Erlang character, or whether it does
2533 not contain control characters, whitespace, etc.
2534 See also: underscore/0, variable_literal/1, variable_name/1.
2536 variable_literal(Node::syntaxTree()) -> string()
2538 Returns the name of a variable node as a string.
2540 See also: variable/1.
2542 variable_name(Node::syntaxTree()) -> atom()
2544 Returns the name of a variable node as an atom.
2546 See also: variable/1.
2548 warning_marker(Warning::term()) -> syntaxTree()
2550 Creates an abstract warning marker. The result represents an
2552 occurrence of a possible problem in the source code, with an
2553 associated Erlang I/O ErrorInfo structure given by Error (see
2554 module io(3) for details). Warning markers are regarded as
2555 source code forms, but have no defined lexical form.
2556 Note: this is supported only for backwards compatibility with
2558 existing parsers and tools.
2559 See also: eof_marker/0, error_marker/1, is_form/1, warn‐
2561 ing_marker_info/1.
2562 warning_marker_info(Node::syntaxTree()) -> term()
2564 Returns the ErrorInfo structure of a warning_marker node.
2566 See also: warning_marker/1.
2568
2570 Richard Carlsson <carlsson.richard@gmail.com>
2571 syntax_tools 2.2.1 erl_syntax(3)