.TH erl_syntax_lib 3erl "syntax_tools 3.0.1" "" "Erlang Module Definition"
.SH NAME
erl_syntax_lib \- Support library for abstract Erlang syntax trees.
.SH DESCRIPTION
.LP
Support library for abstract Erlang syntax trees\&.
.LP
This module contains utility functions for working with the abstract data type defined in the module erl_syntax\&.
.SH "DATA TYPES"

.RS 2
.TP 2
.B
appFunName() = {atom(), arity()} | {atom(), {atom(), arity()}}:

.TP 2
.B
field() = {atom(), {field_default(), field_type()}}:

.TP 2
.B
field_default() = none | erl_syntax:syntaxTree():

.TP 2
.B
field_type() = none | erl_syntax:syntaxTree():

.TP 2
.B
fields() = [field()]:

.TP 2
.B
functionN() = atom() | {atom(), arity()}:

.TP 2
.B
functionName() = functionN() | {atom(), functionN()}:

.TP 2
.B
info() = {atom(), [{atom(), erl_syntax:syntaxTree()}]} | {atom(), atom()} | atom():

.TP 2
.B
info_pair() = {key(), term()}:

.TP 2
.B
key() = attributes | errors | exports | functions | imports | module | records | warnings:

.TP 2
.B
name() = shortname() | {atom(), shortname()}:

.TP 2
.B
ordset(T) = ordsets:ordset(T):

.TP 2
.B
set(T) = sets:set(T):

.TP 2
.B
shortname() = atom() | {atom(), arity()}:

.TP 2
.B
syntaxTree() = erl_syntax:syntaxTree():

.RS 2
.LP
An abstract syntax tree\&. See the erl_syntax module for details\&.
.RE

.TP 2
.B
typeName() = atom() | {module(), {atom(), arity()}} | {atom(), arity()}:

.RE
.SH EXPORTS
.LP
.B
analyze_application(Node::erl_syntax:syntaxTree()) -> appFunName() | arity()
.br
.RS
.LP
Returns the name of a called function\&. The result is a representation of the name of the applied function \fIF/A\fR\&, if \fINode\fR\& represents a function application "\fIF(X_1, \&.\&.\&., X_A)\fR\&"\&. If the function is not explicitly named (i\&.e\&., \fIF\fR\& is given by some expression), only the arity \fIA\fR\& is returned\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed application expression\&.
.LP
\fISee also:\fR\& analyze_function_name/1\&.
.RE

.LP
.B
analyze_attribute(Node::erl_syntax:syntaxTree()) -> preprocessor | {atom(), term()}
.br
.RS
.LP
Analyzes an attribute node\&. If \fINode\fR\& represents a preprocessor directive, the atom \fIpreprocessor\fR\& is returned\&. Otherwise, if \fINode\fR\& represents a module attribute "\fI-Name\&.\&.\&.\fR\&", a tuple \fI{Name, Info}\fR\& is returned, where \fIInfo\fR\& depends on \fIName\fR\&, as follows:
.RS 2
.TP 2
.B
\fI{module, Info}\fR\&:
where \fIInfo = analyze_module_attribute(Node)\fR\&\&.
.TP 2
.B
\fI{export, Info}\fR\&:
where \fIInfo = analyze_export_attribute(Node)\fR\&\&.
.TP 2
.B
\fI{import, Info}\fR\&:
where \fIInfo = analyze_import_attribute(Node)\fR\&\&.
.TP 2
.B
\fI{file, Info}\fR\&:
where \fIInfo = analyze_file_attribute(Node)\fR\&\&.
.TP 2
.B
\fI{record, Info}\fR\&:
where \fIInfo = analyze_record_attribute(Node)\fR\&\&.
.TP 2
.B
\fI{Name, Info}\fR\&:
where \fI{Name, Info} = analyze_wild_attribute(Node)\fR\&\&.
.RE
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed module attribute\&.
.LP
\fISee also:\fR\& analyze_export_attribute/1, analyze_file_attribute/1, analyze_import_attribute/1, analyze_module_attribute/1, analyze_record_attribute/1, analyze_wild_attribute/1\&.
.RE

