epp(3erl) Erlang Module Definition epp(3erl)
NAME
epp - An Erlang code preprocessor.
DESCRIPTION
The Erlang code preprocessor includes functions that are used by the
compile module to preprocess macros and include files before the pars-
ing takes place.
The Erlang source file encoding is selected by a comment in one of the
first two lines of the source file. The first string matching the regu-
lar expression coding\s*[:=]\s*([-a-zA-Z0-9])+ selects the encoding. If
the matching string is not a valid encoding, it is ignored. The valid
encodings are Latin-1 and UTF-8, where the case of the characters can
be chosen freely.
Examples:
%% coding: utf-8
%% For this file we have chosen encoding = Latin-1
%% -*- coding: latin-1 -*-
DATA TYPES
macros() = [atom() | {atom(), term()}]
epp_handle() = pid()
Handle to the epp server.
source_encoding() = latin1 | utf8
EXPORTS
close(Epp) -> ok
Types:
Epp = epp_handle()
Closes the preprocessing of a file.
default_encoding() -> source_encoding()
Returns the default encoding of Erlang source files.
encoding_to_string(Encoding) -> string()
Types:
Encoding = source_encoding()
Returns a string representation of an encoding. The string is
recognized by read_encoding/1,2, read_encoding_from_binary/1,2,
and set_encoding/1,2 as a valid encoding.
format_error(ErrorDescriptor) -> io_lib:chars()
Types:
ErrorDescriptor = term()
Takes an ErrorDescriptor and returns a string that describes the
error or warning. This function is usually called implicitly
when processing an ErrorInfo structure (see section Error Infor-
mation).
open(Options) ->
{ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
Types:
Options =
[{default_encoding, DefEncoding :: source_encoding()} |
{includes, IncludePath :: [DirectoryName ::
file:name()]} |
{source_name, SourceName :: file:name()} |
{macros, PredefMacros :: macros()} |
{name, FileName :: file:name()} |
extra]
Epp = epp_handle()
Extra = [{encoding, source_encoding() | none}]
ErrorDescriptor = term()
Opens a file for preprocessing.
If you want to change the file name of the implicit -file() at-
tributes inserted during preprocessing, you can do with
{source_name, SourceName}. If unset it will default to the name
of the opened file.
If extra is specified in Options, the return value is {ok, Epp,
Extra} instead of {ok, Epp}.
open(FileName, IncludePath) ->
{ok, Epp} | {error, ErrorDescriptor}
Types:
FileName = file:name()
IncludePath = [DirectoryName :: file:name()]
Epp = epp_handle()
ErrorDescriptor = term()
Equivalent to epp:open([{name, FileName}, {includes, Include-
Path}]).
open(FileName, IncludePath, PredefMacros) ->
{ok, Epp} | {error, ErrorDescriptor}
Types:
FileName = file:name()
IncludePath = [DirectoryName :: file:name()]
PredefMacros = macros()
Epp = epp_handle()
ErrorDescriptor = term()
Equivalent to epp:open([{name, FileName}, {includes, Include-
Path}, {macros, PredefMacros}]).
parse_erl_form(Epp) ->
{ok, AbsForm} |
{error, ErrorInfo} |
{warning, WarningInfo} |
{eof, Line}
Types:
Epp = epp_handle()
AbsForm = erl_parse:abstract_form()
Line = erl_anno:line()
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
WarningInfo = warning_info()
warning_info() = {erl_anno:location(), module(), term()}
Returns the next Erlang form from the opened Erlang source file.
Tuple {eof, Line} is returned at the end of the file. The first
form corresponds to an implicit attribute -file(File,1)., where
File is the file name.
parse_file(FileName, Options) ->
{ok, [Form]} |
{ok, [Form], Extra} |
{error, OpenError}
Types:
FileName = file:name()
Options =
[{includes, IncludePath :: [DirectoryName ::
file:name()]} |
{source_name, SourceName :: file:name()} |
{macros, PredefMacros :: macros()} |
{default_encoding, DefEncoding :: source_encoding()} |
extra]
Form =
erl_parse:abstract_form() | {error, ErrorInfo} | {eof,
Line}
Line = erl_anno:line()
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
Extra = [{encoding, source_encoding() | none}]
OpenError = file:posix() | badarg | system_limit
Preprocesses and parses an Erlang source file. Notice that tuple
{eof, Line} returned at the end of the file is included as a
"form".
If you want to change the file name of the implicit -file() at-
tributes inserted during preprocessing, you can do with
{source_name, SourceName}. If unset it will default to the name
of the opened file.
If extra is specified in Options, the return value is {ok,
[Form], Extra} instead of {ok, [Form]}.
parse_file(FileName, IncludePath, PredefMacros) ->
{ok, [Form]} | {error, OpenError}
Types:
FileName = file:name()
IncludePath = [DirectoryName :: file:name()]
Form =
erl_parse:abstract_form() | {error, ErrorInfo} | {eof,
Line}
PredefMacros = macros()
Line = erl_anno:line()
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
OpenError = file:posix() | badarg | system_limit
Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
{macros, PredefMacros}]).
read_encoding(FileName) -> source_encoding() | none
read_encoding(FileName, Options) -> source_encoding() | none
Types:
FileName = file:name()
Options = [Option]
Option = {in_comment_only, boolean()}
Read the encoding from a file. Returns the read encoding, or
none if no valid encoding is found.
Option in_comment_only is true by default, which is correct for
Erlang source files. If set to false, the encoding string does
not necessarily have to occur in a comment.
read_encoding_from_binary(Binary) -> source_encoding() | none
read_encoding_from_binary(Binary, Options) ->
source_encoding() | none
Types:
Binary = binary()
Options = [Option]
Option = {in_comment_only, boolean()}
Read the encoding from a binary. Returns the read encoding, or
none if no valid encoding is found.
Option in_comment_only is true by default, which is correct for
Erlang source files. If set to false, the encoding string does
not necessarily have to occur in a comment.
set_encoding(File) -> source_encoding() | none
Types:
File = io:device()
Reads the encoding from an I/O device and sets the encoding of
the device accordingly. The position of the I/O device refer-
enced by File 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.
Returns the read encoding, or none if no valid encoding is
found.
set_encoding(File, Default) -> source_encoding() | none
Types:
Default = source_encoding()
File = io:device()
Reads the encoding from an I/O device and sets the encoding of
the device accordingly. The position of the I/O device refer-
enced by File 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 Default.
Returns the read encoding, or none if no valid encoding is
found.
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_parse(3erl)
Ericsson AB stdlib 3.13 epp(3erl)