-spec close(Epp :: epp_handle()) -> ok.

Closes the preprocessing of a file.

-spec default_encoding() -> source_encoding().

Returns the default encoding of Erlang source files.

-spec encoding_to_string(Encoding) -> string() when 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.

-spec format_error(ErrorDescriptor) -> io_lib:chars() when 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 Information).

-spec open(Options) -> {ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
              when
                  Options :: [option() | {name, FileName :: file:name()}],
                  Epp :: epp_handle(),
                  Extra :: [{encoding, source_encoding() | none}],
                  ErrorDescriptor :: term().

Opens a file for preprocessing.

The function is used to start parsing of an Erlang source file. To get the forms from the file use scan_erl_form/1 or parse_erl_form/1. When finished, the epp server should be closed with close/1. Use this function if you want to scan or parse a file incrementally. To scan or parse a whole file at once, use scan_file/2 and parse_file/3 respectively.

When using open/1 the option name must always be specified and is the name of the file to preprocess. This name is used in error messages and in the implicit -file() attributes generated during preprocessing.

See option/0 for the other available options and what they do.

Examples

1> file:read_file("example.erl").
{ok, ~"""
      -module(example).

      -export([foo/0]).

      foo() -> ?MODULE.
      """}
2> {ok, EPP} = epp:open("example.erl", []).
3> epp:scan_erl_form(EPP).
{ok,[{'-',1},{atom,1,file},{'(',1},{string,1,"example.erl"},
     {',',1},{integer,1,1},{')',1},{dot,1}]}
4> epp:parse_erl_form(EPP).
{ok,{attribute,1,module,example}}
5> epp:close(EPP).
ok

-spec open(FileName, IncludePath) -> {ok, Epp} | {error, ErrorDescriptor}
              when
                  FileName :: file:name(),
                  IncludePath :: [DirectoryName :: file:name()],
                  Epp :: epp_handle(),
                  ErrorDescriptor :: term().

Equivalent to open([{name, FileName}, {includes, IncludePath}]).

-spec open(FileName, IncludePath, PredefMacros) -> {ok, Epp} | {error, ErrorDescriptor}
              when
                  FileName :: file:name(),
                  IncludePath :: [DirectoryName :: file:name()],
                  PredefMacros :: macros(),
                  Epp :: epp_handle(),
                  ErrorDescriptor :: term().

Equivalent to open([{name, FileName}, {includes, IncludePath}, {macros, PredefMacros}]).

-spec parse_erl_form(Epp) ->
                        {ok, AbsForm} | {error, ErrorInfo} | {warning, WarningInfo} | {eof, Location}
                        when
                            Epp :: epp_handle(),
                            AbsForm :: erl_parse:abstract_form(),
                            Location :: erl_anno:location(),
                            ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
                            WarningInfo :: warning_info().

Returns the next Erlang form from the opened Erlang source file.

Tuple {eof, Location} 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.

-spec parse_file(FileName, Options) -> {ok, [Form]} | {ok, [Form], Extra} | {error, OpenError}
                    when
                        FileName :: file:name(),
                        Options :: [option()],
                        Form :: erl_parse:abstract_form() | {error, ErrorInfo} | {eof, Location},
                        Location :: erl_anno:location(),
                        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, Location} returned at the end of the file is included as a "form".

See option/0 for the available options and what they do.

Examples

Parse a file:

1> file:read_file("example.erl").
{ok, <<"-module(example).\n\n-export([foo/0]).\n\nfoo() -> ?MODULE.", ...>>}
2> epp:parse_file("example.erl", []).
{ok,[{attribute,1,file,{"example.erl",1}},
     {attribute,1,module,example},
     {attribute,3,export,[{foo,0}]},
     {function,5,foo,0,[{clause,5,[],[],[{atom,5,example}]}]},
     {eof,5}]}

Parse a module from a ram file:

1> {ok, IoDevice} = file:open(<<"-module(foo).\n-export([bar/0]).\nbar() ->\n?MODULE.">>,
       [read, binary, ram, cooked]).
