From 7dc58ca03d6c59dadfb6c570b97e05c08644041b Mon Sep 17 00:00:00 2001
From: Richard Carlsson The user may (for special purposes) create additional nodes
-%% with other type tags, using the Note: The primary constructor functions for a node type should
-%% always have the same name as the node type itself. A node of type Note: not all literals are leaf nodes, and vice versa. E.g.,
+%% Note: not all literals are leaf nodes, and vice versa. E.g.,
%% tuples with nonzero arity and nonempty lists may be literals, but are
%% not leaf nodes. Variables, on the other hand, are leaf nodes but not
-%% literals. This is equivalent to If possible, the comment should be moved before any preceding
+%% If possible, the comment should be moved before any preceding
%% separator characters on the same line. E.g.:
-%% erl_parse
(often referred to as "parse
+%% parser module `erl_parse' (often referred to as "parse
%% trees", which is a bit of a misnomer). This means that all
-%% erl_parse
trees are valid abstract syntax trees, but the
+%% `erl_parse' trees are valid abstract syntax trees, but the
%% reverse is not true: abstract syntax trees can in general not be used
-%% as input to functions expecting an erl_parse
tree.
+%% as input to functions expecting an `erl_parse' tree.
%% However, as long as an abstract syntax tree represents a correct
-%% Erlang program, the function revert/1
should be able to
-%% transform it to the corresponding erl_parse
+%% Erlang program, the function {@link revert/1} should be able to
+%% transform it to the corresponding `erl_parse'
%% representation.
%%
-%% A recommended starting point for the first-time user is the
-%% documentation of the syntaxTree()
data type, and
-%% the function type/1
.
+%% A recommended starting point for the first-time user is the documentation
+%% of the {@link syntaxTree()} data type, and the function {@link type/1}.
%%
-%% NOTES:
+%% == NOTES: ==
%%
%% This module deals with the composition and decomposition of
%% syntactic entities (as opposed to semantic ones); its
@@ -50,36 +47,31 @@
%% in general, the user is assumed to pass type-correct arguments - if
%% this is not done, the effects are not defined.
%%
-%% With the exception of the erl_parse
data structures,
+%% With the exception of the {@link erl_parse()} data structures,
%% the internal representations of abstract syntax trees are subject to
%% change without notice, and should not be documented outside this
%% module. Furthermore, we do not give any guarantees on how an abstract
%% syntax tree may or may not be represented, with the following
%% exceptions: no syntax tree is represented by a single atom, such
-%% as none
, by a list constructor [X | Y]
, or
-%% by the empty list []
. This can be relied on when writing
+%% as `none', by a list constructor `[X | Y]', or
+%% by the empty list `[]'. This can be relied on when writing
%% functions that operate on syntax trees.
-%% @type syntaxTree(). An abstract syntax tree. The
-%% erl_parse
"parse tree" representation is a subset of the
-%% syntaxTree()
representation.
+%% @type syntaxTree(). An abstract syntax tree. The {@link erl_parse()}
+%% "parse tree" representation is a proper subset of the `syntaxTree()'
+%% representation.
%%
%% Every abstract syntax tree node has a type, given by the
-%% function type/1
. Each node also
-%% has associated attributes; see get_attrs/1
for details. The
-%% functions make_tree/2
and subtrees/1
are generic
+%% function {@link type/1}. Each node also has associated
+%% attributes; see {@link get_attrs/1} for details. The functions
+%% {@link make_tree/2} and {@link subtrees/1} are generic
%% constructor/decomposition functions for abstract syntax trees. The
-%% functions abstract/1
and concrete/1
convert between
+%% functions {@link abstract/1} and {@link concrete/1} convert between
%% constant Erlang terms and their syntactic representations. The set of
-%% syntax tree nodes is extensible through the tree/2
function.
+%% syntax tree nodes is extensible through the {@link tree/2} function.
%%
-%% A syntax tree can be transformed to the erl_parse
-%% representation with the revert/1
-%% function.
+%% A syntax tree can be transformed to the {@link erl_parse()}
+%% representation with the {@link revert/1} function.
-module(erl_syntax).
@@ -396,8 +388,7 @@
-type erl_parse() :: erl_parse:abstract_form() | erl_parse:abstract_expr().
%% The representation built by the Erlang standard library parser
-%% `erl_parse'. This is a subset of the `syntaxTree' type.
+%% `erl_parse'. This is a subset of the {@link syntaxTree()} type.
%% =====================================================================
%%
@@ -407,10 +398,11 @@
%% =====================================================================
-%% @doc Returns the type tag of Node
. If Node
+%% @doc Returns the type tag of `Node'. If `Node'
%% does not represent a syntax tree, evaluation fails with reason
-%% badarg
. Node types currently defined by this module are:
-%%
+%% `badarg'. Node types currently defined by this module are:
+%%
+%%
%%
%%
-%% application
%% arity_qualifier
@@ -477,12 +469,13 @@
%% variable
%% warning_marker
%% tree/2
function.true
if Node
is a leaf node,
-%% otherwise false
. The currently recognised leaf node
+%% @doc Returns `true' if `Node' is a leaf node,
+%% otherwise `false'. The currently recognised leaf node
%% types are:
-%%
+%%
+%%
%%
-%%
-%% atom
-%% char
-%% comment
-%% eof_marker
+%% error_marker
`atom'
+%% `char'
+%% `comment'
+%% `eof_marker'
+%% `error_marker'
%%
-%%
-%% float
-%% integer
-%% nil
-%% operator
+%% string
`float'
+%% `integer'
+%% `nil'
+%% `operator'
+%% `string'
%%
-%%
-%%
-%% text
-%% underscore
-%% variable
+%% warning_marker
`text'
+%% `underscore'
+%% `variable'
+%% `warning_marker'
%% tuple
is a leaf node if and only if
-%% its arity is zero.true
if Node
is a syntax tree
+%% @doc Returns `true' if `Node' is a syntax tree
%% representing a so-called "source code form", otherwise
-%% false
. Forms are the Erlang source code units which,
+%% `false'. Forms are the Erlang source code units which,
%% placed in sequence, constitute an Erlang program. Current form types
%% are:
-%%
+%%
+%%
%%
-%%
-%% attribute
-%% comment
-%% error_marker
-%% eof_marker
+%% form_list
`attribute'
+%% `comment'
+%% `error_marker'
+%% `eof_marker'
+%% `form_list'
%%
-%%
-%%
-%% function
-%% rule
-%% warning_marker
+%% text
`function'
+%% `rule'
+%% `warning_marker'
+%% `text'
%% Node
. This is usually a nonnegative integer (indicating
+%% `Node'. This is usually a nonnegative integer (indicating
%% the source code line number), but may be any term. By default, all
%% new tree nodes have their associated position information set to the
%% integer zero.
@@ -745,8 +741,7 @@ get_pos(Node) ->
%% =====================================================================
-%% @doc Sets the position information of Node
to
-%% Pos
.
+%% @doc Sets the position information of `Node' to `Pos'.
%%
%% @see get_pos/1
%% @see copy_pos/2
@@ -767,11 +762,10 @@ set_pos(Node, Pos) ->
%% =====================================================================
-%% @doc Copies the position information from Source
to
-%% Target
.
+%% @doc Copies the position information from `Source' to `Target'.
%%
-%% set_pos(Target,
-%% get_pos(Source))
, but potentially more efficient.
-%% % Pre-comment of function
-%% foo(X) -> {bar, X}.
+%% ```% Pre-comment of function
+%% foo(X) -> {bar, X}.'''
%%
-%%
-%% foo([X | Xs]) ->
-%% % Pre-comment of 'bar(X)' node
-%% [bar(X) | foo(Xs)];
-%% ...
-%% (where the comment is moved before the "[
").
Node
to
-%% Comments
. Comments
should be a possibly
+%% @doc Sets the pre-comments of `Node' to
+%% `Comments'. `Comments' should be a possibly
%% empty list of abstract comments, in top-down textual order.
%%
%% @see comment/2
@@ -865,12 +857,11 @@ set_precomments_1(#attr{com = Com} = Attr, Cs) ->
%% =====================================================================
-%% @doc Appends Comments
to the pre-comments of
-%% Node
.
+%% @doc Appends `Comments' to the pre-comments of `Node'.
%%
-%% Note: This is equivalent to set_precomments(Node,
-%% get_precomments(Node) ++ Comments)
, but potentially more
-%% efficient.
-%% {foo, X, Y} % Post-comment of tuple+%% ```{foo, X, Y} % Post-comment of tuple''' %% -%%
If possible, the comment should be moved past any following +%% If possible, the comment should be moved past any following %% separator characters on the same line, rather than placing the %% separators on the following line. E.g.: -%%
-%% foo([X | Xs], Y) -> -%% foo(Xs, bar(X)); % Post-comment of 'bar(X)' node -%% ...-%% (where the comment is moved past the rightmost "
)
" and
-%% the ";
").
+%% ```foo([X | Xs], Y) ->
+%% foo(Xs, bar(X)); % Post-comment of 'bar(X)' node
+%% ...'''
+%% (where the comment is moved past the rightmost "`)'" and
+%% the "`;'").
%%
%% @see comment/2
%% @see set_postcomments/2
@@ -930,8 +919,8 @@ get_postcomments_1(#attr{com = #com{post = Cs}}) -> Cs.
%% =====================================================================
-%% @doc Sets the post-comments of Node
to
-%% Comments
. Comments
should be a possibly
+%% @doc Sets the post-comments of `Node' to
+%% `Comments'. `Comments' should be a possibly
%% empty list of abstract comments, in top-down textual order
%%
%% @see comment/2
@@ -961,12 +950,11 @@ set_postcomments_1(#attr{com = Com} = Attr, Cs) ->
%% =====================================================================
-%% @doc Appends Comments
to the post-comments of
-%% Node
.
+%% @doc Appends `Comments' to the post-comments of `Node'.
%%
-%% Note: This is equivalent to set_postcomments(Node,
-%% get_postcomments(Node) ++ Comments)
, but potentially more
-%% efficient.
false
if the node has no associated
-%% comments, and true
otherwise.
+%% @doc Yields `false' if the node has no associated
+%% comments, and `true' otherwise.
%%
-%% Note: This is equivalent to (get_precomments(Node) == [])
-%% and (get_postcomments(Node) == [])
, but potentially more
-%% efficient.
Node
.
+%% @doc Clears the associated comments of `Node'.
%%
-%% Note: This is equivalent to
-%% set_precomments(set_postcomments(Node, []), [])
, but
-%% potentially more efficient.
Source
to
-%% Target
.
+%% @doc Copies the pre- and postcomments from `Source' to `Target'.
%%
-%% Note: This is equivalent to
-%% set_postcomments(set_precomments(Target,
-%% get_precomments(Source)), get_postcomments(Source))
, but
-%% potentially more efficient.
Source
to the current
-%% comments of Target
.
+%% @doc Appends the comments of `Source' to the current
+%% comments of `Target'.
%%
-%% Note: This is equivalent to
-%% add_postcomments(get_postcomments(Source),
-%% add_precomments(get_precomments(Source), Target))
, but
-%% potentially more efficient.
Node
to
-%% Annotations
.
+%% @doc Sets the list of user annotations of `Node' to `Annotations'.
%%
%% @see get_ann/1
%% @see add_ann/2
@@ -1127,11 +1113,11 @@ set_ann(Node, As) ->
%% =====================================================================
-%% @doc Appends the term Annotation
to the list of user
-%% annotations of Node
.
+%% @doc Appends the term `Annotation' to the list of user
+%% annotations of `Node'.
%%
-%% Note: this is equivalent to set_ann(Node, [Annotation |
-%% get_ann(Node)])
, but potentially more efficient.
Source
to
-%% Target
.
+%% @doc Copies the list of user annotations from `Source' to `Target'.
%%
-%% Note: this is equivalent to set_ann(Target,
-%% get_ann(Source))
, but potentially more efficient.
set_attrs/2
).
+%% another node (see {@link set_attrs/2}).
%%
-%% For accessing individual attributes, see get_pos/1
,
-%% get_ann/1
, get_precomments/1
and
-%% get_postcomments/1
.
get_attrs/1
.
-%%
+%% syntax tree node attributes; see the function {@link get_attrs/1}.
+%%
%% @see set_attrs/2
%% @see get_pos/1
%% @see get_ann/1
@@ -1199,8 +1183,7 @@ get_attrs(Node) -> #attr{pos = get_pos(Node),
%% =====================================================================
-%% @doc Sets the attributes of Node
to
-%% Attributes
.
+%% @doc Sets the attributes of `Node' to `Attributes'.
%%
%% @see get_attrs/1
%% @see copy_attrs/2
@@ -1219,11 +1202,10 @@ set_attrs(Node, Attr) ->
%% =====================================================================
-%% @doc Copies the attributes from Source
to
-%% Target
.
+%% @doc Copies the attributes from `Source' to `Target'.
%%
-%% Note: this is equivalent to set_attrs(Target,
-%% get_attrs(Source))
, but potentially more efficient.
Strings
is a (possibly empty) list
+%% `Strings' is a (possibly empty) list
%% ["Txt1", ..., "TxtN"]
, the result
%% represents the source code text
%% -%% %Txt1 -%% ... -%% %TxtN-%%
Padding
states the number of empty character positions
+%% %Txt1
+%% ...
+%% %TxtN
+%% `Padding' states the number of empty character positions
%% to the left of the comment separating it horizontally from
-%% source code on the same line (if any). If Padding
is
-%% none
, a default positive number is used. If
-%% Padding
is an integer less than 1, there should be no
+%% source code on the same line (if any). If `Padding' is
+%% `none', a default positive number is used. If
+%% `Padding' is an integer less than 1, there should be no
%% separating space. Comments are in themselves regarded as source
%% program forms.
%%
@@ -1292,8 +1274,7 @@ comment_text(Node) ->
%% =====================================================================
%% @doc Returns the amount of padding before the comment, or
-%% none
. The latter means that a default padding may be
-%% used.
+%% `none'. The latter means that a default padding may be used.
%%
%% @see comment/2
@@ -1305,20 +1286,20 @@ comment_padding(Node) ->
%% =====================================================================
%% @doc Creates an abstract sequence of "source code forms". If
-%% Forms
is [F1, ..., Fn]
, where each
-%% Fi
is a form (cf. is_form/1
, the result
+%% `Forms' is `[F1, ..., Fn]', where each
+%% `Fi' is a form (see {@link is_form/1}, the result
%% represents
%% -%% F1 -%% ... -%% Fn-%% where the
Fi
are separated by one or more line breaks. A
-%% node of type form_list
is itself regarded as a source
-%% code form; cf. flatten_form_list/1
.
-%%
-%% Note: this is simply a way of grouping source code forms as a +%% F1 +%% ... +%% Fn +%% where the `Fi' are separated by one or more line breaks. A +%% node of type `form_list' is itself regarded as a source +%% code form; see {@link flatten_form_list/1}. +%% +%% Note: this is simply a way of grouping source code forms as a %% single syntax tree, usually in order to form an Erlang module -%% definition.
+%% definition. %% %% @see form_list_elements/1 %% @see is_form/1 @@ -1337,7 +1318,7 @@ form_list(Forms) -> %% ===================================================================== -%% @doc Returns the list of subnodes of aform_list
node.
+%% @doc Returns the list of subnodes of a `form_list' node.
%%
%% @see form_list/1
@@ -1348,8 +1329,8 @@ form_list_elements(Node) ->
%% =====================================================================
-%% @doc Flattens sublists of a form_list
node. Returns
-%% Node
with all subtrees of type form_list
+%% @doc Flattens sublists of a `form_list' node. Returns
+%% `Node' with all subtrees of type `form_list'
%% recursively expanded, yielding a single "flat" abstract form
%% sequence.
%%
@@ -1376,7 +1357,7 @@ flatten_form_list_1([], As) ->
%% =====================================================================
%% @doc Creates an abstract piece of source code text. The result
-%% represents exactly the sequence of characters in String
.
+%% represents exactly the sequence of characters in `String'.
%% This is useful in cases when one wants full control of the resulting
%% output, e.g., for the appearance of floating-point numbers or macro
%% definitions.
@@ -1393,8 +1374,7 @@ text(String) ->
%% =====================================================================
-%% @doc Returns the character sequence represented by a
-%% text
node.
+%% @doc Returns the character sequence represented by a `text' node.
%%
%% @see text/1
@@ -1406,14 +1386,14 @@ text_string(Node) ->
%% =====================================================================
%% @doc Creates an abstract variable with the given name.
-%% Name
may be any atom or string that represents a
+%% `Name' may be any atom or string that represents a
%% lexically valid variable name, but not a single underscore
-%% character; cf. underscore/0
.
+%% character; see {@link underscore/0}.
%%
-%% Note: no checking is done whether the character sequence +%% Note: no checking is done whether the character sequence %% represents a proper variable name, i.e., whether or not its first %% character is an uppercase Erlang character, or whether it does not -%% contain control characters, whitespace, etc.
+%% contain control characters, whitespace, etc. %% %% @see variable_name/1 %% @see variable_literal/1 @@ -1442,7 +1422,7 @@ revert_variable(Node) -> %% ===================================================================== -%% @doc Returns the name of avariable
node as an atom.
+%% @doc Returns the name of a `variable' node as an atom.
%%
%% @see variable/1
@@ -1458,7 +1438,7 @@ variable_name(Node) ->
%% =====================================================================
-%% @doc Returns the name of a variable
node as a string.
+%% @doc Returns the name of a `variable' node as a string.
%%
%% @see variable/1
@@ -1474,7 +1454,7 @@ variable_literal(Node) ->
%% =====================================================================
-%% @doc Creates an abstract universal pattern ("_
"). The
+%% @doc Creates an abstract universal pattern ("`_'"). The
%% lexical representation is a single underscore character. Note that
%% this is not a variable, lexically speaking.
%%
@@ -1499,7 +1479,7 @@ revert_underscore(Node) ->
%% =====================================================================
%% @doc Creates an abstract integer literal. The lexical representation
-%% is the canonical decimal numeral of Value
.
+%% is the canonical decimal numeral of `Value'.
%%
%% @see integer_value/1
%% @see integer_literal/1
@@ -1525,9 +1505,8 @@ revert_integer(Node) ->
%% =====================================================================
-%% @doc Returns true
if Node
has type
-%% integer
and represents Value
, otherwise
-%% false
.
+%% @doc Returns `true' if `Node' has type
+%% `integer' and represents `Value', otherwise `false'.
%%
%% @see integer/1
@@ -1545,7 +1524,7 @@ is_integer(Node, Value) ->
%% =====================================================================
-%% @doc Returns the value represented by an integer
node.
+%% @doc Returns the value represented by an `integer' node.
%%
%% @see integer/1
@@ -1561,8 +1540,7 @@ integer_value(Node) ->
%% =====================================================================
-%% @doc Returns the numeral string represented by an
-%% integer
node.
+%% @doc Returns the numeral string represented by an `integer' node.
%%
%% @see integer/1
@@ -1574,8 +1552,7 @@ integer_literal(Node) ->
%% =====================================================================
%% @doc Creates an abstract floating-point literal. The lexical
-%% representation is the decimal floating-point numeral of
-%% Value
.
+%% representation is the decimal floating-point numeral of `Value'.
%%
%% @see float_value/1
%% @see float_literal/1
@@ -1610,7 +1587,7 @@ revert_float(Node) ->
%% =====================================================================
-%% @doc Returns the value represented by a float
node. Note
+%% @doc Returns the value represented by a `float' node. Note
%% that floating-point values should usually not be compared for
%% equality.
%%
@@ -1628,8 +1605,7 @@ float_value(Node) ->
%% =====================================================================
-%% @doc Returns the numeral string represented by a float
-%% node.
+%% @doc Returns the numeral string represented by a `float' node.
%%
%% @see float/1
@@ -1641,14 +1617,14 @@ float_literal(Node) ->
%% =====================================================================
%% @doc Creates an abstract character literal. The result represents
-%% "$Name
", where Name
corresponds to
-%% Value
.
+%% "$Name
", where `Name' corresponds to
+%% `Value'.
%%
-%% Note: the literal corresponding to a particular character value is
-%% not uniquely defined. E.g., the character "a
" can be
-%% written both as "$a
" and "$\141
", and a Tab
-%% character can be written as "$\11
", "$\011
"
-%% or "$\t
".
true
if Node
has type
-%% char
and represents Value
, otherwise
-%% false
.
+%% @doc Returns `true' if `Node' has type
+%% `char' and represents `Value', otherwise `false'.
%%
%% @see char/1
@@ -1694,7 +1669,7 @@ is_char(Node, Value) ->
%% =====================================================================
-%% @doc Returns the value represented by a char
node.
+%% @doc Returns the value represented by a `char' node.
%%
%% @see char/1
@@ -1710,8 +1685,8 @@ char_value(Node) ->
%% =====================================================================
-%% @doc Returns the literal string represented by a char
-%% node. This includes the leading "$
" character.
+%% @doc Returns the literal string represented by a `char'
+%% node. This includes the leading "`$'" character.
%%
%% @see char/1
@@ -1724,12 +1699,12 @@ char_literal(Node) ->
%% =====================================================================
%% @doc Creates an abstract string literal. The result represents
%% "Text"
(including the surrounding
-%% double-quotes), where Text
corresponds to the sequence
-%% of characters in Value
, but not representing a
-%% specific string literal. E.g., the result of
-%% string("x\ny")
represents any and all of
-%% "x\ny"
, "x\12y"
, "x\012y"
and
-%% "x\^Jy"
; cf. char/1
.
+%% double-quotes), where `Text' corresponds to the sequence
+%% of characters in `Value', but not representing a
+%% specific string literal.
+%%
+%% For example, the result of `string("x\ny")' represents any and all of
+%% `"x\ny"', `"x\12y"', `"x\012y"' and `"x\^Jy"'; see {@link char/1}.
%%
%% @see string_value/1
%% @see string_literal/1
@@ -1756,9 +1731,8 @@ revert_string(Node) ->
%% =====================================================================
-%% @doc Returns true
if Node
has type
-%% string
and represents Value
, otherwise
-%% false
.
+%% @doc Returns `true' if `Node' has type
+%% `string' and represents `Value', otherwise `false'.
%%
%% @see string/1
@@ -1776,7 +1750,7 @@ is_string(Node, Value) ->
%% =====================================================================
-%% @doc Returns the value represented by a string
node.
+%% @doc Returns the value represented by a `string' node.
%%
%% @see string/1
@@ -1792,7 +1766,7 @@ string_value(Node) ->
%% =====================================================================
-%% @doc Returns the literal string represented by a string
+%% @doc Returns the literal string represented by a `string'
%% node. This includes surrounding double-quote characters.
%%
%% @see string/1
@@ -1805,7 +1779,7 @@ string_literal(Node) ->
%% =====================================================================
%% @doc Creates an abstract atom literal. The print name of the atom is
-%% the character sequence represented by Name
.
+%% the character sequence represented by `Name'.
%%
%% @see atom_value/1
%% @see atom_name/1
@@ -1834,9 +1808,8 @@ revert_atom(Node) ->
%% =====================================================================
-%% @doc Returns true
if Node
has type
-%% atom
and represents Value
, otherwise
-%% false
.
+%% @doc Returns `true' if `Node' has type
+%% `atom' and represents `Value', otherwise `false'.
%%
%% @see atom/1
@@ -1854,7 +1827,7 @@ is_atom(Node, Value) ->
%% =====================================================================
-%% @doc Returns the value represented by an atom
node.
+%% @doc Returns the value represented by an `atom' node.
%%
%% @see atom/1
@@ -1870,7 +1843,7 @@ atom_value(Node) ->
%% =====================================================================
-%% @doc Returns the printname of an atom
node.
+%% @doc Returns the printname of an `atom' node.
%%
%% @see atom/1
@@ -1881,13 +1854,12 @@ atom_name(Node) ->
%% =====================================================================
-%% @doc Returns the literal string represented by an atom
+%% @doc Returns the literal string represented by an `atom'
%% node. This includes surrounding single-quote characters if necessary.
%%
-%% Note that e.g. the result of atom("x\ny")
represents
-%% any and all of 'x\ny'
, 'x\12y'
,
-%% 'x\012y'
and 'x\^Jy\'
; cf.
-%% string/1
.
Elements
is
-%% [X1, ..., Xn]
, the result represents
+%% @doc Creates an abstract tuple. If `Elements' is
+%% `[X1, ..., Xn]', the result represents
%% "{X1, ..., Xn}
".
%%
-%% Note: The Erlang language has distinct 1-tuples, i.e.,
-%% {X}
is always distinct from X
itself.
tuple
-%% node.
+%% @doc Returns the list of element subtrees of a `tuple' node.
%%
%% @see tuple/1
@@ -1948,11 +1919,11 @@ tuple_elements(Node) ->
%% =====================================================================
-%% @doc Returns the number of elements of a tuple
node.
+%% @doc Returns the number of elements of a `tuple' node.
%%
-%% Note: this is equivalent to
-%% length(tuple_elements(Node))
, but potentially more
-%% efficient.
list
or nil
. If List
is a
-%% nonempty list [E1, ..., En]
, the result has type
-%% list
and represents either "[E1, ...,
-%% En]
", if Tail
is none
, or
+%% `list' or `nil'. If `List' is a
+%% nonempty list `[E1, ..., En]', the result has type
+%% `list' and represents either "[E1, ...,
+%% En]
", if `Tail' is `none', or
%% otherwise "[E1, ..., En |
-%% Tail]
". If List
is the empty list,
-%% Tail
must be none
, and in that
-%% case the result has type nil
and represents
-%% "[]
" (cf. nil/0
).
+%% Tail]". If `List' is the empty list,
+%% `Tail' must be `none', and in that
+%% case the result has type `nil' and represents
+%% "`[]'" (see {@link nil/0}).
%%
-%% The difference between lists as semantic objects (built up of +%% The difference between lists as semantic objects (built up of %% individual "cons" and "nil" terms) and the various syntactic forms %% for denoting lists may be bewildering at first. This module provides %% functions both for exact control of the syntactic representation as %% well as for the simple composition and deconstruction in terms of -%% cons and head/tail operations.
+%% cons and head/tail operations. %% -%%Note: in list(Elements, none)
, the "nil" list
-%% terminator is implicit and has no associated information (cf.
-%% get_attrs/1
), while in the seemingly equivalent
-%% list(Elements, Tail)
when Tail
has type
-%% nil
, the list terminator subtree Tail
may
+%% Note: in `list(Elements, none)', the "nil" list
+%% terminator is implicit and has no associated information (see
+%% {@link get_attrs/1}), while in the seemingly equivalent
+%% `list(Elements, Tail)' when `Tail' has type
+%% `nil', the list terminator subtree `Tail' may
%% have attached attributes such as position, comments, and annotations,
-%% which will be preserved in the result.
[]
". The empty list is traditionally called "nil".
+%% "`[]'". The empty list is traditionally called "nil".
%%
%% @see list/2
%% @see is_list_skeleton/1
@@ -2078,11 +2049,11 @@ revert_nil(Node) ->
%% =====================================================================
-%% @doc Returns the prefix element subtrees of a list
node.
-%% If Node
represents "[E1, ...,
+%% @doc Returns the prefix element subtrees of a `list' node.
+%% If `Node' represents "[E1, ...,
%% En]
" or "[E1, ..., En |
-%% Tail]
", the returned value is [E1, ...,
-%% En]
.
+%% Tail]
", the returned value is `[E1, ...,
+%% En]'.
%%
%% @see list/2
@@ -2098,18 +2069,17 @@ list_prefix(Node) ->
%% =====================================================================
-%% @doc Returns the suffix subtree of a list
node, if one
-%% exists. If Node
represents "[E1, ...,
+%% @doc Returns the suffix subtree of a `list' node, if one
+%% exists. If `Node' represents "[E1, ...,
%% En | Tail]
", the returned value is
-%% Tail
, otherwise, i.e., if Node
represents
-%% "[E1, ..., En]
", none
is
+%% `Tail', otherwise, i.e., if `Node' represents
+%% "[E1, ..., En]
", `none' is
%% returned.
%%
-%% Note that even if this function returns some Tail
-%% that is not none
, the type of Tail
can be
-%% nil
, if the tail has been given explicitly, and the list
-%% skeleton has not been compacted (cf.
-%% compact_list/1
).
+%% Note that even if this function returns some `Tail'
+%% that is not `none', the type of `Tail' can be
+%% `nil', if the tail has been given explicitly, and the list
+%% skeleton has not been compacted (see {@link compact_list/1}).
%%
%% @see list/2
%% @see nil/0
@@ -2135,17 +2105,17 @@ list_suffix(Node) ->
%% =====================================================================
%% @doc "Optimising" list skeleton cons operation. Creates an abstract
-%% list skeleton whose first element is Head
and whose tail
-%% corresponds to Tail
. This is similar to
-%% list([Head], Tail)
, except that Tail
may
-%% not be none
, and that the result does not necessarily
+%% list skeleton whose first element is `Head' and whose tail
+%% corresponds to `Tail'. This is similar to
+%% `list([Head], Tail)', except that `Tail' may
+%% not be `none', and that the result does not necessarily
%% represent exactly "[Head | Tail]
", but
-%% may depend on the Tail
subtree. E.g., if
-%% Tail
represents [X, Y]
, the result may
+%% may depend on the `Tail' subtree. E.g., if
+%% `Tail' represents `[X, Y]', the result may
%% represent "[Head, X, Y]
", rather than
%% "[Head | [X, Y]]
". Annotations on
-%% Tail
itself may be lost if Tail
represents
-%% a list skeleton, but comments on Tail
are propagated to
+%% `Tail' itself may be lost if `Tail' represents
+%% a list skeleton, but comments on `Tail' are propagated to
%% the result.
%%
%% @see list/2
@@ -2167,8 +2137,8 @@ cons(Head, Tail) ->
%% =====================================================================
-%% @doc Returns the head element subtree of a list
node. If
-%% Node
represents "[Head ...]
", the
+%% @doc Returns the head element subtree of a `list' node. If
+%% `Node' represents "[Head ...]
", the
%% result will represent "Head
".
%%
%% @see list/2
@@ -2182,13 +2152,13 @@ list_head(Node) ->
%% =====================================================================
-%% @doc Returns the tail of a list
node. If
-%% Node
represents a single-element list
+%% @doc Returns the tail of a `list' node. If
+%% `Node' represents a single-element list
%% "[E]
", then the result has type
-%% nil
, representing "[]
". If
-%% Node
represents "[E1, E2
+%% `nil', representing "`[]'". If
+%% `Node' represents "[E1, E2
%% ...]
", the result will represent "[E2
-%% ...]
", and if Node
represents
+%% ...]
", and if `Node' represents
%% "[Head | Tail]
", the result will
%% represent "Tail
".
%%
@@ -2213,8 +2183,8 @@ list_tail(Node) ->
%% =====================================================================
-%% @doc Returns true
if Node
has type
-%% list
or nil
, otherwise false
.
+%% @doc Returns `true' if `Node' has type
+%% `list' or `nil', otherwise `false'.
%%
%% @see list/2
%% @see nil/0
@@ -2230,22 +2200,22 @@ is_list_skeleton(Node) ->
%% =====================================================================
-%% @doc Returns true
if Node
represents a
-%% proper list, and false
otherwise. A proper list is a
-%% list skeleton either on the form "[]
" or
+%% @doc Returns `true' if `Node' represents a
+%% proper list, and `false' otherwise. A proper list is a
+%% list skeleton either on the form "`[]'" or
%% "[E1, ..., En]
", or "[... |
-%% Tail]
" where recursively Tail
also
+%% Tail]
" where recursively `Tail' also
%% represents a proper list.
%%
-%% Note: Since Node
is a syntax tree, the actual
+%% Note: Since `Node' is a syntax tree, the actual
%% run-time values corresponding to its subtrees may often be partially
-%% or completely unknown. Thus, if Node
represents e.g.
-%% "[... | Ns]
" (where Ns
is a variable), then
-%% the function will return false
, because it is not known
-%% whether Ns
will be bound to a list at run-time. If
-%% Node
instead represents e.g. "[1, 2, 3]
" or
-%% "[A | []]
", then the function will return
-%% true
.
Node
must represent a proper list. E.g., if
-%% Node
represents "[X1, X2 |
+%% `Node' must represent a proper list. E.g., if
+%% `Node' represents "[X1, X2 |
%% [X3, X4 | []]
", then
-%% list_elements(Node)
yields the list [X1, X2, X3,
-%% X4]
.
+%% `list_elements(Node)' yields the list `[X1, X2, X3, X4]'.
%%
%% @see list/2
%% @see is_proper_list/1
@@ -2300,14 +2269,14 @@ list_elements(Node, As) ->
%% =====================================================================
%% @doc Returns the number of element subtrees of a list skeleton.
-%% Node
must represent a proper list. E.g., if
-%% Node
represents "[X1 | [X2, X3 | [X4, X5,
-%% X6]]]
", then list_length(Node)
returns the
+%% `Node' must represent a proper list. E.g., if
+%% `Node' represents "`[X1 | [X2, X3 | [X4, X5,
+%% X6]]]'", then `list_length(Node)' returns the
%% integer 6.
%%
-%% Note: this is equivalent to
-%% length(list_elements(Node))
, but potentially more
-%% efficient.
+%% Note: this is equivalent to
+%% `length(list_elements(Node))', but potentially more
+%% efficient.
%%
%% @see list/2
%% @see is_proper_list/1
@@ -2335,15 +2304,15 @@ list_length(Node, A) ->
%% =====================================================================
%% @doc Expands an abstract list skeleton to its most explicit form. If
-%% Node
represents "[E1, ..., En |
+%% `Node' represents "[E1, ..., En |
%% Tail]
", the result represents "[E1 |
%% ... [En | Tail1] ... ]
", where
-%% Tail1
is the result of
-%% normalize_list(Tail)
. If Node
represents
+%% `Tail1' is the result of
+%% `normalize_list(Tail)'. If `Node' represents
%% "[E1, ..., En]
", the result simply
%% represents "[E1 | ... [En | []] ...
-%% ]
". If Node
does not represent a list skeleton,
-%% Node
itself is returned.
+%% ]
". If `Node' does not represent a list skeleton,
+%% `Node' itself is returned.
%%
%% @see list/2
%% @see compact_list/1
@@ -2375,12 +2344,12 @@ normalize_list_1(Es, Tail) ->
%% =====================================================================
%% @doc Yields the most compact form for an abstract list skeleton. The
%% result either represents "[E1, ..., En |
-%% Tail]
", where Tail
is not a list
+%% Tail]
", where `Tail' is not a list
%% skeleton, or otherwise simply "[E1, ...,
-%% En]
". Annotations on subtrees of Node
+%% En]". Annotations on subtrees of `Node'
%% that represent list skeletons may be lost, but comments will be
-%% propagated to the result. Returns Node
itself if
-%% Node
does not represent a list skeleton.
+%% propagated to the result. Returns `Node' itself if
+%% `Node' does not represent a list skeleton.
%%
%% @see list/2
%% @see normalize_list/1
@@ -2419,7 +2388,7 @@ compact_list(Node) ->
%% =====================================================================
%% @doc Creates an abstract binary-object template. If
-%% Fields
is [F1, ..., Fn]
, the result
+%% `Fields' is `[F1, ..., Fn]', the result
%% represents "<<F1, ...,
%% Fn>>
".
%%
@@ -2452,8 +2421,7 @@ revert_binary(Node) ->
%% =====================================================================
-%% @doc Returns the list of field subtrees of a binary
-%% node.
+%% @doc Returns the list of field subtrees of a `binary' node.
%%
%% @see binary/1
%% @see binary_field/2
@@ -2480,10 +2448,10 @@ binary_field(Body) ->
%% =====================================================================
%% @doc Creates an abstract binary template field.
-%% If Size
is none
, this is equivalent to
-%% "binary_field(Body, Types)
", otherwise it is
-%% equivalent to "binary_field(size_qualifier(Body, Size),
-%% Types)
".
+%% If `Size' is `none', this is equivalent to
+%% "`binary_field(Body, Types)'", otherwise it is
+%% equivalent to "`binary_field(size_qualifier(Body, Size),
+%% Types)'".
%%
%% (This is a utility function.)
%%
@@ -2502,9 +2470,9 @@ binary_field(Body, Size, Types) ->
%% =====================================================================
%% @doc Creates an abstract binary template field. If
-%% Types
is the empty list, the result simply represents
-%% "Body
", otherwise, if Types
is
-%% [T1, ..., Tn]
, the result represents
+%% `Types' is the empty list, the result simply represents
+%% "Body
", otherwise, if `Types' is
+%% `[T1, ..., Tn]', the result represents
%% "Body/T1-...-Tn
".
%%
%% @see binary/1
@@ -2558,7 +2526,7 @@ revert_binary_field(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a binary_field
.
+%% @doc Returns the body subtree of a `binary_field'.
%%
%% @see binary_field/2
@@ -2579,9 +2547,9 @@ binary_field_body(Node) ->
%% =====================================================================
%% @doc Returns the list of type-specifier subtrees of a
-%% binary_field
node. If Node
represents
+%% `binary_field' node. If `Node' represents
%% ".../T1, ..., Tn
", the result is
-%% [T1, ..., Tn]
, otherwise the result is the empty list.
+%% `[T1, ..., Tn]', otherwise the result is the empty list.
%%
%% @see binary_field/2
@@ -2602,11 +2570,11 @@ binary_field_types(Node) ->
%% =====================================================================
%% @doc Returns the size specifier subtree of a
-%% binary_field
node, if any. If Node
+%% `binary_field' node, if any. If `Node'
%% represents "Body:Size
" or
%% "Body:Size/T1, ...,
-%% Tn
", the result is Size
, otherwise
-%% none
is returned.
+%% Tn", the result is `Size', otherwise
+%% `none' is returned.
%%
%% (This is a utility function.)
%%
@@ -2656,8 +2624,7 @@ size_qualifier(Body, Size) ->
%% =====================================================================
-%% @doc Returns the body subtree of a size_qualifier
-%% node.
+%% @doc Returns the body subtree of a `size_qualifier' node.
%%
%% @see size_qualifier/2
@@ -2669,7 +2636,7 @@ size_qualifier_body(Node) ->
%% =====================================================================
%% @doc Returns the argument subtree (the size) of a
-%% size_qualifier
node.
+%% `size_qualifier' node.
%%
%% @see size_qualifier/2
@@ -2682,12 +2649,12 @@ size_qualifier_argument(Node) ->
%% =====================================================================
%% @doc Creates an abstract error marker. The result represents an
%% occurrence of an error in the source code, with an associated Erlang
-%% I/O ErrorInfo structure given by Error
(see module
+%% I/O ErrorInfo structure given by `Error' (see module
%% {@link //stdlib/io} for details). Error markers are regarded as source
%% code forms, but have no defined lexical form.
%%
-%% Note: this is supported only for backwards compatibility with -%% existing parsers and tools.
+%% Note: this is supported only for backwards compatibility with +%% existing parsers and tools. %% %% @see error_marker_info/1 %% @see warning_marker/1 @@ -2718,8 +2685,7 @@ revert_error_marker(Node) -> %% ===================================================================== -%% @doc Returns the ErrorInfo structure of anerror_marker
-%% node.
+%% @doc Returns the ErrorInfo structure of an `error_marker' node.
%%
%% @see error_marker/1
@@ -2737,12 +2703,12 @@ error_marker_info(Node) ->
%% =====================================================================
%% @doc Creates an abstract warning marker. The result represents an
%% occurrence of a possible problem in the source code, with an
-%% associated Erlang I/O ErrorInfo structure given by Error
+%% associated Erlang I/O ErrorInfo structure given by `Error'
%% (see module {@link //stdlib/io} for details). Warning markers are
%% regarded as source code forms, but have no defined lexical form.
%%
-%% Note: this is supported only for backwards compatibility with -%% existing parsers and tools.
+%% Note: this is supported only for backwards compatibility with +%% existing parsers and tools. %% %% @see warning_marker_info/1 %% @see error_marker/1 @@ -2773,8 +2739,7 @@ revert_warning_marker(Node) -> %% ===================================================================== -%% @doc Returns the ErrorInfo structure of awarning_marker
-%% node.
+%% @doc Returns the ErrorInfo structure of a `warning_marker' node.
%%
%% @see warning_marker/1
@@ -2796,8 +2761,8 @@ warning_marker_info(Node) ->
%% (namely, the last in any sequence in which it occurs). It has no
%% defined lexical form.
%%
-%% Note: this is retained only for backwards compatibility with -%% existing parsers and tools.
+%% Note: this is retained only for backwards compatibility with +%% existing parsers and tools. %% %% @see error_marker/1 %% @see warning_marker/1 @@ -2831,19 +2796,19 @@ attribute(Name) -> %% ===================================================================== %% @doc Creates an abstract program attribute. If -%%Arguments
is [A1, ..., An]
, the result
+%% `Arguments' is `[A1, ..., An]', the result
%% represents "-Name(A1, ...,
-%% An).
". Otherwise, if Arguments
is
-%% none
, the result represents
+%% An).". Otherwise, if `Arguments' is
+%% `none', the result represents
%% "-Name.
". The latter form makes it possible
%% to represent preprocessor directives such as
-%% "-endif.
". Attributes are source code forms.
+%% "`-endif.'". Attributes are source code forms.
%%
-%% Note: The preprocessor macro definition directive
+%% Note: The preprocessor macro definition directive
%% "-define(Name, Body).
" has relatively
-%% few requirements on the syntactical form of Body
(viewed
-%% as a sequence of tokens). The text
node type can be used
-%% for a Body
that is not a normal Erlang construct.
attribute
node.
+%% @doc Returns the name subtree of an `attribute' node.
%%
%% @see attribute/1
@@ -3054,11 +3019,11 @@ attribute_name(Node) ->
%% =====================================================================
%% @doc Returns the list of argument subtrees of an
-%% attribute
node, if any. If Node
+%% `attribute' node, if any. If `Node'
%% represents "-Name.
", the result is
-%% none
. Otherwise, if Node
represents
+%% `none'. Otherwise, if `Node' represents
%% "-Name(E1, ..., En).
",
-%% [E1, ..., E1]
is returned.
+%% `[E1, ..., E1]' is returned.
%%
%% @see attribute/1
@@ -3146,8 +3111,7 @@ arity_qualifier(Body, Arity) ->
%% =====================================================================
-%% @doc Returns the body subtree of an arity_qualifier
-%% node.
+%% @doc Returns the body subtree of an `arity_qualifier' node.
%%
%% @see arity_qualifier/2
@@ -3159,7 +3123,7 @@ arity_qualifier_body(Node) ->
%% =====================================================================
%% @doc Returns the argument (the arity) subtree of an
-%% arity_qualifier
node.
+%% `arity_qualifier' node.
%%
%% @see arity_qualifier/2
@@ -3204,7 +3168,7 @@ revert_module_qualifier(Node) ->
%% =====================================================================
%% @doc Returns the argument (the module) subtree of a
-%% module_qualifier
node.
+%% `module_qualifier' node.
%%
%% @see module_qualifier/2
@@ -3220,8 +3184,7 @@ module_qualifier_argument(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a module_qualifier
-%% node.
+%% @doc Returns the body subtree of a `module_qualifier' node.
%%
%% @see module_qualifier/2
@@ -3239,7 +3202,7 @@ module_qualifier_body(Node) ->
%% =====================================================================
%% @doc Creates an abstract qualified name. The result represents
%% "S1.S2. ... .Sn
", if
-%% Segments
is [S1, S2, ..., Sn]
.
+%% `Segments' is `[S1, S2, ..., Sn]'.
%%
%% @see qualified_name_segments/1
@@ -3268,7 +3231,7 @@ revert_qualified_name(Node) ->
%% =====================================================================
%% @doc Returns the list of name segments of a
-%% qualified_name
node.
+%% `qualified_name' node.
%%
%% @see qualified_name/1
@@ -3284,10 +3247,10 @@ qualified_name_segments(Node) ->
%% =====================================================================
-%% @doc Creates an abstract function definition. If Clauses
-%% is [C1, ..., Cn]
, the result represents
+%% @doc Creates an abstract function definition. If `Clauses'
+%% is `[C1, ..., Cn]', the result represents
%% "Name C1; ...; Name
-%% Cn.
". More exactly, if each Ci
+%% Cn.". More exactly, if each `Ci'
%% represents "(Pi1, ..., Pim) Gi ->
%% Bi
", then the result represents
%% "Name(P11, ..., P1m) G1 ->
@@ -3349,7 +3312,7 @@ revert_function(Node) ->
%% =====================================================================
-%% @doc Returns the name subtree of a function
node.
+%% @doc Returns the name subtree of a `function' node.
%%
%% @see function/2
@@ -3365,8 +3328,7 @@ function_name(Node) ->
%% =====================================================================
-%% @doc Returns the list of clause subtrees of a function
-%% node.
+%% @doc Returns the list of clause subtrees of a `function' node.
%%
%% @see function/2
@@ -3382,14 +3344,14 @@ function_clauses(Node) ->
%% =====================================================================
-%% @doc Returns the arity of a function
node. The result
+%% @doc Returns the arity of a `function' node. The result
%% is the number of parameter patterns in the first clause of the
%% function; subsequent clauses are ignored.
%%
-%% An exception is thrown if function_clauses(Node)
+%% An exception is thrown if `function_clauses(Node)'
%% returns an empty list, or if the first element of that list is not
-%% a syntax tree C
of type clause
such that
-%% clause_patterns(C)
is a nonempty list.
+%% a syntax tree `C' of type `clause' such that
+%% `clause_patterns(C)' is a nonempty list.
%%
%% @see function/2
%% @see function_clauses/1
@@ -3416,29 +3378,28 @@ clause(Guard, Body) ->
%% =====================================================================
-%% @doc Creates an abstract clause. If Patterns
is
-%% [P1, ..., Pn]
and Body
is [B1, ...,
-%% Bm]
, then if Guard
is none
, the
+%% @doc Creates an abstract clause. If `Patterns' is
+%% `[P1, ..., Pn]' and `Body' is `[B1, ...,
+%% Bm]', then if `Guard' is `none', the
%% result represents "(P1, ..., Pn) ->
%% B1, ..., Bm
", otherwise, unless
-%% Guard
is a list, the result represents
+%% `Guard' is a list, the result represents
%% "(P1, ..., Pn) when Guard ->
%% B1, ..., Bm
".
%%
-%% For simplicity, the Guard
argument may also be any
+%% For simplicity, the `Guard' argument may also be any
%% of the following:
%%
-%% - An empty list
[]
. This is equivalent to passing
-%% none
.
-%% - A nonempty list
[E1, ..., Ej]
of syntax trees.
-%% This is equivalent to passing conjunction([E1, ...,
-%% Ej])
.
-%% - A nonempty list of lists of syntax trees
[[E1_1, ...,
-%% E1_k1], ..., [Ej_1, ..., Ej_kj]]
, which is equivalent
-%% to passing disjunction([conjunction([E1_1, ...,
-%% E1_k1]), ..., conjunction([Ej_1, ..., Ej_kj])])
.
+%% - An empty list `[]'. This is equivalent to passing
+%% `none'.
+%% - A nonempty list `[E1, ..., Ej]' of syntax trees.
+%% This is equivalent to passing `conjunction([E1, ...,
+%% Ej])'.
+%% - A nonempty list of lists of syntax trees `[[E1_1, ...,
+%% E1_k1], ..., [Ej_1, ..., Ej_kj]]', which is equivalent
+%% to passing `disjunction([conjunction([E1_1, ...,
+%% E1_k1]), ..., conjunction([Ej_1, ..., Ej_kj])])'.
%%
-%%
%%
%% @see clause/2
%% @see clause_patterns/1
@@ -3554,8 +3515,7 @@ unfold_try_clause({clause, Pos, [{tuple, _, [C, V, _]}],
%% =====================================================================
-%% @doc Returns the list of pattern subtrees of a clause
-%% node.
+%% @doc Returns the list of pattern subtrees of a `clause' node.
%%
%% @see clause/3
@@ -3571,11 +3531,11 @@ clause_patterns(Node) ->
%% =====================================================================
-%% @doc Returns the guard subtree of a clause
node, if
-%% any. If Node
represents "(P1, ...,
+%% @doc Returns the guard subtree of a `clause' node, if
+%% any. If `Node' represents "(P1, ...,
%% Pn) when Guard -> B1, ...,
-%% Bm
", Guard
is returned. Otherwise, the
-%% result is none
.
+%% Bm
", `Guard' is returned. Otherwise, the
+%% result is `none'.
%%
%% @see clause/3
@@ -3597,8 +3557,7 @@ clause_guard(Node) ->
%% =====================================================================
-%% @doc Return the list of body subtrees of a clause
-%% node.
+%% @doc Return the list of body subtrees of a `clause' node.
%%
%% @see clause/3
@@ -3614,8 +3573,8 @@ clause_body(Node) ->
%% =====================================================================
-%% @doc Creates an abstract disjunction. If List
is
-%% [E1, ..., En]
, the result represents
+%% @doc Creates an abstract disjunction. If `List' is
+%% `[E1, ..., En]', the result represents
%% "E1; ...; En
".
%%
%% @see disjunction_body/1
@@ -3632,7 +3591,7 @@ disjunction(Tests) ->
%% =====================================================================
%% @doc Returns the list of body subtrees of a
-%% disjunction
node.
+%% `disjunction' node.
%%
%% @see disjunction/1
@@ -3643,8 +3602,8 @@ disjunction_body(Node) ->
%% =====================================================================
-%% @doc Creates an abstract conjunction. If List
is
-%% [E1, ..., En]
, the result represents
+%% @doc Creates an abstract conjunction. If `List' is
+%% `[E1, ..., En]', the result represents
%% "E1, ..., En
".
%%
%% @see conjunction_body/1
@@ -3661,7 +3620,7 @@ conjunction(Tests) ->
%% =====================================================================
%% @doc Returns the list of body subtrees of a
-%% conjunction
node.
+%% `conjunction' node.
%%
%% @see conjunction/1
@@ -3698,7 +3657,7 @@ revert_catch_expr(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a catch_expr
node.
+%% @doc Returns the body subtree of a `catch_expr' node.
%%
%% @see catch_expr/1
@@ -3746,7 +3705,7 @@ revert_match_expr(Node) ->
%% =====================================================================
-%% @doc Returns the pattern subtree of a match_expr
node.
+%% @doc Returns the pattern subtree of a `match_expr' node.
%%
%% @see match_expr/2
@@ -3762,7 +3721,7 @@ match_expr_pattern(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a match_expr
node.
+%% @doc Returns the body subtree of a `match_expr' node.
%%
%% @see match_expr/2
@@ -3779,11 +3738,11 @@ match_expr_body(Node) ->
%% =====================================================================
%% @doc Creates an abstract operator. The name of the operator is the
-%% character sequence represented by Name
. This is
+%% character sequence represented by `Name'. This is
%% analogous to the print name of an atom, but an operator is never
%% written within single-quotes; e.g., the result of
-%% operator('++')
represents "++
" rather
-%% than "'++'
".
+%% `operator('++')' represents "`++'" rather
+%% than "`'++''".
%%
%% @see operator_name/1
%% @see operator_literal/1
@@ -3801,7 +3760,7 @@ operator(Name) ->
%% =====================================================================
-%% @doc Returns the name of an operator
node. Note that
+%% @doc Returns the name of an `operator' node. Note that
%% the name is returned as an atom.
%%
%% @see operator/1
@@ -3814,8 +3773,7 @@ operator_name(Node) ->
%% =====================================================================
%% @doc Returns the literal string represented by an
-%% operator
node. This is simply the operator name as a
-%% string.
+%% `operator' node. This is simply the operator name as a string.
%%
%% @see operator/1
@@ -3875,7 +3833,7 @@ revert_infix_expr(Node) ->
%% =====================================================================
%% @doc Returns the left argument subtree of an
-%% infix_expr
node.
+%% `infix_expr' node.
%%
%% @see infix_expr/3
@@ -3891,8 +3849,7 @@ infix_expr_left(Node) ->
%% =====================================================================
-%% @doc Returns the operator subtree of an infix_expr
-%% node.
+%% @doc Returns the operator subtree of an `infix_expr' node.
%%
%% @see infix_expr/3
@@ -3909,7 +3866,7 @@ infix_expr_operator(Node) ->
%% =====================================================================
%% @doc Returns the right argument subtree of an
-%% infix_expr
node.
+%% `infix_expr' node.
%%
%% @see infix_expr/3
@@ -3968,8 +3925,7 @@ revert_prefix_expr(Node) ->
%% =====================================================================
-%% @doc Returns the operator subtree of a prefix_expr
-%% node.
+%% @doc Returns the operator subtree of a `prefix_expr' node.
%%
%% @see prefix_expr/2
@@ -3985,8 +3941,7 @@ prefix_expr_operator(Node) ->
%% =====================================================================
-%% @doc Returns the argument subtree of a prefix_expr
-%% node.
+%% @doc Returns the argument subtree of a `prefix_expr' node.
%%
%% @see prefix_expr/2
@@ -4012,7 +3967,7 @@ record_field(Name) ->
%% =====================================================================
%% @doc Creates an abstract record field specification. If
-%% Value
is none
, the result represents
+%% `Value' is `none', the result represents
%% simply "Name
", otherwise it represents
%% "Name = Value
".
%%
@@ -4034,7 +3989,7 @@ record_field(Name, Value) ->
%% =====================================================================
-%% @doc Returns the name subtree of a record_field
node.
+%% @doc Returns the name subtree of a `record_field' node.
%%
%% @see record_field/2
@@ -4045,11 +4000,11 @@ record_field_name(Node) ->
%% =====================================================================
-%% @doc Returns the value subtree of a record_field
node,
-%% if any. If Node
represents
-%% "Name
", none
is
-%% returned. Otherwise, if Node
represents
-%% "Name = Value
", Value
+%% @doc Returns the value subtree of a `record_field' node,
+%% if any. If `Node' represents
+%% "Name
", `none' is
+%% returned. Otherwise, if `Node' represents
+%% "Name = Value
", `Value'
%% is returned.
%%
%% @see record_field/2
@@ -4064,9 +4019,9 @@ record_field_value(Node) ->
%% @doc Creates an abstract record field index expression. The result
%% represents "#Type.Field
".
%%
-%% (Note: the function name record_index/2
is reserved
+%% (Note: the function name `record_index/2' is reserved
%% by the Erlang compiler, which is why that name could not be used
-%% for this constructor.)
+%% for this constructor.)
%%
%% @see record_index_expr_type/1
%% @see record_index_expr_field/1
@@ -4105,8 +4060,7 @@ revert_record_index_expr(Node) ->
%% =====================================================================
-%% @doc Returns the type subtree of a record_index_expr
-%% node.
+%% @doc Returns the type subtree of a `record_index_expr' node.
%%
%% @see record_index_expr/2
@@ -4122,8 +4076,7 @@ record_index_expr_type(Node) ->
%% =====================================================================
-%% @doc Returns the field subtree of a record_index_expr
-%% node.
+%% @doc Returns the field subtree of a `record_index_expr' node.
%%
%% @see record_index_expr/2
@@ -4149,12 +4102,12 @@ record_access(Argument, Field) ->
%% =====================================================================
%% @doc Creates an abstract record field access expression. If
-%% Type
is not none
, the result represents
+%% `Type' is not `none', the result represents
%% "Argument#Type.Field
".
%%
-%% If Type
is none
, the result represents
+%% If `Type' is `none', the result represents
%% "Argument.Field
". This is a special
-%% form only allowed within Mnemosyne queries.
+%% form only allowed within Mnemosyne queries.
%%
%% @see record_access/2
%% @see record_access_argument/1
@@ -4209,8 +4162,7 @@ revert_record_access(Node) ->
%% =====================================================================
-%% @doc Returns the argument subtree of a record_access
-%% node.
+%% @doc Returns the argument subtree of a `record_access' node.
%%
%% @see record_access/3
@@ -4228,12 +4180,12 @@ record_access_argument(Node) ->
%% =====================================================================
-%% @doc Returns the type subtree of a record_access
node,
-%% if any. If Node
represents
-%% "Argument.Field
", none
-%% is returned, otherwise if Node
represents
+%% @doc Returns the type subtree of a `record_access' node,
+%% if any. If `Node' represents
+%% "Argument.Field
", `none'
+%% is returned, otherwise if `Node' represents
%% "Argument#Type.Field
",
-%% Type
is returned.
+%% `Type' is returned.
%%
%% @see record_access/3
@@ -4251,8 +4203,7 @@ record_access_type(Node) ->
%% =====================================================================
-%% @doc Returns the field subtree of a record_access
-%% node.
+%% @doc Returns the field subtree of a `record_access' node.
%%
%% @see record_access/3
@@ -4279,9 +4230,9 @@ record_expr(Type, Fields) ->
%% =====================================================================
-%% @doc Creates an abstract record expression. If Fields
is
-%% [F1, ..., Fn]
, then if Argument
is
-%% none
, the result represents
+%% @doc Creates an abstract record expression. If `Fields' is
+%% `[F1, ..., Fn]', then if `Argument' is
+%% `none', the result represents
%% "#Type{F1, ..., Fn}
",
%% otherwise it represents
%% "Argument#Type{F1, ...,
@@ -4347,12 +4298,12 @@ revert_record_expr(Node) ->
%% =====================================================================
-%% @doc Returns the argument subtree of a record_expr
node,
-%% if any. If Node
represents
-%% "#Type{...}
", none
is returned.
-%% Otherwise, if Node
represents
+%% @doc Returns the argument subtree of a `record_expr' node,
+%% if any. If `Node' represents
+%% "#Type{...}
", `none' is returned.
+%% Otherwise, if `Node' represents
%% "Argument#Type{...}
",
-%% Argument
is returned.
+%% `Argument' is returned.
%%
%% @see record_expr/3
@@ -4370,7 +4321,7 @@ record_expr_argument(Node) ->
%% =====================================================================
-%% @doc Returns the type subtree of a record_expr
node.
+%% @doc Returns the type subtree of a `record_expr' node.
%%
%% @see record_expr/3
@@ -4389,7 +4340,7 @@ record_expr_type(Node) ->
%% =====================================================================
%% @doc Returns the list of field subtrees of a
-%% record_expr
node.
+%% `record_expr' node.
%%
%% @see record_expr/3
@@ -4408,10 +4359,10 @@ record_expr_fields(Node) ->
%% =====================================================================
%% @doc Creates an abstract function application expression. If
-%% Module
is none
, this is call is equivalent
-%% to application(Function, Arguments)
, otherwise it is
-%% equivalent to application(module_qualifier(Module, Function),
-%% Arguments)
.
+%% `Module' is `none', this is call is equivalent
+%% to `application(Function, Arguments)', otherwise it is
+%% equivalent to `application(module_qualifier(Module, Function),
+%% Arguments)'.
%%
%% (This is a utility function.)
%%
@@ -4429,7 +4380,7 @@ application(Module, Name, Arguments) ->
%% =====================================================================
%% @doc Creates an abstract function application expression. If
-%% Arguments
is [A1, ..., An]
, the result
+%% `Arguments' is `[A1, ..., An]', the result
%% represents "Operator(A1, ...,
%% An)
".
%%
@@ -4467,12 +4418,11 @@ revert_application(Node) ->
%% =====================================================================
-%% @doc Returns the operator subtree of an application
-%% node.
+%% @doc Returns the operator subtree of an `application' node.
%%
-%% Note: if Node
represents
+%% Note: if `Node' represents
%% "M:F(...)
", then the result is the
-%% subtree representing "M:F
".
+%% subtree representing "M:F
".
%%
%% @see application/2
%% @see module_qualifier/2
@@ -4490,7 +4440,7 @@ application_operator(Node) ->
%% =====================================================================
%% @doc Returns the list of argument subtrees of an
-%% application
node.
+%% `application' node.
%%
%% @see application/2
@@ -4506,8 +4456,8 @@ application_arguments(Node) ->
%% =====================================================================
-%% @doc Creates an abstract list comprehension. If Body
is
-%% [E1, ..., En]
, the result represents
+%% @doc Creates an abstract list comprehension. If `Body' is
+%% `[E1, ..., En]', the result represents
%% "[Template || E1, ..., En]
".
%%
%% @see list_comp_template/1
@@ -4542,7 +4492,7 @@ revert_list_comp(Node) ->
%% =====================================================================
-%% @doc Returns the template subtree of a list_comp
node.
+%% @doc Returns the template subtree of a `list_comp' node.
%%
%% @see list_comp/2
@@ -4558,8 +4508,7 @@ list_comp_template(Node) ->
%% =====================================================================
-%% @doc Returns the list of body subtrees of a list_comp
-%% node.
+%% @doc Returns the list of body subtrees of a `list_comp' node.
%%
%% @see list_comp/2
@@ -4574,8 +4523,8 @@ list_comp_body(Node) ->
end.
%% =====================================================================
-%% @doc Creates an abstract binary comprehension. If Body
is
-%% [E1, ..., En]
, the result represents
+%% @doc Creates an abstract binary comprehension. If `Body' is
+%% `[E1, ..., En]', the result represents
%% "<<Template || E1, ..., En>>
".
%%
%% @see binary_comp_template/1
@@ -4610,7 +4559,7 @@ revert_binary_comp(Node) ->
%% =====================================================================
-%% @doc Returns the template subtree of a binary_comp
node.
+%% @doc Returns the template subtree of a `binary_comp' node.
%%
%% @see binary_comp/2
@@ -4626,8 +4575,7 @@ binary_comp_template(Node) ->
%% =====================================================================
-%% @doc Returns the list of body subtrees of a binary_comp
-%% node.
+%% @doc Returns the list of body subtrees of a `binary_comp' node.
%%
%% @see binary_comp/2
@@ -4671,7 +4619,7 @@ revert_query_expr(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a query_expr
node.
+%% @doc Returns the body subtree of a `query_expr' node.
%%
%% @see query_expr/1
@@ -4687,10 +4635,10 @@ query_expr_body(Node) ->
%% =====================================================================
-%% @doc Creates an abstract Mnemosyne rule. If Clauses
is
-%% [C1, ..., Cn]
, the results represents
+%% @doc Creates an abstract Mnemosyne rule. If `Clauses' is
+%% `[C1, ..., Cn]', the results represents
%% "Name C1; ...; Name
-%% Cn.
". More exactly, if each Ci
+%% Cn.
". More exactly, if each `Ci'
%% represents "(Pi1, ..., Pim) Gi ->
%% Bi
", then the result represents
%% "Name(P11, ..., P1m) G1 :-
@@ -4745,7 +4693,7 @@ revert_rule(Node) ->
%% =====================================================================
-%% @doc Returns the name subtree of a rule
node.
+%% @doc Returns the name subtree of a `rule' node.
%%
%% @see rule/2
@@ -4760,7 +4708,7 @@ rule_name(Node) ->
end.
%% =====================================================================
-%% @doc Returns the list of clause subtrees of a rule
node.
+%% @doc Returns the list of clause subtrees of a `rule' node.
%%
%% @see rule/2
@@ -4775,14 +4723,14 @@ rule_clauses(Node) ->
end.
%% =====================================================================
-%% @doc Returns the arity of a rule
node. The result is the
+%% @doc Returns the arity of a `rule' node. The result is the
%% number of parameter patterns in the first clause of the rule;
%% subsequent clauses are ignored.
%%
-%% An exception is thrown if rule_clauses(Node)
returns
+%% An exception is thrown if `rule_clauses(Node)' returns
%% an empty list, or if the first element of that list is not a syntax
-%% tree C
of type clause
such that
-%% clause_patterns(C)
is a nonempty list.
+%% tree `C' of type `clause' such that
+%% `clause_patterns(C)' is a nonempty list.
%%
%% @see rule/2
%% @see rule_clauses/1
@@ -4832,7 +4780,7 @@ revert_generator(Node) ->
%% =====================================================================
-%% @doc Returns the pattern subtree of a generator
node.
+%% @doc Returns the pattern subtree of a `generator' node.
%%
%% @see generator/2
@@ -4848,7 +4796,7 @@ generator_pattern(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a generator
node.
+%% @doc Returns the body subtree of a `generator' node.
%%
%% @see generator/2
@@ -4898,7 +4846,7 @@ revert_binary_generator(Node) ->
%% =====================================================================
-%% @doc Returns the pattern subtree of a generator
node.
+%% @doc Returns the pattern subtree of a `generator' node.
%%
%% @see binary_generator/2
@@ -4914,7 +4862,7 @@ binary_generator_pattern(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a generator
node.
+%% @doc Returns the body subtree of a `generator' node.
%%
%% @see binary_generator/2
@@ -4930,8 +4878,8 @@ binary_generator_body(Node) ->
%% =====================================================================
-%% @doc Creates an abstract block expression. If Body
is
-%% [B1, ..., Bn]
, the result represents "begin
+%% @doc Creates an abstract block expression. If `Body' is
+%% `[B1, ..., Bn]', the result represents "begin
%% B1, ..., Bn end
".
%%
%% @see block_expr_body/1
@@ -4959,8 +4907,7 @@ revert_block_expr(Node) ->
%% =====================================================================
-%% @doc Returns the list of body subtrees of a block_expr
-%% node.
+%% @doc Returns the list of body subtrees of a `block_expr' node.
%%
%% @see block_expr/1
@@ -4976,10 +4923,10 @@ block_expr_body(Node) ->
%% =====================================================================
-%% @doc Creates an abstract if-expression. If Clauses
is
-%% [C1, ..., Cn]
, the result represents "if
+%% @doc Creates an abstract if-expression. If `Clauses' is
+%% `[C1, ..., Cn]', the result represents "if
%% C1; ...; Cn end
". More exactly, if each
-%% Ci
represents "() Gi ->
+%% `Ci' represents "() Gi ->
%% Bi
", then the result represents "if
%% G1 -> B1; ...; Gn -> Bn
%% end
".
@@ -5014,8 +4961,7 @@ revert_if_expr(Node) ->
%% =====================================================================
-%% @doc Returns the list of clause subtrees of an if_expr
-%% node.
+%% @doc Returns the list of clause subtrees of an `if_expr' node.
%%
%% @see if_expr/1
@@ -5031,10 +4977,10 @@ if_expr_clauses(Node) ->
%% =====================================================================
-%% @doc Creates an abstract case-expression. If Clauses
is
-%% [C1, ..., Cn]
, the result represents "case
+%% @doc Creates an abstract case-expression. If `Clauses' is
+%% `[C1, ..., Cn]', the result represents "case
%% Argument of C1; ...; Cn end
". More
-%% exactly, if each Ci
represents "(Pi)
+%% exactly, if each `Ci' represents "(Pi)
%% Gi -> Bi
", then the result represents
%% "case Argument of P1 G1 ->
%% B1; ...; Pn Gn -> Bn end
".
@@ -5078,7 +5024,7 @@ revert_case_expr(Node) ->
%% =====================================================================
-%% @doc Returns the argument subtree of a case_expr
node.
+%% @doc Returns the argument subtree of a `case_expr' node.
%%
%% @see case_expr/2
@@ -5094,8 +5040,7 @@ case_expr_argument(Node) ->
%% =====================================================================
-%% @doc Returns the list of clause subtrees of a case_expr
-%% node.
+%% @doc Returns the list of clause subtrees of a `case_expr' node.
%%
%% @see case_expr/2
@@ -5111,10 +5056,10 @@ case_expr_clauses(Node) ->
%% =====================================================================
-%% @doc Creates an abstract cond-expression. If Clauses
is
-%% [C1, ..., Cn]
, the result represents "cond
+%% @doc Creates an abstract cond-expression. If `Clauses' is
+%% `[C1, ..., Cn]', the result represents "cond
%% C1; ...; Cn end
". More exactly, if each
-%% Ci
represents "() Ei ->
+%% `Ci' represents "() Ei ->
%% Bi
", then the result represents "cond
%% E1 -> B1; ...; En -> Bn
%% end
".
@@ -5149,8 +5094,7 @@ revert_cond_expr(Node) ->
%% =====================================================================
-%% @doc Returns the list of clause subtrees of a cond_expr
-%% node.
+%% @doc Returns the list of clause subtrees of a `cond_expr' node.
%%
%% @see cond_expr/1
@@ -5175,21 +5119,21 @@ receive_expr(Clauses) ->
%% =====================================================================
-%% @doc Creates an abstract receive-expression. If Timeout
-%% is none
, the result represents "receive
-%% C1; ...; Cn end
" (the Action
-%% argument is ignored). Otherwise, if Clauses
is
-%% [C1, ..., Cn]
and Action
is [A1, ...,
-%% Am]
, the result represents "receive C1; ...;
+%% @doc Creates an abstract receive-expression. If `Timeout'
+%% is `none', the result represents "receive
+%% C1; ...; Cn end
" (the `Action'
+%% argument is ignored). Otherwise, if `Clauses' is
+%% `[C1, ..., Cn]' and `Action' is `[A1, ...,
+%% Am]', the result represents "receive C1; ...;
%% Cn after Timeout -> A1, ..., Am
-%% end
". More exactly, if each Ci
represents
+%% end
". More exactly, if each `Ci' represents
%% "(Pi) Gi -> Bi
", then the
%% result represents "receive P1 G1 ->
%% B1; ...; Pn Gn -> Bn ...
%% end
".
%%
-%% Note that in Erlang, a receive-expression must have at least one
-%% clause if no timeout part is specified.
+%% Note that in Erlang, a receive-expression must have at least one
+%% clause if no timeout part is specified.
%%
%% @see receive_expr_clauses/1
%% @see receive_expr_timeout/1
@@ -5254,7 +5198,7 @@ revert_receive_expr(Node) ->
%% =====================================================================
%% @doc Returns the list of clause subtrees of a
-%% receive_expr
node.
+%% `receive_expr' node.
%%
%% @see receive_expr/3
@@ -5272,12 +5216,12 @@ receive_expr_clauses(Node) ->
%% =====================================================================
-%% @doc Returns the timeout subtree of a receive_expr
node,
-%% if any. If Node
represents "receive C1;
-%% ...; Cn end
", none
is returned.
-%% Otherwise, if Node
represents "receive
+%% @doc Returns the timeout subtree of a `receive_expr' node,
+%% if any. If `Node' represents "receive C1;
+%% ...; Cn end
", `none' is returned.
+%% Otherwise, if `Node' represents "receive
%% C1; ...; Cn after Timeout -> ... end
",
-%% Timeout
is returned.
+%% `Timeout' is returned.
%%
%% @see receive_expr/3
@@ -5296,7 +5240,7 @@ receive_expr_timeout(Node) ->
%% =====================================================================
%% @doc Returns the list of action body subtrees of a
-%% receive_expr
node. If Node
represents
+%% `receive_expr' node. If `Node' represents
%% "receive C1; ...; Cn end
", this is the
%% empty list.
%%
@@ -5343,26 +5287,26 @@ try_after_expr(Body, After) ->
%% =====================================================================
-%% @doc Creates an abstract try-expression. If Body
is
-%% [B1, ..., Bn]
, Clauses
is [C1, ...,
-%% Cj]
, Handlers
is [H1, ..., Hk]
, and
-%% After
is [A1, ..., Am]
, the result
+%% @doc Creates an abstract try-expression. If `Body' is
+%% `[B1, ..., Bn]', `Clauses' is `[C1, ...,
+%% Cj]', `Handlers' is `[H1, ..., Hk]', and
+%% `After' is `[A1, ..., Am]', the result
%% represents "try B1, ..., Bn of C1;
%% ...; Cj catch H1; ...; Hk after
%% A1, ..., Am end
". More exactly, if each
-%% Ci
represents "(CPi) CGi ->
-%% CBi
", and each Hi
represents
+%% `Ci' represents "(CPi) CGi ->
+%% CBi
", and each `Hi' represents
%% "(HPi) HGi -> HBi
", then the
%% result represents "try B1, ..., Bn of
%% CP1 CG1 -> CB1; ...; CPj
%% CGj -> CBj catch HP1 HG1 ->
%% HB1; ...; HPk HGk -> HBk after
-%% A1, ..., Am end
"; cf.
-%% case_expr/2
. If Clauses
is the empty list,
-%% the of ...
section is left out. If After
is
-%% the empty list, the after ...
section is left out. If
-%% Handlers
is the empty list, and After
is
-%% nonempty, the catch ...
section is left out.
+%% A1, ..., Am end
"; see
+%% {@link case_expr/2}. If `Clauses' is the empty list,
+%% the `of ...' section is left out. If `After' is
+%% the empty list, the `after ...' section is left out. If
+%% `Handlers' is the empty list, and `After' is
+%% nonempty, the `catch ...' section is left out.
%%
%% @see try_expr_body/1
%% @see try_expr_clauses/1
@@ -5420,8 +5364,7 @@ revert_try_expr(Node) ->
%% =====================================================================
-%% @doc Returns the list of body subtrees of a try_expr
-%% node.
+%% @doc Returns the list of body subtrees of a `try_expr' node.
%%
%% @see try_expr/4
@@ -5438,7 +5381,7 @@ try_expr_body(Node) ->
%% =====================================================================
%% @doc Returns the list of case-clause subtrees of a
-%% try_expr
node. If Node
represents
+%% `try_expr' node. If `Node' represents
%% "try Body catch H1; ...; Hn
%% end
", the result is the empty list.
%%
@@ -5457,7 +5400,7 @@ try_expr_clauses(Node) ->
%% =====================================================================
%% @doc Returns the list of handler-clause subtrees of a
-%% try_expr
node.
+%% `try_expr' node.
%%
%% @see try_expr/4
@@ -5473,8 +5416,7 @@ try_expr_handlers(Node) ->
%% =====================================================================
-%% @doc Returns the list of "after" subtrees of a try_expr
-%% node.
+%% @doc Returns the list of "after" subtrees of a `try_expr' node.
%%
%% @see try_expr/4
@@ -5513,7 +5455,7 @@ class_qualifier(Class, Body) ->
%% =====================================================================
%% @doc Returns the argument (the class) subtree of a
-%% class_qualifier
node.
+%% `class_qualifier' node.
%%
%% @see class_qualifier/2
@@ -5524,7 +5466,7 @@ class_qualifier_argument(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a class_qualifier
node.
+%% @doc Returns the body subtree of a `class_qualifier' node.
%%
%% @see class_qualifier/2
@@ -5536,9 +5478,9 @@ class_qualifier_body(Node) ->
%% =====================================================================
%% @doc Creates an abstract "implicit fun" expression. If
-%% Arity
is none
, this is equivalent to
-%% implicit_fun(Name)
, otherwise it is equivalent to
-%% implicit_fun(arity_qualifier(Name, Arity))
.
+%% `Arity' is `none', this is equivalent to
+%% `implicit_fun(Name)', otherwise it is equivalent to
+%% `implicit_fun(arity_qualifier(Name, Arity))'.
%%
%% (This is a utility function.)
%%
@@ -5555,10 +5497,10 @@ implicit_fun(Name, Arity) ->
%% =====================================================================
%% @doc Creates an abstract module-qualified "implicit fun" expression.
-%% If Module
is none
, this is equivalent to
-%% implicit_fun(Name, Arity)
, otherwise it is equivalent to
-%% implicit_fun(module_qualifier(Module, arity_qualifier(Name,
-%% Arity))
.
+%% If `Module' is `none', this is equivalent to
+%% `implicit_fun(Name, Arity)', otherwise it is equivalent to
+%% `implicit_fun(module_qualifier(Module, arity_qualifier(Name,
+%% Arity))'.
%%
%% (This is a utility function.)
%%
@@ -5576,7 +5518,7 @@ implicit_fun(Module, Name, Arity) ->
%% =====================================================================
%% @doc Creates an abstract "implicit fun" expression. The result
-%% represents "fun Name
". Name
should
+%% represents "fun Name
". `Name' should
%% represent either F/A
or
%% M:F/A
%%
@@ -5635,13 +5577,13 @@ revert_implicit_fun(Node) ->
%% =====================================================================
-%% @doc Returns the name subtree of an implicit_fun
node.
+%% @doc Returns the name subtree of an `implicit_fun' node.
%%
-%% Note: if Node
represents "fun
+%% Note: if `Node' represents "fun
%% N/A
" or "fun
%% M:N/A
", then the result is the
%% subtree representing "N/A
" or
-%% "M:N/A
", respectively.
+%% "M:N/A
", respectively.
%%
%% @see implicit_fun/1
%% @see arity_qualifier/2
@@ -5671,10 +5613,10 @@ implicit_fun_name(Node) ->
%% =====================================================================
-%% @doc Creates an abstract fun-expression. If Clauses
is
-%% [C1, ..., Cn]
, the result represents "fun
+%% @doc Creates an abstract fun-expression. If `Clauses' is
+%% `[C1, ..., Cn]', the result represents "fun
%% C1; ...; Cn end
". More exactly, if each
-%% Ci
represents "(Pi1, ..., Pim)
+%% `Ci' represents "(Pi1, ..., Pim)
%% Gi -> Bi
", then the result represents
%% "fun (P11, ..., P1m) G1 ->
%% B1; ...; (Pn1, ..., Pnm) Gn ->
@@ -5711,8 +5653,7 @@ revert_fun_expr(Node) ->
%% =====================================================================
-%% @doc Returns the list of clause subtrees of a fun_expr
-%% node.
+%% @doc Returns the list of clause subtrees of a `fun_expr' node.
%%
%% @see fun_expr/1
@@ -5728,14 +5669,14 @@ fun_expr_clauses(Node) ->
%% =====================================================================
-%% @doc Returns the arity of a fun_expr
node. The result is
+%% @doc Returns the arity of a `fun_expr' node. The result is
%% the number of parameter patterns in the first clause of the
%% fun-expression; subsequent clauses are ignored.
%%
-%% An exception is thrown if fun_expr_clauses(Node)
+%% An exception is thrown if `fun_expr_clauses(Node)'
%% returns an empty list, or if the first element of that list is not a
-%% syntax tree C
of type clause
such that
-%% clause_patterns(C)
is a nonempty list.
+%% syntax tree `C' of type `clause' such that
+%% `clause_patterns(C)' is a nonempty list.
%%
%% @see fun_expr/1
%% @see fun_expr_clauses/1
@@ -5768,7 +5709,7 @@ revert_parentheses(Node) ->
%% =====================================================================
-%% @doc Returns the body subtree of a parentheses
node.
+%% @doc Returns the body subtree of a `parentheses' node.
%%
%% @see parentheses/1
@@ -5788,22 +5729,22 @@ macro(Name) ->
%% =====================================================================
-%% @doc Creates an abstract macro application. If Arguments
-%% is none
, the result represents
-%% "?Name
", otherwise, if Arguments
-%% is [A1, ..., An]
, the result represents
+%% @doc Creates an abstract macro application. If `Arguments'
+%% is `none', the result represents
+%% "?Name
", otherwise, if `Arguments'
+%% is `[A1, ..., An]', the result represents
%% "?Name(A1, ..., An)
".
%%
-%% Notes: if Arguments
is the empty list, the result
+%% Notes: if `Arguments' is the empty list, the result
%% will thus represent "?Name()
", including a pair
-%% of matching parentheses.
+%% of matching parentheses.
%%
-%% The only syntactical limitation imposed by the preprocessor on the
+%% The only syntactical limitation imposed by the preprocessor on the
%% arguments to a macro application (viewed as sequences of tokens) is
%% that they must be balanced with respect to parentheses, brackets,
-%% begin ... end
, case ... end
, etc. The
-%% text
node type can be used to represent arguments which
-%% are not regular Erlang constructs.
+%% `begin ... end', `case ... end', etc. The
+%% `text' node type can be used to represent arguments which
+%% are not regular Erlang constructs.
%%
%% @see macro_name/1
%% @see macro_arguments/1
@@ -5825,7 +5766,7 @@ macro(Name, Arguments) ->
%% =====================================================================
-%% @doc Returns the name subtree of a macro
node.
+%% @doc Returns the name subtree of a `macro' node.
%%
%% @see macro/2
@@ -5836,12 +5777,12 @@ macro_name(Node) ->
%% =====================================================================
-%% @doc Returns the list of argument subtrees of a macro
-%% node, if any. If Node
represents
-%% "?Name
", none
is returned.
-%% Otherwise, if Node
represents
+%% @doc Returns the list of argument subtrees of a `macro'
+%% node, if any. If `Node' represents
+%% "?Name
", `none' is returned.
+%% Otherwise, if `Node' represents
%% "?Name(A1, ..., An)
",
-%% [A1, ..., An]
is returned.
+%% `[A1, ..., An]' is returned.
%%
%% @see macro/2
@@ -5853,12 +5794,12 @@ macro_arguments(Node) ->
%% =====================================================================
%% @doc Returns the syntax tree corresponding to an Erlang term.
-%% Term
must be a literal term, i.e., one that can be
+%% `Term' must be a literal term, i.e., one that can be
%% represented as a source code literal. Thus, it may not contain a
%% process identifier, port, reference, binary or function value as a
%% subterm. The function recognises printable strings, in order to get a
%% compact and readable representation. Evaluation fails with reason
-%% badarg
if Term
is not a literal term.
+%% `badarg' if `Term' is not a literal term.
%%
%% @see concrete/1
%% @see is_literal/1
@@ -5909,16 +5850,16 @@ abstract_tail(H, T) ->
%% =====================================================================
%% @doc Returns the Erlang term represented by a syntax tree. Evaluation
-%% fails with reason badarg
if Node
does not
+%% fails with reason `badarg' if `Node' does not
%% represent a literal term.
%%
-%% Note: Currently, the set of syntax trees which have a concrete
+%% Note: Currently, the set of syntax trees which have a concrete
%% representation is larger than the set of trees which can be built
-%% using the function abstract/1
. An abstract character
-%% will be concretised as an integer, while abstract/1
does
+%% using the function {@link abstract/1}. An abstract character
+%% will be concretised as an integer, while {@link abstract/1} does
%% not at present yield an abstract character for any input. (Use the
-%% char/1
function to explicitly create an abstract
-%% character.)
+%% {@link char/1} function to explicitly create an abstract
+%% character.)
%%
%% @see abstract/1
%% @see is_literal/1
@@ -5961,7 +5902,7 @@ concrete(Node) ->
{value, concrete(F), []}
end, [], true),
B;
- _ ->
+ _ ->
erlang:error({badarg, Node})
end.
@@ -5972,10 +5913,10 @@ concrete_list([]) ->
%% =====================================================================
-%% @doc Returns true
if Node
represents a
-%% literal term, otherwise false
. This function returns
-%% true
if and only if the value of
-%% concrete(Node)
is defined.
+%% @doc Returns `true' if `Node' represents a
+%% literal term, otherwise `false'. This function returns
+%% `true' if and only if the value of
+%% `concrete(Node)' is defined.
%%
%% @see abstract/1
%% @see concrete/1
@@ -6006,19 +5947,19 @@ is_literal(T) ->
%% =====================================================================
-%% @doc Returns an erl_parse
-compatible representation of a
-%% syntax tree, if possible. If Tree
represents a
+%% @doc Returns an `erl_parse'-compatible representation of a
+%% syntax tree, if possible. If `Tree' represents a
%% well-formed Erlang program or expression, the conversion should work
-%% without problems. Typically, is_tree/1
yields
-%% true
if conversion failed (i.e., the result is still an
-%% abstract syntax tree), and false
otherwise.
+%% without problems. Typically, {@link is_tree/1} yields
+%% `true' if conversion failed (i.e., the result is still an
+%% abstract syntax tree), and `false' otherwise.
%%
-%% The is_tree/1
test is not completely foolproof. For a
-%% few special node types (e.g. arity_qualifier
), if such a
+%% The {@link is_tree/1} test is not completely foolproof. For a
+%% few special node types (e.g. `arity_qualifier'), if such a
%% node occurs in a context where it is not expected, it will be left
%% unchanged as a non-reverted subtree of the result. This can only
-%% happen if Tree
does not actually represent legal Erlang
-%% code.
+%% happen if `Tree' does not actually represent legal Erlang
+%% code.
%%
%% @see revert_forms/1
%% @see //stdlib/erl_parse
@@ -6155,11 +6096,11 @@ revert_root(Node) ->
%% =====================================================================
%% @doc Reverts a sequence of Erlang source code forms. The sequence can
-%% be given either as a form_list
syntax tree (possibly
+%% be given either as a `form_list' syntax tree (possibly
%% nested), or as a list of "program form" syntax trees. If successful,
-%% the corresponding flat list of erl_parse
-compatible
-%% syntax trees is returned (cf. revert/1
). If some program
-%% form could not be reverted, {error, Form}
is thrown.
+%% the corresponding flat list of `erl_parse'-compatible
+%% syntax trees is returned (see {@link revert/1}). If some program
+%% form could not be reverted, `{error, Form}' is thrown.
%% Standalone comments in the form sequence are discarded.
%%
%% @see revert/1
@@ -6209,57 +6150,53 @@ revert_forms_1([]) ->
%% =====================================================================
%% @doc Returns the grouped list of all subtrees of a syntax tree. If
-%% Node
is a leaf node (cf. is_leaf/1
), this
+%% `Node' is a leaf node (see {@link is_leaf/1}), this
%% is the empty list, otherwise the result is always a nonempty list,
-%% containing the lists of subtrees of Node
, in
+%% containing the lists of subtrees of `Node', in
%% left-to-right order as they occur in the printed program text, and
%% grouped by category. Often, each group contains only a single
%% subtree.
%%
-%% Depending on the type of Node
, the size of some
+%% Depending on the type of `Node', the size of some
%% groups may be variable (e.g., the group consisting of all the
%% elements of a tuple), while others always contain the same number of
%% elements - usually exactly one (e.g., the group containing the
%% argument expression of a case-expression). Note, however, that the
%% exact structure of the returned list (for a given node type) should
%% in general not be depended upon, since it might be subject to change
-%% without notice.
+%% without notice.
%%
-%% The function subtrees/1
and the constructor functions
-%% make_tree/2
and update_tree/2
can be a
+%% The function {@link subtrees/1} and the constructor functions
+%% {@link make_tree/2} and {@link update_tree/2} can be a
%% great help if one wants to traverse a syntax tree, visiting all its
%% subtrees, but treat nodes of the tree in a uniform way in most or all
%% cases. Using these functions makes this simple, and also assures that
%% your code is not overly sensitive to extensions of the syntax tree
%% data type, because any node types not explicitly handled by your code
-%% can be left to a default case.
+%% can be left to a default case.
%%
-%% For example:
-%%
-%% postorder(F, Tree) ->
+%% For example:
+%% ```postorder(F, Tree) ->
%% F(case subtrees(Tree) of
%% [] -> Tree;
%% List -> update_tree(Tree,
%% [[postorder(F, Subtree)
%% || Subtree <- Group]
%% || Group <- List])
-%% end).
-%%
-%% maps the function F
on Tree
and all its
+%% end).'''
+%% maps the function `F' on `Tree' and all its
%% subtrees, doing a post-order traversal of the syntax tree. (Note the
-%% use of update_tree/2
to preserve node attributes.) For a
+%% use of {@link update_tree/2} to preserve node attributes.) For a
%% simple function like:
-%%
-%% f(Node) ->
+%% ```f(Node) ->
%% case type(Node) of
%% atom -> atom("a_" ++ atom_name(Node));
%% _ -> Node
-%% end.
-%%
-%% the call postorder(fun f/1, Tree)
will yield a new
-%% representation of Tree
in which all atom names have been
+%% end.'''
+%% the call `postorder(fun f/1, Tree)' will yield a new
+%% representation of `Tree' in which all atom names have been
%% extended with the prefix "a_", but nothing else (including comments,
-%% annotations and line numbers) has been changed.
+%% annotations and line numbers) has been changed.
%%
%% @see make_tree/2
%% @see type/1
@@ -6430,8 +6367,8 @@ subtrees(T) ->
%% =====================================================================
%% @doc Creates a syntax tree with the same type and attributes as the
-%% given tree. This is equivalent to copy_attrs(Node,
-%% make_tree(type(Node), Groups))
.
+%% given tree. This is equivalent to `copy_attrs(Node,
+%% make_tree(type(Node), Groups))'.
%%
%% @see make_tree/2
%% @see copy_attrs/2
@@ -6445,19 +6382,19 @@ update_tree(Node, Groups) ->
%% =====================================================================
%% @doc Creates a syntax tree with the given type and subtrees.
-%% Type
must be a node type name (cf. type/1
)
-%% that does not denote a leaf node type (cf. is_leaf/1
).
-%% Groups
must be a nonempty list of groups of
+%% `Type' must be a node type name (see {@link type/1})
+%% that does not denote a leaf node type (see {@link is_leaf/1}).
+%% `Groups' must be a nonempty list of groups of
%% syntax trees, representing the subtrees of a node of the given type,
%% in left-to-right order as they would occur in the printed program
-%% text, grouped by category as done by subtrees/1
.
+%% text, grouped by category as done by {@link subtrees/1}.
%%
-%% The result of copy_attrs(Node, make_tree(type(Node),
-%% subtrees(Node)))
(cf. update_tree/2
) represents
-%% the same source code text as the original Node
, assuming
-%% that subtrees(Node)
yields a nonempty list. However, it
+%% The result of `copy_attrs(Node, make_tree(type(Node),
+%% subtrees(Node)))' (see {@link update_tree/2}) represents
+%% the same source code text as the original `Node', assuming
+%% that `subtrees(Node)' yields a nonempty list. However, it
%% does not necessarily have the same data representation as
-%% Node
.
+%% `Node'.
%%
%% @see update_tree/2
%% @see subtrees/1
@@ -6525,37 +6462,37 @@ make_tree(tuple, [E]) -> tuple(E).
%% @doc Creates a meta-representation of a syntax tree. The result
%% represents an Erlang expression "MetaTree
"
%% which, if evaluated, will yield a new syntax tree representing the
-%% same source code text as Tree
(although the actual data
+%% same source code text as `Tree' (although the actual data
%% representation may be different). The expression represented by
-%% MetaTree
is implementation independent with
+%% `MetaTree' is implementation independent with
%% regard to the data structures used by the abstract syntax tree
-%% implementation. Comments attached to nodes of Tree
will
+%% implementation. Comments attached to nodes of `Tree' will
%% be preserved, but other attributes are lost.
%%
-%% Any node in Tree
whose node type is
-%% variable
(cf. type/1
), and whose list of
-%% annotations (cf. get_ann/1
) contains the atom
-%% meta_var
, will remain unchanged in the resulting tree,
-%% except that exactly one occurrence of meta_var
is
-%% removed from its annotation list.
+%% Any node in `Tree' whose node type is
+%% `variable' (see {@link type/1}), and whose list of
+%% annotations (see {@link get_ann/1}) contains the atom
+%% `meta_var', will remain unchanged in the resulting tree,
+%% except that exactly one occurrence of `meta_var' is
+%% removed from its annotation list.
%%
-%% The main use of the function meta/1
is to transform a
-%% data structure Tree
, which represents a piece of program
+%% The main use of the function `meta/1' is to transform a
+%% data structure `Tree', which represents a piece of program
%% code, into a form that is representation independent when
-%% printed. E.g., suppose Tree
represents a variable
-%% named "V". Then (assuming a function print/1
for
-%% printing syntax trees), evaluating print(abstract(Tree))
-%% - simply using abstract/1
to map the actual data
+%% printed. E.g., suppose `Tree' represents a variable
+%% named "V". Then (assuming a function `print/1' for
+%% printing syntax trees), evaluating `print(abstract(Tree))'
+%% - simply using {@link abstract/1} to map the actual data
%% structure onto a syntax tree representation - would output a string
-%% that might look something like "{tree, variable, ..., "V",
-%% ...}
", which is obviously dependent on the implementation of
+%% that might look something like "`{tree, variable, ..., "V",
+%% ...}'", which is obviously dependent on the implementation of
%% the abstract syntax trees. This could e.g. be useful for caching a
%% syntax tree in a file. However, in some situations like in a program
%% generator generator (with two "generator"), it may be unacceptable.
-%% Using print(meta(Tree))
instead would output a
+%% Using `print(meta(Tree))' instead would output a
%% representation independent syntax tree generating
%% expression; in the above case, something like
-%% "erl_syntax:variable("V")
".
+%% "`erl_syntax:variable("V")'".
%%
%% @see abstract/1
%% @see type/1
@@ -6695,29 +6632,30 @@ tree(Type) ->
%% =====================================================================
%% @doc For special purposes only. Creates an abstract syntax
-%% tree node with type tag Type
and associated data
-%% Data
.
+%% tree node with type tag `Type' and associated data
+%% `Data'.
%%
-%% This function and the related is_tree/1
and
-%% data/1
provide a uniform way to extend the set of
-%% erl_parse
node types. The associated data is any term,
-%% whose format may depend on the type tag.
+%% This function and the related {@link is_tree/1} and
+%% {@link data/1} provide a uniform way to extend the set of
+%% `erl_parse' node types. The associated data is any term,
+%% whose format may depend on the type tag.
%%
-%% Notes:
+%% === Notes: ===
%%
%% - Any nodes created outside of this module must have type tags
%% distinct from those currently defined by this module; see
-%%
type/1
for a complete list.
+%% {@link type/1} for a complete list.
%% - The type tag of a syntax tree node may also be used
-%% as a primary tag by the
erl_parse
representation;
+%% as a primary tag by the `erl_parse' representation;
%% in that case, the selector functions for that node type
%% must handle both the abstract syntax tree and the
-%% erl_parse
form. The function type(T)
+%% `erl_parse' form. The function `type(T)'
%% should return the correct type tag regardless of the
-%% representation of T
, so that the user sees no
-%% difference between erl_syntax
and
-%% erl_parse
nodes.
+%% representation of `T', so that the user sees no
+%% difference between `erl_syntax' and
+%% `erl_parse' nodes.
%%
+%%
%% @see is_tree/1
%% @see data/1
%% @see type/1
@@ -6729,12 +6667,12 @@ tree(Type, Data) ->
%% =====================================================================
-%% @doc For special purposes only. Returns true
if
-%% Tree
is an abstract syntax tree and false
+%% @doc For special purposes only. Returns `true' if
+%% `Tree' is an abstract syntax tree and `false'
%% otherwise.
%%
-%% Note: this function yields false
for all
-%% "old-style" erl_parse
-compatible "parse trees".
+%% Note: this function yields `false' for all
+%% "old-style" `erl_parse'-compatible "parse trees".
%%
%% @see tree/2
@@ -6749,8 +6687,8 @@ is_tree(_) ->
%% =====================================================================
%% @doc For special purposes only. Returns the associated data
%% of a syntax tree node. Evaluation fails with reason
-%% badarg
if is_tree(Node)
does not yield
-%% true
.
+%% `badarg' if `is_tree(Node)' does not yield
+%% `true'.
%%
%% @see tree/2
@@ -6766,17 +6704,17 @@ data(T) -> erlang:error({badarg, T}).
%% =====================================================================
-%% @doc Creates a wrapper structure around an erl_parse
+%% @doc Creates a wrapper structure around an `erl_parse'
%% "parse tree".
%%
-%% This function and the related unwrap/1
and
-%% is_wrapper/1
provide a uniform way to attach arbitrary
-%% information to an erl_parse
tree. Some information about
+%% This function and the related {@link unwrap/1} and
+%% {@link is_wrapper/1} provide a uniform way to attach arbitrary
+%% information to an `erl_parse' tree. Some information about
%% the encapsuled tree may be cached in the wrapper, such as the node
%% type. All functions on syntax trees must behave so that the user sees
-%% no difference between wrapped and non-wrapped erl_parse
+%% no difference between wrapped and non-wrapped `erl_parse'
%% trees. Attaching a wrapper onto another wrapper structure is an
-%% error.
+%% error.
-spec wrap(erl_parse()) -> #wrapper{}.
@@ -6787,9 +6725,9 @@ wrap(Node) ->
%% =====================================================================
-%% @doc Removes any wrapper structure, if present. If Node
+%% @doc Removes any wrapper structure, if present. If `Node'
%% is a wrapper structure, this function returns the wrapped
-%% erl_parse
tree; otherwise it returns Node
+%% `erl_parse' tree; otherwise it returns `Node'
%% itself.
-spec unwrap(syntaxTree()) -> #tree{} | erl_parse().
@@ -6799,8 +6737,8 @@ unwrap(Node) -> Node. % This could also be a new-form node.
%% =====================================================================
-%% @doc Returns true
if the argument is a wrapper
-%% structure, otherwise false
.
+%% @doc Returns `true' if the argument is a wrapper
+%% structure, otherwise `false'.
-ifndef(NO_UNUSED).
-spec is_wrapper(term()) -> boolean().
--
cgit v1.2.3