👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for erl_syntax_lib (linux section 3erl)

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 | rules |
	 warnings :

	 ordset(T) = ordset(T) (see module //stdlib/ordsets) :

	 syntaxTree() = syntaxTree() (see module erl_syntax) :

	   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 representation of the name
	      of the applied  function	F/A  ,	if  Node  represents  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  appli-
	      cation 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 follows:

		{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	 ,   ana-
	      lyze_import_attribute/1 , analyze_module_attribute/1 , analyze_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 attribute. We do not guar-
	      antee 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_syn-
	      tax: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) .

		{rule, Info} :
		  where Info = analyze_rule(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  ,  analyze_rule/1  ,  erl_syn-
	      tax:error_marker_info/1 , erl_syntax:is_form/1 , erl_syntax:warning_marker_info/1 .

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

	      Types  Forms = syntaxTree() | [syntaxTree()]
		     Key = attributes | errors | exports | functions | imports | module | records
		     | rules | 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  corresponding  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.  analyze_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 defined.

		{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 guarantee that each name occurs at most
		  once in the list. The order 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_attribute/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 func-
		  tion names. The order of listing is not defined.

		{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}]

		  * Default = none | syntaxTree()

		  Records  is a list of pairs representing the names and corresponding field dec-
		  larations of all record declaration attributes occurring in Forms . For  fields
		  declared  without  a	default value, the corresponding value for Default is the
		  atom none (cf. analyze_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.

		{rules, Rules} :

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

		  Rules is a list of the names of the rules that are defined in Forms  (cf.  ana-
		  lyze_rule/1  ).  We  do not guarantee that each 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  warning_marker  nodes  that
		  occur in Forms . The order of listing is not defined.

	      The  evaluation  throws  syntax_error  if an ill-formed Erlang construct is encoun-
	      tered.

	      See    also:    analyze_export_attribute/1    ,	 analyze_function/1    ,     ana-
	      lyze_import_attribute/1	,  analyze_record_attribute/1  ,  analyze_rule/1  ,  ana-
	      lyze_wild_attribute/1   ,   erl_syntax:error_marker_info/1    ,	 erl_syntax:warn-
	      ing_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 func-
	      tion definition.

	      See also: analyze_rule/1 .

       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  func-
	      tion 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 func-
	      tion 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. analyze_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(), [FunctionName]} | 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 function 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(),  Vari-
       ables::[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 attribute 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(), none | syntaxTree()}]

	      Returns the name and the list of fields of  a  record  declaration  attribute.  The
	      result  is  a  pair  {Name, Fields} , if Node represents " -record(Name, {...}). ",
	      where Fields is a list of pairs {Label, Default} for each field  "  Label  "  or	"
	      Label  =	<em>Default</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 . We do not guarantee that each label occurs at most one 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 = none | syntaxTree()

	      Returns the record name and field name/names of a record expression.  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()} | 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.   (See   ana-
	      lyze_record_field/1  for	details  on  the  field descriptors). For a record_access
	      node, Info 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 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(), Value}

	      Types  Value = none | syntaxTree()

	      Returns the label and value-expression of a record field specifier. The result is a
	      pair  {Label,  Value} , if Node represents " Label = <em>Value</em> " or " Label ",
	      where in the first case, Value is a syntax tree, and in the second  case	Value  is
	      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_rule(Node::syntaxTree()) -> {atom(), integer()}

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

	      The  evaluation  throws  syntax_error  if  Node  does  not  represent a well-formed
	      Mnemosyne rule.

	      See also: analyze_function/1 .

       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 attribute name such as
	      module or export : it is assumed that the attribute 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. Equivalent to annotate_bind-
	      ings(Tree, Bindings) where the top-level environment Bindings  is  taken	from  the
	      annotation  {env, Bindings} 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())) -> syntaxTree()

	      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 annota-
	      tions are affected:

		* {env, Vars} , representing the input environment of the subtree.

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

		* {free, Vars} , representing the free variables in the subtree.

	      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 Func-
	      tion(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 function 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 mapping from unqualified names to the
	      corresponding qualified names.

	      Note: the resulting list can contain more than one tuple {ShortName, Name} for  the
	      same  ShortName  , possibly with different values 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 terminates 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 , erlang: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()) -> syntaxTree()

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

	      When a group of subtrees (as e.g., the argument list of an application 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 previous. 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 original node.

	      See also: map/2 .

       mapfold(F::Function, Start::term(), Tree::syntaxTree()) -> {syntaxTree(), 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 sim-
	      ilar 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 gener-
	      ated  by applying the given Function to a generated integer. Integers are generated
	      using an algorithm which tries to keep the names randomly distributed within a rea-
	      sonably small range relative to the number of elements in the set.

	      This  function uses the module random to generate new keys. The seed it uses may be
	      initialized by calling random:seed/0 or random:seed/3 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 standalone comments are changed into null-comments (no text, no
	      indentation).

       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 formatting function F . The
	      default F simply calls erl_prettypr:format/1 .

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

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

	      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:abstract([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())

	      Types  set(T) (see module //stdlib/sets)

	      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 <richardc@it.uu.se >

					syntax_tools 1.6.7		     erl_syntax_lib(3erl)


All times are GMT -4. The time now is 07:44 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password