NAME

       epp - An Erlang Code Preprocessor

DESCRIPTION

       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(), term()}]

       epp_handle() = pid()

              Handle to the epp server.

       source_encoding() = latin1 | utf8

EXPORTS

       open(FileName, IncludePath) ->
               {ok, Epp} | {error, ErrorDescriptor}

       open(FileName, IncludePath, PredefMacros) ->
               {ok, Epp} | {error, ErrorDescriptor}

              Types:

                 FileName = file:name()
                 IncludePath = [DirectoryName :: file:name()]
                 PredefMacros = macros()
                 Epp = epp_handle()
                 ErrorDescriptor = term()

              Opens a file for preprocessing.

       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, 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

              Preprocesses and parses an Erlang source file. Note  that  the  tuple  {eof,  Line}
              returned at end-of-file is included as a "form".

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

       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)