.TH erl_parse 3erl "stdlib 2.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
erl_parse \- The Erlang Parser
.SH DESCRIPTION
.LP
This module is the basic Erlang parser which converts tokens into the abstract form of either forms (i\&.e\&., top-level constructs), expressions, or terms\&. The Abstract Format is described in the \fBERTS User\&'s Guide\fR\&\&. Note that a token list must end with the \fIdot\fR\& token in order to be acceptable to the parse functions (see \fBerl_scan(3erl)\fR\&)\&.
.SH DATA TYPES
.nf

\fBabstract_clause()\fR\& = term()
.br
.fi
.RS
.LP
Parse tree for Erlang clause\&.
.RE

.nf

\fBabstract_expr()\fR\& = term()
.br
.fi
.RS
.LP
Parse tree for Erlang expression\&.
.RE

.nf

\fBabstract_form()\fR\& = term()
.br
.fi
.RS
.LP
Parse tree for Erlang form\&.
.RE

.nf

\fBerror_description()\fR\& = term()
.br
.fi
.nf

\fBerror_info()\fR\& = {\fBerl_scan:line()\fR\&, module(), \fBerror_description()\fR\&}
.br
.fi
.nf

\fBtoken()\fR\& = \fBerl_scan:token()\fR\&
.br
.fi
.SH EXPORTS
.LP
.nf

.B
parse_form(Tokens) -> {ok, AbsForm} | {error, ErrorInfo}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Tokens = [\fBtoken()\fR\&]
.br
AbsForm = \fBabstract_form()\fR\&
.br
ErrorInfo = \fBerror_info()\fR\&
.br
.RE
.RE
.RS
.LP
This function parses \fITokens\fR\& as if it were a form\&. It returns:
.RS 2
.TP 2
.B
\fI{ok, AbsForm}\fR\&:
The parsing was successful\&. \fIAbsForm\fR\& is the abstract form of the parsed form\&.
.TP 2
.B
\fI{error, ErrorInfo}\fR\&:
An error occurred\&.
.RE
.RE

.LP
.nf

.B
parse_exprs(Tokens) -> {ok, ExprList} | {error, ErrorInfo}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Tokens = [\fBtoken()\fR\&]
.br
ExprList = [\fBabstract_expr()\fR\&]
.br
ErrorInfo = \fBerror_info()\fR\&
.br
.RE
.RE
.RS
.LP
This function parses \fITokens\fR\& as if it were a list of expressions\&. It returns:
.RS 2
.TP 2
.B
\fI{ok, ExprList}\fR\&:
The parsing was successful\&. \fIExprList\fR\& is a list of the abstract forms of the parsed expressions\&.
.TP 2
.B
\fI{error, ErrorInfo}\fR\&:
An error occurred\&.
.RE
.RE

.LP
.nf

.B
parse_term(Tokens) -> {ok, Term} | {error, ErrorInfo}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Tokens = [\fBtoken()\fR\&]
.br
Term = term()
.br
ErrorInfo = \fBerror_info()\fR\&
.br
.RE
.RE
.RS
.LP
This function parses \fITokens\fR\& as if it were a term\&. It returns:
.RS 2
.TP 2
.B
\fI{ok, Term}\fR\&:
The parsing was successful\&. \fITerm\fR\& is the Erlang term corresponding to the token list\&.
.TP 2
.B
\fI{error, ErrorInfo}\fR\&:
An error occurred\&.
.RE
.RE

.LP
.B
format_error(ErrorDescriptor) -> Chars
.br
.RS
.LP
Types:

.RS 3
ErrorDescriptor = \fBerror_description()\fR\&
.br
Chars = [char() | Chars]
.br
.RE
.RE
.RS
.LP
Uses an \fIErrorDescriptor\fR\& and returns a string which describes the error\&. This function is usually called implicitly when an \fIErrorInfo\fR\& structure is processed (see below)\&.
.RE

.LP
.nf

.B
tokens(AbsTerm) -> Tokens
.br
.fi
.br
.nf

.B
tokens(AbsTerm, MoreTokens) -> Tokens
.br
.fi
.br
.RS
.LP
Types:

.RS 3
AbsTerm = \fBabstract_expr()\fR\&
.br
MoreTokens = Tokens = [\fBtoken()\fR\&]
.br
.RE
.RE
.RS
.LP
This function generates a list of tokens representing the abstract form \fIAbsTerm\fR\& of an expression\&. Optionally, it appends \fIMoreTokens\fR\&\&.
.RE

.LP
.nf

.B
normalise(AbsTerm) -> Data
.br
.fi
.br
.RS
.LP
Types:

.RS 3
AbsTerm = \fBabstract_expr()\fR\&
.br
Data = term()
.br
.RE
.RE
.RS
.LP
Converts the abstract form \fIAbsTerm\fR\& of a term into a conventional Erlang data structure (i\&.e\&., the term itself)\&. This is the inverse of \fIabstract/1\fR\&\&.
.RE

.LP
.nf

.B
abstract(Data) -> AbsTerm
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Data = term()
.br
AbsTerm = \fBabstract_expr()\fR\&
.br
.RE
.RE
.RS
.LP
Converts the Erlang data structure \fIData\fR\& into an abstract form of type \fIAbsTerm\fR\&\&. This is the inverse of \fInormalise/1\fR\&\&.
.LP
\fIerl_parse:abstract(T)\fR\& is equivalent to \fIerl_parse:abstract(T, 0)\fR\&\&.
.RE

.LP
.nf

.B
abstract(Data, Options) -> AbsTerm
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Data = term()
.br
Options = Line | [Option]
.br
Option = {line, Line} | {encoding, Encoding}
.br
Encoding = latin1 | unicode | utf8 | none | \fBencoding_func()\fR\&
.br
Line = \fBerl_scan:line()\fR\&
.br
AbsTerm = \fBabstract_expr()\fR\&
.br
.nf
\fBencoding_func()\fR\& = fun((integer() >= 0) -> boolean())
.fi
.br
.RE
.RE
.RS
.LP
Converts the Erlang data structure \fIData\fR\& into an abstract form of type \fIAbsTerm\fR\&\&.
.LP
The \fILine\fR\& option is the line that will be assigned to each node of the abstract form\&.
.LP
The \fIEncoding\fR\& option is used for selecting which integer lists will be considered as strings\&. The default is to use the encoding returned by \fB\fIepp:default_encoding/0\fR\&\fR\&\&. The value \fInone\fR\& means that no integer lists will be considered as strings\&. The \fIencoding_func()\fR\& will be called with one integer of a list at a time, and if it returns \fItrue\fR\& for every integer the list will be considered a string\&.
.RE

.SH "ERROR INFORMATION"

.LP
The \fIErrorInfo\fR\& mentioned above is the standard \fIErrorInfo\fR\& structure which is returned from all IO modules\&. It has the format:
.LP
.nf

    {ErrorLine, Module, ErrorDescriptor}    
.fi
.LP
A string which describes the error is obtained with the following call:
.LP
.nf

    Module:format_error(ErrorDescriptor)    
.fi
.SH "SEE ALSO"

.LP
\fBio(3erl)\fR\&, \fBerl_scan(3erl)\fR\&, ERTS User\&'s Guide