Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
epp(3)			   Erlang Module Definition			epp(3)

NAME
       epp - An	Erlang Code Preprocessor

DESCRIPTION
       The  Erlang code	preprocessor includes functions	which are used by com-
       pile 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	encod-
       ing. 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()

	      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,  Include-
	      Path}]).

       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, Include-
	      Path}, {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

	      Preprocesses and parses an Erlang	source file. Note that the tu-
	      ple {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

	      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  de-
	      fault 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	encod-
	      ing 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(3)

Ericsson AB			  stdlib 2.4				epp(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | ERROR INFORMATION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=epp&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help