An Erlang code preprocessor.
The Erlang code preprocessor includes functions that are used by the
compile
module to preprocess macros and include files before
the 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 matching 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 -*-
Types
macros() = [atom() | {atom(), term()}]
epp_handle() = pid()
Handle to the epp
server.
source_encoding() = latin1 | utf8
Functions
default_encoding() -> source_encoding()
Returns the default encoding of Erlang source files.
encoding_to_string(Encoding) -> string()
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()
ErrorDescriptor = term()
Takes an
and returns
a string that
describes the error or warning. This function is usually
called implicitly when processing an ErrorInfo
structure (see section
Error Information).
open(Options) ->
{ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
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()
attributes inserted during preprocessing, you can do with
{source_name,
. If unset it will
default to the name of the opened file.
If extra
is specified in
, the return value is
{ok,
instead
of {ok,
.
open(FileName, IncludePath) ->
{ok, Epp} | {error, ErrorDescriptor}
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}
FileName = file:name()
IncludePath = [DirectoryName :: file:name()]
PredefMacros = macros()
Epp = epp_handle()
ErrorDescriptor = term()
Equivalent to epp:open([{name, FileName}, {includes, IncludePath},
{macros, PredefMacros}])
.
parse_erl_form(Epp) ->
{ok, AbsForm} |
{error, ErrorInfo} |
{warning, WarningInfo} |
{eof, Line}
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,
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}
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,
returned at the
end of the file is included as a "form".
If you want to change the file name of the implicit -file()
attributes inserted during preprocessing, you can do with
{source_name,
. If unset it will
default to the name of the opened file.
If extra
is specified in
, the return value is
{ok, [
instead
of {ok, [
.
parse_file(FileName, IncludePath, PredefMacros) ->
{ok, [Form]} | {error, OpenError}
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
FileName = file:name()
read_encoding(FileName, Options) -> source_encoding() | none
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
Binary = binary()
read_encoding_from_binary(Binary, Options) ->
source_encoding() | none
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
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 referenced by
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
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 referenced by
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
.
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)