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 that are used	by the
       compile module to preprocess macros and include files before the	 pars-
       ing 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 regu-
       lar 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() | {atom(), term()}]

       epp_handle() = pid()

	      Handle to	the epp	server.

       source_encoding() = latin1 | utf8

EXPORTS
       close(Epp) -> ok

	      Types:

		 Epp = epp_handle()

	      Closes the preprocessing of a file.

       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.

       format_error(ErrorDescriptor) ->	io_lib:chars()

	      Types:

		 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	Infor-
	      mation).

       open(Options) ->
	       {ok, Epp} | {ok,	Epp, Extra} | {error, ErrorDescriptor}

	      Types:

		 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()  at-
	      tributes	 inserted   during  preprocessing,  you	 can  do  with
	      {source_name, SourceName}. If unset it will default to the  name
	      of the opened file.

	      If  extra	is specified in	Options, the return value is {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}]).

       parse_erl_form(Epp) ->
			 {ok, AbsForm} |
			 {error, ErrorInfo} |
			 {warning, WarningInfo}	|
			 {eof, Line}

	      Types:

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

       parse_file(FileName, Options) ->
		     {ok, [Form]} |
		     {ok, [Form], Extra} |
		     {error, OpenError}

	      Types:

		 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, Line} returned at the end of the file  is  included	 as  a
	      "form".

	      If  you want to change the file name of the implicit -file() at-
	      tributes	inserted  during  preprocessing,  you  can   do	  with
	      {source_name,  SourceName}. If unset it will default to the name
	      of the opened file.

	      If extra is specified in	Options,  the  return  value  is  {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_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

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

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

	      Types:

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

       set_encoding(File, Default) -> source_encoding()	| none

	      Types:

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

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)

SEE ALSO
       erl_parse(3)

Ericsson AB			  stdlib 3.8				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.2-RELEASE+and+Ports>

home | help