table of contents
other versions
- jessie 1:17.3-dfsg-4+deb8u2
- jessie-backports 1:19.2.1+dfsg-2+deb9u1~bpo8+1
- stretch 1:19.2.1+dfsg-2+deb9u2
- testing 1:21.2.5+dfsg-1
- unstable 1:21.2.6+dfsg-1
- experimental 1:22.0~rc1+dfsg-1
epp(3erl) | Erlang Module Definition | epp(3erl) |
NAME¶
epp - An Erlang Code PreprocessorDESCRIPTION¶
The Erlang code preprocessor includes functions which are used by compile to preprocess macros and include files before the actual parsing 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 that matches the regular 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¶
open(Options) -> {ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
Types:
Options =
[{default_encoding, DefEncoding :: source_encoding()} |
{includes, IncludePath :: [DirectoryName :: file:name()]} |
{macros, PredefMacros :: macros()} |
{name, FileName :: file:name()} |
extra]
Epp = epp_handle()
Extra = [{encoding, source_encoding() | none}]
ErrorDescriptor = term()
[{default_encoding, DefEncoding :: source_encoding()} |
{includes, IncludePath :: [DirectoryName :: file:name()]} |
{macros, PredefMacros :: macros()} |
{name, FileName :: file:name()} |
extra]
Opens a file for preprocessing.
If extra is given in Options, the return value will be {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,
IncludePath}]).
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, IncludePath}, {macros,
PredefMacros}]).
close(Epp) -> ok
Types:
Epp = epp_handle()
Closes the preprocessing of a file.
parse_erl_form(Epp) -> {ok, AbsForm} | {eof, Line} | {error, ErrorInfo}
Types:
Epp = epp_handle()
AbsForm = erl_parse:abstract_form()
Line = erl_scan:line()
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
Returns the next Erlang form from the opened Erlang source file. The tuple
{eof, Line} is returned at end-of-file. The first form corresponds to
an implicit attribute -file(File,1)., where File is the name of
the file.
parse_file(FileName, Options) -> {ok, [Form]} | {ok, [Form], Extra} | {error, OpenError}
Types:
FileName = file:name()
Options =
[{includes, IncludePath :: [DirectoryName :: file:name()]} |
{macros, PredefMacros :: macros()} |
{default_encoding, DefEncoding :: source_encoding()} |
extra]
Form = erl_parse:abstract_form()
| {error, ErrorInfo}
| {eof, Line}
Line = erl_scan:line()
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
Extra = [{encoding, source_encoding() | none}]
OpenError = file:posix() | badarg | system_limit
[{includes, IncludePath :: [DirectoryName :: file:name()]} |
{macros, PredefMacros :: macros()} |
{default_encoding, DefEncoding :: source_encoding()} |
extra]
| {error, ErrorInfo}
| {eof, Line}
Preprocesses and parses an Erlang source file. Note that the tuple {eof,
Line} returned at end-of-file is included as a "form".
If extra is given in Options, the return value will be {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_scan:line()
ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
OpenError = file:posix() | badarg | system_limit
| {error, ErrorInfo}
| {eof, Line}
Equivalent to epp:parse_file(FileName, [{includes, IncludePath}, {macros,
PredefMacros}]).
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.
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 was found.
The 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 was found.
The 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 IO device and sets the encoding of the device
accordingly. The position of the IO device referenced by File 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.
Returns the read encoding, or none if no valid encoding was found.
set_encoding(File, Default) -> source_encoding() | none
Types:
Default = source_encoding()
File = io:device()
Reads the encoding from an IO device and sets the encoding of the device
accordingly. The position of the IO device referenced by File is not
affected. If no valid encoding can be read from the IO device the encoding of
the IO device is set to the encoding given by Default.
Returns the read encoding, or none if no valid encoding was found.
format_error(ErrorDescriptor) -> io_lib:chars()
Types:
ErrorDescriptor = term()
Takes an ErrorDescriptor and returns a string which describes the error
or warning. This function is usually called implicitly when processing an
ErrorInfo structure (see below).
ERROR INFORMATION¶
The ErrorInfo mentioned above is the standard ErrorInfo structure which is returned from all IO modules. It has the following format:{ErrorLine, Module, ErrorDescriptor}A string which describes the error is obtained with the following call:
Module:format_error(ErrorDescriptor)
SEE ALSO¶
erl_parse(3erl)stdlib 2.2 | Ericsson AB |