.LP
.B
analyze_export_attribute(Node::erl_syntax:syntaxTree()) -> [functionName()]
.br
.RS
.LP
Returns the list of function names declared by an export attribute\&. We do not guarantee that each name occurs at most once in the list\&. The order of listing is not defined\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed export attribute\&.
.LP
\fISee also:\fR\& analyze_attribute/1\&.
.RE

.LP
.B
analyze_file_attribute(Node::erl_syntax:syntaxTree()) -> {string(), integer()}
.br
.RS
.LP
Returns the file name and line number of a \fIfile\fR\& attribute\&. The result is the pair \fI{File, Line}\fR\& if \fINode\fR\& represents "\fI-file(File, Line)\&.\fR\&"\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed \fIfile\fR\& attribute\&.
.LP
\fISee also:\fR\& analyze_attribute/1\&.
.RE

.LP
.B
analyze_form(Node::erl_syntax:syntaxTree()) -> {atom(), term()} | atom()
.br
.RS
.LP
Analyzes a "source code form" node\&. If \fINode\fR\& is a "form" type (cf\&. \fIerl_syntax:is_form/1\fR\&), the returned value is a tuple \fI{Type, Info}\fR\& where \fIType\fR\& is the node type and \fIInfo\fR\& depends on \fIType\fR\&, as follows:
.RS 2
.TP 2
.B
\fI{attribute, Info}\fR\&:
where \fIInfo = analyze_attribute(Node)\fR\&\&.
.TP 2
.B
\fI{error_marker, Info}\fR\&:
where \fIInfo = erl_syntax:error_marker_info(Node)\fR\&\&.
.TP 2
.B
\fI{function, Info}\fR\&:
where \fIInfo = analyze_function(Node)\fR\&\&.
.TP 2
.B
\fI{warning_marker, Info}\fR\&:
where \fIInfo = erl_syntax:warning_marker_info(Node)\fR\&\&.
.RE
.LP
For other types of forms, only the node type is returned\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& is not well-formed\&.
.LP
\fISee also:\fR\& analyze_attribute/1, analyze_function/1, erl_syntax:error_marker_info/1, erl_syntax:is_form/1, erl_syntax:warning_marker_info/1\&.
.RE

.LP
.B
analyze_forms(Forms::erl_syntax:forms()) -> [info_pair()]
.br
.RS
.LP
Analyzes a sequence of "program forms"\&. The given \fIForms\fR\& may be a single syntax tree of type \fIform_list\fR\&, or a list of "program form" syntax trees\&. The returned value is a list of pairs \fI{Key, Info}\fR\&, where each value of \fIKey\fR\& occurs at most once in the list; the absence of a particular key indicates that there is no well-defined value for that key\&.
.LP
Each entry in the resulting list contains the following corresponding information about the program forms:
.RS 2
.TP 2
.B
\fI{attributes, Attributes}\fR\&:

.RS 2
.TP 2
*
\fIAttributes = [{atom(), term()}]\fR\&
.LP
.RE

.RS 2
.LP
\fIAttributes\fR\& is a list of pairs representing the names and corresponding values of all so-called "wild" attributes (as e\&.g\&. "\fI-compile(\&.\&.\&.)\fR\&") occurring in \fIForms\fR\& (cf\&. \fIanalyze_wild_attribute/1\fR\&)\&. We do not guarantee that each name occurs at most once in the list\&. The order of listing is not defined\&.
.RE

.TP 2
.B
\fI{errors, Errors}\fR\&:

.RS 2
.TP 2
*
\fIErrors = [term()]\fR\&
.LP
.RE

.RS 2
.LP
\fIErrors\fR\& is the list of error descriptors of all \fIerror_marker\fR\& nodes that occur in \fIForms\fR\&\&. The order of listing is not defined\&.
.RE

.TP 2
.B
\fI{exports, Exports}\fR\&:

