erl_parse (stdlib v7.0)
View SourceThis module is the basic Erlang parser that converts tokens into the abstract form of either forms (that is, top-level constructs), expressions, or terms.
The Abstract Format is described in the ERTS User's Guide. Notice that a token
list must end with the dot token to be acceptable to the parse functions
(see the erl_scan) module.
Error Information
ErrorInfo is the standard ErrorInfo structure that is returned from all I/O modules. The format is as follows:
{ErrorLine, Module, ErrorDescriptor}A string describing the error is obtained with the following call:
Module:format_error(ErrorDescriptor)See Also
erl_anno, erl_scan, io, section The Abstract Format
in the ERTS User's Guide.
Summary
Types
Abstract form of an Erlang clause.
Abstract form of an Erlang expression.
Abstract form of an Erlang form.
Abstract form of an Erlang type.
Abstract representation of an element of a bitstring.
Abstract representation of a record field.
Abstract representation of a list, bitstring or map generator.
Abstract representation of a remote function call.
Tuples {error, error_info()} and {warning, error_info()}, denoting
syntactically incorrect forms and warnings, and {eof, line()}, denoting an
end-of-stream encountered before a complete form had been parsed.
Functions
Converts the Erlang data structure Data into an abstract form of type
AbsTerm. This function is the inverse of normalise/1.
Converts the Erlang data structure Data into an abstract form of type
AbsTerm.
Assumes that Term is a term with the same structure as a erl_parse tree, but
with terms, say T, where a erl_parse tree has collections of annotations.
Returns a term where each collection of annotations Anno of the nodes of the
erl_parse tree Abstr is replaced by the term returned by
erl_anno:to_term(Anno). The erl_parse tree is
traversed in a depth-first, left-to-right fashion.
Updates an accumulator by applying Fun on each collection of annotations of
the erl_parse tree Abstr.
Uses an ErrorDescriptor and returns a string that describes the error.
Modifies the erl_parse tree Abstr by applying Fun on each collection of
annotations of the nodes of the erl_parse tree. The erl_parse tree is
traversed in a depth-first, left-to-right fashion.
Modifies the erl_parse tree Abstr by applying Fun on each collection of
annotations of the nodes of the erl_parse tree, while at the same time
updating an accumulator.
Assumes that Term is a term with the same structure as a erl_parse tree, but
with locations where a erl_parse tree has
collections of annotations.
Converts the abstract form AbsTerm of a term into a conventional Erlang data
structure (that is, the term itself). This function is the inverse of
abstract/1.
Parses Tokens as if it was a list of expressions.
Parses Tokens as if it was a form.
Parses Tokens as if it was a term.
Equivalent to tokens(AbsTerm, []).
Generates a list of tokens representing the abstract form AbsTerm of an
expression. Optionally, MoreTokens is appended.
Types
-type abstract_clause() :: af_clause().
Abstract form of an Erlang clause.
-type abstract_expr() :: af_literal() | af_match(abstract_expr()) | af_maybe_match() | af_variable() | af_tuple(abstract_expr()) | af_nil() | af_cons(abstract_expr()) | af_bin(abstract_expr()) | af_binary_op(abstract_expr()) | af_unary_op(abstract_expr()) | af_record_creation(abstract_expr()) | af_record_update(abstract_expr()) | af_record_index() | af_record_field_access(abstract_expr()) | af_map_creation(abstract_expr()) | af_map_update(abstract_expr()) | af_catch() | af_local_call() | af_remote_call() | af_list_comprehension() | af_map_comprehension() | af_binary_comprehension() | af_block() | af_if() | af_case() | af_try() | af_receive() | af_local_fun() | af_remote_fun() | af_fun() | af_named_fun() | af_maybe() | af_maybe_else().
Abstract form of an Erlang expression.
-type abstract_form() :: af_module() | af_behavior() | af_behaviour() | af_export() | af_import() | af_export_type() | af_compile() | af_file() | af_record_decl() | af_type_decl() | af_function_spec() | af_wild_attribute() | af_function_decl().
Abstract form of an Erlang form.
-type abstract_type() :: af_annotated_type() | af_atom() | af_bitstring_type() | af_empty_list_type() | af_fun_type() | af_integer_range_type() | af_map_type() | af_predefined_type() | af_record_type() | af_remote_type() | af_singleton_integer_type() | af_tuple_type() | af_type_union() | af_type_variable() | af_user_defined_type().
Abstract form of an Erlang type.
-type af_anno() :: af_variable().
-type af_annotated_type() :: {ann_type, anno(), [af_anno() | abstract_type()]}.
-type af_args() :: [abstract_expr()].
-type af_assoc(T) :: {map_field_assoc, anno(), T, T} | af_assoc_exact(T).
-type af_assoc_exact(T) :: {map_field_exact, anno(), T, T}.
-type af_assoc_type() :: {type, anno(), map_field_assoc, [abstract_type()]} | {type, anno(), map_field_exact, [abstract_type()]}.
-type af_atom() :: af_lit_atom(atom()).
-type af_bin(T) :: {bin, anno(), [af_binelement(T)]}.
-type af_binary_comprehension() :: {bc, anno(), af_template(), af_qualifier_seq()}.
-type af_binelement(T) :: {bin_element, anno(), T, af_binelement_size(), type_specifier_list()}.
Abstract representation of an element of a bitstring.
-type af_binelement_size() :: default | abstract_expr().
-type af_bitstring_type() :: {type, anno(), binary, [af_singleton_integer_type()]}.
-type af_body() :: [abstract_expr(), ...].
-type af_case() :: {'case', anno(), abstract_expr(), af_clause_seq()}.
-type af_catch() :: {'catch', anno(), abstract_expr()}.
-type af_clause() :: {clause, anno(), [af_pattern()], af_guard_seq(), af_body()}.
-type af_clause_seq() :: [af_clause(), ...].
-type af_cons(T) :: {cons, anno(), T, T}.
-type af_constrained_function_type() :: {type, anno(), bounded_fun, [af_function_type() | af_function_constraint()]}.
-type af_constraint() :: {type, anno(), constraint, [af_lit_atom(is_subtype) | [af_type_variable() | abstract_type()]]}.
-type af_empty_list_type() :: {type, anno(), nil, []}.
-type af_export() :: {attribute, anno(), export, af_fa_list()}.
-type af_export_type() :: {attribute, anno(), export_type, af_ta_list()}.
-type af_fa_list() :: [{function_name(), arity()}].
-type af_field() :: {record_field, anno(), af_field_name()} | {record_field, anno(), af_field_name(), abstract_expr()}.
-type af_field_decl() :: af_typed_field() | af_field().
Abstract representation of a record field.
-type af_field_name() :: af_atom().
-type af_filter() :: abstract_expr().
-type af_fun() :: {'fun', anno(), {clauses, af_clause_seq()}}.
-type af_fun_type() :: {type, anno(), 'fun', []} | {type, anno(), 'fun', [{type, anno(), any} | abstract_type()]} | af_function_type().
-type af_function_constraint() :: [af_constraint(), ...].
-type af_function_decl() :: {function, anno(), function_name(), arity(), af_clause_seq()}.
-type af_function_spec() :: {attribute, anno(), spec_attr(), {{function_name(), arity()}, af_function_type_list()}} | {attribute, anno(), spec, {{module(), function_name(), arity()}, af_function_type_list()}}.
-type af_function_type() :: {type, anno(), 'fun', [{type, anno(), product, [abstract_type()]} | abstract_type()]}.
-type af_function_type_list() :: [af_constrained_function_type() | af_function_type(), ...].
-type af_generator() :: {generate, anno(), af_pattern(), abstract_expr()} | {generate_strict, anno(), af_pattern(), abstract_expr()} | {m_generate, anno(), af_assoc_exact(af_pattern()), abstract_expr()} | {m_generate_strict, anno(), af_assoc_exact(af_pattern()), abstract_expr()} | {b_generate, anno(), af_pattern(), abstract_expr()} | {b_generate_strict, anno(), af_pattern(), abstract_expr()} | af_zip_generator().
Abstract representation of a list, bitstring or map generator.
-type af_guard() :: [af_guard_test(), ...].
-type af_guard_call() :: {call, anno(), af_atom(), [af_guard_test()]}.
-type af_guard_seq() :: [af_guard()].
-type af_guard_test() :: af_literal() | af_variable() | af_tuple(af_guard_test()) | af_nil() | af_cons(af_guard_test()) | af_bin(af_guard_test()) | af_binary_op(af_guard_test()) | af_unary_op(af_guard_test()) | af_record_creation(af_guard_test()) | af_record_index() | af_record_field_access(af_guard_test()) | af_map_creation(af_guard_test()) | af_map_update(af_guard_test()) | af_guard_call() | af_remote_guard_call().
-type af_if() :: {'if', anno(), af_clause_seq()}.
-type af_import() :: {attribute, anno(), import, {module(), af_fa_list()}}.
-type af_integer() :: {integer, anno(), non_neg_integer()}.
-type af_integer_range_type() :: {type, anno(), range, [af_singleton_integer_type()]}.
-type af_list_comprehension() :: {lc, anno(), af_template(), af_qualifier_seq()}.
-type af_lit_atom(A) :: {atom, anno(), A}.
-type af_literal() :: af_atom() | af_character() | af_float() | af_integer() | af_string().
-type af_local_call() :: {call, anno(), af_local_function(), af_args()}.
-type af_local_fun() :: {'fun', anno(), {function, function_name(), arity()}}.
-type af_local_function() :: abstract_expr().
-type af_map_comprehension() :: {mc, anno(), af_assoc(abstract_expr()), af_qualifier_seq()}.
-type af_map_pattern() :: {map, anno(), [af_assoc_exact(af_pattern())]}.
-type af_map_type() :: {type, anno(), map, any} | {type, anno(), map, [af_assoc_type()]}.
-type af_match(T) :: {match, anno(), af_pattern(), T}.
-type af_maybe_else() :: {'maybe', anno(), af_body(), {'else', anno(), af_clause_seq()}}.
-type af_maybe_match() :: {maybe_match, anno(), af_pattern(), abstract_expr()}.
-type af_named_fun() :: {named_fun, anno(), fun_name(), af_clause_seq()}.
-type af_nil() :: {nil, anno()}.
-type af_pattern() :: af_literal() | af_match(af_pattern()) | af_variable() | af_tuple(af_pattern()) | af_nil() | af_cons(af_pattern()) | af_bin(af_pattern()) | af_binary_op(af_pattern()) | af_unary_op(af_pattern()) | af_record_creation(af_pattern()) | af_record_index() | af_map_pattern().
-type af_predefined_type() :: {type, anno(), type_name(), [abstract_type()]}.
-type af_qualifier() :: af_generator() | af_filter().
-type af_qualifier_seq() :: [af_qualifier(), ...].
-type af_receive() :: {'receive', anno(), af_clause_seq()} | {'receive', anno(), af_clause_seq(), abstract_expr(), af_body()}.
-type af_record_creation(T) :: {record, anno(), record_name(), [af_record_field(T)]}.
-type af_record_decl() :: {attribute, anno(), record, {record_name(), [af_field_decl()]}}.
-type af_record_field(T) :: {record_field, anno(), af_field_name(), T}.
-type af_record_field_access(T) :: {record_field, anno(), T, record_name(), af_field_name()}.
-type af_record_field_type() :: {type, anno(), field_type, [(Name :: af_atom()) | abstract_type()]}.
-type af_record_index() :: {record_index, anno(), record_name(), af_field_name()}.
-type af_record_type() :: {type, anno(), record, [(Name :: af_atom()) | af_record_field_type()]}.
-type af_record_update(T) :: {record, anno(), abstract_expr(), record_name(), [af_record_field(T)]}.
-type af_remote_call() :: {call, anno(), af_remote_function(), af_args()}.
-type af_remote_fun() :: {'fun', anno(), {function, module(), function_name(), arity()}} | {'fun', anno(), {function, af_atom() | af_variable(), af_atom() | af_variable(), af_integer() | af_variable()}}.
-type af_remote_function() :: {remote, anno(), abstract_expr(), abstract_expr()}.
Abstract representation of a remote function call.
-type af_remote_guard_call() :: {call, anno(), {remote, anno(), af_lit_atom(erlang), af_atom()}, [af_guard_test()]}.
-type af_remote_type() :: {remote_type, anno(), [(Module :: af_atom()) | (TypeName :: af_atom()) | [abstract_type()]]}.
-type af_singleton_integer_type() :: af_integer() | af_character() | af_unary_op(af_singleton_integer_type()) | af_binary_op(af_singleton_integer_type()).
-type af_template() :: abstract_expr().
-type af_try() :: {'try', anno(), af_body(), af_clause_seq() | [], af_clause_seq() | [], af_body() | []}.
-type af_tuple(T) :: {tuple, anno(), [T]}.
-type af_tuple_type() :: {type, anno(), tuple, any} | {type, anno(), tuple, [abstract_type()]}.
-type af_type_decl() :: {attribute, anno(), type_attr(), {type_name(), abstract_type(), [af_variable()]}}.
-type af_type_union() :: {type, anno(), union, [abstract_type(), ...]}.
-type af_typed_field() :: {typed_record_field, af_field(), abstract_type()}.
-type af_user_defined_type() :: {user_type, anno(), type_name(), [abstract_type()]}.
-type af_zip_generator() :: [af_generator(), ...].
-type anno() :: erl_anno:anno().
-type behaviour() :: atom().
-type binary_op() ::
'/' | '*' | 'div' | 'rem' | 'band' | 'and' | '+' | '-' | 'bor' | 'bxor' | 'bsl' | 'bsr' |
'or' | 'xor' | '++' | '--' | '==' | '/=' | '=<' | '<' | '>=' | '>' | '=:=' | '=/=' | '!'.
-type encoding_func() :: fun((non_neg_integer()) -> boolean()).
-type endianness() :: big | little | native.
-type erl_parse_tree() :: abstract_clause() | abstract_expr() | abstract_form() | abstract_type().
-type error_description() :: term().
-type error_info() :: {erl_anno:location(), module(), error_description()}.
-type form_info() :: {eof, erl_anno:location()} | {error, erl_scan:error_info() | error_info()} | {warning, erl_scan:error_info() | error_info()}.
Tuples {error, error_info()} and {warning, error_info()}, denoting
syntactically incorrect forms and warnings, and {eof, line()}, denoting an
end-of-stream encountered before a complete form had been parsed.
-type fun_name() :: atom().
-type function_name() :: atom().
-type record_name() :: atom().
-type signedness() :: signed | unsigned.
-type spec_attr() :: callback | spec.
-type token() :: erl_scan:token().
-type type() :: integer | float | binary | bytes | bitstring | bits | utf8 | utf16 | utf32.
-type type_attr() :: nominal | opaque | type.
-type type_name() :: atom().
-type type_specifier() :: type() | signedness() | endianness() | unit().
-type type_specifier_list() :: default | [type_specifier(), ...].
-type unary_op() :: '+' | '-' | 'bnot' | 'not'.
-type unit() :: {unit, 1..256}.
Functions
-spec abstract(Data) -> AbsTerm when Data :: term(), AbsTerm :: abstract_expr().
Converts the Erlang data structure Data into an abstract form of type
AbsTerm. This function is the inverse of normalise/1.
erl_parse:abstract(T) is equivalent to erl_parse:abstract(T, 0).
-spec abstract(Data, Options) -> AbsTerm when Data :: term(), Options :: Location | [Option], Option :: {encoding, Encoding} | {line, Line} | {location, Location}, Encoding :: latin1 | unicode | utf8 | none | encoding_func(), Line :: erl_anno:line(), Location :: erl_anno:location(), AbsTerm :: abstract_expr().
Converts the Erlang data structure Data into an abstract form of type
AbsTerm.
Each node of AbsTerm is assigned an annotation, see erl_anno. The
annotation contains the location given by option location or by option line.
Option location overrides option line. If neither option location nor
option line is given, 0 is used as location.
Option Encoding is used for selecting which integer lists to be considered as
strings. The default is to use the encoding returned by function
epp:default_encoding/0. Value none means that no integer lists are
considered as strings. encoding_func() is called with one integer of a list at
a time; if it returns true for every integer, the list is considered a string.
-spec anno_from_term(Term) -> erl_parse_tree() | form_info() when Term :: term().
Assumes that Term is a term with the same structure as a erl_parse tree, but
with terms, say T, where a erl_parse tree has collections of annotations.
Returns a erl_parse tree where each term T is replaced by the value returned
by erl_anno:from_term(T). The term Term is
traversed in a depth-first, left-to-right fashion.
-spec anno_to_term(Abstr) -> term() when Abstr :: erl_parse_tree() | form_info().
Returns a term where each collection of annotations Anno of the nodes of the
erl_parse tree Abstr is replaced by the term returned by
erl_anno:to_term(Anno). The erl_parse tree is
traversed in a depth-first, left-to-right fashion.
-spec fold_anno(Fun, Acc0, Abstr) -> Acc1 when Fun :: fun((Anno, AccIn) -> AccOut), Anno :: erl_anno:anno(), Acc0 :: term(), Acc1 :: term(), AccIn :: term(), AccOut :: term(), Abstr :: erl_parse_tree() | form_info().
Updates an accumulator by applying Fun on each collection of annotations of
the erl_parse tree Abstr.
The first call to Fun has AccIn as argument, the returned accumulator
AccOut is passed to the next call, and so on. The
final value of the accumulator is returned. The erl_parse tree is traversed in
a depth-first, left-to-right fashion.
Uses an ErrorDescriptor and returns a string that describes the error.
This function is usually called implicitly when an ErrorInfo structure is processed (see section Error Information).
-spec map_anno(Fun, Abstr) -> NewAbstr when Fun :: fun((Anno) -> NewAnno), Anno :: erl_anno:anno(), NewAnno :: erl_anno:anno(), Abstr :: erl_parse_tree() | form_info(), NewAbstr :: erl_parse_tree() | form_info().
Modifies the erl_parse tree Abstr by applying Fun on each collection of
annotations of the nodes of the erl_parse tree. The erl_parse tree is
traversed in a depth-first, left-to-right fashion.
-spec mapfold_anno(Fun, Acc0, Abstr) -> {NewAbstr, Acc1} when Fun :: fun((Anno, AccIn) -> {NewAnno, AccOut}), Anno :: erl_anno:anno(), NewAnno :: erl_anno:anno(), Acc0 :: term(), Acc1 :: term(), AccIn :: term(), AccOut :: term(), Abstr :: erl_parse_tree() | form_info(), NewAbstr :: erl_parse_tree() | form_info().
Modifies the erl_parse tree Abstr by applying Fun on each collection of
annotations of the nodes of the erl_parse tree, while at the same time
updating an accumulator.
The first call to Fun has AccIn as second argument,
the returned accumulator AccOut is passed to the next call, and so on. The
modified erl_parse tree and the final value of the accumulator are returned.
The erl_parse tree is traversed in a depth-first, left-to-right fashion.
-spec new_anno(Term) -> Abstr when Term :: term(), Abstr :: erl_parse_tree() | form_info().
Assumes that Term is a term with the same structure as a erl_parse tree, but
with locations where a erl_parse tree has
collections of annotations.
Returns a erl_parse tree where each location L
is replaced by the value returned by erl_anno:new(L). The
term Term is traversed in a depth-first, left-to-right fashion.
-spec normalise(AbsTerm) -> Data when AbsTerm :: abstract_expr(), Data :: term().
Converts the abstract form AbsTerm of a term into a conventional Erlang data
structure (that is, the term itself). This function is the inverse of
abstract/1.
-spec parse_exprs(Tokens) -> {ok, ExprList} | {error, ErrorInfo} when Tokens :: [token()], ExprList :: [abstract_expr()], ErrorInfo :: error_info().
Parses Tokens as if it was a list of expressions.
Returns one of the following:
{ok, ExprList}- The parsing was successful.ExprListis a list of the abstract forms of the parsed expressions.{error, ErrorInfo}- An error occurred.
-spec parse_form(Tokens) -> {ok, AbsForm} | {error, ErrorInfo} when Tokens :: [token()], AbsForm :: abstract_form(), ErrorInfo :: error_info().
Parses Tokens as if it was a form.
Returns one of the following:
{ok, AbsForm}- The parsing was successful.AbsFormis the abstract form of the parsed form.{error, ErrorInfo}- An error occurred.
-spec parse_term(Tokens) -> {ok, Term} | {error, ErrorInfo} when Tokens :: [token()], Term :: term(), ErrorInfo :: error_info().
Parses Tokens as if it was a term.
Returns one of the following:
{ok, Term}- The parsing was successful.Termis the Erlang term corresponding to the token list.{error, ErrorInfo}- An error occurred.
-spec tokens(AbsTerm) -> Tokens when AbsTerm :: abstract_expr(), Tokens :: [token()].
Equivalent to tokens(AbsTerm, []).
-spec tokens(AbsTerm, MoreTokens) -> Tokens when AbsTerm :: abstract_expr(), MoreTokens :: [token()], Tokens :: [token()].
Generates a list of tokens representing the abstract form AbsTerm of an
expression. Optionally, MoreTokens is appended.