erl_syntax_lib(3)



erl_syntax_lib(3erl)       Erlang Module Definition       erl_syntax_lib(3erl)

NAME
       erl_syntax_lib - Support library for abstract Erlang syntax trees.

DESCRIPTION
       Support library for abstract Erlang syntax trees.

       This  module  contains  utility functions for working with the abstract
       data type defined in the module erl_syntax.

DATA TYPES
         info_pair() = {key(), term()}:

         key() = attributes | errors | exports | functions | imports |  module
         | records | warnings:

         ordset(T) = ordsets:ordset(T):

         set(T) = sets:set(T):

         syntaxTree() = erl_syntax:syntaxTree():

           An abstract syntax tree. See the erl_syntax module for details.

EXPORTS
       analyze_application(Node::syntaxTree()) -> FunctionName | Arity

              Types:

                 FunctionName = {atom(), Arity} | {ModuleName, FunctionName}
                 Arity = integer()
                 ModuleName = atom()

              Returns the name of a called function. The result is a represen-
              tation of the name of the applied function F/A, if  Node  repre-
              sents  a  function  application  "<em>F</em>(<em>X_1</em>,  ...,
              <em>X_A</em>)". If the function is not explicitly named (i.e., F
              is given by some expression), only the arity A is returned.

              The  evaluation throws syntax_error if Node does not represent a
              well-formed application expression.

              See also: analyze_function_name/1.

       analyze_attribute(Node::syntaxTree())  ->   preprocessor   |   {atom(),
       atom()}

              Analyzes  an  attribute  node. If Node represents a preprocessor
              directive, the atom preprocessor is returned. Otherwise, if Node
              represents  a  module  attribute  "-<em>Name</em>...",  a  tuple
              {Name, Info} is returned, where Info depends on  Name,  as  fol-
              lows:

                {module, Info}:
                  where Info = analyze_module_attribute(Node).

                {export, Info}:
                  where Info = analyze_export_attribute(Node).

                {import, Info}:
                  where Info = analyze_import_attribute(Node).

                {file, Info}:
                  where Info = analyze_file_attribute(Node).

                {record, Info}:
                  where Info = analyze_record_attribute(Node).

                {Name, Info}:
                  where {Name, Info} = analyze_wild_attribute(Node).

              The  evaluation throws syntax_error if Node does not represent a
              well-formed module attribute.

              See also: analyze_export_attribute/1,  analyze_file_attribute/1,
              analyze_import_attribute/1,   analyze_module_attribute/1,   ana-
              lyze_record_attribute/1, analyze_wild_attribute/1.

       analyze_export_attribute(Node::syntaxTree()) -> [FunctionName]

              Types:

                 FunctionName = atom() | {atom(),  integer()}  |  {ModuleName,
                 FunctionName}
                 ModuleName = atom()

              Returns  the list of function names declared by an export attri-
              bute. We do not guarantee that each name occurs at most once  in
              the list. The order of listing is not defined.

              The  evaluation throws syntax_error if Node does not represent a
              well-formed export attribute.

              See also: analyze_attribute/1.

       analyze_file_attribute(Node::syntaxTree()) -> {string(), integer()}

              Returns the file name and line number of a file  attribute.  The
              result  is the pair {File, Line} if Node represents "-file(File,
              Line).".

              The evaluation throws syntax_error if Node does not represent  a
              well-formed file attribute.

              See also: analyze_attribute/1.

       analyze_form(Node::syntaxTree()) -> {atom(), term()} | atom()

              Analyzes  a  "source  code  form" node. If Node is a "form" type
              (cf. erl_syntax:is_form/1), the returned value is a tuple {Type,
              Info}  where  Type is the node type and Info depends on Type, as
              follows:

                {attribute, Info}:
                  where Info = analyze_attribute(Node).

                {error_marker, Info}:
                  where Info = erl_syntax:error_marker_info(Node).

                {function, Info}:
                  where Info = analyze_function(Node).

                {warning_marker, Info}:
                  where Info = erl_syntax:warning_marker_info(Node).

              For other types of forms, only the node type is returned.

              The evaluation throws syntax_error if Node is not well-formed.

              See  also:  analyze_attribute/1,  analyze_function/1,   erl_syn-
              tax:error_marker_info/1,  erl_syntax:is_form/1, erl_syntax:warn-
              ing_marker_info/1.

       analyze_forms(Forms) -> [{Key, term()}]

              Types:

                 Forms = syntaxTree() | [syntaxTree()]
                 Key = attributes | errors | exports | functions |  imports  |
                 module | records | warnings

              Analyzes a sequence of "program forms". The given Forms may be a
              single syntax tree of type form_list,  or  a  list  of  "program
              form"  syntax trees. The returned value is a list of pairs {Key,
              Info}, where each value of Key occurs at most once in the  list;
              the absence of a particular key indicates that there is no well-
              defined value for that key.

              Each entry in the resulting list contains the  following  corre-
              sponding information about the program forms:

                {attributes, Attributes}:

                  * Attributes = [{atom(), term()}]

                  Attributes  is  a  list  of pairs representing the names and
                  corresponding values of all so-called "wild" attributes  (as
                  e.g.   "-compile(...)")   occurring   in   Forms  (cf.  ana-
                  lyze_wild_attribute/1). We do not guarantee that  each  name
                  occurs at most once in the list. The order of listing is not
                  defined.

                {errors, Errors}:

                  * Errors = [term()]

                  Errors is the list of error descriptors of all  error_marker
                  nodes  that  occur in Forms. The order of listing is not de-
                  fined.

                {exports, Exports}:

                  * Exports = [FunctionName]

                  * FunctionName = atom() | {atom(), integer()} | {ModuleName,
                    FunctionName}

                  * ModuleName = atom()

                  Exports is a list of representations of those function names
                  that are listed by export declaration  attributes  in  Forms
                  (cf.  analyze_export_attribute/1).  We do not guarantee that
                  each name occurs at most once in  the  list.  The  order  of
                  listing is not defined.

                {functions, Functions}:

                  * Functions = [{atom(), integer()}]

                  Functions  is  a list of the names of the functions that are
                  defined in Forms (cf. analyze_function/1). We do not guaran-
                  tee  that each name occurs at most once in the list. The or-
                  der of listing is not defined.

                {imports, Imports}:

                  * Imports = [{Module, Names}]

                  * Module = atom()

                  * Names = [FunctionName]

                  * FunctionName = atom() | {atom(), integer()} | {ModuleName,
                    FunctionName}

                  * ModuleName = atom()

                  Imports  is  a list of pairs representing those module names
                  and corresponding function names that are listed  by  import
                  declaration  attributes  in Forms (cf. analyze_import_attri-
                  bute/1), where each Module occurs at most once  in  Imports.
                  We  do  not  guarantee that each name occurs at most once in
                  the lists of function names. The order of listing is not de-
                  fined.

                {module, ModuleName}:

                  * ModuleName = atom()

                  ModuleName  is  the  name  declared by a module attribute in
                  Forms. If no module name is defined  in  Forms,  the  result
                  will contain no entry for the module key. If multiple module
                  name declarations should occur, all but the  first  will  be
                  ignored.

                {records, Records}:

                  * Records = [{atom(), Fields}]

                  * Fields = [{atom(), {Default, Type}}]

                  * Default = none | syntaxTree()

                  * Type = none | syntaxTree()

                  Records is a list of pairs representing the names and corre-
                  sponding field declarations of all  record  declaration  at-
                  tributes  occurring  in Forms. For fields declared without a
                  default value, the corresponding value for  Default  is  the
                  atom  none.  Similarly,  for fields declared without a type,
                  the corresponding value for Type is the atom none (cf.  ana-
                  lyze_record_attribute/1).  We  do  not  guarantee  that each
                  record name occurs at most once in the list.  The  order  of
                  listing is not defined.

                {warnings, Warnings}:

                  * Warnings = [term()]

                  Warnings  is  the  list  of  error  descriptors of all warn-
                  ing_marker nodes that occur in Forms. The order  of  listing
                  is not defined.

              The  evaluation throws syntax_error if an ill-formed Erlang con-
              struct is encountered.

              See also: analyze_export_attribute/1,  analyze_function/1,  ana-
              lyze_import_attribute/1,     analyze_record_attribute/1,    ana-
              lyze_wild_attribute/1, erl_syntax:error_marker_info/1,  erl_syn-
              tax:warning_marker_info/1.

       analyze_function(Node::syntaxTree()) -> {atom(), integer()}

              Returns  the name and arity of a function definition. The result
              is a pair {Name, A} if Node  represents  a  function  definition
              "Name(<em>P_1</em>, ..., <em>P_A</em>) -> ...".

              The  evaluation throws syntax_error if Node does not represent a
              well-formed function definition.

       analyze_function_name(Node::syntaxTree()) -> FunctionName

              Types:

                 FunctionName = atom() | {atom(),  integer()}  |  {ModuleName,
                 FunctionName}
                 ModuleName = atom()

              Returns  the function name represented by a syntax tree. If Node
              represents a function name, such as "foo/1" or  "bloggs:fred/2",
              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.

              The  evaluation throws syntax_error if Node does not represent a
              well-formed function name.

       analyze_implicit_fun(Node::syntaxTree()) -> FunctionName

              Types:

                 FunctionName = atom() | {atom(),  integer()}  |  {ModuleName,
                 FunctionName}
                 ModuleName = atom()

              Returns the name of an implicit fun expression "fun <em>F</em>".
              The result is a representation of the function name F. (Cf. ana-
              lyze_function_name/1.)

              The  evaluation throws syntax_error if Node does not represent a
              well-formed implicit fun.

              See also: analyze_function_name/1.

       analyze_import_attribute(Node::syntaxTree())  ->  {atom(),   [Function-
       Name]} | atom()

              Types:

                 FunctionName  =  atom()  | {atom(), integer()} | {ModuleName,
                 FunctionName}
                 ModuleName = atom()

              Returns the module name and (if present) list of function  names
              declared  by  an import attribute. The returned value is an atom
              Module or a pair {Module, Names}, where Names is a list of func-
              tion names declared as imported from the module named by Module.
              We do not guarantee that each name occurs at most once in Names.
              The order of listing is not defined.

              The  evaluation throws syntax_error if Node does not represent a
              well-formed import attribute.

              See also: analyze_attribute/1.

       analyze_module_attribute(Node::syntaxTree())    ->    Name::atom()    |
       {Name::atom(), Variables::[atom()]}

              Returns  the  module  name and possible parameters declared by a
              module attribute. If the attribute is a plain module declaration
              such as -module(name), the result is the module name. If the at-
              tribute is a parameterized module declaration, the result  is  a
              tuple  containing  the  module  name and a list of the parameter
              variable names.

              The evaluation throws syntax_error if Node does not represent  a
              well-formed module attribute.

              See also: analyze_attribute/1.

       analyze_record_attribute(Node::syntaxTree()) -> {atom(), Fields}

              Types:

                 Fields = [{atom(), {Default, Type}}]
                 Default = none | syntaxTree()
                 Type = none | syntaxTree()

              Returns  the name and the list of fields of a record declaration
              attribute. The result is a pair {Name, Fields}, if  Node  repre-
              sents  "-record(Name,  {...}).", where Fields is a list of pairs
              {Label, {Default,  Type}}  for  each  field  "Label",  "Label  =
              <em>Default</em>", "Label :: <em>Type</em>", or "Label = <em>De-
              fault</em> :: <em>Type</em>" in the declaration, listed in left-
              to-right  order.  If the field has no default-value declaration,
              the value for Default will be the atom none. If the field has no
              type  declaration,  the value for Type will be the atom none. We
              do not guarantee that each label occurs  at  most  once  in  the
              list.

              The  evaluation throws syntax_error if Node does not represent a
              well-formed record declaration attribute.

              See also: analyze_attribute/1, analyze_record_field/1.

       analyze_record_expr(Node::syntaxTree()) -> {atom(), Info} | atom()

              Types:

                 Info = {atom(),  [{atom(),  Value}]}  |  {atom(),  atom()}  |
                 atom()
                 Value = syntaxTree()

              Returns the record name and field name/names of a record expres-
              sion.  If  Node  has  type  record_expr,  record_index_expr   or
              record_access,  a  pair  {Type,  Info} is returned, otherwise an
              atom Type is returned. Type is the node type of Node,  and  Info
              depends on Type, as follows:

                record_expr::
                  {atom(), [{atom(), Value}]}

                record_access::
                  {atom(), atom()}

                record_index_expr::
                  {atom(), atom()}

              For  a record_expr node, Info 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 {Label, Value}, if
              Node represents "Label = <em>Value</em>".  For  a  record_access
              node,  Info represents the record name and the field name. For a
              record_index_expr node, Info represents the record name and  the
              name field name.

              The  evaluation  throws syntax_error if Node represents a record
              expression that is not well-formed.

              See also: analyze_record_attribute/1, analyze_record_field/1.

       analyze_record_field(Node::syntaxTree()) -> {atom(), {Default, Type}}

              Types:

                 Default = none | syntaxTree()
                 Type = none | syntaxTree()

              Returns the label, value-expression, and type of a record  field
              specifier.  The  result  is  a pair {Label, {Default, Type}}, if
              Node represents "Label", "Label = <em>Default</em>",  "Label  ::
              <em>Type</em>",  or "Label = <em>Default</em> :: <em>Type</em>".
              If the field has no value-expression, the value for Default will
              be  the  atom none. If the field has no type, the value for Type
              will be the atom none.

              The evaluation throws syntax_error if Node does not represent  a
              well-formed record field specifier.

              See also: analyze_record_attribute/1, analyze_record_expr/1.

       analyze_type_application(Node::syntaxTree()) -> TypeName

              Types:

                 TypeName  = {atom(), integer()} | {ModuleName, {atom(), inte-
                 ger()}}
                 ModuleName = atom()

              Returns the name of a used type. The result is a  representation
              of  the  name of the used pre-defined or local type N/A, if Node
              represents     a     local     (user)      type      application
              "<em>N</em>(<em>T_1</em>,  ..., <em>T_A</em>)", or a representa-
              tion of the name of the used remote type M:N/A  if  Node  repre-
              sents       a       remote       user      type      application
              "<em>M</em>:<em>N</em>(<em>T_1</em>, ..., <em>T_A</em>)".

              The evaluation throws syntax_error if Node does not represent  a
              well-formed (user) type application expression.

              See also: analyze_type_name/1.

       analyze_type_name(Node::syntaxTree()) -> TypeName

              Types:

                 TypeName  =  atom()  |  {atom(),  integer()}  |  {ModuleName,
                 {atom(), integer()}}
                 ModuleName = atom()

              Returns the type name represented by a syntax tree. If Node rep-
              resents  a type name, such as "foo/1" or "bloggs:fred/2", a uni-
              form representation of that name is returned.

              The evaluation throws syntax_error if Node does not represent  a
              well-formed type name.

       analyze_wild_attribute(Node::syntaxTree()) -> {atom(), term()}

              Returns  the name and value of a "wild" attribute. The result is
              the pair {Name, Value}, if Node represents "-Name(Value)".

              Note that no checking is done whether Name is a reserved  attri-
              bute  name  such as module or export: it is assumed that the at-
              tribute is "wild".

              The evaluation throws syntax_error if Node does not represent  a
              well-formed wild attribute.

              See also: analyze_attribute/1.

       annotate_bindings(Tree::syntaxTree()) -> syntaxTree()

              Adds  or  updates annotations on nodes in a syntax tree. Equiva-
              lent to annotate_bindings(Tree, Bindings)  where  the  top-level
              environment  Bindings  is  taken from the annotation {env, Bind-
              ings} on the root node of Tree. An exception  is  thrown  if  no
              such annotation should exist.

              See also: annotate_bindings/2.

       annotate_bindings(Tree::syntaxTree(), Bindings::ordset(atom())) -> syn-
       taxTree()

              Adds or updates annotations on nodes in a syntax tree.  Bindings
              specifies  the  set of bound variables in the environment of the
              top level node. The following annotations are affected:

                * {env, Vars}, representing the input environment of the  sub-
                  tree.

                * {bound,  Vars}, representing the variables that are bound in
                  the subtree.

                * {free, Vars}, representing the free variables  in  the  sub-
                  tree.

              Bindings  and Vars are ordered-set lists (cf. module ordsets) of
              atoms representing variable names.

              See also: ordsets(3erl), annotate_bindings/1.

       fold(F::Function, Start::term(), Tree::syntaxTree()) -> term()

              Types:

                 Function = (syntaxTree(), term()) -> term()

              Folds a function over all nodes of a syntax tree. The result  is
              the  value  of Function(X1, Function(X2, ... Function(Xn, Start)
              ... )), where [X1, X2, ..., Xn] are the nodes of Tree in a post-
              order traversal.

              See also: fold_subtrees/3, foldl_listlist/3.

       fold_subtrees(F::Function, Start::term(), Tree::syntaxTree()) -> term()

              Types:

                 Function = (syntaxTree(), term()) -> term()

              Folds  a  function over the immediate subtrees of a syntax tree.
              This is similar to fold/3, but only on the immediate subtrees of
              Tree,  in left-to-right order; it does not include the root node
              of Tree.

              See also: fold/3.

       foldl_listlist(F::Function, Start::term(), Ls::[[term()]]) -> term()

              Types:

                 Function = (term(), term()) -> term()

              Like lists:foldl/3, but over a list of lists.

              See also: lists:foldl/3, fold/3.

       function_name_expansions(Names::[Name]) -> [{ShortName, Name}]

              Types:

                 Name = ShortName | {atom(), Name}
                 ShortName = atom() | {atom(), integer()}

              Creates a mapping from corresponding short names to  full  func-
              tion  names. Names are represented by nested tuples of atoms and
              integers (cf. analyze_function_name/1). The  result  is  a  list
              containing a pair {ShortName, Name} for each element Name in the
              given list, where the corresponding ShortName is the  rightmost-
              innermost  part  of Name. The list thus represents a finite map-
              ping from  unqualified  names  to  the  corresponding  qualified
              names.

              Note: the resulting list can contain more than one tuple {Short-
              Name, Name} for the same ShortName, possibly with different val-
              ues for Name, depending on the given list.

              See also: analyze_function_name/1.

       is_fail_expr(Tree::syntaxTree()) -> boolean()

              Returns true if Tree represents an expression which never termi-
              nates normally. Note that the reverse does not apply. Currently,
              the  detected cases are calls to exit/1, throw/1, erlang:error/1
              and erlang:error/2.

              See also:  erlang:error/1,  erlang:error/2,  erlang:exit/1,  er-
              lang:throw/1.

       limit(Tree, Depth) -> syntaxTree()

              Equivalent  to  limit(Tree, Depth, Text) using the text "..." as
              default replacement.

              See also: limit/3, erl_syntax:text/1.

       limit(Tree::syntaxTree(), Depth::integer(), Node::syntaxTree()) -> syn-
       taxTree()

              Limits a syntax tree to a specified depth. Replaces all non-leaf
              subtrees in Tree at the given Depth by Node. If Depth  is  nega-
              tive, the result is always Node, even if Tree has no subtrees.

              When  a  group of subtrees (as e.g., the argument list of an ap-
              plication node) is at the specified depth, and there are two  or
              more  subtrees in the group, these will be collectively replaced
              by Node 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 pre-
              vious. E.g., if Tree represents a list of integers "[1, 2, 3, 4,
              5, 6, 7, 8, 9, 10]", the result of limit(Tree, 5) will represent
              [1, 2, 3, 4, ...].

              The  resulting  syntax tree is typically only useful for pretty-
              printing or similar visual formatting.

              See also: limit/2.

       map(F::Function, Tree::syntaxTree()) -> syntaxTree()

              Types:

                 Function = (syntaxTree()) -> syntaxTree()

              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.

              See also: map_subtrees/2.

       map_subtrees(F::Function, Tree::syntaxTree()) -> syntaxTree()

              Types:

                 Function = (Tree) -> Tree1

              Applies a function to each immediate subtree of a  syntax  tree.
              The result of each application replaces the corresponding origi-
              nal node.

              See also: map/2.

       mapfold(F::Function,  Start::term(),  Tree::syntaxTree())  ->  {syntax-
       Tree(), term()}

              Types:

                 Function = (syntaxTree(), term()) -> {syntaxTree(), term()}

              Combines  map and fold in a single operation. This is similar to
              map/2, but also propagates an extra value from each  application
              of  the Function to the next, while doing a post-order traversal
              of the tree like fold/3. The value Start is passed to the  first
              function  application, and the final result is the result of the
              last application.

              See also: fold/3, map/2.

       mapfold_subtrees(F::Function,  Start::term(),  Tree::syntaxTree())   ->
       {syntaxTree(), term()}

              Types:

                 Function = (syntaxTree(), term()) -> {syntaxTree(), term()}

              Does a mapfold operation over the immediate subtrees of a syntax
              tree. This is similar to mapfold/3, but only  on  the  immediate
              subtrees  of  Tree,  in left-to-right order; it does not include
              the root node of Tree.

              See also: mapfold/3.

       mapfoldl_listlist(F::Function,     S::State,     Ls::[[term()]])     ->
       {[[term()]], term()}

              Types:

                 Function = (term(), term()) -> {term(), term()}

              Like  lists:mapfoldl/3,  but  over  a list of lists. The list of
              lists in the result has the same structure as the given list  of
              lists.

       new_variable_name(Used::set(atom())) -> atom()

              Returns  an  atom  which is not already in the set Used. This is
              equivalent to new_variable_name(Function, Used), where  Function
              maps  a  given  integer N to the atom whose name consists of "V"
              followed by the numeral for N.

              See also: new_variable_name/2.

       new_variable_name(F::Function, Used::set(atom())) -> atom()

              Types:

                 Function = (integer()) -> atom()

              Returns a user-named atom which is not already in the set  Used.
              The atom is generated by applying the given Function to a gener-
              ated 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.

              This function uses the module rand to  generate  new  keys.  The
              seed  it  uses  may  be  initialized  by  calling rand:seed/1 or
              rand:seed/2 before this function is first called.

              See also: random(3erl), sets(3erl), new_variable_name/1.

       new_variable_names(N::integer(), Used::set(atom())) -> [atom()]

              Like new_variable_name/1, but generates a list of N new names.

              See also: new_variable_name/1.

       new_variable_names(N::integer(),  F::Function,  Used::set(atom()))   ->
       [atom()]

              Types:

                 Function = (integer()) -> atom()

              Like new_variable_name/2, but generates a list of N new names.

              See also: new_variable_name/2.

       strip_comments(Tree::syntaxTree()) -> syntaxTree()

              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 stand-
              alone comments are changed into null-comments (no text,  no  in-
              dentation).

       to_comment(Tree) -> syntaxTree()

              Equivalent to to_comment(Tree, "% ").

       to_comment(Tree::syntaxTree(), Prefix::string()) -> syntaxTree()

              Equivalent  to to_comment(Tree, Prefix, F) for a default format-
              ting function F. The default F  simply  calls  erl_prettypr:for-
              mat/1.

              See also: to_comment/3, erl_prettypr:format/1.

       to_comment(Tree::syntaxTree(), Prefix::string(), F::Printer) -> syntax-
       Tree()

              Types:

                 Printer = (syntaxTree()) -> string()

              Transforms a syntax tree into an abstract comment. The lines  of
              the  comment contain the text for Node, as produced by the given
              Printer function. Each line of the comment is  prefixed  by  the
              string  Prefix  (this does not include the initial "%" character
              of the comment line).

              For   example,   the   result    of    to_comment(erl_syntax:ab-
              stract([a,b,c])) represents

                        %% [a,b,c]

              (cf. to_comment/1).

              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.

              See also: to_comment/1, to_comment/2.

       variables(Tree::syntaxTree()) -> set(atom())

              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.

              See also: sets(3erl).

AUTHORS
       Richard Carlsson <carlsson.richard@gmail.com>

                               syntax_tools 2.3           erl_syntax_lib(3erl)

Man(1) output converted with man2html
list of all man pages