.RS 2
.TP 2
*
\fIExports = [FunctionName]\fR\&
.LP
.TP 2
*
\fIFunctionName = atom() | {atom(), integer()} | {ModuleName, FunctionName}\fR\&
.LP
.TP 2
*
\fIModuleName = atom()\fR\&
.LP
.RE

.RS 2
.LP
\fIExports\fR\& is a list of representations of those function names that are listed by export declaration attributes in \fIForms\fR\& (cf\&. \fIanalyze_export_attribute/1\fR\&)\&. We do not guarantee that each name occurs at most once in the list\&. The order of listing is not defined\&.
.RE

.TP 2
.B
\fI{functions, Functions}\fR\&:

.RS 2
.TP 2
*
\fIFunctions = [{atom(), integer()}]\fR\&
.LP
.RE

.RS 2
.LP
\fIFunctions\fR\& is a list of the names of the functions that are defined in \fIForms\fR\& (cf\&. \fIanalyze_function/1\fR\&)\&. We do not guarantee that each name occurs at most once in the list\&. The order of listing is not defined\&.
.RE

.TP 2
.B
\fI{imports, Imports}\fR\&:

.RS 2
.TP 2
*
\fIImports = [{Module, Names}]\fR\&
.LP
.TP 2
*
\fIModule = atom()\fR\&
.LP
.TP 2
*
\fINames = [FunctionName]\fR\&
.LP
.TP 2
*
\fIFunctionName = atom() | {atom(), integer()} | {ModuleName, FunctionName}\fR\&
.LP
.TP 2
*
\fIModuleName = atom()\fR\&
.LP
.RE

.RS 2
.LP
\fIImports\fR\& is a list of pairs representing those module names and corresponding function names that are listed by import declaration attributes in \fIForms\fR\& (cf\&. \fIanalyze_import_attribute/1\fR\&), where each \fIModule\fR\& occurs at most once in \fIImports\fR\&\&. We do not guarantee that each name occurs at most once in the lists of function names\&. The order of listing is not defined\&.
.RE

.TP 2
.B
\fI{module, ModuleName}\fR\&:

.RS 2
.TP 2
*
\fIModuleName = atom()\fR\&
.LP
.RE

.RS 2
.LP
\fIModuleName\fR\& is the name declared by a module attribute in \fIForms\fR\&\&. If no module name is defined in \fIForms\fR\&, the result will contain no entry for the \fImodule\fR\& key\&. If multiple module name declarations should occur, all but the first will be ignored\&.
.RE

.TP 2
.B
\fI{records, Records}\fR\&:

.RS 2
.TP 2
*
\fIRecords = [{atom(), Fields}]\fR\&
.LP
.TP 2
*
\fIFields = [{atom(), {Default, Type}}]\fR\&
.LP
.TP 2
*
\fIDefault = none | syntaxTree()\fR\&
.LP
.TP 2
*
\fIType = none | syntaxTree()\fR\&
.LP
.RE

.RS 2
.LP
\fIRecords\fR\& is a list of pairs representing the names and corresponding field declarations of all record declaration attributes occurring in \fIForms\fR\&\&. For fields declared without a default value, the corresponding value for \fIDefault\fR\& is the atom \fInone\fR\&\&. Similarly, for fields declared without a type, the corresponding value for \fIType\fR\& is the atom \fInone\fR\& (cf\&. \fIanalyze_record_attribute/1\fR\&)\&. We do not guarantee that each record name occurs at most once in the list\&. The order of listing is not defined\&.
.RE

.TP 2
.B
\fI{warnings, Warnings}\fR\&:

.RS 2
.TP 2
*
\fIWarnings = [term()]\fR\&
.LP
.RE

.RS 2
.LP
\fIWarnings\fR\& is the list of error descriptors of all \fIwarning_marker\fR\& nodes that occur in \fIForms\fR\&\&. The order of listing is not defined\&.
.RE

