trusty (3) epp.3erl.gz

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)