2> epp:parse_file("foo.erl", [{fd, IoDevice}]).
{ok,[{attribute,1,file,{"foo.erl",1}},
     {attribute,1,module,foo},
     {attribute,2,export,[{bar,0}]},
     {function,3,bar,0,[{clause,3,[],[],[{atom,4,foo}]}]},
     {eof,4}]}

Parse a broken ram file:

1> {ok, IoDevice} = file:open(<<"-module(Foo).\n-export([bar/0]).\nbar() ->\n?MODULE.">>,
       [read, binary, ram, cooked]).
2> {ok, Forms} = epp:parse_file("foo.erl", [{fd, IoDevice}]).
{ok,[{attribute,1,file,{"foo.erl",1}},
     {error,{1,erl_parse,
             [98,97,100,32,"module",32,100,101,99,108,97,114,97,116,105,
              111,110]}},
     {attribute,2,export,[{bar,0}]},
     {error,{4,epp,{undefined,'MODULE',none}}},
     {eof,4}]}
3> [io:format("%% ~ts~n", [M:format_error(E)]) || {error,{Loc,M,E}} <- Forms].
%% bad module declaration
%% undefined macro 'MODULE'
[ok,ok]

-spec parse_file(FileName, IncludePath, PredefMacros) -> {ok, [Form]} | {error, OpenError}
                    when
                        FileName :: file:name(),
                        IncludePath :: [DirectoryName :: file:name()],
                        Form :: erl_parse:abstract_form() | {error, ErrorInfo} | {eof, Location},
                        PredefMacros :: macros(),
                        Location :: erl_anno:location(),
                        ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
                        OpenError :: file:posix() | badarg | system_limit.

Equivalent to parse_file(Filename, [{includes, IncludePath}, {macros, PredefMacros}]).

-spec read_encoding(FileName) -> source_encoding() | none when FileName :: file:name().

Equivalent to read_encoding/2.

-spec read_encoding(FileName, Options) -> source_encoding() | none
                       when
                           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.

-spec read_encoding_from_binary(Binary) -> source_encoding() | none when Binary :: binary().

Equivalent to read_encoding_from_binary/2.

-spec read_encoding_from_binary(Binary, Options) -> source_encoding() | none
                                   when
                                       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.

-spec scan_erl_form(Epp) -> {ok, Tokens} | {error, ErrorInfo} | {warning, WarningInfo} | {eof, Line}
                       when
                           Epp :: epp_handle(),
                           Tokens :: erl_scan:tokens(),
                           Line :: erl_anno:line(),
                           ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
                           WarningInfo :: warning_info().

Returns the raw tokens of the next Erlang form from the opened Erlang source file.

A 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.

-spec scan_file(FileName, Options) -> {ok, [Form], Extra} | {error, OpenError}
                   when
                       FileName :: file:name(),
                       Options :: [option()],
                       Form :: erl_scan:tokens() | {error, ErrorInfo} | {eof, Loc},
                       Loc :: erl_anno:location(),
                       ErrorInfo :: erl_scan:error_info(),
                       Extra :: [{encoding, source_encoding() | none}],
                       OpenError :: file:posix() | badarg | system_limit.

Preprocesses an Erlang source file returning a list of the lists of raw tokens of each form.

Notice that the tuple {eof, Line} returned at the end of the file is included as a "form", and any failures to scan a form are included in the list as tuples {error, ErrorInfo}.

For details on what each Option does, see option/0.

Examples

1> file:read_file("example.erl").
{ok, <<"-module(example).\n\n-export([foo/0]).\n\nfoo() -> ?MODULE.", ...>>}
2> epp:scan_file("example.erl", []).
{ok,[[{'-',1},{atom,1,file},{'(',1},{string,1,"example.erl"},
      {',',1},{integer,1,1},{')',1},{dot,1}], ...],
    [{encoding,none}]}

-spec set_encoding(File) -> source_encoding() | none when 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 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.

-spec set_encoding(File, Default) -> source_encoding() | none
                      when 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 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.