.RE
.LP
The evaluation throws \fIsyntax_error\fR\& if an ill-formed Erlang construct is encountered\&.
.LP
\fISee also:\fR\& analyze_export_attribute/1, analyze_function/1, analyze_import_attribute/1, analyze_record_attribute/1, analyze_wild_attribute/1, erl_syntax:error_marker_info/1, erl_syntax:warning_marker_info/1\&.
.RE

.LP
.B
analyze_function(Node::erl_syntax:syntaxTree()) -> {atom(), arity()}
.br
.RS
.LP
Returns the name and arity of a function definition\&. The result is a pair \fI{Name, A}\fR\& if \fINode\fR\& represents a function definition "\fIName(P_1, \&.\&.\&., P_A) -> \&.\&.\&.\fR\&"\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed function definition\&.
.RE

.LP
.B
analyze_function_name(Node::erl_syntax:syntaxTree()) -> functionName()
.br
.RS
.LP
Returns the function name represented by a syntax tree\&. If \fINode\fR\& represents a function name, such as "\fIfoo/1\fR\&" or "\fIbloggs:fred/2\fR\&", a uniform representation of that name is returned\&. Different nestings of arity and module name qualifiers in the syntax tree does not affect the result\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed function name\&.
.RE

.LP
.B
analyze_implicit_fun(Node::erl_syntax:syntaxTree()) -> functionName()
.br
.RS
.LP
Returns the name of an implicit fun expression "\fIfun F\fR\&"\&. The result is a representation of the function name \fIF\fR\&\&. (Cf\&. \fIanalyze_function_name/1\fR\&\&.)
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed implicit fun\&.
.LP
\fISee also:\fR\& analyze_function_name/1\&.
.RE

.LP
.B
analyze_import_attribute(Node::erl_syntax:syntaxTree()) -> {atom(), [functionName()]} | atom()
.br
.RS
.LP
Returns the module name and (if present) list of function names declared by an import attribute\&. The returned value is an atom \fIModule\fR\& or a pair \fI{Module, Names}\fR\&, where \fINames\fR\& is a list of function names declared as imported from the module named by \fIModule\fR\&\&. We do not guarantee that each name occurs at most once in \fINames\fR\&\&. The order of listing is not defined\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed import attribute\&.
.LP
\fISee also:\fR\& analyze_attribute/1\&.
.RE

.LP
.B
analyze_module_attribute(Node::erl_syntax:syntaxTree()) -> atom() | {atom(), [atom()]}
.br
.RS
.LP
Returns the module name and possible parameters declared by a module attribute\&. If the attribute is a plain module declaration such as \fI-module(name)\fR\&, the result is the module name\&. If the attribute is a parameterized module declaration, the result is a tuple containing the module name and a list of the parameter variable names\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed module attribute\&.
.LP
\fISee also:\fR\& analyze_attribute/1\&.
.RE

.LP
.B
analyze_record_attribute(Node::erl_syntax:syntaxTree()) -> {atom(), fields()}
.br
.RS
.LP
Returns the name and the list of fields of a record declaration attribute\&. The result is a pair \fI{Name, Fields}\fR\&, if \fINode\fR\& represents "\fI-record(Name, {\&.\&.\&.})\&.\fR\&", where \fIFields\fR\& is a list of pairs \fI{Label, {Default, Type}}\fR\& for each field "\fILabel\fR\&", "\fILabel = Default\fR\&", "\fILabel :: Type\fR\&", or "\fILabel = Default :: Type\fR\&" in the declaration, listed in left-to-right order\&. If the field has no default-value declaration, the value for \fIDefault\fR\& will be the atom \fInone\fR\&\&. If the field has no type declaration, the value for \fIType\fR\& will be the atom \fInone\fR\&\&. We do not guarantee that each label occurs at most once in the list\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed record declaration attribute\&.
.LP
\fISee also:\fR\& analyze_attribute/1, analyze_record_field/1\&.
.RE

