EVOLUTION-MANAGER

Edit File: erl_syntax_lib.3

.TH erl_syntax_lib 3 "syntax_tools 1.6.13" "" "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 \fBerl_syntax\fR\&\&.
.SH "DATA TYPES"

.RS 2
.TP 2
.B
\fIinfo_pair() = {key(), term()}\fR\&:

.TP 2
.B
\fIordset(T) = ordset(T) (see module //stdlib/ordsets)\fR\&:

.TP 2
.B
\fIsyntaxTree() = syntaxTree() (see module erl_syntax)\fR\&:

.RS 2
.LP
An abstract syntax tree\&. See the \fBerl_syntax\fR\& module for details\&.
.RE
.RE
.SH EXPORTS
.LP
.B
analyze_application(Node::syntaxTree()) -> FunctionName | Arity
.br
.RS
.LP
Types:

.RS 3
FunctionName = {atom(), Arity} | {ModuleName, FunctionName}
.br
Arity = integer()
.br
ModuleName = atom()
.br
.RE
.RE
.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\& \fBanalyze_function_name/1\fR\&\&.
.RE
.LP
.B
analyze_attribute(Node::syntaxTree()) -> preprocessor | {atom(), atom()}
.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\& \fBanalyze_export_attribute/1\fR\&, \fBanalyze_file_attribute/1\fR\&, \fBanalyze_import_attribute/1\fR\&, \fBanalyze_module_attribute/1\fR\&, \fBanalyze_record_attribute/1\fR\&, \fBanalyze_wild_attribute/1\fR\&\&.
.RE
.LP
.B
analyze_export_attribute(Node::syntaxTree()) -> [FunctionName]
.br
.RS
.LP
Types:

.RS 3
FunctionName = atom() | {atom(), integer()} | {ModuleName, FunctionName}
.br
ModuleName = atom()
.br
.RE
.RE
.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\& \fBanalyze_attribute/1\fR\&\&.
.RE
.LP
.B
analyze_file_attribute(Node::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\& \fBanalyze_attribute/1\fR\&\&.
.RE
.LP
.B
analyze_form(Node::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{rule, Info}\fR\&:
where \fIInfo = analyze_rule(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\& \fBanalyze_attribute/1\fR\&, \fBanalyze_function/1\fR\&, \fBanalyze_rule/1\fR\&, \fBerl_syntax:error_marker_info/1\fR\&, \fBerl_syntax:is_form/1\fR\&, \fBerl_syntax:warning_marker_info/1\fR\&\&.
.RE
.LP
.B
analyze_forms(Forms) -> [{Key, term()}]
.br
.RS
.LP
Types:

.RS 3
Forms = syntaxTree() | [syntaxTree()]
.br
Key = attributes | errors | exports | functions | imports | module | records | rules | warnings
.br
.RE
.RE
.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}]\fR\&
.LP
.TP 2
*
\fIDefault = 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\& (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{rules, Rules}\fR\&:

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

.RS 2
.LP
\fIRules\fR\& is a list of the names of the rules that are defined in \fIForms\fR\& (cf\&. \fIanalyze_rule/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{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\& \fBanalyze_export_attribute/1\fR\&, \fBanalyze_function/1\fR\&, \fBanalyze_import_attribute/1\fR\&, \fBanalyze_record_attribute/1\fR\&, \fBanalyze_rule/1\fR\&, \fBanalyze_wild_attribute/1\fR\&, \fBerl_syntax:error_marker_info/1\fR\&, \fBerl_syntax:warning_marker_info/1\fR\&\&.
.RE
.LP
.B
analyze_function(Node::syntaxTree()) -> {atom(), integer()}
.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\&.
.LP
\fISee also:\fR\& \fBanalyze_rule/1\fR\&\&.
.RE
.LP
.B
analyze_function_name(Node::syntaxTree()) -> FunctionName
.br
.RS
.LP
Types:

.RS 3
FunctionName = atom() | {atom(), integer()} | {ModuleName, FunctionName}
.br
ModuleName = atom()
.br
.RE
.RE
.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::syntaxTree()) -> FunctionName
.br
.RS
.LP
Types:

.RS 3
FunctionName = atom() | {atom(), integer()} | {ModuleName, FunctionName}
.br
ModuleName = atom()
.br
.RE
.RE
.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\& \fBanalyze_function_name/1\fR\&\&.
.RE
.LP
.B
analyze_import_attribute(Node::syntaxTree()) -> {atom(), [FunctionName]} | atom()
.br
.RS
.LP
Types:

.RS 3
FunctionName = atom() | {atom(), integer()} | {ModuleName, FunctionName}
.br
ModuleName = atom()
.br
.RE
.RE
.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\& \fBanalyze_attribute/1\fR\&\&.
.RE
.LP
.B
analyze_module_attribute(Node::syntaxTree()) -> Name::atom() | {Name::atom(), Variables::[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\& \fBanalyze_attribute/1\fR\&\&.
.RE
.LP
.B
analyze_record_attribute(Node::syntaxTree()) -> {atom(), Fields}
.br
.RS
.LP
Types:

.RS 3
Fields = [{atom(), none | syntaxTree()}]
.br
.RE
.RE
.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}\fR\& for each field "\fILabel\fR\&" or "\fILabel = Default\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\&\&. We do not guarantee that each label occurs at most one 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\& \fBanalyze_attribute/1\fR\&, \fBanalyze_record_field/1\fR\&\&.
.RE
.LP
.B
analyze_record_expr(Node::syntaxTree()) -> {atom(), Info} | atom()
.br
.RS
.LP
Types:

.RS 3
Info = {atom(), [{atom(), Value}]} | {atom(), atom()} | atom()
.br
Value = none | syntaxTree()
.br
.RE
.RE
.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()} | 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\&. (See \fIanalyze_record_field/1\fR\& for details on the field descriptors)\&. For a \fIrecord_access\fR\& node, \fIInfo\fR\& represents the record name and the field name (or if the record name is not included, only the field name; this is allowed only in Mnemosyne-query syntax)\&. 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\& \fBanalyze_record_attribute/1\fR\&, \fBanalyze_record_field/1\fR\&\&.
.RE
.LP
.B
analyze_record_field(Node::syntaxTree()) -> {atom(), Value}
.br
.RS
.LP
Types:

.RS 3
Value = none | syntaxTree()
.br
.RE
.RE
.RS
.LP
Returns the label and value-expression of a record field specifier\&. The result is a pair \fI{Label, Value}\fR\&, if \fINode\fR\& represents "\fILabel = Value\fR\&" or "\fILabel\fR\&", where in the first case, \fIValue\fR\& is a syntax tree, and in the second case \fIValue\fR\& is \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\& \fBanalyze_record_attribute/1\fR\&, \fBanalyze_record_expr/1\fR\&\&.
.RE
.LP
.B
analyze_rule(Node::syntaxTree()) -> {atom(), integer()}
.br
.RS
.LP
Returns the name and arity of a Mnemosyne rule\&. The result is a pair \fI{Name, A}\fR\& if \fINode\fR\& represents a rule "\fIName(P_1, \&.\&.\&., P_A) :- \&.\&.\&.\fR\&"\&.
.LP
The evaluation throws \fIsyntax_error\fR\& if \fINode\fR\& does not represent a well-formed Mnemosyne rule\&.
.LP
\fISee also:\fR\& \fBanalyze_function/1\fR\&\&.
.RE
.LP
.B
analyze_wild_attribute(Node::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\& \fBanalyze_attribute/1\fR\&\&.
.RE
.LP
.B
annotate_bindings(Tree::syntaxTree()) -> 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\& \fBannotate_bindings/2\fR\&\&.
.RE
.LP
.B
annotate_bindings(Tree::syntaxTree(), Bindings::ordset(atom())) -> 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\& \fBordsets(3)\fR\&, \fBannotate_bindings/1\fR\&\&.
.RE
.LP
.B
fold(F::Function, Start::term(), Tree::syntaxTree()) -> term()
.br
.RS
.LP
Types:

.RS 3
Function = (syntaxTree(), term()) -> term()
.br
.RE
.RE
.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\& \fBfold_subtrees/3\fR\&, \fBfoldl_listlist/3\fR\&\&.
.RE
.LP
.B
fold_subtrees(F::Function, Start::term(), Tree::syntaxTree()) -> term()
.br
.RS
.LP
Types:

.RS 3
Function = (syntaxTree(), term()) -> term()
.br
.RE
.RE
.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\& \fBfold/3\fR\&\&.
.RE
.LP
.B
foldl_listlist(F::Function, Start::term(), Ls::[[term()]]) -> term()
.br
.RS
.LP
Types:

.RS 3
Function = (term(), term()) -> term()
.br
.RE
.RE
.RS
.LP
Like \fIlists:foldl/3\fR\&, but over a list of lists\&.
.LP
\fISee also:\fR\& \fBlists:foldl/3\fR\&, \fBfold/3\fR\&\&.
.RE
.LP
.B
function_name_expansions(Names::[Name]) -> [{ShortName, Name}]
.br
.RS
.LP
Types:

.RS 3
Name = ShortName | {atom(), Name}
.br
ShortName = atom() | {atom(), integer()}
.br
.RE
.RE
.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\& \fBanalyze_function_name/1\fR\&\&.
.RE
.LP
.B
is_fail_expr(Tree::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\& \fBerlang:error/1\fR\&, \fBerlang:error/2\fR\&, \fBerlang:exit/1\fR\&, \fBerlang:throw/1\fR\&\&.
.RE
.LP
.B
limit(Tree, Depth) -> syntaxTree()
.br
.RS
.LP
Equivalent to \fIlimit(Tree, Depth, Text)\fR\& using the text \fI"\&.\&.\&."\fR\& as default replacement\&.
.LP
\fISee also:\fR\& \fBlimit/3\fR\&, \fBerl_syntax:text/1\fR\&\&.
.RE
.LP
.B
limit(Tree::syntaxTree(), Depth::integer(), Node::syntaxTree()) -> 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\& \fBlimit/2\fR\&\&.
.RE
.LP
.B
map(F::Function, Tree::syntaxTree()) -> syntaxTree()
.br
.RS
.LP
Types:

.RS 3
Function = (syntaxTree()) -> syntaxTree()
.br
.RE
.RE
.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\& \fBmap_subtrees/2\fR\&\&.
.RE
.LP
.B
map_subtrees(F::Function, Tree::syntaxTree()) -> syntaxTree()
.br
.RS
.LP
Types:

.RS 3
Function = (Tree) -> Tree1
.br
.RE
.RE
.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\& \fBmap/2\fR\&\&.
.RE
.LP
.B
mapfold(F::Function, Start::term(), Tree::syntaxTree()) -> {syntaxTree(), term()}
.br
.RS
.LP
Types:

.RS 3
Function = (syntaxTree(), term()) -> {syntaxTree(), term()}
.br
.RE
.RE
.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\& \fBfold/3\fR\&, \fBmap/2\fR\&\&.
.RE
.LP
.B
mapfold_subtrees(F::Function, Start::term(), Tree::syntaxTree()) -> {syntaxTree(), term()}
.br
.RS
.LP
Types:

.RS 3
Function = (syntaxTree(), term()) -> {syntaxTree(), term()}
.br
.RE
.RE
.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\& \fBmapfold/3\fR\&\&.
.RE
.LP
.B
mapfoldl_listlist(F::Function, S::State, Ls::[[term()]]) -> {[[term()]], term()}
.br
.RS
.LP
Types:

.RS 3
Function = (term(), term()) -> {term(), term()}
.br
.RE
.RE
.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(Used::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\& \fBnew_variable_name/2\fR\&\&.
.RE
.LP
.B
new_variable_name(F::Function, Used::set(atom())) -> atom()
.br
.RS
.LP
Types:

.RS 3
Function = (integer()) -> atom()
.br
.RE
.RE
.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 \fIrandom\fR\& to generate new keys\&. The seed it uses may be initialized by calling \fIrandom:seed/0\fR\& or \fIrandom:seed/3\fR\& before this function is first called\&.
.LP
\fISee also:\fR\& \fBrandom(3)\fR\&, \fBsets(3)\fR\&, \fBnew_variable_name/1\fR\&\&.
.RE
.LP
.B
new_variable_names(N::integer(), Used::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\& \fBnew_variable_name/1\fR\&\&.
.RE
.LP
.B
new_variable_names(N::integer(), F::Function, Used::set(atom())) -> [atom()]
.br
.RS
.LP
Types:

.RS 3
Function = (integer()) -> atom()
.br
.RE
.RE
.RS
.LP
Like \fInew_variable_name/2\fR\&, but generates a list of \fIN\fR\& new names\&.
.LP
\fISee also:\fR\& \fBnew_variable_name/2\fR\&\&.
.RE
.LP
.B
strip_comments(Tree::syntaxTree()) -> 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) -> syntaxTree()
.br
.RS
.LP
Equivalent to \fBto_comment(Tree, "% ")\fR\&\&.
.RE
.LP
.B
to_comment(Tree::syntaxTree(), Prefix::string()) -> 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\& \fBto_comment/3\fR\&, \fBerl_prettypr:format/1\fR\&\&.
.RE
.LP
.B
to_comment(Tree::syntaxTree(), Prefix::string(), F::Printer) -> syntaxTree()
.br
.RS
.LP
Types:

.RS 3
Printer = (syntaxTree()) -> string()
.br
.RE
.RE
.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\& \fBto_comment/1\fR\&, \fBto_comment/2\fR\&\&.
.RE
.LP
.B
variables(Tree::syntaxTree()) -> set(atom())
.br
.RS
.LP
Types:

.RS 3
set(T) (see module //stdlib/sets)
.br
.RE
.RE
.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\& \fBsets(3)\fR\&\&.
.RE
.SH AUTHORS
.LP
Richard Carlsson
.I
<carlsson\&.richard@gmail\&.com>