erl_syntax — syntax_tools v3.2

Search documentation of syntax_tools

# 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

## Types

annotation_or_location()
encoding()
erl_parse()
forms()
guard()
padding()
syntaxTree()
syntaxTreeAttributes()
tree()
wrapper()

## Functions

nil()

Creates an abstract empty list. The result represents "`[]`". The empty list is traditionally called "nil".

abstract/1

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.

add_ann(A, Node)

Appends the term `Annotation` to the list of user annotations of `Node`.

add_postcomments(Cs, Node)

Appends `Comments` to the post-comments of `Node`.

add_precomments(Cs, Node)

Appends `Comments` to the pre-comments of `Node`.

annotated_type(Name, Type)

Creates an abstract annotated type expression. The result represents "`*Name* :: *Type*`".

annotated_type_body(Node)

Returns the type subtrees of an `annotated_type` node.

annotated_type_name(Node)

Returns the name subtree of an `annotated_type` node.

application(Operator, Arguments)

Creates an abstract function application expression. If `Arguments` is `[A1, ..., An]`, the result represents "`*Operator*(*A1*, ..., *An*)`".

application/3

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)`.

application_arguments(Node)

Returns the list of argument subtrees of an `application` node.

application_operator(Node)

Returns the operator subtree of an `application` node.

arity_qualifier(Body, Arity)

Creates an abstract arity qualifier. The result represents "`*Body*/*Arity*`".

arity_qualifier_argument(Node)

Returns the argument (the arity) subtree of an `arity_qualifier` node.

arity_qualifier_body(Node)

Returns the body subtree of an `arity_qualifier` node.

atom/1

Creates an abstract atom literal. The print name of the atom is the character sequence represented by `Name`.

atom_literal(Node)

Returns the literal string represented by an `atom` node. This includes surrounding single-quote characters if necessary. Characters beyond 255 will be escaped.

atom_literal/2

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`).

atom_name(Node)

Returns the printname of an `atom` node.

atom_value(Node)

Returns the value represented by an `atom` node.

attribute(Name)

Equivalent to attribute(Name, none).

attribute(Name, Args)

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.

attribute_arguments(Node)

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.

attribute_name(Node)

Returns the name subtree of an `attribute` node.

binary(List)

Creates an abstract binary-object template. If `Fields` is `[F1, ..., Fn]`, the result represents "`<<*F1*, ..., *Fn*>>`".

binary_comp(Template, Body)

Creates an abstract binary comprehension. If `Body` is `[E1, ..., En]`, the result represents "`<<*Template* || *E1*, ..., *En*>>`".

binary_comp_body(Node)

Returns the list of body subtrees of a `binary_comp` node.

binary_comp_template(Node)

Returns the template subtree of a `binary_comp` node.

binary_field(Body)

Equivalent to binary_field(Body, []).

binary_field(Body, Types)

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*`".

binary_field/3

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)`".

binary_field_body(Node)

Returns the body subtree of a `binary_field`.

binary_field_size(Node)

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.

binary_field_types(Node)

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.

binary_fields(Node)

Returns the list of field subtrees of a `binary` node.

binary_generator(Pattern, Body)

Creates an abstract binary_generator. The result represents "`*Pattern*<- *Body*`".

binary_generator_body(Node)

Returns the body subtree of a `generator` node.

binary_generator_pattern(Node)

Returns the pattern subtree of a `generator` node.

bitstring_type(M, N)

Creates an abstract bitstring type. The result represents "`*<<_:M, _:_*N>>*`".

bitstring_type_m(Node)

Returns the number of start bits, `M`, of a `bitstring_type` node.

bitstring_type_n(Node)

Returns the segment size, `N`, of a `bitstring_type` node.

block_expr(Body)

Creates an abstract block expression. If `Body` is `[B1, ..., Bn]`, the result represents "`begin *B1*, ..., *Bn* end`".

block_expr_body(Node)

Returns the list of body subtrees of a `block_expr` node.

case_expr(Argument, Clauses)

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`".

case_expr_argument(Node)

Returns the argument subtree of a `case_expr` node.

case_expr_clauses(Node)

Returns the list of clause subtrees of a `case_expr` node.

catch_expr(Expr)

Creates an abstract catch-expression. The result represents "`catch *Expr*`".

catch_expr_body(Node)

Returns the body subtree of a `catch_expr` node.

char(Char)

Creates an abstract character literal. The result represents "`$*Name*`", where `Name` corresponds to `Value`.

char_literal(Node)

Returns the literal string represented by a `char` node. This includes the leading "`$`" character. Characters beyond 255 will be escaped.

char_literal/2

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`).

char_value(Node)

Returns the value represented by a `char` node.

class_qualifier(Class, Body)

Creates an abstract class qualifier. The result represents "`*Class*:*Body*`".

class_qualifier(Class, Body, Stacktrace)

Creates an abstract class qualifier. The result represents "`*Class*:*Body*:*Stacktrace*`".

class_qualifier_argument(Node)

Returns the argument (the class) subtree of a `class_qualifier` node.

class_qualifier_body(Node)

Returns the body subtree of a `class_qualifier` node.

class_qualifier_stacktrace(Node)

Returns the stacktrace subtree of a `class_qualifier` node.

clause(Guard, Body)

Equivalent to clause([], Guard, Body).

clause(Patterns, 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*`".

clause_body(Node)

Return the list of body subtrees of a `clause` node.

clause_guard(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`.

clause_patterns(Node)

Returns the list of pattern subtrees of a `clause` node.

comment(Strings)

Equivalent to comment(none, Strings).

comment(Pad, 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

comment_padding(Node)

Returns the amount of padding before the comment, or `none`. The latter means that a default padding may be used.

comment_text(Node)

Returns the lines of text of the abstract comment.

compact_list(Node)

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.

concrete(Node)

Returns the Erlang term represented by a syntax tree. Evaluation fails with reason `badarg` if `Node` does not represent a literal term.

conjunction(Tests)

Creates an abstract conjunction. If `List` is `[E1, ..., En]`, the result represents "`*E1*, ..., *En*`".

conjunction_body(Node)

Returns the list of body subtrees of a `conjunction` node.

cons(Head, Tail)

"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.

constrained_function_type(FunctionType, FunctionConstraint)

Creates an abstract constrained function type. If `FunctionConstraint` is `[C1, ..., Cn]`, the result represents "`*FunctionType* when *C1*, ...*Cn*`".

constrained_function_type_argument(Node)

Returns the function constraint subtree of a `constrained_function_type` node.

constrained_function_type_body(Node)

Returns the function type subtree of a `constrained_function_type` node.

constraint(Name, Types)

Creates an abstract (subtype) constraint. The result represents "`*Name* :: *Type*`".

constraint_argument(Node)

Returns the name subtree of a `constraint` node.

constraint_body(Node)

Returns the type subtree of a `constraint` node.

copy_ann(Source, Target)

Copies the list of user annotations from `Source` to `Target`.

copy_attrs(S, T)

Copies the attributes from `Source` to `Target`.

copy_comments(Source, Target)

Copies the pre- and postcomments from `Source` to `Target`.

copy_pos(Source, Target)

Copies the annotation from `Source` to `Target`.

data/1

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`.

disjunction(Tests)

Creates an abstract disjunction. If `List` is `[E1, ..., En]`, the result represents "`*E1*; ...; *En*`".

disjunction_body(Node)

Returns the list of body subtrees of a `disjunction` node.

else_expr(Clauses)

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`".

else_expr_clauses(Node)

Returns the list of clause subtrees of an `else_expr` node.

eof_marker()

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.

error_marker(Error)

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.

error_marker_info(Node)

Returns the ErrorInfo structure of an `error_marker` node.

flatten_form_list(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.

float(Value)

Creates an abstract floating-point literal. The lexical representation is the decimal floating-point numeral of `Value`.

float_literal(Node)

Returns the numeral string represented by a `float` node.

float_value(Node)

Returns the value represented by a `float` node. Note that floating-point values should usually not be compared for equality.

form_list(Forms)

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

form_list_elements(Node)

Returns the list of subnodes of a `form_list` node.

fun_expr(Clauses)

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`".

fun_expr_arity(Node)

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.

fun_expr_clauses(Node)

Returns the list of clause subtrees of a `fun_expr` node.

fun_type()

Creates an abstract fun of any type. The result represents "`fun()`".

function(Name, Clauses)

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.

function_arity(Node)

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.

function_clauses(Node)

Returns the list of clause subtrees of a `function` node.

function_name(Node)

Returns the name subtree of a `function` node.

function_type(Type)

Equivalent to function_type(any_arity, Type).

function_type(Arguments, Return)

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*)`".

function_type_arguments(Node)

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.

function_type_return(Node)

Returns the return type subtrees of a `function_type` node.

generator(Pattern, Body)

Creates an abstract generator. The result represents "`*Pattern*<- *Body*`".

generator_body(Node)

Returns the body subtree of a `generator` node.

generator_pattern(Node)

Returns the pattern subtree of a `generator` node.

get_ann/1

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.

get_attrs/1

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`).

get_pos/1

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.

get_postcomments/1

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

get_precomments/1

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

has_comments/1

Yields `false` if the node has no associated comments, and `true` otherwise.

if_expr(Clauses)

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`".

if_expr_clauses(Node)

Returns the list of clause subtrees of an `if_expr` node.

implicit_fun(Name)

Creates an abstract "implicit fun" expression. The result represents "`fun *Name*`". `Name` should represent either `*F*/*A*` or `*M*:*F*/*A*`

implicit_fun/2

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))`.

implicit_fun/3

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))`.

implicit_fun_name(Node)

Returns the name subtree of an `implicit_fun` node.

infix_expr(Left, Operator, Right)

Creates an abstract infix operator expression. The result represents "`*Left**Operator**Right*`".

infix_expr_left(Node)

Returns the left argument subtree of an `infix_expr` node.

infix_expr_operator(Node)

Returns the operator subtree of an `infix_expr` node.

infix_expr_right(Node)

Returns the right argument subtree of an `infix_expr` node.

integer(Value)

Creates an abstract integer literal. The lexical representation is the canonical decimal numeral of `Value`.

integer_literal(Node)

Returns the numeral string represented by an `integer` node.

integer_range_type(Low, High)

Creates an abstract range type. The result represents "`*Low* .. *High*`".

integer_range_type_high(Node)

Returns the high limit of an `integer_range_type` node.

integer_range_type_low(Node)

Returns the low limit of an `integer_range_type` node.

integer_value(Node)

Returns the value represented by an `integer` node.

is_atom(Node, Value)

Returns `true` if `Node` has type `atom` and represents `Value`, otherwise `false`.

is_char(Node, Value)

Returns `true` if `Node` has type `char` and represents `Value`, otherwise `false`.

is_form(Node)

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

is_integer(Node, Value)

Returns `true` if `Node` has type `integer` and represents `Value`, otherwise `false`.

is_leaf(Node)

Returns `true` if `Node` is a leaf node, otherwise `false`. The currently recognised leaf node types are

is_list_skeleton(Node)

Returns `true` if `Node` has type `list` or `nil`, otherwise `false`.

is_literal(T)

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.

is_proper_list(Node)

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.

is_string(Node, Value)

Returns `true` if `Node` has type `string` and represents `Value`, otherwise `false`.

is_tree/1

For special purposes only. Returns `true` if `Tree` is an abstract syntax tree and `false` otherwise.

join_comments(Source, Target)

Appends the comments of `Source` to the current comments of `Target`.

list(List)

Equivalent to list(List, none).

list/2

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`).

list_comp(Template, Body)

Creates an abstract list comprehension. If `Body` is `[E1, ..., En]`, the result represents "`[*Template* || *E1*, ..., *En*]`".

list_comp_body(Node)

Returns the list of body subtrees of a `list_comp` node.

list_comp_template(Node)

Returns the template subtree of a `list_comp` node.

list_elements(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]`.

list_head(Node)

Returns the head element subtree of a `list` node. If `Node` represents "`[*Head* ...]`", the result will represent "`*Head*`".

list_length(Node)

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.

list_prefix(Node)

Returns the prefix element subtrees of a `list` node. If `Node` represents "`[*E1*, ..., *En*]`" or "`[*E1*, ..., *En* | *Tail*]`", the returned value is `[E1, ..., En]`.

list_suffix(Node)

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.

list_tail(Node)

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*`".

macro(Name)

Equivalent to macro(Name, none).

macro(Name, Arguments)

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*)`".

macro_arguments(Node)

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.

macro_name(Node)

Returns the name subtree of a `macro` node.

make_tree/2

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`.

map_comp(Template, Body)

Creates an abstract map comprehension. If `Body` is `[E1, ..., En]`, the result represents "`#{*Template* || *E1*, ..., *En*}`".

map_comp_body(Node)

Returns the list of body subtrees of a `map_comp` node.

map_comp_template(Node)

Returns the template subtree of a `map_comp` node.

map_expr(Fields)

Equivalent to map_expr(none, Fields).

map_expr(Argument, 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*}`".

map_expr_argument(Node)

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.

map_expr_fields(Node)

Returns the list of field subtrees of a `map_expr` node.

map_field_assoc(Name, Value)

Creates an abstract map assoc field. The result represents "`*Name* => *Value*`".

map_field_assoc_name(Node)

Returns the name subtree of a `map_field_assoc` node.

map_field_assoc_value(Node)

Returns the value subtree of a `map_field_assoc` node.

map_field_exact(Name, Value)

Creates an abstract map exact field. The result represents "`*Name* := *Value*`".

map_field_exact_name(Node)

Returns the name subtree of a `map_field_exact` node.

map_field_exact_value(Node)

Returns the value subtree of a `map_field_exact` node.

map_generator(Pattern, Body)

Creates an abstract map_generator. The result represents "`*Pattern*<- *Body*`".

map_generator_body(Node)

Returns the body subtree of a `generator` node.

map_generator_pattern(Node)

Returns the pattern subtree of a `generator` node.

map_type()

Equivalent to map_type(any_size).

map_type(Fields)

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`".

map_type_assoc(Name, Value)

Creates an abstract map type assoc field. The result represents "`*Name* => *Value*`".

map_type_assoc_name(Node)

Returns the name subtree of a `map_type_assoc` node.

map_type_assoc_value(Node)

Returns the value subtree of a `map_type_assoc` node.

map_type_exact(Name, Value)

Creates an abstract map type exact field. The result represents "`*Name* := *Value*`".

map_type_exact_name(Node)

Returns the name subtree of a `map_type_exact` node.

map_type_exact_value(Node)

Returns the value subtree of a `map_type_exact` node.

map_type_fields(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.

match_expr(Pattern, Body)

Creates an abstract match-expression. The result represents "`*Pattern* = *Body*`".

match_expr_body(Node)

Returns the body subtree of a `match_expr` node.

match_expr_pattern(Node)

Returns the pattern subtree of a `match_expr` node.

maybe_expr(Body)

Equivalent to maybe_expr(Body, none).

maybe_expr(Body, OptionalElse)

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`".

maybe_expr_body(Node)

Returns the list of body subtrees of a `maybe_expr` node.

maybe_expr_else(Node)

Returns the else subtree of a `maybe_expr` node.

maybe_match_expr(Pattern, Body)

Creates an abstract maybe-expression, as used in `maybe` blocks. The result represents "`*Pattern* ?= *Body*`".

maybe_match_expr_body(Node)

Returns the body subtree of a `maybe_expr` node.

maybe_match_expr_pattern(Node)

Returns the pattern subtree of a `maybe_expr` node.

meta(T)

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.

module_qualifier(Module, Body)

Creates an abstract module qualifier. The result represents "`*Module*:*Body*`".

module_qualifier_argument(Node)

Returns the argument (the module) subtree of a `module_qualifier` node.

module_qualifier_body(Node)

Returns the body subtree of a `module_qualifier` node.

named_fun_expr(Name, Clauses)

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`".

named_fun_expr_arity(Node)

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.

named_fun_expr_clauses(Node)

Returns the list of clause subtrees of a `named_fun_expr` node.

named_fun_expr_name(Node)

Returns the name subtree of a `named_fun_expr` node.

normalize_list(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.

operator/1

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 "`'++'`".

operator_literal(Node)

Returns the literal string represented by an `operator` node. This is simply the operator name as a string.

operator_name(Node)

Returns the name of an `operator` node. Note that the name is returned as an atom.

parentheses(Expr)

Creates an abstract parenthesised expression. The result represents "`(*Body*)`", independently of the context.

parentheses_body(Node)

Returns the body subtree of a `parentheses` node.

prefix_expr(Operator, Argument)

Creates an abstract prefix operator expression. The result represents "`*Operator**Argument*`".

prefix_expr_argument(Node)

Returns the argument subtree of a `prefix_expr` node.

prefix_expr_operator(Node)

Returns the operator subtree of a `prefix_expr` node.

receive_expr(Clauses)

Equivalent to receive_expr(Clauses, none, []).

receive_expr(Clauses, Timeout, Action)

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`".

receive_expr_action(Node)

Returns the list of action body subtrees of a `receive_expr` node. If `Node` represents "`receive *C1*; ...; *Cn* end`", this is the empty list.

receive_expr_clauses(Node)

Returns the list of clause subtrees of a `receive_expr` node.

receive_expr_timeout(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.

record_access(Argument, Type, Field)

Creates an abstract record field access expression. The result represents "`*Argument*#*Type*.*Field*`".

record_access_argument(Node)

Returns the argument subtree of a `record_access` node.

record_access_field(Node)

Returns the field subtree of a `record_access` node.

record_access_type(Node)

Returns the type subtree of a `record_access` node.

record_expr(Type, Fields)

Equivalent to record_expr(none, Type, Fields).

record_expr(Argument, 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*}`".

record_expr_argument(Node)

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.

record_expr_fields(Node)

Returns the list of field subtrees of a `record_expr` node.

record_expr_type(Node)

Returns the type subtree of a `record_expr` node.

record_field(Name)

Equivalent to record_field(Name, none).

record_field(Name, Value)

Creates an abstract record field specification. If `Value` is `none`, the result represents simply "`*Name*`", otherwise it represents "`*Name* = *Value*`".

record_field_name(Node)

Returns the name subtree of a `record_field` node.

record_field_value(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.

record_index_expr(Type, Field)

Creates an abstract record field index expression. The result represents "`#*Type*.*Field*`".

record_index_expr_field(Node)

Returns the field subtree of a `record_index_expr` node.

record_index_expr_type(Node)

Returns the type subtree of a `record_index_expr` node.

record_type(Name, Fields)

Creates an abstract record type. If `Fields` is `[F1, ..., Fn]`, the result represents "`#*Name*{*F1*, ..., *Fn*}`".

record_type_field(Name, Type)

Creates an abstract record type field. The result represents "`*Name* :: *Type*`".

record_type_field_name(Node)

Returns the name subtree of a `record_type_field` node.

record_type_field_type(Node)

Returns the type subtree of a `record_type_field` node.

record_type_fields(Node)

Returns the fields subtree of a `record_type` node.

record_type_name(Node)

Returns the name subtree of a `record_type` node.

remove_comments(Node)

Clears the associated comments of `Node`.

revert(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.

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.

set_ann(Node, As)

Sets the list of user annotations of `Node` to `Annotations`.

set_attrs(Node, Attr)

Sets the attributes of `Node` to `Attributes`.

set_pos(Node, Pos)

Sets the position information of `Node` to `Pos`.

set_postcomments(Node, Cs)

Sets the post-comments of `Node` to `Comments`. `Comments` should be a possibly empty list of abstract comments, in top-down textual order

set_precomments(Node, Cs)

Sets the pre-comments of `Node` to `Comments`. `Comments` should be a possibly empty list of abstract comments, in top-down textual order.

size_qualifier(Body, Size)

Creates an abstract size qualifier. The result represents "`*Body*:*Size*`".

size_qualifier_argument(Node)

Returns the argument subtree (the size) of a `size_qualifier` node.

size_qualifier_body(Node)

Returns the body subtree of a `size_qualifier` node.

string(String)

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.

string_literal(Node)

Returns the literal string represented by a `string` node. This includes surrounding double-quote characters. Characters beyond 255 will be escaped.

string_literal/2

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`).

string_value(Node)

Returns the value represented by a `string` node.

subtrees(T)

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.

text(String)

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.

text_string(Node)

Returns the character sequence represented by a `text` node.

tree(Type)

Equivalent to tree(Type, []).

tree(Type, Data)

For special purposes only. Creates an abstract syntax tree node with type tag `Type` and associated data `Data`.

try_after_expr(Body, After)

Equivalent to try_expr(Body, [], [], After).

try_expr(Body, Handlers)

Equivalent to try_expr(Body, [], Handlers).

try_expr(Body, Clauses, Handlers)

Equivalent to try_expr(Body, Clauses, Handlers, []).

try_expr(Body, Clauses, Handlers, After)

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.

try_expr_after(Node)

Returns the list of "after" subtrees of a `try_expr` node.

try_expr_body(Node)

Returns the list of body subtrees of a `try_expr` node.

try_expr_clauses(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.

try_expr_handlers(Node)

Returns the list of handler-clause subtrees of a `try_expr` node.

tuple(List)

Creates an abstract tuple. If `Elements` is `[X1, ..., Xn]`, the result represents "`{*X1*, ..., *Xn*}`".

tuple_elements(Node)

Returns the list of element subtrees of a `tuple` node.

tuple_size(Node)

Returns the number of elements of a `tuple` node.

tuple_type()

Equivalent to tuple_type(any_size).

tuple_type(Elements)

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`".

tuple_type_elements(Node)

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.

type/1

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

type_application(TypeName, Arguments)

Creates an abstract type application expression. If `Arguments` is `[T1, ..., Tn]`, the result represents "`*TypeName*(*T1*, ...*Tn*)`".

type_application/3

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)`.

type_application_arguments(Node)

Returns the arguments subtrees of a `type_application` node.

type_application_name(Node)

Returns the type name subtree of a `type_application` node.

type_union(Types)

Creates an abstract type union. If `Types` is `[T1, ..., Tn]`, the result represents "`*T1* | ... | *Tn*`".

type_union_types(Node)

Returns the list of type subtrees of a `type_union` node.

typed_record_field(Field, Type)

Creates an abstract typed record field specification. The result represents "`*Field* :: *Type*`".

typed_record_field_body(Node)

Returns the field subtree of a `typed_record_field` node.

typed_record_field_type(Node)

Returns the type subtree of a `typed_record_field` node.

underscore()

Creates an abstract universal pattern ("`_`"). The lexical representation is a single underscore character. Note that this is not a variable, lexically speaking.

update_tree(Node, Groups)

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))`.

user_type_application(TypeName, Arguments)

Creates an abstract user type. If `Arguments` is `[T1, ..., Tn]`, the result represents "`*TypeName*(*T1*, ...*Tn*)`".

user_type_application_arguments(Node)

Returns the arguments subtrees of a `user_type_application` node.

user_type_application_name(Node)

Returns the type name subtree of a `user_type_application` node.

variable/1

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`.

variable_literal(Node)

Returns the name of a `variable` node as a string.

variable_name(Node)

Returns the name of a `variable` node as an atom.

warning_marker(Warning)

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.

warning_marker_info(Node)

Returns the ErrorInfo structure of a `warning_marker` node.

# Types

Link to this type

# annotation_or_location()

View Source

    -type annotation_or_location() :: erl_anno:anno() | erl_anno:location().

Link to this type

# encoding()

View Source (not exported)

    -type encoding() :: utf8 | unicode | latin1.

Link to this type

# erl_parse()

View Source (not exported)

    -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().

Link to this type

# forms()

View Source

    -type forms() :: syntaxTree() | [syntaxTree()].

Link to this type

# guard()

View Source (not exported)

    -type guard() :: none | syntaxTree() | [syntaxTree()] | [[syntaxTree()]].

Link to this type

# padding()

View Source

    -type padding() :: none | integer().

Link to this type

# syntaxTree()

View Source

    -type syntaxTree() :: tree() | wrapper() | erl_parse().

Link to this type

# syntaxTreeAttributes()

View Source

    -type syntaxTreeAttributes() ::
              #attr{pos :: term(),
                    ann :: [term()],
                    com :: none | #com{pre :: [syntaxTree()], post :: [syntaxTree()]}}.

Link to this type

# tree()

View Source (not exported)

    -type tree() ::
              #tree{type :: atom(),
                    attr ::
                        #attr{pos :: term(),
                              ann :: [term()],
                              com :: none | #com{pre :: [syntaxTree()], post :: [syntaxTree()]}},
                    data :: term()}.

Link to this type

# wrapper()

View Source (not exported)

    -type wrapper() ::
              #wrapper{type :: atom(),
                       attr ::
                           #attr{pos :: term(),
                                 ann :: [term()],
                                 com :: none | #com{pre :: [syntaxTree()], post :: [syntaxTree()]}},
                       tree :: erl_parse()}.

# Functions

Link to this function

# nil()

View Source

    -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`.

Link to this function

# abstract/1

View Source

    -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`.

Link to this function

# add_ann(A, Node)

View Source

    -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.

See also: `get_ann/1`, `set_ann/2`.

Link to this function

# add_postcomments(Cs, Node)

View Source

    -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`.

Link to this function

# add_precomments(Cs, Node)

View Source

    -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`.

Link to this function

# annotated_type(Name, Type)

View Source

    -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`.

Link to this function

# annotated_type_body(Node)

View Source

    -spec annotated_type_body(syntaxTree()) -> syntaxTree().

Returns the type subtrees of an `annotated_type` node.

See also: `annotated_type/2`.

Link to this function

# annotated_type_name(Node)

View Source

    -spec annotated_type_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of an `annotated_type` node.

See also: `annotated_type/2`.

Link to this function

# application(Operator, Arguments)

View Source

    -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`.

Link to this function

# application/3

View Source

    -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`.

Link to this function

# application_arguments(Node)

View Source

    -spec application_arguments(syntaxTree()) -> [syntaxTree()].

Returns the list of argument subtrees of an `application` node.

See also: `application/2`.

Link to this function

# application_operator(Node)

View Source

    -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`.

Link to this function

# arity_qualifier(Body, Arity)

View Source

    -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`.

Link to this function

# arity_qualifier_argument(Node)

View Source

    -spec arity_qualifier_argument(syntaxTree()) -> syntaxTree().

Returns the argument (the arity) subtree of an `arity_qualifier` node.

See also: `arity_qualifier/2`.

Link to this function

# arity_qualifier_body(Node)

View Source

    -spec arity_qualifier_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of an `arity_qualifier` node.

See also: `arity_qualifier/2`.

Link to this function

# atom/1

View Source

    -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`.

Link to this function

# atom_literal(Node)

View Source

    -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`.

See also: `atom/1`, `string/1`.

Link to this function

# atom_literal/2

View Source

    -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`.

Link to this function

# atom_name(Node)

View Source

    -spec atom_name(syntaxTree()) -> string().

Returns the printname of an `atom` node.

See also: `atom/1`.

Link to this function

# atom_value(Node)

View Source

    -spec atom_value(syntaxTree()) -> atom().

Returns the value represented by an `atom` node.

See also: `atom/1`.

Link to this function

# attribute(Name)

View Source

    -spec attribute(syntaxTree()) -> syntaxTree().

Equivalent to attribute(Name, none).

Link to this function

# attribute(Name, Args)

View Source

    -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`.

Link to this function

# attribute_arguments(Node)

View Source

    -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`.

Link to this function

# attribute_name(Node)

View Source

    -spec attribute_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of an `attribute` node.

See also: `attribute/1`.

Link to this function

# binary(List)

View Source

    -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`.

Link to this function

# binary_comp(Template, Body)

View Source

    -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`.

Link to this function

# binary_comp_body(Node)

View Source

    -spec binary_comp_body(syntaxTree()) -> [syntaxTree()].

Returns the list of body subtrees of a `binary_comp` node.

See also: `binary_comp/2`.

Link to this function

# binary_comp_template(Node)

View Source

    -spec binary_comp_template(syntaxTree()) -> syntaxTree().

Returns the template subtree of a `binary_comp` node.

See also: `binary_comp/2`.

Link to this function

# binary_field(Body)

View Source

    -spec binary_field(syntaxTree()) -> syntaxTree().

Equivalent to binary_field(Body, []).

Link to this function

# binary_field(Body, Types)

View Source

    -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`.

Link to this function

# binary_field/3

View Source

    -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`.

Link to this function

# binary_field_body(Node)

View Source

    -spec binary_field_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `binary_field`.

See also: `binary_field/2`.

Link to this function

# binary_field_size(Node)

View Source

    -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`.

Link to this function

# binary_field_types(Node)

View Source

    -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`.

Link to this function

# binary_fields(Node)

View Source

    -spec binary_fields(syntaxTree()) -> [syntaxTree()].

Returns the list of field subtrees of a `binary` node.

See also: `binary/1`, `binary_field/2`.

Link to this function

# binary_generator(Pattern, Body)

View Source

    -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`.

Link to this function

# binary_generator_body(Node)

View Source

    -spec binary_generator_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `generator` node.

See also: `binary_generator/2`.

Link to this function

# binary_generator_pattern(Node)

View Source

    -spec binary_generator_pattern(syntaxTree()) -> syntaxTree().

Returns the pattern subtree of a `generator` node.

See also: `binary_generator/2`.

Link to this function

# bitstring_type(M, N)

View Source

    -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`.

Link to this function

# bitstring_type_m(Node)

View Source

    -spec bitstring_type_m(syntaxTree()) -> syntaxTree().

Returns the number of start bits, `M`, of a `bitstring_type` node.

See also: `bitstring_type/2`.

Link to this function

# bitstring_type_n(Node)

View Source

    -spec bitstring_type_n(syntaxTree()) -> syntaxTree().

Returns the segment size, `N`, of a `bitstring_type` node.

See also: `bitstring_type/2`.

Link to this function

# block_expr(Body)

View Source

    -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`.

Link to this function

# block_expr_body(Node)

View Source

    -spec block_expr_body(syntaxTree()) -> [syntaxTree()].

Returns the list of body subtrees of a `block_expr` node.

See also: `block_expr/1`.

Link to this function

# case_expr(Argument, Clauses)

View Source

    -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`.

Link to this function

# case_expr_argument(Node)

View Source

    -spec case_expr_argument(syntaxTree()) -> syntaxTree().

Returns the argument subtree of a `case_expr` node.

See also: `case_expr/2`.

Link to this function

# case_expr_clauses(Node)

View Source

    -spec case_expr_clauses(syntaxTree()) -> [syntaxTree()].

Returns the list of clause subtrees of a `case_expr` node.

See also: `case_expr/2`.

Link to this function

# catch_expr(Expr)

View Source

    -spec catch_expr(syntaxTree()) -> syntaxTree().

Creates an abstract catch-expression. The result represents "`catch *Expr*`".

See also: `catch_expr_body/1`.

Link to this function

# catch_expr_body(Node)

View Source

    -spec catch_expr_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `catch_expr` node.

See also: `catch_expr/1`.

Link to this function

# char(Char)

View Source

    -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`.

Link to this function

# char_literal(Node)

View Source

    -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`.

Link to this function

# char_literal/2

View Source

    -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`.

Link to this function

# char_value(Node)

View Source

    -spec char_value(syntaxTree()) -> char().

Returns the value represented by a `char` node.

See also: `char/1`.

Link to this function

# class_qualifier(Class, Body)

View Source

    -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`.

Link to this function

# class_qualifier(Class, Body, Stacktrace)

View Source

    -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`.

Link to this function

# class_qualifier_argument(Node)

View Source

    -spec class_qualifier_argument(syntaxTree()) -> syntaxTree().

Returns the argument (the class) subtree of a `class_qualifier` node.

See also: `class_qualifier/2`.

Link to this function

# class_qualifier_body(Node)

View Source

    -spec class_qualifier_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `class_qualifier` node.

See also: `class_qualifier/2`.

Link to this function

# class_qualifier_stacktrace(Node)

View Source

    -spec class_qualifier_stacktrace(syntaxTree()) -> syntaxTree().

Returns the stacktrace subtree of a `class_qualifier` node.

See also: `class_qualifier/2`.

Link to this function

# clause(Guard, Body)

View Source

    -spec clause(guard(), [syntaxTree()]) -> syntaxTree().

Equivalent to clause([], Guard, Body).

Link to this function

# clause(Patterns, Guard, Body)

View Source

    -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 passing `none`.
- A nonempty list `[E1, ..., Ej]` of syntax trees. This is equivalent to passing `conjunction([E1, ..., Ej])`.
- A nonempty list of lists of syntax trees `[[E1_1, ..., E1_k1], ..., [Ej_1, ..., Ej_kj]]`, which is equivalent to passing `disjunction([conjunction([E1_1, ..., E1_k1]), ..., conjunction([Ej_1, ..., Ej_kj])])`.

See also: `clause/2`, `clause_body/1`, `clause_guard/1`, `clause_patterns/1`.

Link to this function

# clause_body(Node)

View Source

    -spec clause_body(syntaxTree()) -> [syntaxTree()].

Return the list of body subtrees of a `clause` node.

See also: `clause/3`.

Link to this function

# clause_guard(Node)

View Source

    -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`.

Link to this function

# clause_patterns(Node)

View Source

    -spec clause_patterns(syntaxTree()) -> [syntaxTree()].

Returns the list of pattern subtrees of a `clause` node.

See also: `clause/3`.

Link to this function

# comment(Strings)

View Source

    -spec comment([string()]) -> syntaxTree().

Equivalent to comment(none, Strings).

Link to this function

# comment(Pad, Strings)

View Source

    -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.

See also: `comment/1`, `is_form/1`.

Link to this function

# comment_padding(Node)

View Source

    -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`.

Link to this function

# comment_text(Node)

View Source

    -spec comment_text(syntaxTree()) -> [string()].

Returns the lines of text of the abstract comment.

See also: `comment/2`.

Link to this function

# compact_list(Node)

View Source

    -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`.

Link to this function

# concrete(Node)

View Source

    -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`.

Link to this function

# conjunction(Tests)

View Source

    -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`.

Link to this function

# conjunction_body(Node)

View Source

    -spec conjunction_body(syntaxTree()) -> [syntaxTree()].

Returns the list of body subtrees of a `conjunction` node.

See also: `conjunction/1`.

Link to this function

# cons(Head, Tail)

View Source

    -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`.

Link to this function

# constrained_function_type(FunctionType, FunctionConstraint)

View Source

    -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`.

Link to this function

# constrained_function_type_argument(Node)

View Source

    -spec constrained_function_type_argument(syntaxTree()) -> syntaxTree().

Returns the function constraint subtree of a `constrained_function_type` node.

See also: `constrained_function_type/2`.

Link to this function

# constrained_function_type_body(Node)

View Source

    -spec constrained_function_type_body(syntaxTree()) -> syntaxTree().

Returns the function type subtree of a `constrained_function_type` node.

See also: `constrained_function_type/2`.

Link to this function

# constraint(Name, Types)

View Source

    -spec constraint(syntaxTree(), [syntaxTree()]) -> syntaxTree().

Creates an abstract (subtype) constraint. The result represents "`*Name* :: *Type*`".

See also: `constraint_argument/1`, `constraint_body/1`.

Link to this function

# constraint_argument(Node)

View Source

    -spec constraint_argument(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `constraint` node.

See also: `constraint/2`.

Link to this function

# constraint_body(Node)

View Source

    -spec constraint_body(syntaxTree()) -> [syntaxTree()].

Returns the type subtree of a `constraint` node.

See also: `constraint/2`.

Link to this function

# copy_ann(Source, Target)

View Source

    -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.

See also: `get_ann/1`, `set_ann/2`.

Link to this function

# copy_attrs(S, T)

View Source

    -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`.

Link to this function

# copy_comments(Source, Target)

View Source

    -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`.

Link to this function

# copy_pos(Source, Target)

View Source

    -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.

See also: `get_pos/1`, `set_pos/2`.

Link to this function

# data/1

View Source

    -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`.

Link to this function

# disjunction(Tests)

View Source

    -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`.

Link to this function

# disjunction_body(Node)

View Source

    -spec disjunction_body(syntaxTree()) -> [syntaxTree()].

Returns the list of body subtrees of a `disjunction` node.

See also: `disjunction/1`.

Link to this function

# else_expr(Clauses)

View Source

    -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`.

Link to this function

# else_expr_clauses(Node)

View Source

    -spec else_expr_clauses(syntaxTree()) -> [syntaxTree()].

Returns the list of clause subtrees of an `else_expr` node.

See also: `else_expr/1`.

Link to this function

# eof_marker()

View Source

    -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`.

Link to this function

# error_marker(Error)

View Source

    -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`.

Link to this function

# error_marker_info(Node)

View Source

    -spec error_marker_info(syntaxTree()) -> term().

Returns the ErrorInfo structure of an `error_marker` node.

See also: `error_marker/1`.

Link to this function

# flatten_form_list(Node)

View Source

    -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`.

Link to this function

# float(Value)

View Source

    -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`.

Link to this function

# float_literal(Node)

View Source

    -spec float_literal(syntaxTree()) -> string().

Returns the numeral string represented by a `float` node.

See also: `float/1`.

Link to this function

# float_value(Node)

View Source

    -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`.

Link to this function

# form_list(Forms)

View Source

    -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`.

Link to this function

# form_list_elements(Node)

View Source

    -spec form_list_elements(syntaxTree()) -> [syntaxTree()].

Returns the list of subnodes of a `form_list` node.

See also: `form_list/1`.

Link to this function

# fun_expr(Clauses)

View Source

    -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`.

Link to this function

# fun_expr_arity(Node)

View Source

    -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`.

Link to this function

# fun_expr_clauses(Node)

View Source

    -spec fun_expr_clauses(syntaxTree()) -> [syntaxTree()].

Returns the list of clause subtrees of a `fun_expr` node.

See also: `fun_expr/1`.

Link to this function

# fun_type()

View Source

    -spec fun_type() -> syntaxTree().

Creates an abstract fun of any type. The result represents "`fun()`".

Link to this function

# function(Name, Clauses)

View Source

    -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`.

Link to this function

# function_arity(Node)

View Source

    -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`.

Link to this function

# function_clauses(Node)

View Source

    -spec function_clauses(syntaxTree()) -> [syntaxTree()].

Returns the list of clause subtrees of a `function` node.

See also: `function/2`.

Link to this function

# function_name(Node)

View Source

    -spec function_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `function` node.

See also: `function/2`.

Link to this function

# function_type(Type)

View Source

    -spec function_type(syntaxTree()) -> syntaxTree().

Equivalent to function_type(any_arity, Type).

Link to this function

# function_type(Arguments, Return)

View Source

    -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`.

Link to this function

# function_type_arguments(Node)

View Source

    -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`.

Link to this function

# function_type_return(Node)

View Source

    -spec function_type_return(syntaxTree()) -> syntaxTree().

Returns the return type subtrees of a `function_type` node.

See also: `function_type/1`, `function_type/2`.

Link to this function

# generator(Pattern, Body)

View Source

    -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`.

Link to this function

# generator_body(Node)

View Source

    -spec generator_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `generator` node.

See also: `generator/2`.

Link to this function

# generator_pattern(Node)

View Source

    -spec generator_pattern(syntaxTree()) -> syntaxTree().

Returns the pattern subtree of a `generator` node.

See also: `generator/2`.

Link to this function

# get_ann/1

View Source

    -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`.

Link to this function

# get_attrs/1

View Source

    -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`.

Link to this function

# get_pos/1

View Source

    -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`.

Link to this function

# get_postcomments/1

View Source

    -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`.

Link to this function

# get_precomments/1

View Source

    -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`.

Link to this function

# has_comments/1

View Source

    -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`.

Link to this function

# if_expr(Clauses)

View Source

    -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`.

Link to this function

# if_expr_clauses(Node)

View Source

    -spec if_expr_clauses(syntaxTree()) -> [syntaxTree()].

Returns the list of clause subtrees of an `if_expr` node.

See also: `if_expr/1`.

Link to this function

# implicit_fun(Name)

View Source

    -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`.

Link to this function

# implicit_fun/2

View Source

    -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`.

Link to this function

# implicit_fun/3

View Source

    -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`.

Link to this function

# implicit_fun_name(Node)

View Source

    -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`.

Link to this function

# infix_expr(Left, Operator, Right)

View Source

    -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`.

Link to this function

# infix_expr_left(Node)

View Source

    -spec infix_expr_left(syntaxTree()) -> syntaxTree().

Returns the left argument subtree of an `infix_expr` node.

See also: `infix_expr/3`.

Link to this function

# infix_expr_operator(Node)

View Source

    -spec infix_expr_operator(syntaxTree()) -> syntaxTree().

Returns the operator subtree of an `infix_expr` node.

See also: `infix_expr/3`.

Link to this function

# infix_expr_right(Node)

View Source

    -spec infix_expr_right(syntaxTree()) -> syntaxTree().

Returns the right argument subtree of an `infix_expr` node.

See also: `infix_expr/3`.

Link to this function

# integer(Value)

View Source

    -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`.

Link to this function

# integer_literal(Node)

View Source

    -spec integer_literal(syntaxTree()) -> string().

Returns the numeral string represented by an `integer` node.

See also: `integer/1`.

Link to this function

# integer_range_type(Low, High)

View Source

    -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`.

Link to this function

# integer_range_type_high(Node)

View Source

    -spec integer_range_type_high(syntaxTree()) -> syntaxTree().

Returns the high limit of an `integer_range_type` node.

See also: `integer_range_type/2`.

Link to this function

# integer_range_type_low(Node)

View Source

    -spec integer_range_type_low(syntaxTree()) -> syntaxTree().

Returns the low limit of an `integer_range_type` node.

See also: `integer_range_type/2`.

Link to this function

# integer_value(Node)

View Source

    -spec integer_value(syntaxTree()) -> integer().

Returns the value represented by an `integer` node.

See also: `integer/1`.

Link to this function

# is_atom(Node, Value)

View Source

    -spec is_atom(syntaxTree(), atom()) -> boolean().

Returns `true` if `Node` has type `atom` and represents `Value`, otherwise `false`.

See also: `atom/1`.

Link to this function

# is_char(Node, Value)

View Source

    -spec is_char(syntaxTree(), char()) -> boolean().

Returns `true` if `Node` has type `char` and represents `Value`, otherwise `false`.

See also: `char/1`.

Link to this function

# is_form(Node)

View Source

    -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`.

Link to this function

# is_integer(Node, Value)

View Source

    -spec is_integer(syntaxTree(), integer()) -> boolean().

Returns `true` if `Node` has type `integer` and represents `Value`, otherwise `false`.

See also: `integer/1`.

Link to this function

# is_leaf(Node)

View Source

    -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`.

Link to this function

# is_list_skeleton(Node)

View Source

    -spec is_list_skeleton(syntaxTree()) -> boolean().

Returns `true` if `Node` has type `list` or `nil`, otherwise `false`.

See also: `list/2`, `nil/0`.

Link to this function

# is_literal(T)

View Source

    -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`.

Link to this function

# is_proper_list(Node)

View Source

    -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`.

Link to this function

# is_string(Node, Value)

View Source

    -spec is_string(syntaxTree(), string()) -> boolean().

Returns `true` if `Node` has type `string` and represents `Value`, otherwise `false`.

See also: `string/1`.

Link to this function

# is_tree/1

View Source

    -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`.

Link to this function

# join_comments(Source, Target)

View Source

    -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`.

Link to this function

# list(List)

View Source

    -spec list([syntaxTree()]) -> syntaxTree().

Equivalent to list(List, none).

Link to this function

# list/2

View Source

    -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`.

Link to this function

# list_comp(Template, Body)

View Source

    -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`.

Link to this function

# list_comp_body(Node)

View Source

    -spec list_comp_body(syntaxTree()) -> [syntaxTree()].

Returns the list of body subtrees of a `list_comp` node.

See also: `list_comp/2`.

Link to this function

# list_comp_template(Node)

View Source

    -spec list_comp_template(syntaxTree()) -> syntaxTree().

Returns the template subtree of a `list_comp` node.

See also: `list_comp/2`.

Link to this function

# list_elements(Node)

View Source

    -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`.

Link to this function

# list_head(Node)

View Source

    -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`.

Link to this function

# list_length(Node)

View Source

    -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`.

Link to this function

# list_prefix(Node)

View Source

    -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`.

Link to this function

# list_suffix(Node)

View Source

    -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`.

Link to this function

# list_tail(Node)

View Source

    -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`.

Link to this function

# macro(Name)

View Source

    -spec macro(syntaxTree()) -> syntaxTree().

Equivalent to macro(Name, none).

Link to this function

# macro(Name, Arguments)

View Source

    -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`.

Link to this function

# macro_arguments(Node)

View Source

    -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`.

Link to this function

# macro_name(Node)

View Source

    -spec macro_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `macro` node.

See also: `macro/2`.

Link to this function

# make_tree/2

View Source

    -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`.

Link to this function

# map_comp(Template, Body)

View Source

    -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`.

Link to this function

# map_comp_body(Node)

View Source

    -spec map_comp_body(syntaxTree()) -> [syntaxTree()].

Returns the list of body subtrees of a `map_comp` node.

See also: `map_comp/2`.

Link to this function

# map_comp_template(Node)

View Source

    -spec map_comp_template(syntaxTree()) -> syntaxTree().

Returns the template subtree of a `map_comp` node.

See also: `map_comp/2`.

Link to this function

# map_expr(Fields)

View Source

    -spec map_expr([syntaxTree()]) -> syntaxTree().

Equivalent to map_expr(none, Fields).

Link to this function

# map_expr(Argument, Fields)

View Source

    -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`.

Link to this function

# map_expr_argument(Node)

View Source

    -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`.

Link to this function

# map_expr_fields(Node)

View Source

    -spec map_expr_fields(syntaxTree()) -> [syntaxTree()].

Returns the list of field subtrees of a `map_expr` node.

See also: `map_expr/2`.

Link to this function

# map_field_assoc(Name, Value)

View Source

    -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`.

Link to this function

# map_field_assoc_name(Node)

View Source

    -spec map_field_assoc_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `map_field_assoc` node.

See also: `map_field_assoc/2`.

Link to this function

# map_field_assoc_value(Node)

View Source

    -spec map_field_assoc_value(syntaxTree()) -> syntaxTree().

Returns the value subtree of a `map_field_assoc` node.

See also: `map_field_assoc/2`.

Link to this function

# map_field_exact(Name, Value)

View Source

    -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`.

Link to this function

# map_field_exact_name(Node)

View Source

    -spec map_field_exact_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `map_field_exact` node.

See also: `map_field_exact/2`.

Link to this function

# map_field_exact_value(Node)

View Source

    -spec map_field_exact_value(syntaxTree()) -> syntaxTree().

Returns the value subtree of a `map_field_exact` node.

See also: `map_field_exact/2`.

Link to this function

# map_generator(Pattern, Body)

View Source

    -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`.

Link to this function

# map_generator_body(Node)

View Source

    -spec map_generator_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `generator` node.

See also: `map_generator/2`.

Link to this function

# map_generator_pattern(Node)

View Source

    -spec map_generator_pattern(syntaxTree()) -> syntaxTree().

Returns the pattern subtree of a `generator` node.

See also: `map_generator/2`.

Link to this function

# map_type()

View Source

    -spec map_type() -> syntaxTree().

Equivalent to map_type(any_size).

Link to this function

# map_type(Fields)

View Source

    -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`.

Link to this function

# map_type_assoc(Name, Value)

View Source

    -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`.

Link to this function

# map_type_assoc_name(Node)

View Source

    -spec map_type_assoc_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `map_type_assoc` node.

See also: `map_type_assoc/2`.

Link to this function

# map_type_assoc_value(Node)

View Source

    -spec map_type_assoc_value(syntaxTree()) -> syntaxTree().

Returns the value subtree of a `map_type_assoc` node.

See also: `map_type_assoc/2`.

Link to this function

# map_type_exact(Name, Value)

View Source

    -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`.

Link to this function

# map_type_exact_name(Node)

View Source

    -spec map_type_exact_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `map_type_exact` node.

See also: `map_type_exact/2`.

Link to this function

# map_type_exact_value(Node)

View Source

    -spec map_type_exact_value(syntaxTree()) -> syntaxTree().

Returns the value subtree of a `map_type_exact` node.

See also: `map_type_exact/2`.

Link to this function

# map_type_fields(Node)

View Source

    -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`.

Link to this function

# match_expr(Pattern, Body)

View Source

    -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`.

Link to this function

# match_expr_body(Node)

View Source

    -spec match_expr_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `match_expr` node.

See also: `match_expr/2`.

Link to this function

# match_expr_pattern(Node)

View Source

    -spec match_expr_pattern(syntaxTree()) -> syntaxTree().

Returns the pattern subtree of a `match_expr` node.

See also: `match_expr/2`.

Link to this function

# maybe_expr(Body)

View Source

    -spec maybe_expr([syntaxTree()]) -> syntaxTree().

Equivalent to maybe_expr(Body, none).

Link to this function

# maybe_expr(Body, OptionalElse)

View Source

    -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`.

Link to this function

# maybe_expr_body(Node)

View Source

    -spec maybe_expr_body(syntaxTree()) -> [syntaxTree()].

Returns the list of body subtrees of a `maybe_expr` node.

See also: `maybe_expr/2`.

Link to this function

# maybe_expr_else(Node)

View Source

    -spec maybe_expr_else(syntaxTree()) -> none | syntaxTree().

Returns the else subtree of a `maybe_expr` node.

See also: `maybe_expr/2`.

Link to this function

# maybe_match_expr(Pattern, Body)

View Source

    -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`.

Link to this function

# maybe_match_expr_body(Node)

View Source

    -spec maybe_match_expr_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `maybe_expr` node.

See also: `maybe_match_expr/2`.

Link to this function

# maybe_match_expr_pattern(Node)

View Source

    -spec maybe_match_expr_pattern(syntaxTree()) -> syntaxTree().

Returns the pattern subtree of a `maybe_expr` node.

See also: `maybe_match_expr/2`.

Link to this function

# meta(T)

View Source

    -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`.

Link to this function

# module_qualifier(Module, Body)

View Source

    -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`.

Link to this function

# module_qualifier_argument(Node)

View Source

    -spec module_qualifier_argument(syntaxTree()) -> syntaxTree().

Returns the argument (the module) subtree of a `module_qualifier` node.

See also: `module_qualifier/2`.

Link to this function

# module_qualifier_body(Node)

View Source

    -spec module_qualifier_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `module_qualifier` node.

See also: `module_qualifier/2`.

Link to this function

# named_fun_expr(Name, Clauses)

View Source

    -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`.

Link to this function

# named_fun_expr_arity(Node)

View Source

    -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`.

Link to this function

# named_fun_expr_clauses(Node)

View Source

    -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`.

Link to this function

# named_fun_expr_name(Node)

View Source

    -spec named_fun_expr_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `named_fun_expr` node.

See also: `named_fun_expr/2`.

Link to this function

# normalize_list(Node)

View Source

    -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`.

Link to this function

# operator/1

View Source

    -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`.

Link to this function

# operator_literal(Node)

View Source

    -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`.

Link to this function

# operator_name(Node)

View Source

    -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`.

Link to this function

# parentheses(Expr)

View Source

    -spec parentheses(syntaxTree()) -> syntaxTree().

Creates an abstract parenthesised expression. The result represents "`(*Body*)`", independently of the context.

See also: `parentheses_body/1`.

Link to this function

# parentheses_body(Node)

View Source

    -spec parentheses_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `parentheses` node.

See also: `parentheses/1`.

Link to this function

# prefix_expr(Operator, Argument)

View Source

    -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`.

Link to this function

# prefix_expr_argument(Node)

View Source

    -spec prefix_expr_argument(syntaxTree()) -> syntaxTree().

Returns the argument subtree of a `prefix_expr` node.

See also: `prefix_expr/2`.

Link to this function

# prefix_expr_operator(Node)

View Source

    -spec prefix_expr_operator(syntaxTree()) -> syntaxTree().

Returns the operator subtree of a `prefix_expr` node.

See also: `prefix_expr/2`.

Link to this function

# receive_expr(Clauses)

View Source

    -spec receive_expr([syntaxTree()]) -> syntaxTree().

Equivalent to receive_expr(Clauses, none, []).

Link to this function

# receive_expr(Clauses, Timeout, Action)

View Source

    -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`.

Link to this function

# receive_expr_action(Node)

View Source

    -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`.

Link to this function

# receive_expr_clauses(Node)

View Source

    -spec receive_expr_clauses(syntaxTree()) -> [syntaxTree()].

Returns the list of clause subtrees of a `receive_expr` node.

See also: `receive_expr/3`.

Link to this function

# receive_expr_timeout(Node)

View Source

    -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`.

Link to this function

# record_access(Argument, Type, Field)

View Source

    -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`.

Link to this function

# record_access_argument(Node)

View Source

    -spec record_access_argument(syntaxTree()) -> syntaxTree().

Returns the argument subtree of a `record_access` node.

See also: `record_access/3`.

Link to this function

# record_access_field(Node)

View Source

    -spec record_access_field(syntaxTree()) -> syntaxTree().

Returns the field subtree of a `record_access` node.

See also: `record_access/3`.

Link to this function

# record_access_type(Node)

View Source

    -spec record_access_type(syntaxTree()) -> syntaxTree().

Returns the type subtree of a `record_access` node.

See also: `record_access/3`.

Link to this function

# record_expr(Type, Fields)

View Source

    -spec record_expr(syntaxTree(), [syntaxTree()]) -> syntaxTree().

Equivalent to record_expr(none, Type, Fields).

Link to this function

# record_expr(Argument, Type, Fields)

View Source

    -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`.

Link to this function

# record_expr_argument(Node)

View Source

    -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`.

Link to this function

# record_expr_fields(Node)

View Source

    -spec record_expr_fields(syntaxTree()) -> [syntaxTree()].

Returns the list of field subtrees of a `record_expr` node.

See also: `record_expr/3`.

Link to this function

# record_expr_type(Node)

View Source

    -spec record_expr_type(syntaxTree()) -> syntaxTree().

Returns the type subtree of a `record_expr` node.

See also: `record_expr/3`.

Link to this function

# record_field(Name)

View Source

    -spec record_field(syntaxTree()) -> syntaxTree().

Equivalent to record_field(Name, none).

Link to this function

# record_field(Name, Value)

View Source

    -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`.

Link to this function

# record_field_name(Node)

View Source

    -spec record_field_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `record_field` node.

See also: `record_field/2`.

Link to this function

# record_field_value(Node)

View Source

    -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`.

Link to this function

# record_index_expr(Type, Field)

View Source

    -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`.

Link to this function

# record_index_expr_field(Node)

View Source

    -spec record_index_expr_field(syntaxTree()) -> syntaxTree().

Returns the field subtree of a `record_index_expr` node.

See also: `record_index_expr/2`.

Link to this function

# record_index_expr_type(Node)

View Source

    -spec record_index_expr_type(syntaxTree()) -> syntaxTree().

Returns the type subtree of a `record_index_expr` node.

See also: `record_index_expr/2`.

Link to this function

# record_type(Name, Fields)

View Source

    -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`.

Link to this function

# record_type_field(Name, Type)

View Source

    -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`.

Link to this function

# record_type_field_name(Node)

View Source

    -spec record_type_field_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `record_type_field` node.

See also: `record_type_field/2`.

Link to this function

# record_type_field_type(Node)

View Source

    -spec record_type_field_type(syntaxTree()) -> syntaxTree().

Returns the type subtree of a `record_type_field` node.

See also: `record_type_field/2`.

Link to this function

# record_type_fields(Node)

View Source

    -spec record_type_fields(syntaxTree()) -> [syntaxTree()].

Returns the fields subtree of a `record_type` node.

See also: `record_type/2`.

Link to this function

# record_type_name(Node)

View Source

    -spec record_type_name(syntaxTree()) -> syntaxTree().

Returns the name subtree of a `record_type` node.

See also: `record_type/2`.

Link to this function

# remove_comments(Node)

View Source

    -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`.

Link to this function

# revert(Node)

View Source

    -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`.

Link to this function

# revert_forms/1

View Source

    -spec revert_forms(forms()) -> [erl_parse()].

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`.

Link to this function

# set_ann(Node, As)

View Source

    -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`.

Link to this function

# set_attrs(Node, Attr)

View Source

    -spec set_attrs(syntaxTree(), syntaxTreeAttributes()) -> syntaxTree().

Sets the attributes of `Node` to `Attributes`.

See also: `copy_attrs/2`, `get_attrs/1`.

Link to this function

# set_pos(Node, Pos)

View Source

    -spec set_pos(syntaxTree(), annotation_or_location()) -> syntaxTree().

Sets the position information of `Node` to `Pos`.

See also: `copy_pos/2`, `get_pos/1`.

Link to this function

# set_postcomments(Node, Cs)

View Source

    -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`.

Link to this function

# set_precomments(Node, Cs)

View Source

    -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`.

Link to this function

# size_qualifier(Body, Size)

View Source

    -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`.

Link to this function

# size_qualifier_argument(Node)

View Source

    -spec size_qualifier_argument(syntaxTree()) -> syntaxTree().

Returns the argument subtree (the size) of a `size_qualifier` node.

See also: `size_qualifier/2`.

Link to this function

# size_qualifier_body(Node)

View Source

    -spec size_qualifier_body(syntaxTree()) -> syntaxTree().

Returns the body subtree of a `size_qualifier` node.

See also: `size_qualifier/2`.

Link to this function

# string(String)

View Source

    -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`.

Link to this function

# string_literal(Node)

View Source

    -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`.

Link to this function

# string_literal/2

View Source

    -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`.

Link to this function

# string_value(Node)

View Source

    -spec string_value(syntaxTree()) -> string().

Returns the value represented by a `string` node.

See also: `string/1`.

Link to this function

# subtrees(T)

View Source

    -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 &lt;- Group]
                                     || Group &lt;- 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`.

Link to this function

# text(String)

View Source

    -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`.

Link to this function

# text_string(Node)

View Source

    -spec text_string(syntaxTree()) -> string().

Returns the character sequence represented by a `text` node.

See also: `text/1`.

Link to this function

# tree(Type)

View Source

    -spec tree(atom()) -> tree().

Equivalent to tree(Type, []).

Link to this function

# tree(Type, Data)

View Source

    -spec tree(atom(), term()) -> tree().

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 the `erl_parse` form. The function `type(T)` should return the correct type tag regardless of the representation of `T`, so that the user sees no difference between `erl_syntax` and `erl_parse` nodes.

See also: `data/1`, `is_tree/1`, `type/1`.

Link to this function

# try_after_expr(Body, After)

View Source

    -spec try_after_expr([syntaxTree()], [syntaxTree()]) -> syntaxTree().

Equivalent to try_expr(Body, [], [], After).

Link to this function

# try_expr(Body, Handlers)

View Source

    -spec try_expr([syntaxTree()], [syntaxTree()]) -> syntaxTree().

Equivalent to try_expr(Body, [], Handlers).

Link to this function

# try_expr(Body, Clauses, Handlers)

View Source

    -spec try_expr([syntaxTree()], [syntaxTree()], [syntaxTree()]) -> syntaxTree().

Equivalent to try_expr(Body, Clauses, Handlers, []).

Link to this function

# try_expr(Body, Clauses, Handlers, After)

View Source

    -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`.

Link to this function

# try_expr_after(Node)

View Source

    -spec try_expr_after(syntaxTree()) -> [syntaxTree()].

Returns the list of "after" subtrees of a `try_expr` node.

See also: `try_expr/4`.

Link to this function

# try_expr_body(Node)

View Source

    -spec try_expr_body(syntaxTree()) -> [syntaxTree()].

Returns the list of body subtrees of a `try_expr` node.

See also: `try_expr/4`.

Link to this function

# try_expr_clauses(Node)

View Source

    -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`.

Link to this function

# try_expr_handlers(Node)

View Source

    -spec try_expr_handlers(syntaxTree()) -> [syntaxTree()].

Returns the list of handler-clause subtrees of a `try_expr` node.

See also: `try_expr/4`.

Link to this function

# tuple(List)

View Source

    -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`.

Link to this function

# tuple_elements(Node)

View Source

    -spec tuple_elements(syntaxTree()) -> [syntaxTree()].

Returns the list of element subtrees of a `tuple` node.

See also: `tuple/1`.

Link to this function

# tuple_size(Node)

View Source

    -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`.

Link to this function

# tuple_type()

View Source

    -spec tuple_type() -> syntaxTree().

Equivalent to tuple_type(any_size).

Link to this function

# tuple_type(Elements)

View Source

    -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`.

Link to this function

# tuple_type_elements(Node)

View Source

    -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`.

Link to this function

# type/1

View Source

    -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`.

Link to this function

# type_application(TypeName, Arguments)

View Source

    -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`.

Link to this function

# type_application/3

View Source

    -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`.

Link to this function

# type_application_arguments(Node)

View Source

    -spec type_application_arguments(syntaxTree()) -> [syntaxTree()].

Returns the arguments subtrees of a `type_application` node.

See also: `type_application/2`.

Link to this function

# type_application_name(Node)

View Source

    -spec type_application_name(syntaxTree()) -> syntaxTree().

Returns the type name subtree of a `type_application` node.

See also: `type_application/2`.

Link to this function

# type_union(Types)

View Source

    -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`.

Link to this function

# type_union_types(Node)

View Source

    -spec type_union_types(syntaxTree()) -> [syntaxTree()].

Returns the list of type subtrees of a `type_union` node.

See also: `type_union/1`.

Link to this function

# typed_record_field(Field, Type)

View Source

    -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`.

Link to this function

# typed_record_field_body(Node)

View Source

    -spec typed_record_field_body(syntaxTree()) -> syntaxTree().

Returns the field subtree of a `typed_record_field` node.

See also: `typed_record_field/2`.

Link to this function

# typed_record_field_type(Node)

View Source

    -spec typed_record_field_type(syntaxTree()) -> syntaxTree().

Returns the type subtree of a `typed_record_field` node.

See also: `typed_record_field/2`.

Link to this function

# underscore()

View Source

    -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`.

Link to this function

# update_tree(Node, Groups)

View Source

    -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`.

Link to this function

# user_type_application(TypeName, Arguments)

View Source

    -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`.

Link to this function

# user_type_application_arguments(Node)

View Source

    -spec user_type_application_arguments(syntaxTree()) -> [syntaxTree()].

Returns the arguments subtrees of a `user_type_application` node.

See also: `user_type_application/2`.

Link to this function

# user_type_application_name(Node)

View Source

    -spec user_type_application_name(syntaxTree()) -> syntaxTree().

Returns the type name subtree of a `user_type_application` node.

See also: `user_type_application/2`.

Link to this function

# variable/1

View Source

    -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`.

Link to this function

# variable_literal(Node)

View Source

    -spec variable_literal(syntaxTree()) -> string().

Returns the name of a `variable` node as a string.

See also: `variable/1`.

Link to this function

# variable_name(Node)

View Source

    -spec variable_name(syntaxTree()) -> atom().

Returns the name of a `variable` node as an atom.

See also: `variable/1`.

Link to this function

# warning_marker(Warning)

View Source

    -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`.

Link to this function

# warning_marker_info(Node)

View Source

    -spec warning_marker_info(syntaxTree()) -> term().

Returns the ErrorInfo structure of a `warning_marker` node.

See also: `warning_marker/1`.