.LP
.B
analyze_record_expr(Node::erl_syntax:syntaxTree()) -> {atom(), info()} | atom()
.br
.RS
.LP
Returns the record name and field name/names of a record expression\&. If \fINode\fR\& has type \fIrecord_expr\fR\&, \fIrecord_index_expr\fR\& or \fIrecord_access\fR\&, a pair \fI{Type, Info}\fR\& is returned, otherwise an atom \fIType\fR\& is returned\&. \fIType\fR\& is the node type of \fINode\fR\&, and \fIInfo\fR\& depends on \fIType\fR\&, as follows:
.RS 2
.TP 2
.B
\fIrecord_expr\fR\&::
\fI{atom(), [{atom(), Value}]}\fR\&
.TP 2
.B
\fIrecord_access\fR\&::
\fI{atom(), atom()}\fR\&
.TP 2
.B
\fIrecord_index_expr\fR\&::
\fI{atom(), atom()}\fR\&
.RE
.LP

.LP
For a \fIrecord_expr\fR\& node, \fIInfo\fR\& represents the record name and the list of descriptors for the involved fields, listed in the order they appear\&. A field descriptor is a pair \fI{Label, Value}\fR\&, if \fINode\fR\& represents "\fILabel = Value\fR\&"\&. For a \fIrecord_access\fR\& node, \fIInfo\fR\& represents the record name and the field name\&. For a \fIrecord_index_expr\fR\& node, \fIInfo\fR\& represents the record name and the name field name\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& represents a record expression that is not well-formed\&.
.LP
\fISee also:\fR\& analyze_record_attribute/1, analyze_record_field/1\&.
.RE

.LP
.B
analyze_record_field(Node::erl_syntax:syntaxTree()) -> field()
.br
.RS
.LP
Returns the label, value-expression, and type of a record field specifier\&. The result is a pair \fI{Label, {Default, Type}}\fR\&, if \fINode\fR\& represents "\fILabel\fR\&", "\fILabel = Default\fR\&", "\fILabel :: Type\fR\&", or "\fILabel = Default :: Type\fR\&"\&. If the field has no value-expression, the value for \fIDefault\fR\& will be the atom \fInone\fR\&\&. If the field has no type, the value for \fIType\fR\& will be the atom \fInone\fR\&\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed record field specifier\&.
.LP
\fISee also:\fR\& analyze_record_attribute/1, analyze_record_expr/1\&.
.RE

.LP
.B
analyze_type_application(Node::erl_syntax:syntaxTree()) -> typeName()
.br
.RS
.LP
Returns the name of a used type\&. The result is a representation of the name of the used pre-defined or local type \fIN/A\fR\&, if \fINode\fR\& represents a local (user) type application "\fIN(T_1, \&.\&.\&., T_A)\fR\&", or a representation of the name of the used remote type \fIM:N/A\fR\& if \fINode\fR\& represents a remote user type application "\fIM:N(T_1, \&.\&.\&., T_A)\fR\&"\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed (user) type application expression\&.
.LP
\fISee also:\fR\& analyze_type_name/1\&.
.RE

.LP
.B
analyze_type_name(Node::erl_syntax:syntaxTree()) -> typeName()
.br
.RS
.LP
Returns the type name represented by a syntax tree\&. If \fINode\fR\& represents a type name, such as "\fIfoo/1\fR\&" or "\fIbloggs:fred/2\fR\&", a uniform representation of that name is returned\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed type name\&.
.RE

.LP
.B
analyze_wild_attribute(Node::erl_syntax:syntaxTree()) -> {atom(), term()}
.br
.RS
.LP
Returns the name and value of a "wild" attribute\&. The result is the pair \fI{Name, Value}\fR\&, if \fINode\fR\& represents "\fI-Name(Value)\fR\&"\&.
.LP
Note that no checking is done whether \fIName\fR\& is a reserved attribute name such as \fImodule\fR\& or \fIexport\fR\&: it is assumed that the attribute is "wild"\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed wild attribute\&.
.LP
\fISee also:\fR\& analyze_attribute/1\&.
.RE

