.TH epp 3erl "stdlib 3.14" "Ericsson AB" "Erlang Module Definition"
.SH NAME
epp \- An Erlang code preprocessor.
.SH DESCRIPTION
.LP
The Erlang code preprocessor includes functions that are used by the \fIcompile\fR\& module to preprocess macros and include files before the parsing takes place\&.
.LP
The Erlang source file \fIencoding\fR\& is selected by a comment in one of the first two lines of the source file\&. The first string matching 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\&.
.LP
\fIExamples:\fR\&
.LP
.nf

%% coding: utf-8
.fi
.LP
.nf

%% For this file we have chosen encoding = Latin-1
.fi
.LP
.nf

%% -*- coding: latin-1 -*-
.fi
.SH DATA TYPES
.nf

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

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

.nf

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

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

.RS 3
Epp = epp_handle()
.br
.RE
.RE
.RS
.LP
Closes the preprocessing of a file\&.
.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 = source_encoding()
.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,2\fR\& as a valid encoding\&.
.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 that describes the error or warning\&. This function is usually called implicitly when processing an \fIErrorInfo\fR\& structure (see section Error Information)\&.
.RE

.LP
.nf

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

.RS 3
Options = 
.br
    [{default_encoding, DefEncoding :: source_encoding()} |
.br
     {includes, IncludePath :: [DirectoryName :: file:name()]} |
.br
     {source_name, SourceName :: file:name()} |
.br
     {macros, PredefMacros :: macros()} |
.br
     {name, FileName :: file:name()} |
.br
     extra]
.br
Epp = epp_handle()
.br
Extra = [{encoding, source_encoding() | none}]
.br
ErrorDescriptor = term()
.br
.RE
.RE
.RS
.LP
Opens a file for preprocessing\&.
.LP
If you want to change the file name of the implicit -file() attributes inserted during preprocessing, you can do with \fI{source_name, SourceName}\fR\&\&. If unset it will default to the name of the opened file\&.
.LP
If \fIextra\fR\& is specified in \fIOptions\fR\&, the return value is \fI{ok, Epp, Extra}\fR\& instead of \fI{ok, Epp}\fR\&\&.
.RE

.LP
.nf

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

.RS 3
FileName = file:name()
.br
IncludePath = [DirectoryName :: file:name()]
.br
Epp = epp_handle()
.br
ErrorDescriptor = term()
.br
.RE
.RE
.RS
.LP
Equivalent to \fIepp:open([{name, FileName}, {includes, IncludePath}])\fR\&\&.
.RE

.LP
.nf

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

.RS 3
FileName = file:name()
.br
IncludePath = [DirectoryName :: file:name()]
.br
PredefMacros = macros()
.br
Epp = epp_handle()
.br
ErrorDescriptor = term()
.br
.RE
.RE
.RS
.LP
Equivalent to \fIepp:open([{name, FileName}, {includes, IncludePath}, {macros, PredefMacros}])\fR\&\&.
.RE

.LP
.nf

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

.RS 3
Epp = epp_handle()
.br
AbsForm = erl_parse:abstract_form()
.br
Line = erl_anno:line()
.br
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
.br
WarningInfo = warning_info()
.br
.nf
\fBwarning_info()\fR\& = {erl_anno:location(), module(), term()}
.fi
.br
.RE
.RE
.RS
.LP
Returns the next Erlang form from the opened Erlang source file\&. Tuple \fI{eof, Line}\fR\& is returned at the end of the file\&. The first form corresponds to an implicit attribute \fI-file(File,1)\&.\fR\&, where \fIFile\fR\& is the file name\&.
.RE

.LP
.nf

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

.RS 3
FileName = file:name()
.br
Options = 
.br
    [{includes, IncludePath :: [DirectoryName :: file:name()]} |
.br
     {source_name, SourceName :: file:name()} |
.br
     {macros, PredefMacros :: macros()} |
.br
     {default_encoding, DefEncoding :: source_encoding()} |
.br
     extra]
.br
Form = 
.br
    erl_parse:abstract_form() | {error, ErrorInfo} | {eof, Line}
.br
Line = erl_anno:line()
.br
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
.br
Extra = [{encoding, source_encoding() | none}]
.br
OpenError = file:posix() | badarg | system_limit
.br
.RE
.RE
.RS
.LP
Preprocesses and parses an Erlang source file\&. Notice that tuple \fI{eof, Line}\fR\& returned at the end of the file is included as a "form"\&.
.LP
If you want to change the file name of the implicit -file() attributes inserted during preprocessing, you can do with \fI{source_name, SourceName}\fR\&\&. If unset it will default to the name of the opened file\&.
.LP
If \fIextra\fR\& is specified in \fIOptions\fR\&, the return value is \fI{ok, [Form], Extra}\fR\& instead of \fI{ok, [Form]}\fR\&\&.
.RE

.LP
.nf

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

.RS 3
FileName = file:name()
.br
IncludePath = [DirectoryName :: file:name()]
.br
Form = 
.br
    erl_parse:abstract_form() | {error, ErrorInfo} | {eof, Line}
.br
PredefMacros = macros()
.br
Line = erl_anno:line()
.br
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
.br
OpenError = file:posix() | badarg | system_limit
.br
.RE
.RE
.RS
.LP
Equivalent to \fIepp:parse_file(FileName, [{includes, IncludePath}, {macros, PredefMacros}])\fR\&\&.
.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 = file:name()
.br
Options = [Option]
.br
Option = {in_comment_only, boolean()}
.br
.RE
.RE
.RS
.LP
Read the encoding from a file\&. Returns the read encoding, or \fInone\fR\& if no valid encoding is found\&.
.LP
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 encoding from a binary\&. Returns the read encoding, or \fInone\fR\& if no valid encoding is found\&.
.LP
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 = io:device()
.br
.RE
.RE
.RS
.LP
Reads the encoding from an I/O device and sets the encoding of the device accordingly\&. The position of the I/O device referenced by \fIFile\fR\& is not affected\&. If no valid encoding can be read from the I/O device, the encoding of the I/O device is set to the default encoding\&.
.LP
Returns the read encoding, or \fInone\fR\& if no valid encoding is found\&.
.RE

.LP
.nf

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

.RS 3
Default = source_encoding()
.br
File = io:device()
.br
.RE
.RE
.RS
.LP
Reads the encoding from an I/O device and sets the encoding of the device accordingly\&. The position of the I/O device referenced by \fIFile\fR\& is not affected\&. If no valid encoding can be read from the I/O device, the encoding of the I/O device is set to the encoding specified by \fIDefault\fR\&\&.
.LP
Returns the read encoding, or \fInone\fR\& if no valid encoding is found\&.
.RE

.SH "ERROR INFORMATION"

.LP
\fIErrorInfo\fR\& is the standard \fIErrorInfo\fR\& structure that is returned from all I/O modules\&. The format is as follows:
.LP
.nf

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

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

.LP
\fIerl_parse(3erl)\fR\&