View Source erl_syntax (syntax_tools v3.2)
Abstract Erlang syntax trees.
This module defines an abstract data type for representing Erlang source code as
syntax trees, in a way that is backwards compatible with the data structures
created by the Erlang standard library parser module erl_parse
(often referred
to as "parse trees", which is a bit of a misnomer). This means that all
erl_parse
trees are valid abstract syntax trees, but the reverse is not true:
abstract syntax trees can in general not be used as input to functions expecting
an erl_parse
tree. However, as long as an abstract syntax tree represents a
correct Erlang program, the function revert/1
should be able to transform it
to the corresponding erl_parse
representation.
A recommended starting point for the first-time user is the documentation of the
syntaxTree()
data type, and the function type/1
.
NOTES:
This module deals with the composition and decomposition of syntactic entities (as opposed to semantic ones); its purpose is to hide all direct references to the data structures used to represent these entities. With few exceptions, the functions in this module perform no semantic interpretation of their inputs, and in general, the user is assumed to pass type-correct arguments - if this is not done, the effects are not defined.
With the exception of the erl_parse()
data structures, the
internal representations of abstract syntax trees are subject to change without
notice, and should not be documented outside this module. Furthermore, we do not
give any guarantees on how an abstract syntax tree may or may not be
represented, with the following exceptions: no syntax tree is represented by a
single atom, such as none
, by a list constructor [X | Y]
, or by the empty
list []
. This can be relied on when writing functions that operate on syntax
trees.
Summary
Functions
Creates an abstract empty list. The result represents "[]
". The empty list is
traditionally called "nil".
Returns the syntax tree corresponding to an Erlang term. Term
must be a
literal term, i.e., one that can be represented as a source code literal. Thus,
it may not contain a process identifier, port, reference or function value as a
subterm. The function recognises printable strings, in order to get a compact
and readable representation. Evaluation fails with reason badarg
if Term
is
not a literal term.
Appends the term Annotation
to the list of user annotations of Node
.
Appends Comments
to the post-comments of Node
.
Appends Comments
to the pre-comments of Node
.
Creates an abstract annotated type expression. The result represents
"*Name* :: *Type*
".
Returns the type subtrees of an annotated_type
node.
Returns the name subtree of an annotated_type
node.
Creates an abstract function application expression. If Arguments
is
[A1, ..., An]
, the result represents "*Operator*(*A1*, ..., *An*)
".
Creates an abstract function application expression. If Module
is none
, this
is call is equivalent to application(Function, Arguments)
,
otherwise it is equivalent to
application(module_qualifier(Module, Function), Arguments)
.
Returns the list of argument subtrees of an application
node.
Returns the operator subtree of an application
node.
Creates an abstract arity qualifier. The result represents "*Body*/*Arity*
".
Returns the argument (the arity) subtree of an arity_qualifier
node.
Returns the body subtree of an arity_qualifier
node.
Creates an abstract atom literal. The print name of the atom is the character
sequence represented by Name
.
Returns the literal string represented by an atom
node. This includes
surrounding single-quote characters if necessary. Characters beyond 255 will be
escaped.
Returns the literal string represented by an atom
node. This includes
surrounding single-quote characters if necessary. Depending on the encoding a
character beyond 255 will be escaped (latin1
) or copied as is (utf8
).
Returns the printname of an atom
node.
Returns the value represented by an atom
node.
Equivalent to attribute(Name, none).
Creates an abstract program attribute. If Arguments
is [A1, ..., An]
, the
result represents "-*Name*(*A1*, ..., *An*).
". Otherwise, if Arguments
is
none
, the result represents "-*Name*.
". The latter form makes it possible to
represent preprocessor directives such as "-endif.
". Attributes are source
code forms.
Returns the list of argument subtrees of an attribute
node, if any. If Node
represents "-*Name*.
", the result is none
. Otherwise, if Node
represents
"-*Name*(*E1*, ..., *En*).
", [E1, ..., E1]
is returned.
Returns the name subtree of an attribute
node.
Creates an abstract binary-object template. If Fields
is [F1, ..., Fn]
, the
result represents "<<*F1*, ..., *Fn*>>
".
Creates an abstract binary comprehension. If Body
is [E1, ..., En]
, the
result represents "<<*Template* || *E1*, ..., *En*>>
".
Returns the list of body subtrees of a binary_comp
node.
Returns the template subtree of a binary_comp
node.
Equivalent to binary_field(Body, []).
Creates an abstract binary template field. If Types
is the empty list, the
result simply represents "*Body*
", otherwise, if Types
is [T1, ..., Tn]
,
the result represents "*Body*/*T1*-...-*Tn*
".
Creates an abstract binary template field. If Size
is none
, this is
equivalent to "binary_field(Body, Types)
", otherwise it is
equivalent to
"binary_field(size_qualifier(Body, Size), Types)
".
Returns the body subtree of a binary_field
.
Returns the size specifier subtree of a binary_field
node, if any. If Node
represents "*Body*:*Size*
" or "*Body*:*Size*/*T1*, ..., *Tn*
", the result is
Size
, otherwise none
is returned.
Returns the list of type-specifier subtrees of a binary_field
node. If Node
represents ".../*T1*, ..., *Tn*
", the result is [T1, ..., Tn]
, otherwise the
result is the empty list.
Returns the list of field subtrees of a binary
node.
Creates an abstract binary_generator. The result represents
"*Pattern*<- *Body*
".
Returns the body subtree of a generator
node.
Returns the pattern subtree of a generator
node.
Creates an abstract bitstring type. The result represents "*<<_:M, _:_*N>>*
".
Returns the number of start bits, M
, of a bitstring_type
node.
Returns the segment size, N
, of a bitstring_type
node.
Creates an abstract block expression. If Body
is [B1, ..., Bn]
, the result
represents "begin *B1*, ..., *Bn* end
".
Returns the list of body subtrees of a block_expr
node.
Creates an abstract case-expression. If Clauses
is [C1, ..., Cn]
, the result
represents "case *Argument* of *C1*; ...; *Cn* end
". More exactly, if each
Ci
represents "(*Pi*) *Gi* -> *Bi*
", then the result represents
"case *Argument* of *P1**G1* -> *B1*; ...; *Pn**Gn* -> *Bn* end
".
Returns the argument subtree of a case_expr
node.
Returns the list of clause subtrees of a case_expr
node.
Creates an abstract catch-expression. The result represents "catch *Expr*
".
Returns the body subtree of a catch_expr
node.
Creates an abstract character literal. The result represents "$*Name*
", where
Name
corresponds to Value
.
Returns the literal string represented by a char
node. This includes the
leading "$
" character. Characters beyond 255 will be escaped.
Returns the literal string represented by a char
node. This includes the
leading "$
" character. Depending on the encoding a character beyond 255 will
be escaped (latin1
) or copied as is (utf8
).
Returns the value represented by a char
node.
Creates an abstract class qualifier. The result represents "*Class*:*Body*
".
Creates an abstract class qualifier. The result represents
"*Class*:*Body*:*Stacktrace*
".
Returns the argument (the class) subtree of a class_qualifier
node.
Returns the body subtree of a class_qualifier
node.
Returns the stacktrace subtree of a class_qualifier
node.
Equivalent to clause([], Guard, Body).
Creates an abstract clause. If Patterns
is [P1, ..., Pn]
and Body
is
[B1, ..., Bm]
, then if Guard
is none
, the result represents
"(*P1*, ..., *Pn*) -> *B1*, ..., *Bm*
", otherwise, unless Guard
is a list,
the result represents "(*P1*, ..., *Pn*) when *Guard* -> *B1*, ..., *Bm*
".
Return the list of body subtrees of a clause
node.
Returns the guard subtree of a clause
node, if any. If Node
represents
"(*P1*, ..., *Pn*) when *Guard* -> *B1*, ..., *Bm*
", Guard
is returned.
Otherwise, the result is none
.
Returns the list of pattern subtrees of a clause
node.
Equivalent to comment(none, Strings).
Creates an abstract comment with the given padding and text. If Strings
is a
(possibly empty) list ["*Txt1*", ..., "*TxtN*"]
, the result represents the
source code text
Returns the amount of padding before the comment, or none
. The latter means
that a default padding may be used.
Returns the lines of text of the abstract comment.
Yields the most compact form for an abstract list skeleton. The result either
represents "[*E1*, ..., *En* | *Tail*]
", where Tail
is not a list skeleton,
or otherwise simply "[*E1*, ..., *En*]
". Annotations on subtrees of Node
that represent list skeletons may be lost, but comments will be propagated to
the result. Returns Node
itself if Node
does not represent a list skeleton.
Returns the Erlang term represented by a syntax tree. Evaluation fails with
reason badarg
if Node
does not represent a literal term.
Creates an abstract conjunction. If List
is [E1, ..., En]
, the result
represents "*E1*, ..., *En*
".
Returns the list of body subtrees of a conjunction
node.
"Optimising" list skeleton cons operation. Creates an abstract list skeleton
whose first element is Head
and whose tail corresponds to Tail
. This is
similar to list([Head], Tail)
, except that Tail
may not be
none
, and that the result does not necessarily represent exactly
"[*Head* | *Tail*]
", but may depend on the Tail
subtree. E.g., if Tail
represents [X, Y]
, the result may represent "[*Head*, X, Y]
", rather than
"[*Head* | [X, Y]]
". Annotations on Tail
itself may be lost if Tail
represents a list skeleton, but comments on Tail
are propagated to the result.
Creates an abstract constrained function type. If FunctionConstraint
is
[C1, ..., Cn]
, the result represents "*FunctionType* when *C1*, ...*Cn*
".
Returns the function constraint subtree of a constrained_function_type
node.
Returns the function type subtree of a constrained_function_type
node.
Creates an abstract (subtype) constraint. The result represents
"*Name* :: *Type*
".
Returns the name subtree of a constraint
node.
Returns the type subtree of a constraint
node.
Copies the list of user annotations from Source
to Target
.
Copies the attributes from Source
to Target
.
Copies the pre- and postcomments from Source
to Target
.
Copies the annotation from Source
to Target
.
For special purposes only. Returns the associated data of a syntax tree node.
Evaluation fails with reason badarg
if is_tree(Node)
does not
yield true
.
Creates an abstract disjunction. If List
is [E1, ..., En]
, the result
represents "*E1*; ...; *En*
".
Returns the list of body subtrees of a disjunction
node.
Creates an abstract else-expression. If Clauses
is [C1, ..., Cn]
, the result
represents "else *C1*; ...; *Cn* end
". More exactly, if each Ci
represents
"(*Pi*) *Gi* -> *Bi*
", then the result represents
"else *G1* -> *B1*; ...; *Pn**Gn* -> *Bn* end
".
Returns the list of clause subtrees of an else_expr
node.
Creates an abstract end-of-file marker. This represents the end of input when reading a sequence of source code forms. An end-of-file marker is itself regarded as a source code form (namely, the last in any sequence in which it occurs). It has no defined lexical form.
Creates an abstract error marker. The result represents an occurrence of an
error in the source code, with an associated Erlang I/O ErrorInfo structure
given by Error
(see module //stdlib/io
for details). Error markers
are regarded as source code forms, but have no defined lexical form.
Returns the ErrorInfo structure of an error_marker
node.
Flattens sublists of a form_list
node. Returns Node
with all subtrees of
type form_list
recursively expanded, yielding a single "flat" abstract form
sequence.
Creates an abstract floating-point literal. The lexical representation is the
decimal floating-point numeral of Value
.
Returns the numeral string represented by a float
node.
Returns the value represented by a float
node. Note that floating-point values
should usually not be compared for equality.
Creates an abstract sequence of "source code forms". If Forms
is
[F1, ..., Fn]
, where each Fi
is a form (see is_form/1
, the result
represents
Returns the list of subnodes of a form_list
node.
Creates an abstract fun-expression. If Clauses
is [C1, ..., Cn]
, the result
represents "fun *C1*; ...; *Cn* end
". More exactly, if each Ci
represents
"(*Pi1*, ..., *Pim*) *Gi* -> *Bi*
", then the result represents
"fun (*P11*, ..., *P1m*) *G1* -> *B1*; ...; (*Pn1*, ..., *Pnm*) *Gn* -> *Bn* end
".
Returns the arity of a fun_expr
node. The result is the number of parameter
patterns in the first clause of the fun-expression; subsequent clauses are
ignored.
Returns the list of clause subtrees of a fun_expr
node.
Creates an abstract fun of any type. The result represents "fun()
".
Creates an abstract function definition. If Clauses
is [C1, ..., Cn]
, the
result represents "*Name**C1*; ...; *Name**Cn*.
". More exactly, if each Ci
represents "(*Pi1*, ..., *Pim*) *Gi* -> *Bi*
", then the result represents
"*Name*(*P11*, ..., *P1m*) *G1* -> *B1*; ...; *Name*(*Pn1*, ..., *Pnm*) *Gn* -> *Bn*.
".
Function definitions are source code forms.
Returns the arity of a function
node. The result is the number of parameter
patterns in the first clause of the function; subsequent clauses are ignored.
Returns the list of clause subtrees of a function
node.
Returns the name subtree of a function
node.
Equivalent to function_type(any_arity, Type).
Creates an abstract function type. If Arguments
is [T1, ..., Tn]
, then if it
occurs within a function specification, the result represents
"(*T1*, ...*Tn*) -> *Return*
"; otherwise it represents
"fun((*T1*, ...*Tn*) -> *Return*)
". If Arguments
is any_arity
, it
represents "fun((...) -> *Return*)
".
Returns the argument types subtrees of a function_type
node. If Node
represents "fun((...) -> *Return*)
", any_arity
is returned; otherwise, if
Node
represents "(*T1*, ...*Tn*) -> *Return*
" or
"fun((*T1*, ...*Tn*) -> *Return*)
", [T1, ..., Tn]
is returned.
Returns the return type subtrees of a function_type
node.
Creates an abstract generator. The result represents "*Pattern*<- *Body*
".
Returns the body subtree of a generator
node.
Returns the pattern subtree of a generator
node.
Returns the list of user annotations associated with a syntax tree node. For a newly created node, this is the empty list. The annotations may be any terms.
Returns a representation of the attributes associated with a syntax tree node.
The attributes are all the extra information that can be attached to a node.
Currently, this includes position information, source code comments, and user
annotations. The result of this function cannot be inspected directly; only
attached to another node (see set_attrs/2
).
Returns the annotation (see //stdlib/erl_anno
) associated with
Node
. By default, all new tree nodes have their associated position
information set to the integer zero. Use
//stdlib/erl_anno:location/1
or
//stdlib/erl_anno:line/1
to get the position information.
Returns the associated post-comments of a node. This is a possibly empty list of abstract comments, in top-down textual order. When the code is formatted, post-comments are typically displayed to the right of and/or below the node. For example
Returns the associated pre-comments of a node. This is a possibly empty list of abstract comments, in top-down textual order. When the code is formatted, pre-comments are typically displayed directly above the node. For example
Yields false
if the node has no associated comments, and true
otherwise.
Creates an abstract if-expression. If Clauses
is [C1, ..., Cn]
, the result
represents "if *C1*; ...; *Cn* end
". More exactly, if each Ci
represents
"() *Gi* -> *Bi*
", then the result represents
"if *G1* -> *B1*; ...; *Gn* -> *Bn* end
".
Returns the list of clause subtrees of an if_expr
node.
Creates an abstract "implicit fun" expression. The result represents
"fun *Name*
". Name
should represent either *F*/*A*
or *M*:*F*/*A*
Creates an abstract "implicit fun" expression. If Arity
is none
, this is
equivalent to implicit_fun(Name)
, otherwise it is
equivalent to implicit_fun(arity_qualifier(Name, Arity))
.
Creates an abstract module-qualified "implicit fun" expression. If Module
is
none
, this is equivalent to implicit_fun(Name, Arity)
,
otherwise it is equivalent to
implicit_fun(module_qualifier(Module, arity_qualifier(Name, Arity))
.
Returns the name subtree of an implicit_fun
node.
Creates an abstract infix operator expression. The result represents
"*Left**Operator**Right*
".
Returns the left argument subtree of an infix_expr
node.
Returns the operator subtree of an infix_expr
node.
Returns the right argument subtree of an infix_expr
node.
Creates an abstract integer literal. The lexical representation is the canonical
decimal numeral of Value
.
Returns the numeral string represented by an integer
node.
Creates an abstract range type. The result represents "*Low* .. *High*
".
Returns the high limit of an integer_range_type
node.
Returns the low limit of an integer_range_type
node.
Returns the value represented by an integer
node.
Returns true
if Node
has type atom
and represents Value
, otherwise
false
.
Returns true
if Node
has type char
and represents Value
, otherwise
false
.
Returns true
if Node
is a syntax tree representing a so-called "source code
form", otherwise false
. Forms are the Erlang source code units which, placed
in sequence, constitute an Erlang program. Current form types are
Returns true
if Node
has type integer
and represents Value
, otherwise
false
.
Returns true
if Node
is a leaf node, otherwise false
. The currently
recognised leaf node types are
Returns true
if Node
has type list
or nil
, otherwise false
.
Returns true
if Node
represents a literal term, otherwise false
. This
function returns true
if and only if the value of
concrete(Node)
is defined.
Returns true
if Node
represents a proper list, and false
otherwise. A
proper list is a list skeleton either on the form "[]
" or
"[*E1*, ..., *En*]
", or "[... | *Tail*]
" where recursively Tail
also
represents a proper list.
Returns true
if Node
has type string
and represents Value
, otherwise
false
.
For special purposes only. Returns true
if Tree
is an abstract syntax tree
and false
otherwise.
Appends the comments of Source
to the current comments of Target
.
Equivalent to list(List, none).
Constructs an abstract list skeleton. The result has type list
or nil
. If
List
is a nonempty list [E1, ..., En]
, the result has type list
and
represents either "[*E1*, ..., *En*]
", if Tail
is none
, or otherwise
"[*E1*, ..., *En* | *Tail*]
". If List
is the empty list, Tail
must be
none
, and in that case the result has type nil
and represents "[]
" (see
nil/0
).
Creates an abstract list comprehension. If Body
is [E1, ..., En]
, the result
represents "[*Template* || *E1*, ..., *En*]
".
Returns the list of body subtrees of a list_comp
node.
Returns the template subtree of a list_comp
node.
Returns the list of element subtrees of a list skeleton. Node
must represent a
proper list. E.g., if Node
represents "[*X1*, *X2* | [*X3*, *X4* | []]
",
then list_elements(Node)
yields the list
[X1, X2, X3, X4]
.
Returns the head element subtree of a list
node. If Node
represents
"[*Head* ...]
", the result will represent "*Head*
".
Returns the number of element subtrees of a list skeleton. Node
must represent
a proper list. E.g., if Node
represents "[X1 | [X2, X3 | [X4, X5, X6]]]
",
then list_length(Node)
returns the integer 6.
Returns the prefix element subtrees of a list
node. If Node
represents
"[*E1*, ..., *En*]
" or "[*E1*, ..., *En* | *Tail*]
", the returned value is
[E1, ..., En]
.
Returns the suffix subtree of a list
node, if one exists. If Node
represents
"[*E1*, ..., *En* | *Tail*]
", the returned value is Tail
, otherwise, i.e.,
if Node
represents "[*E1*, ..., *En*]
", none
is returned.
Returns the tail of a list
node. If Node
represents a single-element list
"[*E*]
", then the result has type nil
, representing "[]
". If Node
represents "[*E1*, *E2* ...]
", the result will represent "[*E2* ...]
", and
if Node
represents "[*Head* | *Tail*]
", the result will represent
"*Tail*
".
Equivalent to macro(Name, none).
Creates an abstract macro application. If Arguments
is none
, the result
represents "?*Name*
", otherwise, if Arguments
is [A1, ..., An]
, the result
represents "?*Name*(*A1*, ..., *An*)
".
Returns the list of argument subtrees of a macro
node, if any. If Node
represents "?*Name*
", none
is returned. Otherwise, if Node
represents
"?*Name*(*A1*, ..., *An*)
", [A1, ..., An]
is returned.
Returns the name subtree of a macro
node.
Creates a syntax tree with the given type and subtrees. Type
must be a node
type name (see type/1
) that does not denote a leaf node type (see
is_leaf/1
). Groups
must be a nonempty list of groups of syntax trees,
representing the subtrees of a node of the given type, in left-to-right order as
they would occur in the printed program text, grouped by category as done by
subtrees/1
.
Creates an abstract map comprehension. If Body
is [E1, ..., En]
, the result
represents "#{*Template* || *E1*, ..., *En*}
".
Returns the list of body subtrees of a map_comp
node.
Returns the template subtree of a map_comp
node.
Equivalent to map_expr(none, Fields).
Creates an abstract map expression. If Fields
is [F1, ..., Fn]
, then if
Argument
is none
, the result represents "#{*F1*, ..., *Fn*}
", otherwise it
represents "*Argument*#{*F1*, ..., *Fn*}
".
Returns the argument subtree of a map_expr
node, if any. If Node
represents
"#{...}
", none
is returned. Otherwise, if Node
represents
"*Argument*#{...}
", Argument
is returned.
Returns the list of field subtrees of a map_expr
node.
Creates an abstract map assoc field. The result represents
"*Name* => *Value*
".
Returns the name subtree of a map_field_assoc
node.
Returns the value subtree of a map_field_assoc
node.
Creates an abstract map exact field. The result represents
"*Name* := *Value*
".
Returns the name subtree of a map_field_exact
node.
Returns the value subtree of a map_field_exact
node.
Creates an abstract map_generator. The result represents "*Pattern*<- *Body*
".
Returns the body subtree of a generator
node.
Returns the pattern subtree of a generator
node.
Equivalent to map_type(any_size).
Creates an abstract type map. If Fields
is [F1, ..., Fn]
, the result
represents "#{*F1*, ..., *Fn*}
"; otherwise, if Fields
is any_size
, it
represents "map/0
".
Creates an abstract map type assoc field. The result represents
"*Name* => *Value*
".
Returns the name subtree of a map_type_assoc
node.
Returns the value subtree of a map_type_assoc
node.
Creates an abstract map type exact field. The result represents
"*Name* := *Value*
".
Returns the name subtree of a map_type_exact
node.
Returns the value subtree of a map_type_exact
node.
Returns the list of field subtrees of a map_type
node. If Node
represents
"map/0
", any_size
is returned; otherwise, if Node
represents
"#{*F1*, ..., *Fn*}
", [F1, ..., Fn]
is returned.
Creates an abstract match-expression. The result represents
"*Pattern* = *Body*
".
Returns the body subtree of a match_expr
node.
Returns the pattern subtree of a match_expr
node.
Equivalent to maybe_expr(Body, none).
Creates an abstract maybe-expression. If Body
is [B1, ..., Bn]
, and
OptionalElse
is none
, the result represents "maybe *B1*, ..., *Bn* end
".
If Body
is [B1, ..., Bn]
, and OptionalElse
reprsents an else_expr
node
with clauses [C1, ..., Cn]
, the result represents
"maybe *B1*, ..., *Bn* else *C1*; ..., *Cn* end
".
Returns the list of body subtrees of a maybe_expr
node.
Returns the else subtree of a maybe_expr
node.
Creates an abstract maybe-expression, as used in maybe
blocks. The result
represents "*Pattern* ?= *Body*
".
Returns the body subtree of a maybe_expr
node.
Returns the pattern subtree of a maybe_expr
node.
Creates a meta-representation of a syntax tree. The result represents an Erlang
expression "*MetaTree*
" which, if evaluated, will yield a new syntax tree
representing the same source code text as Tree
(although the actual data
representation may be different). The expression represented by MetaTree
is
implementation independent with regard to the data structures used by the
abstract syntax tree implementation. Comments attached to nodes of Tree
will
be preserved, but other attributes are lost.
Creates an abstract module qualifier. The result represents "*Module*:*Body*
".
Returns the argument (the module) subtree of a module_qualifier
node.
Returns the body subtree of a module_qualifier
node.
Creates an abstract named fun-expression. If Clauses
is [C1, ..., Cn]
, the
result represents "fun *Name**C1*; ...; *Name**Cn* end
". More exactly, if each
Ci
represents "(*Pi1*, ..., *Pim*) *Gi* -> *Bi*
", then the result represents
"fun *Name*(*P11*, ..., *P1m*) *G1* -> *B1*; ...; *Name*(*Pn1*, ..., *Pnm*) *Gn* -> *Bn* end
".
Returns the arity of a named_fun_expr
node. The result is the number of
parameter patterns in the first clause of the named fun-expression; subsequent
clauses are ignored.
Returns the list of clause subtrees of a named_fun_expr
node.
Returns the name subtree of a named_fun_expr
node.
Expands an abstract list skeleton to its most explicit form. If Node
represents "[*E1*, ..., *En* | *Tail*]
", the result represents
"[*E1* | ... [*En* | *Tail1*] ... ]
", where Tail1
is the result of
normalize_list(Tail)
. If Node
represents
"[*E1*, ..., *En*]
", the result simply represents
"[*E1* | ... [*En* | []] ... ]
". If Node
does not represent a list skeleton,
Node
itself is returned.
Creates an abstract operator. The name of the operator is the character sequence
represented by Name
. This is analogous to the print name of an atom, but an
operator is never written within single-quotes; e.g., the result of
operator('++')
represents "++
" rather than "'++'
".
Returns the literal string represented by an operator
node. This is simply the
operator name as a string.
Returns the name of an operator
node. Note that the name is returned as an
atom.
Creates an abstract parenthesised expression. The result represents
"(*Body*)
", independently of the context.
Returns the body subtree of a parentheses
node.
Creates an abstract prefix operator expression. The result represents
"*Operator**Argument*
".
Returns the argument subtree of a prefix_expr
node.
Returns the operator subtree of a prefix_expr
node.
Equivalent to receive_expr(Clauses, none, []).
Creates an abstract receive-expression. If Timeout
is none
, the result
represents "receive *C1*; ...; *Cn* end
" (the Action
argument is ignored).
Otherwise, if Clauses
is [C1, ..., Cn]
and Action
is [A1, ..., Am]
, the
result represents
"receive *C1*; ...; *Cn* after *Timeout* -> *A1*, ..., *Am* end
". More
exactly, if each Ci
represents "(*Pi*) *Gi* -> *Bi*
", then the result
represents "receive *P1**G1* -> *B1*; ...; *Pn**Gn* -> *Bn* ... end
".
Returns the list of action body subtrees of a receive_expr
node. If Node
represents "receive *C1*; ...; *Cn* end
", this is the empty list.
Returns the list of clause subtrees of a receive_expr
node.
Returns the timeout subtree of a receive_expr
node, if any. If Node
represents "receive *C1*; ...; *Cn* end
", none
is returned. Otherwise, if
Node
represents "receive *C1*; ...; *Cn* after *Timeout* -> ... end
",
Timeout
is returned.
Creates an abstract record field access expression. The result represents
"*Argument*#*Type*.*Field*
".
Returns the argument subtree of a record_access
node.
Returns the field subtree of a record_access
node.
Returns the type subtree of a record_access
node.
Equivalent to record_expr(none, Type, Fields).
Creates an abstract record expression. If Fields
is [F1, ..., Fn]
, then if
Argument
is none
, the result represents "#*Type*{*F1*, ..., *Fn*}
",
otherwise it represents "*Argument*#*Type*{*F1*, ..., *Fn*}
".
Returns the argument subtree of a record_expr
node, if any. If Node
represents "#*Type*{...}
", none
is returned. Otherwise, if Node
represents
"*Argument*#*Type*{...}
", Argument
is returned.
Returns the list of field subtrees of a record_expr
node.
Returns the type subtree of a record_expr
node.
Equivalent to record_field(Name, none).
Creates an abstract record field specification. If Value
is none
, the result
represents simply "*Name*
", otherwise it represents "*Name* = *Value*
".
Returns the name subtree of a record_field
node.
Returns the value subtree of a record_field
node, if any. If Node
represents
"*Name*
", none
is returned. Otherwise, if Node
represents
"*Name* = *Value*
", Value
is returned.
Creates an abstract record field index expression. The result represents
"#*Type*.*Field*
".
Returns the field subtree of a record_index_expr
node.
Returns the type subtree of a record_index_expr
node.
Creates an abstract record type. If Fields
is [F1, ..., Fn]
, the result
represents "#*Name*{*F1*, ..., *Fn*}
".
Creates an abstract record type field. The result represents
"*Name* :: *Type*
".
Returns the name subtree of a record_type_field
node.
Returns the type subtree of a record_type_field
node.
Returns the fields subtree of a record_type
node.
Returns the name subtree of a record_type
node.
Clears the associated comments of Node
.
Returns an erl_parse
-compatible representation of a syntax tree, if possible.
If Tree
represents a well-formed Erlang program or expression, the conversion
should work without problems. Typically, is_tree/1
yields true
if conversion
failed (i.e., the result is still an abstract syntax tree), and false
otherwise.
Reverts a sequence of Erlang source code forms. The sequence can be given either
as a form_list
syntax tree (possibly nested), or as a list of "program form"
syntax trees. If successful, the corresponding flat list of
erl_parse
-compatible syntax trees is returned (see revert/1
). If some
program form could not be reverted, {error, Form}
is thrown. Standalone
comments in the form sequence are discarded.
Sets the list of user annotations of Node
to Annotations
.
Sets the attributes of Node
to Attributes
.
Sets the position information of Node
to Pos
.
Sets the post-comments of Node
to Comments
. Comments
should be a possibly
empty list of abstract comments, in top-down textual order
Sets the pre-comments of Node
to Comments
. Comments
should be a possibly
empty list of abstract comments, in top-down textual order.
Creates an abstract size qualifier. The result represents "*Body*:*Size*
".
Returns the argument subtree (the size) of a size_qualifier
node.
Returns the body subtree of a size_qualifier
node.
Creates an abstract string literal. The result represents "*Text*"
(including
the surrounding double-quotes), where Text
corresponds to the sequence of
characters in Value
, but not representing a specific string literal.
Returns the literal string represented by a string
node. This includes
surrounding double-quote characters. Characters beyond 255 will be escaped.
Returns the literal string represented by a string
node. This includes
surrounding double-quote characters. Depending on the encoding characters beyond
255 will be escaped (latin1
) or copied as is (utf8
).
Returns the value represented by a string
node.
Returns the grouped list of all subtrees of a syntax tree. If Node
is a leaf
node (see is_leaf/1
), this is the empty list, otherwise the result is always a
nonempty list, containing the lists of subtrees of Node
, in left-to-right
order as they occur in the printed program text, and grouped by category. Often,
each group contains only a single subtree.
Creates an abstract piece of source code text. The result represents exactly the
sequence of characters in String
. This is useful in cases when one wants full
control of the resulting output, e.g., for the appearance of floating-point
numbers or macro definitions.
Returns the character sequence represented by a text
node.
Equivalent to tree(Type, []).
For special purposes only. Creates an abstract syntax tree node with type tag
Type
and associated data Data
.
Equivalent to try_expr(Body, [], [], After).
Equivalent to try_expr(Body, [], Handlers).
Creates an abstract try-expression. If Body
is [B1, ..., Bn]
, Clauses
is
[C1, ..., Cj]
, Handlers
is [H1, ..., Hk]
, and After
is [A1, ..., Am]
,
the result represents
"try *B1*, ..., *Bn* of *C1*; ...; *Cj* catch *H1*; ...; *Hk* after *A1*, ..., *Am* end
".
More exactly, if each Ci
represents "(*CPi*) *CGi* -> *CBi*
", and each Hi
represents "(*HPi*) *HGi* -> *HBi*
", then the result represents
"try *B1*, ..., *Bn* of *CP1**CG1* -> *CB1*; ...; *CPj**CGj* -> *CBj* catch *HP1**HG1* -> *HB1*; ...; *HPk**HGk* -> *HBk* after *A1*, ..., *Am* end
";
see case_expr/2
. If Clauses
is the empty list, the of ...
section is left
out. If After
is the empty list, the after ...
section is left out. If
Handlers
is the empty list, and After
is nonempty, the catch ...
section
is left out.
Returns the list of "after" subtrees of a try_expr
node.
Returns the list of body subtrees of a try_expr
node.
Returns the list of case-clause subtrees of a try_expr
node. If Node
represents "try *Body* catch *H1*; ...; *Hn* end
", the result is the empty
list.
Returns the list of handler-clause subtrees of a try_expr
node.
Creates an abstract tuple. If Elements
is [X1, ..., Xn]
, the result
represents "{*X1*, ..., *Xn*}
".
Returns the list of element subtrees of a tuple
node.
Returns the number of elements of a tuple
node.
Equivalent to tuple_type(any_size).
Creates an abstract type tuple. If Elements
is [T1, ..., Tn]
, the result
represents "{*T1*, ..., *Tn*}
"; otherwise, if Elements
is any_size
, it
represents "tuple/0
".
Returns the list of type element subtrees of a tuple_type
node. If Node
represents "tuple/0
", any_size
is returned; otherwise, if Node
represents "{*T1*, ..., *Tn*}
", [T1, ..., Tn]
is returned.
Returns the type tag of Node
. If Node
does not represent a syntax tree,
evaluation fails with reason badarg
. Node types currently defined by this
module are
Creates an abstract type application expression. If Arguments
is
[T1, ..., Tn]
, the result represents "*TypeName*(*T1*, ...*Tn*)
".
Creates an abstract type application expression. If Module
is none
, this is
call is equivalent to
type_application(TypeName, Arguments)
, otherwise it is
equivalent to
type_application(module_qualifier(Module, TypeName), Arguments)
.
Returns the arguments subtrees of a type_application
node.
Returns the type name subtree of a type_application
node.
Creates an abstract type union. If Types
is [T1, ..., Tn]
, the result
represents "*T1* | ... | *Tn*
".
Returns the list of type subtrees of a type_union
node.
Creates an abstract typed record field specification. The result represents
"*Field* :: *Type*
".
Returns the field subtree of a typed_record_field
node.
Returns the type subtree of a typed_record_field
node.
Creates an abstract universal pattern ("_
"). The lexical representation is a
single underscore character. Note that this is not a variable, lexically
speaking.
Creates a syntax tree with the same type and attributes as the given tree. This
is equivalent to
copy_attrs(Node, make_tree(type(Node), Groups))
.
Creates an abstract user type. If Arguments
is [T1, ..., Tn]
, the result
represents "*TypeName*(*T1*, ...*Tn*)
".
Returns the arguments subtrees of a user_type_application
node.
Returns the type name subtree of a user_type_application
node.
Creates an abstract variable with the given name. Name
may be any atom or
string that represents a lexically valid variable name, but not a single
underscore character; see underscore/0
.
Returns the name of a variable
node as a string.
Returns the name of a variable
node as an atom.
Creates an abstract warning marker. The result represents an occurrence of a
possible problem in the source code, with an associated Erlang I/O ErrorInfo
structure given by Error
(see module //stdlib/io
for details).
Warning markers are regarded as source code forms, but have no defined lexical
form.
Returns the ErrorInfo structure of a warning_marker
node.
Types
-type annotation_or_location() :: erl_anno:anno() | erl_anno:location().
-type encoding() :: utf8 | unicode | latin1.
-type erl_parse() :: erl_parse:abstract_clause() | erl_parse:abstract_expr() | erl_parse:abstract_form() | erl_parse:abstract_type() | erl_parse:form_info() | erl_parse:af_binelement(term()) | erl_parse:af_generator() | erl_parse:af_remote_function().
-type forms() :: syntaxTree() | [syntaxTree()].
-type guard() :: none | syntaxTree() | [syntaxTree()] | [[syntaxTree()]].
-type padding() :: none | integer().
-type syntaxTreeAttributes() :: #attr{pos :: term(), ann :: [term()], com :: none | #com{pre :: [syntaxTree()], post :: [syntaxTree()]}}.
-type tree() :: #tree{type :: atom(), attr :: #attr{pos :: term(), ann :: [term()], com :: none | #com{pre :: [syntaxTree()], post :: [syntaxTree()]}}, data :: term()}.
-type wrapper() :: #wrapper{type :: atom(), attr :: #attr{pos :: term(), ann :: [term()], com :: none | #com{pre :: [syntaxTree()], post :: [syntaxTree()]}}, tree :: erl_parse()}.
Functions
-spec nil() -> syntaxTree().
Creates an abstract empty list. The result represents "[]
". The empty list is
traditionally called "nil".
See also: is_list_skeleton/1
, list/2
.
-spec abstract(term()) -> syntaxTree().
Returns the syntax tree corresponding to an Erlang term. Term
must be a
literal term, i.e., one that can be represented as a source code literal. Thus,
it may not contain a process identifier, port, reference or function value as a
subterm. The function recognises printable strings, in order to get a compact
and readable representation. Evaluation fails with reason badarg
if Term
is
not a literal term.
See also: concrete/1
, is_literal/1
.
-spec add_ann(term(), syntaxTree()) -> syntaxTree().
Appends the term Annotation
to the list of user annotations of Node
.
Note: this is equivalent to
set_ann(Node, [Annotation | get_ann(Node)])
, but potentially
more efficient.
-spec add_postcomments([syntaxTree()], syntaxTree()) -> syntaxTree().
Appends Comments
to the post-comments of Node
.
Note: This is equivalent to
set_postcomments(Node, get_postcomments(Node) ++ Comments)
,
but potentially more efficient.
See also: add_precomments/2
, comment/2
, get_postcomments/1
,
join_comments/2
, set_postcomments/2
.
-spec add_precomments([syntaxTree()], syntaxTree()) -> syntaxTree().
Appends Comments
to the pre-comments of Node
.
Note: This is equivalent to
set_precomments(Node, get_precomments(Node) ++ Comments)
,
but potentially more efficient.
See also: add_postcomments/2
, comment/2
, get_precomments/1
,
join_comments/2
, set_precomments/2
.
-spec annotated_type(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract annotated type expression. The result represents
"*Name* :: *Type*
".
See also: annotated_type_body/1
, annotated_type_name/1
.
-spec annotated_type_body(syntaxTree()) -> syntaxTree().
Returns the type subtrees of an annotated_type
node.
See also: annotated_type/2
.
-spec annotated_type_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of an annotated_type
node.
See also: annotated_type/2
.
-spec application(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract function application expression. If Arguments
is
[A1, ..., An]
, the result represents "*Operator*(*A1*, ..., *An*)
".
See also: application/3
, application_arguments/1
,
application_operator/1
.
-spec application(none | syntaxTree(), syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract function application expression. If Module
is none
, this
is call is equivalent to application(Function, Arguments)
,
otherwise it is equivalent to
application(module_qualifier(Module, Function), Arguments)
.
(This is a utility function.)
See also: application/2
, module_qualifier/2
.
-spec application_arguments(syntaxTree()) -> [syntaxTree()].
Returns the list of argument subtrees of an application
node.
See also: application/2
.
-spec application_operator(syntaxTree()) -> syntaxTree().
Returns the operator subtree of an application
node.
Note: if Node
represents "*M*:*F*(...)
", then the result is the subtree
representing "*M*:*F*
".
See also: application/2
, module_qualifier/2
.
-spec arity_qualifier(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract arity qualifier. The result represents "*Body*/*Arity*
".
See also: arity_qualifier_argument/1
, arity_qualifier_body/1
.
-spec arity_qualifier_argument(syntaxTree()) -> syntaxTree().
Returns the argument (the arity) subtree of an arity_qualifier
node.
See also: arity_qualifier/2
.
-spec arity_qualifier_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of an arity_qualifier
node.
See also: arity_qualifier/2
.
-spec atom(atom() | string()) -> syntaxTree().
Creates an abstract atom literal. The print name of the atom is the character
sequence represented by Name
.
See also: atom_literal/1
, atom_literal/2
, atom_name/1
, atom_value/1
,
is_atom/2
.
-spec atom_literal(syntaxTree()) -> string().
Returns the literal string represented by an atom
node. This includes
surrounding single-quote characters if necessary. Characters beyond 255 will be
escaped.
Note that e.g. the result of atom("x\ny")
represents any and all
of `x\ny'', `x\12y'', `x\012y'' and `x\^Jy\''; see string/1
.
-spec atom_literal(syntaxTree(), utf8 | unicode | latin1) -> string().
Returns the literal string represented by an atom
node. This includes
surrounding single-quote characters if necessary. Depending on the encoding a
character beyond 255 will be escaped (latin1
) or copied as is (utf8
).
See also: atom/1
, atom_literal/1
, string/1
.
-spec atom_name(syntaxTree()) -> string().
Returns the printname of an atom
node.
See also: atom/1
.
-spec atom_value(syntaxTree()) -> atom().
Returns the value represented by an atom
node.
See also: atom/1
.
-spec attribute(syntaxTree()) -> syntaxTree().
Equivalent to attribute(Name, none).
-spec attribute(syntaxTree(), none | [syntaxTree()]) -> syntaxTree().
Creates an abstract program attribute. If Arguments
is [A1, ..., An]
, the
result represents "-*Name*(*A1*, ..., *An*).
". Otherwise, if Arguments
is
none
, the result represents "-*Name*.
". The latter form makes it possible to
represent preprocessor directives such as "-endif.
". Attributes are source
code forms.
Note: The preprocessor macro definition directive "-define(*Name*, *Body*).
"
has relatively few requirements on the syntactical form of Body
(viewed as a
sequence of tokens). The text
node type can be used for a Body
that is not a
normal Erlang construct.
See also: attribute/1
, attribute_arguments/1
, attribute_name/1
,
is_form/1
, text/1
.
-spec attribute_arguments(syntaxTree()) -> none | [syntaxTree()].
Returns the list of argument subtrees of an attribute
node, if any. If Node
represents "-*Name*.
", the result is none
. Otherwise, if Node
represents
"-*Name*(*E1*, ..., *En*).
", [E1, ..., E1]
is returned.
See also: attribute/1
.
-spec attribute_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of an attribute
node.
See also: attribute/1
.
-spec binary([syntaxTree()]) -> syntaxTree().
Creates an abstract binary-object template. If Fields
is [F1, ..., Fn]
, the
result represents "<<*F1*, ..., *Fn*>>
".
See also: binary_field/2
, binary_fields/1
.
-spec binary_comp(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract binary comprehension. If Body
is [E1, ..., En]
, the
result represents "<<*Template* || *E1*, ..., *En*>>
".
See also: binary_comp_body/1
, binary_comp_template/1
, generator/2
.
-spec binary_comp_body(syntaxTree()) -> [syntaxTree()].
Returns the list of body subtrees of a binary_comp
node.
See also: binary_comp/2
.
-spec binary_comp_template(syntaxTree()) -> syntaxTree().
Returns the template subtree of a binary_comp
node.
See also: binary_comp/2
.
-spec binary_field(syntaxTree()) -> syntaxTree().
Equivalent to binary_field(Body, []).
-spec binary_field(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract binary template field. If Types
is the empty list, the
result simply represents "*Body*
", otherwise, if Types
is [T1, ..., Tn]
,
the result represents "*Body*/*T1*-...-*Tn*
".
See also: binary/1
, binary_field/1
, binary_field/3
,
binary_field_body/1
, binary_field_size/1
, binary_field_types/1
.
-spec binary_field(syntaxTree(), none | syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract binary template field. If Size
is none
, this is
equivalent to "binary_field(Body, Types)
", otherwise it is
equivalent to
"binary_field(size_qualifier(Body, Size), Types)
".
(This is a utility function.)
See also: binary/1
, binary_field/2
, size_qualifier/2
.
-spec binary_field_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a binary_field
.
See also: binary_field/2
.
-spec binary_field_size(syntaxTree()) -> none | syntaxTree().
Returns the size specifier subtree of a binary_field
node, if any. If Node
represents "*Body*:*Size*
" or "*Body*:*Size*/*T1*, ..., *Tn*
", the result is
Size
, otherwise none
is returned.
(This is a utility function.)
See also: binary_field/2
, binary_field/3
.
-spec binary_field_types(syntaxTree()) -> [syntaxTree()].
Returns the list of type-specifier subtrees of a binary_field
node. If Node
represents ".../*T1*, ..., *Tn*
", the result is [T1, ..., Tn]
, otherwise the
result is the empty list.
See also: binary_field/2
.
-spec binary_fields(syntaxTree()) -> [syntaxTree()].
Returns the list of field subtrees of a binary
node.
See also: binary/1
, binary_field/2
.
-spec binary_generator(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract binary_generator. The result represents
"*Pattern*<- *Body*
".
See also: binary_comp/2
, binary_generator_body/1
,
binary_generator_pattern/1
, list_comp/2
.
-spec binary_generator_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a generator
node.
See also: binary_generator/2
.
-spec binary_generator_pattern(syntaxTree()) -> syntaxTree().
Returns the pattern subtree of a generator
node.
See also: binary_generator/2
.
-spec bitstring_type(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract bitstring type. The result represents "*<<_:M, _:_*N>>*
".
See also: bitstring_type_m/1
, bitstring_type_n/1
.
-spec bitstring_type_m(syntaxTree()) -> syntaxTree().
Returns the number of start bits, M
, of a bitstring_type
node.
See also: bitstring_type/2
.
-spec bitstring_type_n(syntaxTree()) -> syntaxTree().
Returns the segment size, N
, of a bitstring_type
node.
See also: bitstring_type/2
.
-spec block_expr([syntaxTree()]) -> syntaxTree().
Creates an abstract block expression. If Body
is [B1, ..., Bn]
, the result
represents "begin *B1*, ..., *Bn* end
".
See also: block_expr_body/1
.
-spec block_expr_body(syntaxTree()) -> [syntaxTree()].
Returns the list of body subtrees of a block_expr
node.
See also: block_expr/1
.
-spec case_expr(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract case-expression. If Clauses
is [C1, ..., Cn]
, the result
represents "case *Argument* of *C1*; ...; *Cn* end
". More exactly, if each
Ci
represents "(*Pi*) *Gi* -> *Bi*
", then the result represents
"case *Argument* of *P1**G1* -> *B1*; ...; *Pn**Gn* -> *Bn* end
".
See also: case_expr_argument/1
, case_expr_clauses/1
, clause/3
,
if_expr/1
.
-spec case_expr_argument(syntaxTree()) -> syntaxTree().
Returns the argument subtree of a case_expr
node.
See also: case_expr/2
.
-spec case_expr_clauses(syntaxTree()) -> [syntaxTree()].
Returns the list of clause subtrees of a case_expr
node.
See also: case_expr/2
.
-spec catch_expr(syntaxTree()) -> syntaxTree().
Creates an abstract catch-expression. The result represents "catch *Expr*
".
See also: catch_expr_body/1
.
-spec catch_expr_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a catch_expr
node.
See also: catch_expr/1
.
-spec char(char()) -> syntaxTree().
Creates an abstract character literal. The result represents "$*Name*
", where
Name
corresponds to Value
.
Note: the literal corresponding to a particular character value is not uniquely
defined. E.g., the character "a
" can be written both as "$a
" and "$\141
",
and a Tab character can be written as "$\11
", "$\011
" or "$\t
".
See also: char_literal/1
, char_literal/2
, char_value/1
, is_char/2
.
-spec char_literal(syntaxTree()) -> nonempty_string().
Returns the literal string represented by a char
node. This includes the
leading "$
" character. Characters beyond 255 will be escaped.
See also: char/1
.
-spec char_literal(syntaxTree(), encoding()) -> nonempty_string().
Returns the literal string represented by a char
node. This includes the
leading "$
" character. Depending on the encoding a character beyond 255 will
be escaped (latin1
) or copied as is (utf8
).
See also: char/1
.
-spec char_value(syntaxTree()) -> char().
Returns the value represented by a char
node.
See also: char/1
.
-spec class_qualifier(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract class qualifier. The result represents "*Class*:*Body*
".
See also: class_qualifier_argument/1
, class_qualifier_body/1
,
class_qualifier_stacktrace/1
, try_expr/4
.
-spec class_qualifier(syntaxTree(), syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract class qualifier. The result represents
"*Class*:*Body*:*Stacktrace*
".
See also: class_qualifier_argument/1
, class_qualifier_body/1
,
try_expr/4
.
-spec class_qualifier_argument(syntaxTree()) -> syntaxTree().
Returns the argument (the class) subtree of a class_qualifier
node.
See also: class_qualifier/2
.
-spec class_qualifier_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a class_qualifier
node.
See also: class_qualifier/2
.
-spec class_qualifier_stacktrace(syntaxTree()) -> syntaxTree().
Returns the stacktrace subtree of a class_qualifier
node.
See also: class_qualifier/2
.
-spec clause(guard(), [syntaxTree()]) -> syntaxTree().
Equivalent to clause([], Guard, Body).
-spec clause([syntaxTree()], guard(), [syntaxTree()]) -> syntaxTree().
Creates an abstract clause. If Patterns
is [P1, ..., Pn]
and Body
is
[B1, ..., Bm]
, then if Guard
is none
, the result represents
"(*P1*, ..., *Pn*) -> *B1*, ..., *Bm*
", otherwise, unless Guard
is a list,
the result represents "(*P1*, ..., *Pn*) when *Guard* -> *B1*, ..., *Bm*
".
For simplicity, the Guard
argument may also be any of the following:
- An empty list
[]
. This is equivalent to passingnone
. - A nonempty list
[E1, ..., Ej]
of syntax trees. This is equivalent to passingconjunction([E1, ..., Ej])
. - A nonempty list of lists of syntax trees
[[E1_1, ..., E1_k1], ..., [Ej_1, ..., Ej_kj]]
, which is equivalent to passingdisjunction([conjunction([E1_1, ..., E1_k1]), ..., conjunction([Ej_1, ..., Ej_kj])])
.
See also: clause/2
, clause_body/1
, clause_guard/1
, clause_patterns/1
.
-spec clause_body(syntaxTree()) -> [syntaxTree()].
Return the list of body subtrees of a clause
node.
See also: clause/3
.
-spec clause_guard(syntaxTree()) -> none | syntaxTree().
Returns the guard subtree of a clause
node, if any. If Node
represents
"(*P1*, ..., *Pn*) when *Guard* -> *B1*, ..., *Bm*
", Guard
is returned.
Otherwise, the result is none
.
See also: clause/3
.
-spec clause_patterns(syntaxTree()) -> [syntaxTree()].
Returns the list of pattern subtrees of a clause
node.
See also: clause/3
.
-spec comment([string()]) -> syntaxTree().
Equivalent to comment(none, Strings).
-spec comment(padding(), [string()]) -> syntaxTree().
Creates an abstract comment with the given padding and text. If Strings
is a
(possibly empty) list ["*Txt1*", ..., "*TxtN*"]
, the result represents the
source code text
%Txt1
...
%TxtN
Padding
states the number of empty character positions to the left of the
comment separating it horizontally from source code on the same line (if any).
If Padding
is none
, a default positive number is used. If Padding
is an
integer less than 1, there should be no separating space. Comments are in
themselves regarded as source program forms.
-spec comment_padding(syntaxTree()) -> padding().
Returns the amount of padding before the comment, or none
. The latter means
that a default padding may be used.
See also: comment/2
.
-spec comment_text(syntaxTree()) -> [string()].
Returns the lines of text of the abstract comment.
See also: comment/2
.
-spec compact_list(syntaxTree()) -> syntaxTree().
Yields the most compact form for an abstract list skeleton. The result either
represents "[*E1*, ..., *En* | *Tail*]
", where Tail
is not a list skeleton,
or otherwise simply "[*E1*, ..., *En*]
". Annotations on subtrees of Node
that represent list skeletons may be lost, but comments will be propagated to
the result. Returns Node
itself if Node
does not represent a list skeleton.
See also: list/2
, normalize_list/1
.
-spec concrete(syntaxTree()) -> term().
Returns the Erlang term represented by a syntax tree. Evaluation fails with
reason badarg
if Node
does not represent a literal term.
Note: Currently, the set of syntax trees which have a concrete representation is
larger than the set of trees which can be built using the function abstract/1
.
An abstract character will be concretised as an integer, while abstract/1
does
not at present yield an abstract character for any input. (Use the char/1
function to explicitly create an abstract character.)
Note: arity_qualifier
nodes are recognized. This is to follow The Erlang
Parser when it comes to wild attributes: both {F, A} and F/A are recognized,
which makes it possible to turn wild attributes into recognized attributes
without at the same time making it impossible to compile files using the new
syntax with the old version of the Erlang Compiler.
See also: abstract/1
, char/1
, is_literal/1
.
-spec conjunction([syntaxTree()]) -> syntaxTree().
Creates an abstract conjunction. If List
is [E1, ..., En]
, the result
represents "*E1*, ..., *En*
".
See also: conjunction_body/1
, disjunction/1
.
-spec conjunction_body(syntaxTree()) -> [syntaxTree()].
Returns the list of body subtrees of a conjunction
node.
See also: conjunction/1
.
-spec cons(syntaxTree(), syntaxTree()) -> syntaxTree().
"Optimising" list skeleton cons operation. Creates an abstract list skeleton
whose first element is Head
and whose tail corresponds to Tail
. This is
similar to list([Head], Tail)
, except that Tail
may not be
none
, and that the result does not necessarily represent exactly
"[*Head* | *Tail*]
", but may depend on the Tail
subtree. E.g., if Tail
represents [X, Y]
, the result may represent "[*Head*, X, Y]
", rather than
"[*Head* | [X, Y]]
". Annotations on Tail
itself may be lost if Tail
represents a list skeleton, but comments on Tail
are propagated to the result.
See also: list/2
, list_head/1
, list_tail/1
.
-spec constrained_function_type(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract constrained function type. If FunctionConstraint
is
[C1, ..., Cn]
, the result represents "*FunctionType* when *C1*, ...*Cn*
".
See also: constrained_function_type_argument/1
,
constrained_function_type_body/1
.
-spec constrained_function_type_argument(syntaxTree()) -> syntaxTree().
Returns the function constraint subtree of a constrained_function_type
node.
See also: constrained_function_type/2
.
-spec constrained_function_type_body(syntaxTree()) -> syntaxTree().
Returns the function type subtree of a constrained_function_type
node.
See also: constrained_function_type/2
.
-spec constraint(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract (subtype) constraint. The result represents
"*Name* :: *Type*
".
See also: constraint_argument/1
, constraint_body/1
.
-spec constraint_argument(syntaxTree()) -> syntaxTree().
Returns the name subtree of a constraint
node.
See also: constraint/2
.
-spec constraint_body(syntaxTree()) -> [syntaxTree()].
Returns the type subtree of a constraint
node.
See also: constraint/2
.
-spec copy_ann(syntaxTree(), syntaxTree()) -> syntaxTree().
Copies the list of user annotations from Source
to Target
.
Note: this is equivalent to set_ann(Target, get_ann(Source))
,
but potentially more efficient.
-spec copy_attrs(syntaxTree(), syntaxTree()) -> syntaxTree().
Copies the attributes from Source
to Target
.
Note: this is equivalent to
set_attrs(Target, get_attrs(Source))
, but potentially more
efficient.
See also: get_attrs/1
, set_attrs/2
.
-spec copy_comments(syntaxTree(), syntaxTree()) -> syntaxTree().
Copies the pre- and postcomments from Source
to Target
.
Note: This is equivalent to
set_postcomments(set_precomments(Target, get_precomments(Source)), get_postcomments(Source))
,
but potentially more efficient.
See also: comment/2
, get_postcomments/1
, get_precomments/1
,
set_postcomments/2
, set_precomments/2
.
-spec copy_pos(syntaxTree(), syntaxTree()) -> syntaxTree().
Copies the annotation from Source
to Target
.
This is equivalent to set_pos(Target, get_pos(Source))
, but
potentially more efficient.
-spec data(syntaxTree()) -> term().
For special purposes only. Returns the associated data of a syntax tree node.
Evaluation fails with reason badarg
if is_tree(Node)
does not
yield true
.
See also: tree/2
.
-spec disjunction([syntaxTree()]) -> syntaxTree().
Creates an abstract disjunction. If List
is [E1, ..., En]
, the result
represents "*E1*; ...; *En*
".
See also: conjunction/1
, disjunction_body/1
.
-spec disjunction_body(syntaxTree()) -> [syntaxTree()].
Returns the list of body subtrees of a disjunction
node.
See also: disjunction/1
.
-spec else_expr([syntaxTree()]) -> syntaxTree().
Creates an abstract else-expression. If Clauses
is [C1, ..., Cn]
, the result
represents "else *C1*; ...; *Cn* end
". More exactly, if each Ci
represents
"(*Pi*) *Gi* -> *Bi*
", then the result represents
"else *G1* -> *B1*; ...; *Pn**Gn* -> *Bn* end
".
See also: clause/3
, else_expr_clauses/1
, maybe_expr/2
.
-spec else_expr_clauses(syntaxTree()) -> [syntaxTree()].
Returns the list of clause subtrees of an else_expr
node.
See also: else_expr/1
.
-spec eof_marker() -> syntaxTree().
Creates an abstract end-of-file marker. This represents the end of input when reading a sequence of source code forms. An end-of-file marker is itself regarded as a source code form (namely, the last in any sequence in which it occurs). It has no defined lexical form.
Note: this is retained only for backwards compatibility with existing parsers and tools.
See also: error_marker/1
, is_form/1
, warning_marker/1
.
-spec error_marker(term()) -> syntaxTree().
Creates an abstract error marker. The result represents an occurrence of an
error in the source code, with an associated Erlang I/O ErrorInfo structure
given by Error
(see module //stdlib/io
for details). Error markers
are regarded as source code forms, but have no defined lexical form.
Note: this is supported only for backwards compatibility with existing parsers and tools.
See also: eof_marker/0
, error_marker_info/1
, is_form/1
,
warning_marker/1
.
-spec error_marker_info(syntaxTree()) -> term().
Returns the ErrorInfo structure of an error_marker
node.
See also: error_marker/1
.
-spec flatten_form_list(syntaxTree()) -> syntaxTree().
Flattens sublists of a form_list
node. Returns Node
with all subtrees of
type form_list
recursively expanded, yielding a single "flat" abstract form
sequence.
See also: form_list/1
.
-spec float(float()) -> syntaxTree().
Creates an abstract floating-point literal. The lexical representation is the
decimal floating-point numeral of Value
.
See also: float_literal/1
, float_value/1
.
-spec float_literal(syntaxTree()) -> string().
Returns the numeral string represented by a float
node.
See also: float/1
.
-spec float_value(syntaxTree()) -> float().
Returns the value represented by a float
node. Note that floating-point values
should usually not be compared for equality.
See also: float/1
.
-spec form_list([syntaxTree()]) -> syntaxTree().
Creates an abstract sequence of "source code forms". If Forms
is
[F1, ..., Fn]
, where each Fi
is a form (see is_form/1
, the result
represents
F1
...
Fn
where the Fi
are separated by one or more line breaks. A node of type
form_list
is itself regarded as a source code form; see flatten_form_list/1
.
Note: this is simply a way of grouping source code forms as a single syntax tree, usually in order to form an Erlang module definition.
See also: flatten_form_list/1
, form_list_elements/1
, is_form/1
.
-spec form_list_elements(syntaxTree()) -> [syntaxTree()].
Returns the list of subnodes of a form_list
node.
See also: form_list/1
.
-spec fun_expr([syntaxTree()]) -> syntaxTree().
Creates an abstract fun-expression. If Clauses
is [C1, ..., Cn]
, the result
represents "fun *C1*; ...; *Cn* end
". More exactly, if each Ci
represents
"(*Pi1*, ..., *Pim*) *Gi* -> *Bi*
", then the result represents
"fun (*P11*, ..., *P1m*) *G1* -> *B1*; ...; (*Pn1*, ..., *Pnm*) *Gn* -> *Bn* end
".
See also: fun_expr_arity/1
, fun_expr_clauses/1
.
-spec fun_expr_arity(syntaxTree()) -> arity().
Returns the arity of a fun_expr
node. The result is the number of parameter
patterns in the first clause of the fun-expression; subsequent clauses are
ignored.
An exception is thrown if fun_expr_clauses(Node)
returns an empty list, or if the first element of that list is not a syntax tree
C
of type clause
such that clause_patterns(C)
is a
nonempty list.
See also: clause/3
, clause_patterns/1
, fun_expr/1
, fun_expr_clauses/1
.
-spec fun_expr_clauses(syntaxTree()) -> [syntaxTree()].
Returns the list of clause subtrees of a fun_expr
node.
See also: fun_expr/1
.
-spec fun_type() -> syntaxTree().
Creates an abstract fun of any type. The result represents "fun()
".
-spec function(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract function definition. If Clauses
is [C1, ..., Cn]
, the
result represents "*Name**C1*; ...; *Name**Cn*.
". More exactly, if each Ci
represents "(*Pi1*, ..., *Pim*) *Gi* -> *Bi*
", then the result represents
"*Name*(*P11*, ..., *P1m*) *G1* -> *B1*; ...; *Name*(*Pn1*, ..., *Pnm*) *Gn* -> *Bn*.
".
Function definitions are source code forms.
See also: function_arity/1
, function_clauses/1
, function_name/1
,
is_form/1
.
-spec function_arity(syntaxTree()) -> arity().
Returns the arity of a function
node. The result is the number of parameter
patterns in the first clause of the function; subsequent clauses are ignored.
An exception is thrown if function_clauses(Node)
returns an empty list, or if the first element of that list is not a syntax tree
C
of type clause
such that clause_patterns(C)
is a
nonempty list.
See also: clause/3
, clause_patterns/1
, function/2
, function_clauses/1
.
-spec function_clauses(syntaxTree()) -> [syntaxTree()].
Returns the list of clause subtrees of a function
node.
See also: function/2
.
-spec function_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a function
node.
See also: function/2
.
-spec function_type(syntaxTree()) -> syntaxTree().
Equivalent to function_type(any_arity, Type).
-spec function_type(any_arity | [syntaxTree()], syntaxTree()) -> syntaxTree().
Creates an abstract function type. If Arguments
is [T1, ..., Tn]
, then if it
occurs within a function specification, the result represents
"(*T1*, ...*Tn*) -> *Return*
"; otherwise it represents
"fun((*T1*, ...*Tn*) -> *Return*)
". If Arguments
is any_arity
, it
represents "fun((...) -> *Return*)
".
Note that the erl_parse
representation is identical for "*FunctionType*
" and
"fun(*FunctionType*)
".
See also: function_type_arguments/1
, function_type_return/1
.
-spec function_type_arguments(syntaxTree()) -> any_arity | [syntaxTree()].
Returns the argument types subtrees of a function_type
node. If Node
represents "fun((...) -> *Return*)
", any_arity
is returned; otherwise, if
Node
represents "(*T1*, ...*Tn*) -> *Return*
" or
"fun((*T1*, ...*Tn*) -> *Return*)
", [T1, ..., Tn]
is returned.
See also: function_type/1
, function_type/2
.
-spec function_type_return(syntaxTree()) -> syntaxTree().
Returns the return type subtrees of a function_type
node.
See also: function_type/1
, function_type/2
.
-spec generator(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract generator. The result represents "*Pattern*<- *Body*
".
See also: binary_comp/2
, generator_body/1
, generator_pattern/1
,
list_comp/2
.
-spec generator_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a generator
node.
See also: generator/2
.
-spec generator_pattern(syntaxTree()) -> syntaxTree().
Returns the pattern subtree of a generator
node.
See also: generator/2
.
-spec get_ann(syntaxTree()) -> [term()].
Returns the list of user annotations associated with a syntax tree node. For a newly created node, this is the empty list. The annotations may be any terms.
See also: get_attrs/1
, set_ann/2
.
-spec get_attrs(syntaxTree()) -> syntaxTreeAttributes().
Returns a representation of the attributes associated with a syntax tree node.
The attributes are all the extra information that can be attached to a node.
Currently, this includes position information, source code comments, and user
annotations. The result of this function cannot be inspected directly; only
attached to another node (see set_attrs/2
).
For accessing individual attributes, see get_pos/1
, get_ann/1
,
get_precomments/1
and get_postcomments/1
.
See also: get_ann/1
, get_pos/1
, get_postcomments/1
, get_precomments/1
,
set_attrs/2
.
-spec get_pos(syntaxTree()) -> annotation_or_location().
Returns the annotation (see //stdlib/erl_anno
) associated with
Node
. By default, all new tree nodes have their associated position
information set to the integer zero. Use
//stdlib/erl_anno:location/1
or
//stdlib/erl_anno:line/1
to get the position information.
See also: get_attrs/1
, set_pos/2
.
-spec get_postcomments(syntaxTree()) -> [syntaxTree()].
Returns the associated post-comments of a node. This is a possibly empty list of abstract comments, in top-down textual order. When the code is formatted, post-comments are typically displayed to the right of and/or below the node. For example:
{foo, X, Y} % Post-comment of tuple
If possible, the comment should be moved past any following separator characters on the same line, rather than placing the separators on the following line. E.g.:
foo([X | Xs], Y) ->
foo(Xs, bar(X)); % Post-comment of 'bar(X)' node
...
(where the comment is moved past the rightmost ")
" and the ";
").
See also: comment/2
, get_attrs/1
, get_precomments/1
,
set_postcomments/2
.
-spec get_precomments(syntaxTree()) -> [syntaxTree()].
Returns the associated pre-comments of a node. This is a possibly empty list of abstract comments, in top-down textual order. When the code is formatted, pre-comments are typically displayed directly above the node. For example:
% Pre-comment of function
foo(X) -> {bar, X}.
If possible, the comment should be moved before any preceding separator characters on the same line. E.g.:
foo([X | Xs]) ->
% Pre-comment of 'bar(X)' node
[bar(X) | foo(Xs)];
...
(where the comment is moved before the "[
").
See also: comment/2
, get_attrs/1
, get_postcomments/1
,
set_precomments/2
.
-spec has_comments(syntaxTree()) -> boolean().
Yields false
if the node has no associated comments, and true
otherwise.
Note: This is equivalent to
(get_precomments(Node) == []) and (get_postcomments(Node) == [])
, but
potentially more efficient.
See also: get_postcomments/1
, get_precomments/1
, remove_comments/1
.
-spec if_expr([syntaxTree()]) -> syntaxTree().
Creates an abstract if-expression. If Clauses
is [C1, ..., Cn]
, the result
represents "if *C1*; ...; *Cn* end
". More exactly, if each Ci
represents
"() *Gi* -> *Bi*
", then the result represents
"if *G1* -> *B1*; ...; *Gn* -> *Bn* end
".
See also: case_expr/2
, clause/3
, if_expr_clauses/1
.
-spec if_expr_clauses(syntaxTree()) -> [syntaxTree()].
Returns the list of clause subtrees of an if_expr
node.
See also: if_expr/1
.
-spec implicit_fun(syntaxTree()) -> syntaxTree().
Creates an abstract "implicit fun" expression. The result represents
"fun *Name*
". Name
should represent either *F*/*A*
or *M*:*F*/*A*
See also: arity_qualifier/2
, implicit_fun/2
, implicit_fun/3
,
implicit_fun_name/1
, module_qualifier/2
.
-spec implicit_fun(syntaxTree(), none | syntaxTree()) -> syntaxTree().
Creates an abstract "implicit fun" expression. If Arity
is none
, this is
equivalent to implicit_fun(Name)
, otherwise it is
equivalent to implicit_fun(arity_qualifier(Name, Arity))
.
(This is a utility function.)
See also: implicit_fun/1
, implicit_fun/3
.
-spec implicit_fun(none | syntaxTree(), syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract module-qualified "implicit fun" expression. If Module
is
none
, this is equivalent to implicit_fun(Name, Arity)
,
otherwise it is equivalent to
implicit_fun(module_qualifier(Module, arity_qualifier(Name, Arity))
.
(This is a utility function.)
See also: implicit_fun/1
, implicit_fun/2
.
-spec implicit_fun_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of an implicit_fun
node.
Note: if Node
represents "fun *N*/*A*
" or "fun *M*:*N*/*A*
", then the
result is the subtree representing "*N*/*A*
" or "*M*:*N*/*A*
", respectively.
See also: arity_qualifier/2
, implicit_fun/1
, module_qualifier/2
.
-spec infix_expr(syntaxTree(), syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract infix operator expression. The result represents
"*Left**Operator**Right*
".
See also: infix_expr_left/1
, infix_expr_operator/1
, infix_expr_right/1
,
prefix_expr/2
.
-spec infix_expr_left(syntaxTree()) -> syntaxTree().
Returns the left argument subtree of an infix_expr
node.
See also: infix_expr/3
.
-spec infix_expr_operator(syntaxTree()) -> syntaxTree().
Returns the operator subtree of an infix_expr
node.
See also: infix_expr/3
.
-spec infix_expr_right(syntaxTree()) -> syntaxTree().
Returns the right argument subtree of an infix_expr
node.
See also: infix_expr/3
.
-spec integer(integer()) -> syntaxTree().
Creates an abstract integer literal. The lexical representation is the canonical
decimal numeral of Value
.
See also: integer_literal/1
, integer_value/1
, is_integer/2
.
-spec integer_literal(syntaxTree()) -> string().
Returns the numeral string represented by an integer
node.
See also: integer/1
.
-spec integer_range_type(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract range type. The result represents "*Low* .. *High*
".
See also: integer_range_type_high/1
, integer_range_type_low/1
.
-spec integer_range_type_high(syntaxTree()) -> syntaxTree().
Returns the high limit of an integer_range_type
node.
See also: integer_range_type/2
.
-spec integer_range_type_low(syntaxTree()) -> syntaxTree().
Returns the low limit of an integer_range_type
node.
See also: integer_range_type/2
.
-spec integer_value(syntaxTree()) -> integer().
Returns the value represented by an integer
node.
See also: integer/1
.
-spec is_atom(syntaxTree(), atom()) -> boolean().
Returns true
if Node
has type atom
and represents Value
, otherwise
false
.
See also: atom/1
.
-spec is_char(syntaxTree(), char()) -> boolean().
Returns true
if Node
has type char
and represents Value
, otherwise
false
.
See also: char/1
.
-spec is_form(syntaxTree()) -> boolean().
Returns true
if Node
is a syntax tree representing a so-called "source code
form", otherwise false
. Forms are the Erlang source code units which, placed
in sequence, constitute an Erlang program. Current form types are:
`attribute` | `comment` | `error_marker` | `eof_marker` |
`form_list` | `function` | `warning_marker` | `text` |
See also: attribute/2
, comment/2
, eof_marker/0
, error_marker/1
,
form_list/1
, function/2
, type/1
, warning_marker/1
.
-spec is_integer(syntaxTree(), integer()) -> boolean().
Returns true
if Node
has type integer
and represents Value
, otherwise
false
.
See also: integer/1
.
-spec is_leaf(syntaxTree()) -> boolean().
Returns true
if Node
is a leaf node, otherwise false
. The currently
recognised leaf node types are:
`atom` | `char` | `comment` | `eof_marker` | `error_marker` | |
`float` | `fun_type` | `integer` | `nil` | `operator` | `string` |
`text` | `underscore` | `variable` | `warning_marker` |
A node of type map_expr
is a leaf node if and only if it has no argument and
no fields. A node of type map_type
is a leaf node if and only if it has no
fields (any_size
). A node of type tuple
is a leaf node if and only if its
arity is zero. A node of type tuple_type
is a leaf node if and only if it has
no elements (any_size
).
Note: not all literals are leaf nodes, and vice versa. E.g., tuples with nonzero arity and nonempty lists may be literals, but are not leaf nodes. Variables, on the other hand, are leaf nodes but not literals.
See also: is_literal/1
, type/1
.
-spec is_list_skeleton(syntaxTree()) -> boolean().
Returns true
if Node
has type list
or nil
, otherwise false
.
-spec is_literal(syntaxTree()) -> boolean().
Returns true
if Node
represents a literal term, otherwise false
. This
function returns true
if and only if the value of
concrete(Node)
is defined.
See also: abstract/1
, concrete/1
.
-spec is_proper_list(syntaxTree()) -> boolean().
Returns true
if Node
represents a proper list, and false
otherwise. A
proper list is a list skeleton either on the form "[]
" or
"[*E1*, ..., *En*]
", or "[... | *Tail*]
" where recursively Tail
also
represents a proper list.
Note: Since Node
is a syntax tree, the actual run-time values corresponding to
its subtrees may often be partially or completely unknown. Thus, if Node
represents e.g. "[... | Ns]
" (where Ns
is a variable), then the function
will return false
, because it is not known whether Ns
will be bound to a
list at run-time. If Node
instead represents e.g. "[1, 2, 3]
" or
"[A | []]
", then the function will return true
.
See also: list/2
.
-spec is_string(syntaxTree(), string()) -> boolean().
Returns true
if Node
has type string
and represents Value
, otherwise
false
.
See also: string/1
.
-spec is_tree(syntaxTree()) -> boolean().
For special purposes only. Returns true
if Tree
is an abstract syntax tree
and false
otherwise.
Note: this function yields false
for all "old-style" erl_parse
-compatible
"parse trees".
See also: tree/2
.
-spec join_comments(syntaxTree(), syntaxTree()) -> syntaxTree().
Appends the comments of Source
to the current comments of Target
.
Note: This is equivalent to
add_postcomments(get_postcomments(Source), add_precomments(get_precomments(Source), Target))
,
but potentially more efficient.
See also: add_postcomments/2
, add_precomments/2
, comment/2
,
get_postcomments/1
, get_precomments/1
.
-spec list([syntaxTree()]) -> syntaxTree().
Equivalent to list(List, none).
-spec list([syntaxTree()], none | syntaxTree()) -> syntaxTree().
Constructs an abstract list skeleton. The result has type list
or nil
. If
List
is a nonempty list [E1, ..., En]
, the result has type list
and
represents either "[*E1*, ..., *En*]
", if Tail
is none
, or otherwise
"[*E1*, ..., *En* | *Tail*]
". If List
is the empty list, Tail
must be
none
, and in that case the result has type nil
and represents "[]
" (see
nil/0
).
The difference between lists as semantic objects (built up of individual "cons" and "nil" terms) and the various syntactic forms for denoting lists may be bewildering at first. This module provides functions both for exact control of the syntactic representation as well as for the simple composition and deconstruction in terms of cons and head/tail operations.
Note: in list(Elements, none)
, the "nil" list terminator is
implicit and has no associated information (see get_attrs/1
), while in the
seemingly equivalent list(Elements, Tail)
when Tail
has type
nil
, the list terminator subtree Tail
may have attached attributes such as
position, comments, and annotations, which will be preserved in the result.
See also: compact_list/1
, cons/2
, get_attrs/1
, is_list_skeleton/1
,
is_proper_list/1
, list/1
, list_elements/1
, list_head/1
, list_length/1
,
list_prefix/1
, list_suffix/1
, list_tail/1
, nil/0
, normalize_list/1
.
-spec list_comp(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract list comprehension. If Body
is [E1, ..., En]
, the result
represents "[*Template* || *E1*, ..., *En*]
".
See also: generator/2
, list_comp_body/1
, list_comp_template/1
.
-spec list_comp_body(syntaxTree()) -> [syntaxTree()].
Returns the list of body subtrees of a list_comp
node.
See also: list_comp/2
.
-spec list_comp_template(syntaxTree()) -> syntaxTree().
Returns the template subtree of a list_comp
node.
See also: list_comp/2
.
-spec list_elements(syntaxTree()) -> [syntaxTree()].
Returns the list of element subtrees of a list skeleton. Node
must represent a
proper list. E.g., if Node
represents "[*X1*, *X2* | [*X3*, *X4* | []]
",
then list_elements(Node)
yields the list
[X1, X2, X3, X4]
.
See also: is_proper_list/1
, list/2
.
-spec list_head(syntaxTree()) -> syntaxTree().
Returns the head element subtree of a list
node. If Node
represents
"[*Head* ...]
", the result will represent "*Head*
".
See also: cons/2
, list/2
, list_tail/1
.
-spec list_length(syntaxTree()) -> non_neg_integer().
Returns the number of element subtrees of a list skeleton. Node
must represent
a proper list. E.g., if Node
represents "[X1 | [X2, X3 | [X4, X5, X6]]]
",
then list_length(Node)
returns the integer 6.
Note: this is equivalent to length(list_elements(Node))
, but
potentially more efficient.
See also: is_proper_list/1
, list/2
, list_elements/1
.
-spec list_prefix(syntaxTree()) -> [syntaxTree()].
Returns the prefix element subtrees of a list
node. If Node
represents
"[*E1*, ..., *En*]
" or "[*E1*, ..., *En* | *Tail*]
", the returned value is
[E1, ..., En]
.
See also: list/2
.
-spec list_suffix(syntaxTree()) -> none | syntaxTree().
Returns the suffix subtree of a list
node, if one exists. If Node
represents
"[*E1*, ..., *En* | *Tail*]
", the returned value is Tail
, otherwise, i.e.,
if Node
represents "[*E1*, ..., *En*]
", none
is returned.
Note that even if this function returns some Tail
that is not none
, the type
of Tail
can be nil
, if the tail has been given explicitly, and the list
skeleton has not been compacted (see compact_list/1
).
See also: compact_list/1
, list/2
, nil/0
.
-spec list_tail(syntaxTree()) -> syntaxTree().
Returns the tail of a list
node. If Node
represents a single-element list
"[*E*]
", then the result has type nil
, representing "[]
". If Node
represents "[*E1*, *E2* ...]
", the result will represent "[*E2* ...]
", and
if Node
represents "[*Head* | *Tail*]
", the result will represent
"*Tail*
".
See also: cons/2
, list/2
, list_head/1
.
-spec macro(syntaxTree()) -> syntaxTree().
Equivalent to macro(Name, none).
-spec macro(syntaxTree(), none | [syntaxTree()]) -> syntaxTree().
Creates an abstract macro application. If Arguments
is none
, the result
represents "?*Name*
", otherwise, if Arguments
is [A1, ..., An]
, the result
represents "?*Name*(*A1*, ..., *An*)
".
Notes: if Arguments
is the empty list, the result will thus represent
"?*Name*()
", including a pair of matching parentheses.
The only syntactical limitation imposed by the preprocessor on the arguments to
a macro application (viewed as sequences of tokens) is that they must be
balanced with respect to parentheses, brackets, begin ... end
, case ... end
,
etc. The text
node type can be used to represent arguments which are not
regular Erlang constructs.
See also: macro/1
, macro_arguments/1
, macro_name/1
, text/1
.
-spec macro_arguments(syntaxTree()) -> none | [syntaxTree()].
Returns the list of argument subtrees of a macro
node, if any. If Node
represents "?*Name*
", none
is returned. Otherwise, if Node
represents
"?*Name*(*A1*, ..., *An*)
", [A1, ..., An]
is returned.
See also: macro/2
.
-spec macro_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a macro
node.
See also: macro/2
.
-spec make_tree(atom(), [[syntaxTree()]]) -> syntaxTree().
Creates a syntax tree with the given type and subtrees. Type
must be a node
type name (see type/1
) that does not denote a leaf node type (see
is_leaf/1
). Groups
must be a nonempty list of groups of syntax trees,
representing the subtrees of a node of the given type, in left-to-right order as
they would occur in the printed program text, grouped by category as done by
subtrees/1
.
The result of
copy_attrs(Node, make_tree(type(Node), subtrees(Node)))
(see
update_tree/2
) represents the same source code text as the original Node
,
assuming that subtrees(Node)
yields a nonempty list. However,
it does not necessarily have the same data representation as Node
.
See also: copy_attrs/2
, is_leaf/1
, subtrees/1
, type/1
,
update_tree/2
.
-spec map_comp(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract map comprehension. If Body
is [E1, ..., En]
, the result
represents "#{*Template* || *E1*, ..., *En*}
".
See also: generator/2
, map_comp_body/1
, map_comp_template/1
.
-spec map_comp_body(syntaxTree()) -> [syntaxTree()].
Returns the list of body subtrees of a map_comp
node.
See also: map_comp/2
.
-spec map_comp_template(syntaxTree()) -> syntaxTree().
Returns the template subtree of a map_comp
node.
See also: map_comp/2
.
-spec map_expr([syntaxTree()]) -> syntaxTree().
Equivalent to map_expr(none, Fields).
-spec map_expr(none | syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract map expression. If Fields
is [F1, ..., Fn]
, then if
Argument
is none
, the result represents "#{*F1*, ..., *Fn*}
", otherwise it
represents "*Argument*#{*F1*, ..., *Fn*}
".
See also: map_expr/1
, map_expr_argument/1
, map_expr_fields/1
,
map_field_assoc/2
, map_field_exact/2
.
-spec map_expr_argument(syntaxTree()) -> none | syntaxTree().
Returns the argument subtree of a map_expr
node, if any. If Node
represents
"#{...}
", none
is returned. Otherwise, if Node
represents
"*Argument*#{...}
", Argument
is returned.
See also: map_expr/2
.
-spec map_expr_fields(syntaxTree()) -> [syntaxTree()].
Returns the list of field subtrees of a map_expr
node.
See also: map_expr/2
.
-spec map_field_assoc(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract map assoc field. The result represents
"*Name* => *Value*
".
See also: map_expr/2
, map_field_assoc_name/1
, map_field_assoc_value/1
.
-spec map_field_assoc_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a map_field_assoc
node.
See also: map_field_assoc/2
.
-spec map_field_assoc_value(syntaxTree()) -> syntaxTree().
Returns the value subtree of a map_field_assoc
node.
See also: map_field_assoc/2
.
-spec map_field_exact(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract map exact field. The result represents
"*Name* := *Value*
".
See also: map_expr/2
, map_field_exact_name/1
, map_field_exact_value/1
.
-spec map_field_exact_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a map_field_exact
node.
See also: map_field_exact/2
.
-spec map_field_exact_value(syntaxTree()) -> syntaxTree().
Returns the value subtree of a map_field_exact
node.
See also: map_field_exact/2
.
-spec map_generator(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract map_generator. The result represents "*Pattern*<- *Body*
".
See also: list_comp/2
, map_comp/2
, map_generator_body/1
,
map_generator_pattern/1
.
-spec map_generator_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a generator
node.
See also: map_generator/2
.
-spec map_generator_pattern(syntaxTree()) -> syntaxTree().
Returns the pattern subtree of a generator
node.
See also: map_generator/2
.
-spec map_type() -> syntaxTree().
Equivalent to map_type(any_size).
-spec map_type(any_size | [syntaxTree()]) -> syntaxTree().
Creates an abstract type map. If Fields
is [F1, ..., Fn]
, the result
represents "#{*F1*, ..., *Fn*}
"; otherwise, if Fields
is any_size
, it
represents "map/0
".
See also: map_type_fields/1
.
-spec map_type_assoc(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract map type assoc field. The result represents
"*Name* => *Value*
".
See also: map_type/1
, map_type_assoc_name/1
, map_type_assoc_value/1
.
-spec map_type_assoc_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a map_type_assoc
node.
See also: map_type_assoc/2
.
-spec map_type_assoc_value(syntaxTree()) -> syntaxTree().
Returns the value subtree of a map_type_assoc
node.
See also: map_type_assoc/2
.
-spec map_type_exact(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract map type exact field. The result represents
"*Name* := *Value*
".
See also: map_type/1
, map_type_exact_name/1
, map_type_exact_value/1
.
-spec map_type_exact_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a map_type_exact
node.
See also: map_type_exact/2
.
-spec map_type_exact_value(syntaxTree()) -> syntaxTree().
Returns the value subtree of a map_type_exact
node.
See also: map_type_exact/2
.
-spec map_type_fields(syntaxTree()) -> any_size | [syntaxTree()].
Returns the list of field subtrees of a map_type
node. If Node
represents
"map/0
", any_size
is returned; otherwise, if Node
represents
"#{*F1*, ..., *Fn*}
", [F1, ..., Fn]
is returned.
See also: map_type/0
, map_type/1
.
-spec match_expr(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract match-expression. The result represents
"*Pattern* = *Body*
".
See also: match_expr_body/1
, match_expr_pattern/1
.
-spec match_expr_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a match_expr
node.
See also: match_expr/2
.
-spec match_expr_pattern(syntaxTree()) -> syntaxTree().
Returns the pattern subtree of a match_expr
node.
See also: match_expr/2
.
-spec maybe_expr([syntaxTree()]) -> syntaxTree().
Equivalent to maybe_expr(Body, none).
-spec maybe_expr([syntaxTree()], none | syntaxTree()) -> syntaxTree().
Creates an abstract maybe-expression. If Body
is [B1, ..., Bn]
, and
OptionalElse
is none
, the result represents "maybe *B1*, ..., *Bn* end
".
If Body
is [B1, ..., Bn]
, and OptionalElse
reprsents an else_expr
node
with clauses [C1, ..., Cn]
, the result represents
"maybe *B1*, ..., *Bn* else *C1*; ..., *Cn* end
".
See clause
for documentation on erl_parse
clauses.
See also: maybe_expr_body/1
, maybe_expr_else/1
.
-spec maybe_expr_body(syntaxTree()) -> [syntaxTree()].
Returns the list of body subtrees of a maybe_expr
node.
See also: maybe_expr/2
.
-spec maybe_expr_else(syntaxTree()) -> none | syntaxTree().
Returns the else subtree of a maybe_expr
node.
See also: maybe_expr/2
.
-spec maybe_match_expr(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract maybe-expression, as used in maybe
blocks. The result
represents "*Pattern* ?= *Body*
".
See also: maybe_expr/2
, maybe_match_expr_body/1
,
maybe_match_expr_pattern/1
.
-spec maybe_match_expr_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a maybe_expr
node.
See also: maybe_match_expr/2
.
-spec maybe_match_expr_pattern(syntaxTree()) -> syntaxTree().
Returns the pattern subtree of a maybe_expr
node.
See also: maybe_match_expr/2
.
-spec meta(syntaxTree()) -> syntaxTree().
Creates a meta-representation of a syntax tree. The result represents an Erlang
expression "*MetaTree*
" which, if evaluated, will yield a new syntax tree
representing the same source code text as Tree
(although the actual data
representation may be different). The expression represented by MetaTree
is
implementation independent with regard to the data structures used by the
abstract syntax tree implementation. Comments attached to nodes of Tree
will
be preserved, but other attributes are lost.
Any node in Tree
whose node type is variable
(see type/1
), and whose list
of annotations (see get_ann/1
) contains the atom meta_var
, will remain
unchanged in the resulting tree, except that exactly one occurrence of
meta_var
is removed from its annotation list.
The main use of the function meta/1
is to transform a data
structure Tree
, which represents a piece of program code, into a form that is
representation independent when printed. E.g., suppose Tree
represents a
variable named "V". Then (assuming a function print/1
for printing syntax
trees), evaluating print(abstract(Tree))
- simply using abstract/1
to map
the actual data structure onto a syntax tree representation - would output a
string that might look something like "{tree, variable, ..., "V", ...}
", which
is obviously dependent on the implementation of the abstract syntax trees. This
could e.g. be useful for caching a syntax tree in a file. However, in some
situations like in a program generator generator (with two "generator"), it may
be unacceptable. Using print(meta(Tree))
instead would output a
representation independent syntax tree generating expression; in the above
case, something like "erl_syntax:variable("V")
".
See also: abstract/1
, get_ann/1
, type/1
.
-spec module_qualifier(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract module qualifier. The result represents "*Module*:*Body*
".
See also: module_qualifier_argument/1
, module_qualifier_body/1
.
-spec module_qualifier_argument(syntaxTree()) -> syntaxTree().
Returns the argument (the module) subtree of a module_qualifier
node.
See also: module_qualifier/2
.
-spec module_qualifier_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a module_qualifier
node.
See also: module_qualifier/2
.
-spec named_fun_expr(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract named fun-expression. If Clauses
is [C1, ..., Cn]
, the
result represents "fun *Name**C1*; ...; *Name**Cn* end
". More exactly, if each
Ci
represents "(*Pi1*, ..., *Pim*) *Gi* -> *Bi*
", then the result represents
"fun *Name*(*P11*, ..., *P1m*) *G1* -> *B1*; ...; *Name*(*Pn1*, ..., *Pnm*) *Gn* -> *Bn* end
".
See also: named_fun_expr_arity/1
, named_fun_expr_clauses/1
,
named_fun_expr_name/1
.
-spec named_fun_expr_arity(syntaxTree()) -> arity().
Returns the arity of a named_fun_expr
node. The result is the number of
parameter patterns in the first clause of the named fun-expression; subsequent
clauses are ignored.
An exception is thrown if
named_fun_expr_clauses(Node)
returns an empty
list, or if the first element of that list is not a syntax tree C
of type
clause
such that clause_patterns(C)
is a nonempty
list.
See also: clause/3
, clause_patterns/1
, named_fun_expr/2
,
named_fun_expr_clauses/1
.
-spec named_fun_expr_clauses(syntaxTree()) -> [syntaxTree()].
Returns the list of clause subtrees of a named_fun_expr
node.
See also: named_fun_expr/2
.
-spec named_fun_expr_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a named_fun_expr
node.
See also: named_fun_expr/2
.
-spec normalize_list(syntaxTree()) -> syntaxTree().
Expands an abstract list skeleton to its most explicit form. If Node
represents "[*E1*, ..., *En* | *Tail*]
", the result represents
"[*E1* | ... [*En* | *Tail1*] ... ]
", where Tail1
is the result of
normalize_list(Tail)
. If Node
represents
"[*E1*, ..., *En*]
", the result simply represents
"[*E1* | ... [*En* | []] ... ]
". If Node
does not represent a list skeleton,
Node
itself is returned.
See also: compact_list/1
, list/2
.
-spec operator(atom() | string()) -> syntaxTree().
Creates an abstract operator. The name of the operator is the character sequence
represented by Name
. This is analogous to the print name of an atom, but an
operator is never written within single-quotes; e.g., the result of
operator('++')
represents "++
" rather than "'++'
".
See also: atom/1
, operator_literal/1
, operator_name/1
.
-spec operator_literal(syntaxTree()) -> string().
Returns the literal string represented by an operator
node. This is simply the
operator name as a string.
See also: operator/1
.
-spec operator_name(syntaxTree()) -> atom().
Returns the name of an operator
node. Note that the name is returned as an
atom.
See also: operator/1
.
-spec parentheses(syntaxTree()) -> syntaxTree().
Creates an abstract parenthesised expression. The result represents
"(*Body*)
", independently of the context.
See also: parentheses_body/1
.
-spec parentheses_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a parentheses
node.
See also: parentheses/1
.
-spec prefix_expr(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract prefix operator expression. The result represents
"*Operator**Argument*
".
See also: infix_expr/3
, prefix_expr_argument/1
, prefix_expr_operator/1
.
-spec prefix_expr_argument(syntaxTree()) -> syntaxTree().
Returns the argument subtree of a prefix_expr
node.
See also: prefix_expr/2
.
-spec prefix_expr_operator(syntaxTree()) -> syntaxTree().
Returns the operator subtree of a prefix_expr
node.
See also: prefix_expr/2
.
-spec receive_expr([syntaxTree()]) -> syntaxTree().
Equivalent to receive_expr(Clauses, none, []).
-spec receive_expr([syntaxTree()], none | syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract receive-expression. If Timeout
is none
, the result
represents "receive *C1*; ...; *Cn* end
" (the Action
argument is ignored).
Otherwise, if Clauses
is [C1, ..., Cn]
and Action
is [A1, ..., Am]
, the
result represents
"receive *C1*; ...; *Cn* after *Timeout* -> *A1*, ..., *Am* end
". More
exactly, if each Ci
represents "(*Pi*) *Gi* -> *Bi*
", then the result
represents "receive *P1**G1* -> *B1*; ...; *Pn**Gn* -> *Bn* ... end
".
Note that in Erlang, a receive-expression must have at least one clause if no timeout part is specified.
See also: case_expr/2
, clause/3
, receive_expr/1
,
receive_expr_action/1
, receive_expr_clauses/1
, receive_expr_timeout/1
.
-spec receive_expr_action(syntaxTree()) -> [syntaxTree()].
Returns the list of action body subtrees of a receive_expr
node. If Node
represents "receive *C1*; ...; *Cn* end
", this is the empty list.
See also: receive_expr/3
.
-spec receive_expr_clauses(syntaxTree()) -> [syntaxTree()].
Returns the list of clause subtrees of a receive_expr
node.
See also: receive_expr/3
.
-spec receive_expr_timeout(syntaxTree()) -> none | syntaxTree().
Returns the timeout subtree of a receive_expr
node, if any. If Node
represents "receive *C1*; ...; *Cn* end
", none
is returned. Otherwise, if
Node
represents "receive *C1*; ...; *Cn* after *Timeout* -> ... end
",
Timeout
is returned.
See also: receive_expr/3
.
-spec record_access(syntaxTree(), syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract record field access expression. The result represents
"*Argument*#*Type*.*Field*
".
See also: record_access_argument/1
, record_access_field/1
,
record_access_type/1
, record_expr/3
.
-spec record_access_argument(syntaxTree()) -> syntaxTree().
Returns the argument subtree of a record_access
node.
See also: record_access/3
.
-spec record_access_field(syntaxTree()) -> syntaxTree().
Returns the field subtree of a record_access
node.
See also: record_access/3
.
-spec record_access_type(syntaxTree()) -> syntaxTree().
Returns the type subtree of a record_access
node.
See also: record_access/3
.
-spec record_expr(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Equivalent to record_expr(none, Type, Fields).
-spec record_expr(none | syntaxTree(), syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract record expression. If Fields
is [F1, ..., Fn]
, then if
Argument
is none
, the result represents "#*Type*{*F1*, ..., *Fn*}
",
otherwise it represents "*Argument*#*Type*{*F1*, ..., *Fn*}
".
See also: record_access/3
, record_expr/2
, record_expr_argument/1
,
record_expr_fields/1
, record_expr_type/1
, record_field/2
,
record_index_expr/2
.
-spec record_expr_argument(syntaxTree()) -> none | syntaxTree().
Returns the argument subtree of a record_expr
node, if any. If Node
represents "#*Type*{...}
", none
is returned. Otherwise, if Node
represents
"*Argument*#*Type*{...}
", Argument
is returned.
See also: record_expr/3
.
-spec record_expr_fields(syntaxTree()) -> [syntaxTree()].
Returns the list of field subtrees of a record_expr
node.
See also: record_expr/3
.
-spec record_expr_type(syntaxTree()) -> syntaxTree().
Returns the type subtree of a record_expr
node.
See also: record_expr/3
.
-spec record_field(syntaxTree()) -> syntaxTree().
Equivalent to record_field(Name, none).
-spec record_field(syntaxTree(), none | syntaxTree()) -> syntaxTree().
Creates an abstract record field specification. If Value
is none
, the result
represents simply "*Name*
", otherwise it represents "*Name* = *Value*
".
See also: record_expr/3
, record_field_name/1
, record_field_value/1
.
-spec record_field_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a record_field
node.
See also: record_field/2
.
-spec record_field_value(syntaxTree()) -> none | syntaxTree().
Returns the value subtree of a record_field
node, if any. If Node
represents
"*Name*
", none
is returned. Otherwise, if Node
represents
"*Name* = *Value*
", Value
is returned.
See also: record_field/2
.
-spec record_index_expr(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract record field index expression. The result represents
"#*Type*.*Field*
".
(Note: the function name record_index/2
is reserved by the Erlang compiler,
which is why that name could not be used for this constructor.)
See also: record_expr/3
, record_index_expr_field/1
,
record_index_expr_type/1
.
-spec record_index_expr_field(syntaxTree()) -> syntaxTree().
Returns the field subtree of a record_index_expr
node.
See also: record_index_expr/2
.
-spec record_index_expr_type(syntaxTree()) -> syntaxTree().
Returns the type subtree of a record_index_expr
node.
See also: record_index_expr/2
.
-spec record_type(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract record type. If Fields
is [F1, ..., Fn]
, the result
represents "#*Name*{*F1*, ..., *Fn*}
".
See also: record_type_fields/1
, record_type_name/1
.
-spec record_type_field(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract record type field. The result represents
"*Name* :: *Type*
".
See also: record_type_field_name/1
, record_type_field_type/1
.
-spec record_type_field_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a record_type_field
node.
See also: record_type_field/2
.
-spec record_type_field_type(syntaxTree()) -> syntaxTree().
Returns the type subtree of a record_type_field
node.
See also: record_type_field/2
.
-spec record_type_fields(syntaxTree()) -> [syntaxTree()].
Returns the fields subtree of a record_type
node.
See also: record_type/2
.
-spec record_type_name(syntaxTree()) -> syntaxTree().
Returns the name subtree of a record_type
node.
See also: record_type/2
.
-spec remove_comments(syntaxTree()) -> syntaxTree().
Clears the associated comments of Node
.
Note: This is equivalent to
set_precomments(set_postcomments(Node, []), [])
, but
potentially more efficient.
See also: set_postcomments/2
, set_precomments/2
.
-spec revert(syntaxTree()) -> syntaxTree().
Returns an erl_parse
-compatible representation of a syntax tree, if possible.
If Tree
represents a well-formed Erlang program or expression, the conversion
should work without problems. Typically, is_tree/1
yields true
if conversion
failed (i.e., the result is still an abstract syntax tree), and false
otherwise.
The is_tree/1
test is not completely foolproof. For a few special node types
(e.g. arity_qualifier
), if such a node occurs in a context where it is not
expected, it will be left unchanged as a non-reverted subtree of the result.
This can only happen if Tree
does not actually represent legal Erlang code.
See also: //stdlib/erl_parse, revert_forms/1
.
Reverts a sequence of Erlang source code forms. The sequence can be given either
as a form_list
syntax tree (possibly nested), or as a list of "program form"
syntax trees. If successful, the corresponding flat list of
erl_parse
-compatible syntax trees is returned (see revert/1
). If some
program form could not be reverted, {error, Form}
is thrown. Standalone
comments in the form sequence are discarded.
See also: form_list/1
, is_form/1
, revert/1
.
-spec set_ann(syntaxTree(), [term()]) -> syntaxTree().
Sets the list of user annotations of Node
to Annotations
.
See also: add_ann/2
, copy_ann/2
, get_ann/1
.
-spec set_attrs(syntaxTree(), syntaxTreeAttributes()) -> syntaxTree().
Sets the attributes of Node
to Attributes
.
See also: copy_attrs/2
, get_attrs/1
.
-spec set_pos(syntaxTree(), annotation_or_location()) -> syntaxTree().
Sets the position information of Node
to Pos
.
See also: copy_pos/2
, get_pos/1
.
-spec set_postcomments(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Sets the post-comments of Node
to Comments
. Comments
should be a possibly
empty list of abstract comments, in top-down textual order
See also: add_postcomments/2
, comment/2
, copy_comments/2
,
get_postcomments/1
, join_comments/2
, remove_comments/1
,
set_precomments/2
.
-spec set_precomments(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Sets the pre-comments of Node
to Comments
. Comments
should be a possibly
empty list of abstract comments, in top-down textual order.
See also: add_precomments/2
, comment/2
, copy_comments/2
,
get_precomments/1
, join_comments/2
, remove_comments/1
,
set_postcomments/2
.
-spec size_qualifier(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract size qualifier. The result represents "*Body*:*Size*
".
See also: size_qualifier_argument/1
, size_qualifier_body/1
.
-spec size_qualifier_argument(syntaxTree()) -> syntaxTree().
Returns the argument subtree (the size) of a size_qualifier
node.
See also: size_qualifier/2
.
-spec size_qualifier_body(syntaxTree()) -> syntaxTree().
Returns the body subtree of a size_qualifier
node.
See also: size_qualifier/2
.
-spec string(string()) -> syntaxTree().
Creates an abstract string literal. The result represents "*Text*"
(including
the surrounding double-quotes), where Text
corresponds to the sequence of
characters in Value
, but not representing a specific string literal.
For example, the result of string("x\ny")
represents any and all
of "x\ny"
, "x\12y"
, "x\012y"
and "x\^Jy"
; see char/1
.
See also: char/1
, is_string/2
, string_literal/1
, string_literal/2
,
string_value/1
.
-spec string_literal(syntaxTree()) -> nonempty_string().
Returns the literal string represented by a string
node. This includes
surrounding double-quote characters. Characters beyond 255 will be escaped.
See also: string/1
.
-spec string_literal(syntaxTree(), encoding()) -> nonempty_string().
Returns the literal string represented by a string
node. This includes
surrounding double-quote characters. Depending on the encoding characters beyond
255 will be escaped (latin1
) or copied as is (utf8
).
See also: string/1
.
-spec string_value(syntaxTree()) -> string().
Returns the value represented by a string
node.
See also: string/1
.
-spec subtrees(syntaxTree()) -> [[syntaxTree()]].
Returns the grouped list of all subtrees of a syntax tree. If Node
is a leaf
node (see is_leaf/1
), this is the empty list, otherwise the result is always a
nonempty list, containing the lists of subtrees of Node
, in left-to-right
order as they occur in the printed program text, and grouped by category. Often,
each group contains only a single subtree.
Depending on the type of Node
, the size of some groups may be variable (e.g.,
the group consisting of all the elements of a tuple), while others always
contain the same number of elements - usually exactly one (e.g., the group
containing the argument expression of a case-expression). Note, however, that
the exact structure of the returned list (for a given node type) should in
general not be depended upon, since it might be subject to change without
notice.
The function subtrees/1
and the constructor functions make_tree/2
and
update_tree/2
can be a great help if one wants to traverse a syntax tree,
visiting all its subtrees, but treat nodes of the tree in a uniform way in most
or all cases. Using these functions makes this simple, and also assures that
your code is not overly sensitive to extensions of the syntax tree data type,
because any node types not explicitly handled by your code can be left to a
default case.
For example:
postorder(F, Tree) ->
F(case subtrees(Tree) of
[] -> Tree;
List -> update_tree(Tree,
[[postorder(F, Subtree)
|| Subtree <- Group]
|| Group <- List])
end).
maps the function F
on Tree
and all its subtrees, doing a post-order
traversal of the syntax tree. (Note the use of update_tree/2
to preserve node
attributes.) For a simple function like:
f(Node) ->
case type(Node) of
atom -> atom("a_" ++ atom_name(Node));
_ -> Node
end.
the call postorder(fun f/1, Tree)
will yield a new representation of Tree
in
which all atom names have been extended with the prefix "a_", but nothing else
(including comments, annotations and line numbers) has been changed.
See also: copy_attrs/2
, is_leaf/1
, make_tree/2
, type/1
.
-spec text(string()) -> syntaxTree().
Creates an abstract piece of source code text. The result represents exactly the
sequence of characters in String
. This is useful in cases when one wants full
control of the resulting output, e.g., for the appearance of floating-point
numbers or macro definitions.
See also: text_string/1
.
-spec text_string(syntaxTree()) -> string().
Returns the character sequence represented by a text
node.
See also: text/1
.
Equivalent to tree(Type, []).
For special purposes only. Creates an abstract syntax tree node with type tag
Type
and associated data Data
.
This function and the related is_tree/1
and data/1
provide a uniform way to
extend the set of erl_parse
node types. The associated data is any term, whose
format may depend on the type tag.
Notes:
- Any nodes created outside of this module must have type tags distinct from
those currently defined by this module; see
type/1
for a complete list. - The type tag of a syntax tree node may also be used as a primary tag by the
erl_parse
representation; in that case, the selector functions for that node type must handle both the abstract syntax tree and theerl_parse
form. The functiontype(T)
should return the correct type tag regardless of the representation ofT
, so that the user sees no difference betweenerl_syntax
anderl_parse
nodes.
-spec try_after_expr([syntaxTree()], [syntaxTree()]) -> syntaxTree().
Equivalent to try_expr(Body, [], [], After).
-spec try_expr([syntaxTree()], [syntaxTree()]) -> syntaxTree().
Equivalent to try_expr(Body, [], Handlers).
-spec try_expr([syntaxTree()], [syntaxTree()], [syntaxTree()]) -> syntaxTree().
Equivalent to try_expr(Body, Clauses, Handlers, []).
-spec try_expr([syntaxTree()], [syntaxTree()], [syntaxTree()], [syntaxTree()]) -> syntaxTree().
Creates an abstract try-expression. If Body
is [B1, ..., Bn]
, Clauses
is
[C1, ..., Cj]
, Handlers
is [H1, ..., Hk]
, and After
is [A1, ..., Am]
,
the result represents
"try *B1*, ..., *Bn* of *C1*; ...; *Cj* catch *H1*; ...; *Hk* after *A1*, ..., *Am* end
".
More exactly, if each Ci
represents "(*CPi*) *CGi* -> *CBi*
", and each Hi
represents "(*HPi*) *HGi* -> *HBi*
", then the result represents
"try *B1*, ..., *Bn* of *CP1**CG1* -> *CB1*; ...; *CPj**CGj* -> *CBj* catch *HP1**HG1* -> *HB1*; ...; *HPk**HGk* -> *HBk* after *A1*, ..., *Am* end
";
see case_expr/2
. If Clauses
is the empty list, the of ...
section is left
out. If After
is the empty list, the after ...
section is left out. If
Handlers
is the empty list, and After
is nonempty, the catch ...
section
is left out.
See also: case_expr/2
, class_qualifier/2
, clause/3
, try_after_expr/2
,
try_expr/2
, try_expr/3
, try_expr_after/1
, try_expr_body/1
,
try_expr_clauses/1
, try_expr_handlers/1
.
-spec try_expr_after(syntaxTree()) -> [syntaxTree()].
Returns the list of "after" subtrees of a try_expr
node.
See also: try_expr/4
.
-spec try_expr_body(syntaxTree()) -> [syntaxTree()].
Returns the list of body subtrees of a try_expr
node.
See also: try_expr/4
.
-spec try_expr_clauses(syntaxTree()) -> [syntaxTree()].
Returns the list of case-clause subtrees of a try_expr
node. If Node
represents "try *Body* catch *H1*; ...; *Hn* end
", the result is the empty
list.
See also: try_expr/4
.
-spec try_expr_handlers(syntaxTree()) -> [syntaxTree()].
Returns the list of handler-clause subtrees of a try_expr
node.
See also: try_expr/4
.
-spec tuple([syntaxTree()]) -> syntaxTree().
Creates an abstract tuple. If Elements
is [X1, ..., Xn]
, the result
represents "{*X1*, ..., *Xn*}
".
Note: The Erlang language has distinct 1-tuples, i.e., {X}
is always distinct
from X
itself.
See also: tuple_elements/1
, tuple_size/1
.
-spec tuple_elements(syntaxTree()) -> [syntaxTree()].
Returns the list of element subtrees of a tuple
node.
See also: tuple/1
.
-spec tuple_size(syntaxTree()) -> non_neg_integer().
Returns the number of elements of a tuple
node.
Note: this is equivalent to length(tuple_elements(Node))
, but
potentially more efficient.
See also: tuple/1
, tuple_elements/1
.
-spec tuple_type() -> syntaxTree().
Equivalent to tuple_type(any_size).
-spec tuple_type(any_size | [syntaxTree()]) -> syntaxTree().
Creates an abstract type tuple. If Elements
is [T1, ..., Tn]
, the result
represents "{*T1*, ..., *Tn*}
"; otherwise, if Elements
is any_size
, it
represents "tuple/0
".
See also: tuple_type_elements/1
.
-spec tuple_type_elements(syntaxTree()) -> any_size | [syntaxTree()].
Returns the list of type element subtrees of a tuple_type
node. If Node
represents "tuple/0
", any_size
is returned; otherwise, if Node
represents "{*T1*, ..., *Tn*}
", [T1, ..., Tn]
is returned.
See also: tuple_type/0
, tuple_type/1
.
-spec type(syntaxTree()) -> atom().
Returns the type tag of Node
. If Node
does not represent a syntax tree,
evaluation fails with reason badarg
. Node types currently defined by this
module are:
application | annotated_type | arity_qualifier | atom | |||
attribute | binary | binary_field | bitstring_type | |||
block_expr | case_expr | catch_expr | char | |||
class_qualifier | clause | comment | conjunction | |||
constrained_function_type | constraint | disjunction | ||||
else_expr | eof_marker | error_marker | ||||
float | form_list | fun_expr | fun_type | function | function_type | generator |
if_expr | implicit_fun | infix_expr | integer | |||
integer_range_type | list | list_comp | macro | |||
map_expr | map_field_assoc | map_field_exact | map_type | |||
map_type_assoc | map_type_exact | match_expr | ||||
maybe_expr | maybe_match_expr | module_qualifier | ||||
named_fun_expr | nil | operator | parentheses | |||
prefix_expr | receive_expr | record_access | record_expr | |||
record_field | record_index_expr | record_type | record_type_field | |||
size_qualifier | string | text | try_expr | |||
tuple | tuple_type | typed_record_field | type_application | |||
type_union | underscore | user_type_application | variable | |||
warning_marker |
The user may (for special purposes) create additional nodes with other type
tags, using the tree/2
function.
Note: The primary constructor functions for a node type should always have the same name as the node type itself.
See also: annotated_type/2
, application/3
, arity_qualifier/2
, atom/1
,
attribute/2
, binary/1
, binary_field/2
, bitstring_type/2
, block_expr/1
,
case_expr/2
, catch_expr/1
, char/1
, class_qualifier/2
, clause/3
,
comment/2
, conjunction/1
, constrained_function_type/2
, constraint/2
,
disjunction/1
, else_expr/1
, eof_marker/0
, error_marker/1
, float/1
,
form_list/1
, fun_expr/1
, fun_type/0
, function/2
, function_type/1
,
function_type/2
, generator/2
, if_expr/1
, implicit_fun/2
, infix_expr/3
,
integer/1
, integer_range_type/2
, list/2
, list_comp/2
, macro/2
,
map_expr/2
, map_field_assoc/2
, map_field_exact/2
, map_type/0
,
map_type/1
, map_type_assoc/2
, map_type_exact/2
, match_expr/2
,
maybe_expr/1
, maybe_expr/2
, maybe_match_expr/2
, module_qualifier/2
,
named_fun_expr/2
, nil/0
, operator/1
, parentheses/1
, prefix_expr/2
,
receive_expr/3
, record_access/3
, record_expr/2
, record_field/2
,
record_index_expr/2
, record_type/2
, record_type_field/2
,
size_qualifier/2
, string/1
, text/1
, tree/2
, try_expr/3
, tuple/1
,
tuple_type/0
, tuple_type/1
, type_application/2
, type_union/1
,
typed_record_field/2
, underscore/0
, user_type_application/2
, variable/1
,
warning_marker/1
.
-spec type_application(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract type application expression. If Arguments
is
[T1, ..., Tn]
, the result represents "*TypeName*(*T1*, ...*Tn*)
".
See also: type_application/3
, type_application_arguments/1
,
type_application_name/1
, user_type_application/2
.
-spec type_application(none | syntaxTree(), syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract type application expression. If Module
is none
, this is
call is equivalent to
type_application(TypeName, Arguments)
, otherwise it is
equivalent to
type_application(module_qualifier(Module, TypeName), Arguments)
.
(This is a utility function.)
See also: module_qualifier/2
, type_application/2
.
-spec type_application_arguments(syntaxTree()) -> [syntaxTree()].
Returns the arguments subtrees of a type_application
node.
See also: type_application/2
.
-spec type_application_name(syntaxTree()) -> syntaxTree().
Returns the type name subtree of a type_application
node.
See also: type_application/2
.
-spec type_union([syntaxTree()]) -> syntaxTree().
Creates an abstract type union. If Types
is [T1, ..., Tn]
, the result
represents "*T1* | ... | *Tn*
".
See also: type_union_types/1
.
-spec type_union_types(syntaxTree()) -> [syntaxTree()].
Returns the list of type subtrees of a type_union
node.
See also: type_union/1
.
-spec typed_record_field(syntaxTree(), syntaxTree()) -> syntaxTree().
Creates an abstract typed record field specification. The result represents
"*Field* :: *Type*
".
See also: typed_record_field_body/1
, typed_record_field_type/1
.
-spec typed_record_field_body(syntaxTree()) -> syntaxTree().
Returns the field subtree of a typed_record_field
node.
See also: typed_record_field/2
.
-spec typed_record_field_type(syntaxTree()) -> syntaxTree().
Returns the type subtree of a typed_record_field
node.
See also: typed_record_field/2
.
-spec underscore() -> syntaxTree().
Creates an abstract universal pattern ("_
"). The lexical representation is a
single underscore character. Note that this is not a variable, lexically
speaking.
See also: variable/1
.
-spec update_tree(syntaxTree(), [[syntaxTree()]]) -> syntaxTree().
Creates a syntax tree with the same type and attributes as the given tree. This
is equivalent to
copy_attrs(Node, make_tree(type(Node), Groups))
.
See also: copy_attrs/2
, make_tree/2
, type/1
.
-spec user_type_application(syntaxTree(), [syntaxTree()]) -> syntaxTree().
Creates an abstract user type. If Arguments
is [T1, ..., Tn]
, the result
represents "*TypeName*(*T1*, ...*Tn*)
".
See also: type_application/2
, user_type_application_arguments/1
,
user_type_application_name/1
.
-spec user_type_application_arguments(syntaxTree()) -> [syntaxTree()].
Returns the arguments subtrees of a user_type_application
node.
See also: user_type_application/2
.
-spec user_type_application_name(syntaxTree()) -> syntaxTree().
Returns the type name subtree of a user_type_application
node.
See also: user_type_application/2
.
-spec variable(atom() | string()) -> syntaxTree().
Creates an abstract variable with the given name. Name
may be any atom or
string that represents a lexically valid variable name, but not a single
underscore character; see underscore/0
.
Note: no checking is done whether the character sequence represents a proper variable name, i.e., whether or not its first character is an uppercase Erlang character, or whether it does not contain control characters, whitespace, etc.
See also: underscore/0
, variable_literal/1
, variable_name/1
.
-spec variable_literal(syntaxTree()) -> string().
Returns the name of a variable
node as a string.
See also: variable/1
.
-spec variable_name(syntaxTree()) -> atom().
Returns the name of a variable
node as an atom.
See also: variable/1
.
-spec warning_marker(term()) -> syntaxTree().
Creates an abstract warning marker. The result represents an occurrence of a
possible problem in the source code, with an associated Erlang I/O ErrorInfo
structure given by Error
(see module //stdlib/io
for details).
Warning markers are regarded as source code forms, but have no defined lexical
form.
Note: this is supported only for backwards compatibility with existing parsers and tools.
See also: eof_marker/0
, error_marker/1
, is_form/1
,
warning_marker_info/1
.
-spec warning_marker_info(syntaxTree()) -> term().
Returns the ErrorInfo structure of a warning_marker
node.
See also: warning_marker/1
.