EVOLUTION-MANAGER

Edit File: epp.3

.TH epp 3 "stdlib 1.19.4" "Ericsson AB" "Erlang Module Definition"
.SH NAME
epp \- An Erlang Code Preprocessor
.SH DESCRIPTION
.LP
The Erlang code preprocessor includes functions which are used by \fIcompile\fR\& to preprocess macros and include files before the actual parsing takes place\&.
.LP
The Erlang source file \fB\fIencoding\fR\&\fR\& is selected by a comment in one of the first two lines of the source file\&. The first string that matches the regular expression \fIcoding\\s*[:=]\\s*([-a-zA-Z0-9])+\fR\& selects the encoding\&. If the matching string is not a valid encoding it is ignored\&. The valid encodings are \fILatin-1\fR\& and \fIUTF-8\fR\& where the case of the characters can be chosen freely\&. Examples:
.LP
.nf

%% coding: utf-8
%% For this file we have chosen encoding = Latin-1
%% -*- coding: latin-1 -*-
.fi
.SH DATA TYPES
.nf

\fBmacros()\fR\& = [{atom(), term()}]
.br
.fi
.nf

\fBepp_handle()\fR\& = pid()
.br
.fi
.RS
.LP
Handle to the epp server\&.
.RE
.nf

\fBsource_encoding()\fR\& = latin1 | utf8
.br
.fi
.SH EXPORTS
.LP
.nf

.B
open(FileName, IncludePath) ->
.B
        {ok, Epp} | {error, ErrorDescriptor}
.br
.fi
.br
.nf

.B
open(FileName, IncludePath, PredefMacros) ->
.B
        {ok, Epp} | {error, ErrorDescriptor}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
FileName = \fBfile:name()\fR\&
.br
IncludePath = [DirectoryName :: \fBfile:name()\fR\&]
.br
PredefMacros = \fBmacros()\fR\&
.br
Epp = \fBepp_handle()\fR\&
.br
ErrorDescriptor = term()
.br
.RE
.RE
.RS
.LP
Opens a file for preprocessing\&.
.RE
.LP
.nf

.B
close(Epp) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Epp = \fBepp_handle()\fR\&
.br
.RE
.RE
.RS
.LP
Closes the preprocessing of a file\&.
.RE
.LP
.nf

.B
parse_erl_form(Epp) ->
.B
                  {ok, AbsForm} | {eof, Line} | {error, ErrorInfo}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Epp = \fBepp_handle()\fR\&
.br
AbsForm = \fBerl_parse:abstract_form()\fR\&
.br
Line = \fBerl_scan:line()\fR\&
.br
ErrorInfo = \fBerl_scan:error_info()\fR\& | \fBerl_parse:error_info()\fR\&
.br
.RE
.RE
.RS
.LP
Returns the next Erlang form from the opened Erlang source file\&. The tuple \fI{eof, Line}\fR\& is returned at end-of-file\&. The first form corresponds to an implicit attribute \fI-file(File,1)\&.\fR\&, where \fIFile\fR\& is the name of the file\&.
.RE
.LP
.nf

.B
parse_file(FileName, IncludePath, PredefMacros) ->
.B
              {ok, [Form]} | {error, OpenError}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
FileName = \fBfile:name()\fR\&
.br
IncludePath = [DirectoryName :: \fBfile:name()\fR\&]
.br
Form = \fBerl_parse:abstract_form()\fR\&
.br
     | {error, ErrorInfo}
.br
     | {eof, Line}
.br
PredefMacros = \fBmacros()\fR\&
.br
Line = \fBerl_scan:line()\fR\&
.br
ErrorInfo = \fBerl_scan:error_info()\fR\& | \fBerl_parse:error_info()\fR\&
.br
OpenError = \fBfile:posix()\fR\& | badarg | system_limit
.br
.RE
.RE
.RS
.LP
Preprocesses and parses an Erlang source file\&. Note that the tuple \fI{eof, Line}\fR\& returned at end-of-file is included as a "form"\&.
.RE
.LP
.nf

.B
default_encoding() -> source_encoding()
.br
.fi
.br
.RS
.LP
Returns the default encoding of Erlang source files\&.
.RE
.LP
.nf

.B
encoding_to_string(Encoding) -> string()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Encoding = \fBsource_encoding()\fR\&
.br
.RE
.RE
.RS
.LP
Returns a string representation of an encoding\&. The string is recognized by \fIread_encoding/1,2\fR\&, \fIread_encoding_from_binary/1,2\fR\&, and \fIset_encoding/1\fR\& as a valid encoding\&.
.RE
.LP
.nf

.B
read_encoding(FileName) -> source_encoding() | none
.br
.fi
.br
.nf

.B
read_encoding(FileName, Options) -> source_encoding() | none
.br
.fi
.br
.RS
.LP
Types:

.RS 3
FileName = \fBfile:name()\fR\&
.br
Options = [Option]
.br
Option = {in_comment_only, boolean()}
.br
.RE
.RE
.RS
.LP
Read the \fBencoding\fR\& from a file\&. Returns the read encoding, or \fInone\fR\& if no valid encoding was found\&.
.LP
The option \fIin_comment_only\fR\& is \fItrue\fR\& by default, which is correct for Erlang source files\&. If set to \fIfalse\fR\& the encoding string does not necessarily have to occur in a comment\&.
.RE
.LP
.nf

.B
read_encoding_from_binary(Binary) -> source_encoding() | none
.br
.fi
.br
.nf

.B
read_encoding_from_binary(Binary, Options) ->
.B
                             source_encoding() | none
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Binary = binary()
.br
Options = [Option]
.br
Option = {in_comment_only, boolean()}
.br
.RE
.RE
.RS
.LP
Read the \fBencoding\fR\& from a binary\&. Returns the read encoding, or \fInone\fR\& if no valid encoding was found\&.
.LP
The option \fIin_comment_only\fR\& is \fItrue\fR\& by default, which is correct for Erlang source files\&. If set to \fIfalse\fR\& the encoding string does not necessarily have to occur in a comment\&.
.RE
.LP
.nf

.B
set_encoding(File) -> source_encoding() | none
.br
.fi
.br
.RS
.LP
Types:

.RS 3
File = \fBio:device()\fR\&
.br
.RE
.RE
.RS
.LP
Reads the \fBencoding\fR\& from an IO device and sets the encoding of the device accordingly\&. The position of the IO device referenced by \fIFile\fR\& is not affected\&. If no valid encoding can be read from the IO device the encoding of the IO device is set to the default encoding\&.
.LP
Returns the read encoding, or \fInone\fR\& if no valid encoding was found\&.
.RE
.LP
.nf

.B
format_error(ErrorDescriptor) -> io_lib:chars()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
ErrorDescriptor = term()
.br
.RE
.RE
.RS
.LP
Takes an \fIErrorDescriptor\fR\& and returns a string which describes the error or warning\&. This function is usually called implicitly when processing an \fIErrorInfo\fR\& structure (see below)\&.
.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 following 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
\fBerl_parse(3)\fR\&