.LP
.B
annotate_bindings(Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Adds or updates annotations on nodes in a syntax tree\&. Equivalent to \fIannotate_bindings(Tree, Bindings)\fR\& where the top-level environment \fIBindings\fR\& is taken from the annotation \fI{env, Bindings}\fR\& on the root node of \fITree\fR\&\&. An exception is thrown if no such annotation should exist\&.
.LP
\fISee also:\fR\& annotate_bindings/2\&.
.RE

.LP
.B
annotate_bindings(Tree::erl_syntax:syntaxTree(), Env::ordsets:ordset(atom())) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Adds or updates annotations on nodes in a syntax tree\&. \fIBindings\fR\& specifies the set of bound variables in the environment of the top level node\&. The following annotations are affected:
.RS 2
.TP 2
*
\fI{env, Vars}\fR\&, representing the input environment of the subtree\&.
.LP
.TP 2
*
\fI{bound, Vars}\fR\&, representing the variables that are bound in the subtree\&.
.LP
.TP 2
*
\fI{free, Vars}\fR\&, representing the free variables in the subtree\&.
.LP
.RE

.LP
\fIBindings\fR\& and \fIVars\fR\& are ordered-set lists (cf\&. module \fIordsets\fR\&) of atoms representing variable names\&.
.LP
\fISee also:\fR\& ordsets(3erl), annotate_bindings/1\&.
.RE

.LP
.B
fold(F::(erl_syntax:syntaxTree(), term()) -> term(), S::term(), Tree::erl_syntax:syntaxTree()) -> term()
.br
.RS
.LP
Folds a function over all nodes of a syntax tree\&. The result is the value of \fIFunction(X1, Function(X2, \&.\&.\&. Function(Xn, Start) \&.\&.\&. ))\fR\&, where \fI[X1, X2, \&.\&.\&., Xn]\fR\& are the nodes of \fITree\fR\& in a post-order traversal\&.
.LP
\fISee also:\fR\& fold_subtrees/3, foldl_listlist/3\&.
.RE

.LP
.B
fold_subtrees(F::(erl_syntax:syntaxTree(), term()) -> term(), S::term(), Tree::erl_syntax:syntaxTree()) -> term()
.br
.RS
.LP
Folds a function over the immediate subtrees of a syntax tree\&. This is similar to \fIfold/3\fR\&, but only on the immediate subtrees of \fITree\fR\&, in left-to-right order; it does not include the root node of \fITree\fR\&\&.
.LP
\fISee also:\fR\& fold/3\&.
.RE

.LP
.B
foldl_listlist(F::(term(), term()) -> term(), S::term(), Ls::[[term()]]) -> term()
.br
.RS
.LP
Like \fIlists:foldl/3\fR\&, but over a list of lists\&.
.LP
\fISee also:\fR\& lists:foldl/3, fold/3\&.
.RE

.LP
.B
function_name_expansions(Fs::[name()]) -> [{shortname(), name()}]
.br
.RS
.LP
Creates a mapping from corresponding short names to full function names\&. Names are represented by nested tuples of atoms and integers (cf\&. \fIanalyze_function_name/1\fR\&)\&. The result is a list containing a pair \fI{ShortName, Name}\fR\& for each element \fIName\fR\& in the given list, where the corresponding \fIShortName\fR\& is the rightmost-innermost part of \fIName\fR\&\&. The list thus represents a finite mapping from unqualified names to the corresponding qualified names\&.
.LP
Note: the resulting list can contain more than one tuple \fI{ShortName, Name}\fR\& for the same \fIShortName\fR\&, possibly with different values for \fIName\fR\&, depending on the given list\&.
.LP
\fISee also:\fR\& analyze_function_name/1\&.
.RE

.LP
.B
is_fail_expr(E::erl_syntax:syntaxTree()) -> boolean()
.br
.RS
.LP
Returns \fItrue\fR\& if \fITree\fR\& represents an expression which never terminates normally\&. Note that the reverse does not apply\&. Currently, the detected cases are calls to \fIexit/1\fR\&, \fIthrow/1\fR\&, \fIerlang:error/1\fR\& and \fIerlang:error/2\fR\&\&.
.LP
\fISee also:\fR\& erlang:error/1, erlang:error/2, erlang:exit/1, erlang:throw/1\&.
.RE

.LP
.B
limit(Tree::erl_syntax:syntaxTree(), Depth::integer()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Equivalent to \fIlimit(Tree, Depth, Text)\fR\& using the text \fI"\&.\&.\&."\fR\& as default replacement\&.
.LP
\fISee also:\fR\& limit/3, erl_syntax:text/1\&.
.RE

.LP
.B
limit(Tree::erl_syntax:syntaxTree(), Depth::integer(), Node::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Limits a syntax tree to a specified depth\&. Replaces all non-leaf subtrees in \fITree\fR\& at the given \fIDepth\fR\& by \fINode\fR\&\&. If \fIDepth\fR\& is negative, the result is always \fINode\fR\&, even if \fITree\fR\& has no subtrees\&.
.LP
When a group of subtrees (as e\&.g\&., the argument list of an \fIapplication\fR\& node) is at the specified depth, and there are two or more subtrees in the group, these will be collectively replaced by \fINode\fR\& even if they are leaf nodes\&. Groups of subtrees that are above the specified depth will be limited in size, as if each subsequent tree in the group were one level deeper than the previous\&. E\&.g\&., if \fITree\fR\& represents a list of integers "\fI[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\fR\&", the result of \fIlimit(Tree, 5)\fR\& will represent \fI[1, 2, 3, 4, \&.\&.\&.]\fR\&\&.
.LP
The resulting syntax tree is typically only useful for pretty-printing or similar visual formatting\&.
.LP
\fISee also:\fR\& limit/2\&.
.RE

.LP
.B
map(F::(erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree(), Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Applies a function to each node of a syntax tree\&. The result of each application replaces the corresponding original node\&. The order of traversal is bottom-up\&.
.LP
\fISee also:\fR\& map_subtrees/2\&.
.RE

.LP
.B
map_subtrees(F::(erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree(), Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Applies a function to each immediate subtree of a syntax tree\&. The result of each application replaces the corresponding original node\&.
.LP
\fISee also:\fR\& map/2\&.
.RE

.LP
.B
mapfold(F::(erl_syntax:syntaxTree(), term()) -> {erl_syntax:syntaxTree(), term()}, S::term(), Tree::erl_syntax:syntaxTree()) -> {erl_syntax:syntaxTree(), term()}
.br
.RS
.LP
Combines map and fold in a single operation\&. This is similar to \fImap/2\fR\&, but also propagates an extra value from each application of the \fIFunction\fR\& to the next, while doing a post-order traversal of the tree like \fIfold/3\fR\&\&. The value \fIStart\fR\& is passed to the first function application, and the final result is the result of the last application\&.
.LP
\fISee also:\fR\& fold/3, map/2\&.
.RE

.LP
.B
mapfold_subtrees(F::(erl_syntax:syntaxTree(), term()) -> {erl_syntax:syntaxTree(), term()}, S::term(), Tree::erl_syntax:syntaxTree()) -> {erl_syntax:syntaxTree(), term()}
.br
.RS
.LP
Does a mapfold operation over the immediate subtrees of a syntax tree\&. This is similar to \fImapfold/3\fR\&, but only on the immediate subtrees of \fITree\fR\&, in left-to-right order; it does not include the root node of \fITree\fR\&\&.
.LP
\fISee also:\fR\& mapfold/3\&.
.RE

.LP
.B
mapfoldl_listlist(F::(term(), term()) -> {term(), term()}, S::term(), Ls::[[term()]]) -> {[[term()]], term()}
.br
.RS
.LP
Like \fIlists:mapfoldl/3\fR\&, but over a list of lists\&. The list of lists in the result has the same structure as the given list of lists\&.
.RE

.LP
.B
new_variable_name(S::sets:set(atom())) -> atom()
.br
.RS
.LP
Returns an atom which is not already in the set \fIUsed\fR\&\&. This is equivalent to \fInew_variable_name(Function, Used)\fR\&, where \fIFunction\fR\& maps a given integer \fIN\fR\& to the atom whose name consists of "\fIV\fR\&" followed by the numeral for \fIN\fR\&\&.
.LP
\fISee also:\fR\& new_variable_name/2\&.
.RE

.LP
.B
new_variable_name(F::(integer()) -> atom(), S::sets:set(atom())) -> atom()
.br
.RS
.LP
Returns a user-named atom which is not already in the set \fIUsed\fR\&\&. The atom is generated by applying the given \fIFunction\fR\& to a generated integer\&. Integers are generated using an algorithm which tries to keep the names randomly distributed within a reasonably small range relative to the number of elements in the set\&.
.LP
This function uses the module \fIrand\fR\& to generate new keys\&. The seed it uses may be initialized by calling \fIrand:seed/1\fR\& or \fIrand:seed/2\fR\& before this function is first called\&.
.LP
\fISee also:\fR\& random(3erl), sets(3erl), new_variable_name/1\&.
.RE

.LP
.B
new_variable_names(N::integer(), S::sets:set(atom())) -> [atom()]
.br
.RS
.LP
Like \fInew_variable_name/1\fR\&, but generates a list of \fIN\fR\& new names\&.
.LP
\fISee also:\fR\& new_variable_name/1\&.
.RE

.LP
.B
new_variable_names(N::integer(), F::(integer()) -> atom(), S::sets:set(atom())) -> [atom()]
.br
.RS
.LP
Like \fInew_variable_name/2\fR\&, but generates a list of \fIN\fR\& new names\&.
.LP
\fISee also:\fR\& new_variable_name/2\&.
.RE

.LP
.B
strip_comments(Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Removes all comments from all nodes of a syntax tree\&. All other attributes (such as position information) remain unchanged\&. Standalone comments in form lists are removed; any other standalone comments are changed into null-comments (no text, no indentation)\&.
.RE

.LP
.B
to_comment(Tree::erl_syntax:syntaxTree()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Equivalent to to_comment(Tree, "% ")\&.
.RE

.LP
.B
to_comment(Tree::erl_syntax:syntaxTree(), Prefix::string()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Equivalent to \fIto_comment(Tree, Prefix, F)\fR\& for a default formatting function \fIF\fR\&\&. The default \fIF\fR\& simply calls \fIerl_prettypr:format/1\fR\&\&.
.LP
\fISee also:\fR\& to_comment/3, erl_prettypr:format/1\&.
.RE

.LP
.B
to_comment(Tree::erl_syntax:syntaxTree(), Prefix::string(), F::(erl_syntax:syntaxTree()) -> string()) -> erl_syntax:syntaxTree()
.br
.RS
.LP
Transforms a syntax tree into an abstract comment\&. The lines of the comment contain the text for \fINode\fR\&, as produced by the given \fIPrinter\fR\& function\&. Each line of the comment is prefixed by the string \fIPrefix\fR\& (this does not include the initial "\fI%\fR\&" character of the comment line)\&.
.LP
For example, the result of \fIto_comment(erl_syntax:abstract([a,b,c]))\fR\& represents
.LP
.nf

          %% [a,b,c]
.fi
.LP
(cf\&. \fIto_comment/1\fR\&)\&.
.LP
Note: the text returned by the formatting function will be split automatically into separate comment lines at each line break\&. No extra work is needed\&.
.LP
\fISee also:\fR\& to_comment/1, to_comment/2\&.
.RE

.LP
.B
variables(Tree::erl_syntax:syntaxTree()) -> sets:set(atom())
.br
.RS
.LP
Returns the names of variables occurring in a syntax tree, The result is a set of variable names represented by atoms\&. Macro names are not included\&.
.LP
\fISee also:\fR\& sets(3erl)\&.
.RE

.SH AUTHORS
.LP
Richard Carlsson
.I
<carlsson\&.richard@gmail\&.com>