1epp(3)                     Erlang Module Definition                     epp(3)
2
3
4

NAME

6       epp - An Erlang code preprocessor.
7

DESCRIPTION

9       The  Erlang  code  preprocessor includes functions that are used by the
10       compile module to preprocess macros and include files before the  pars‐
11       ing takes place.
12
13       The  Erlang source file encoding is selected by a comment in one of the
14       first two lines of the source file. The first string matching the regu‐
15       lar expression coding\s*[:=]\s*([-a-zA-Z0-9])+ selects the encoding. If
16       the matching string is not a valid encoding, it is ignored.  The  valid
17       encodings  are  Latin-1 and UTF-8, where the case of the characters can
18       be chosen freely.
19
20       Examples:
21
22       %% coding: utf-8
23
24       %% For this file we have chosen encoding = Latin-1
25
26       %% -*- coding: latin-1 -*-
27

DATA TYPES

29       macros() = [atom() | {atom(), term()}]
30
31       epp_handle() = pid()
32
33              Handle to the epp server.
34
35       source_encoding() = latin1 | utf8
36

EXPORTS

38       close(Epp) -> ok
39
40              Types:
41
42                 Epp = epp_handle()
43
44              Closes the preprocessing of a file.
45
46       default_encoding() -> source_encoding()
47
48              Returns the default encoding of Erlang source files.
49
50       encoding_to_string(Encoding) -> string()
51
52              Types:
53
54                 Encoding = source_encoding()
55
56              Returns a string representation of an encoding.  The  string  is
57              recognized  by read_encoding/1,2, read_encoding_from_binary/1,2,
58              and set_encoding/1,2 as a valid encoding.
59
60       format_error(ErrorDescriptor) -> io_lib:chars()
61
62              Types:
63
64                 ErrorDescriptor = term()
65
66              Takes an ErrorDescriptor and returns a string that describes the
67              error  or  warning.  This  function is usually called implicitly
68              when processing an ErrorInfo structure (see section Error Infor‐
69              mation).
70
71       open(Options) ->
72               {ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
73
74              Types:
75
76                 Options =
77                     [{default_encoding, DefEncoding :: source_encoding()} |
78                      {includes,     IncludePath    ::    [DirectoryName    ::
79                 file:name()]} |
80                      {source_name, SourceName :: file:name()} |
81                      {macros, PredefMacros :: macros()} |
82                      {name, FileName :: file:name()} |
83                      extra]
84                 Epp = epp_handle()
85                 Extra = [{encoding, source_encoding() | none}]
86                 ErrorDescriptor = term()
87
88              Opens a file for preprocessing.
89
90              If you want to change the file  name  of  the  implicit  -file()
91              attributes  inserted  during  preprocessing,  you  can  do  with
92              {source_name, SourceName}. If unset it will default to the  name
93              of the opened file.
94
95              If  extra is specified in Options, the return value is {ok, Epp,
96              Extra} instead of {ok, Epp}.
97
98       open(FileName, IncludePath) ->
99               {ok, Epp} | {error, ErrorDescriptor}
100
101              Types:
102
103                 FileName = file:name()
104                 IncludePath = [DirectoryName :: file:name()]
105                 Epp = epp_handle()
106                 ErrorDescriptor = term()
107
108              Equivalent to epp:open([{name,  FileName},  {includes,  Include‐
109              Path}]).
110
111       open(FileName, IncludePath, PredefMacros) ->
112               {ok, Epp} | {error, ErrorDescriptor}
113
114              Types:
115
116                 FileName = file:name()
117                 IncludePath = [DirectoryName :: file:name()]
118                 PredefMacros = macros()
119                 Epp = epp_handle()
120                 ErrorDescriptor = term()
121
122              Equivalent  to  epp:open([{name,  FileName}, {includes, Include‐
123              Path}, {macros, PredefMacros}]).
124
125       parse_erl_form(Epp) ->
126                         {ok, AbsForm} |
127                         {error, ErrorInfo} |
128                         {warning, WarningInfo} |
129                         {eof, Line}
130
131              Types:
132
133                 Epp = epp_handle()
134                 AbsForm = erl_parse:abstract_form()
135                 Line = erl_anno:line()
136                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
137                 WarningInfo = warning_info()
138                 warning_info() = {erl_anno:location(), module(), term()}
139
140              Returns the next Erlang form from the opened Erlang source file.
141              Tuple  {eof, Line} is returned at the end of the file. The first
142              form corresponds to an implicit attribute -file(File,1).,  where
143              File is the file name.
144
145       parse_file(FileName, Options) ->
146                     {ok, [Form]} |
147                     {ok, [Form], Extra} |
148                     {error, OpenError}
149
150              Types:
151
152                 FileName = file:name()
153                 Options =
154                     [{includes,     IncludePath    ::    [DirectoryName    ::
155                 file:name()]} |
156                      {source_name, SourceName :: file:name()} |
157                      {macros, PredefMacros :: macros()} |
158                      {default_encoding, DefEncoding :: source_encoding()} |
159                      extra]
160                 Form =
161                     erl_parse:abstract_form() | {error,  ErrorInfo}  |  {eof,
162                 Line}
163                 Line = erl_anno:line()
164                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
165                 Extra = [{encoding, source_encoding() | none}]
166                 OpenError = file:posix() | badarg | system_limit
167
168              Preprocesses and parses an Erlang source file. Notice that tuple
169              {eof, Line} returned at the end of the file  is  included  as  a
170              "form".
171
172              If  you  want  to  change  the file name of the implicit -file()
173              attributes  inserted  during  preprocessing,  you  can  do  with
174              {source_name,  SourceName}. If unset it will default to the name
175              of the opened file.
176
177              If extra is specified in  Options,  the  return  value  is  {ok,
178              [Form], Extra} instead of {ok, [Form]}.
179
180       parse_file(FileName, IncludePath, PredefMacros) ->
181                     {ok, [Form]} | {error, OpenError}
182
183              Types:
184
185                 FileName = file:name()
186                 IncludePath = [DirectoryName :: file:name()]
187                 Form =
188                     erl_parse:abstract_form()  |  {error,  ErrorInfo} | {eof,
189                 Line}
190                 PredefMacros = macros()
191                 Line = erl_anno:line()
192                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
193                 OpenError = file:posix() | badarg | system_limit
194
195              Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
196              {macros, PredefMacros}]).
197
198       read_encoding(FileName) -> source_encoding() | none
199
200       read_encoding(FileName, Options) -> source_encoding() | none
201
202              Types:
203
204                 FileName = file:name()
205                 Options = [Option]
206                 Option = {in_comment_only, boolean()}
207
208              Read  the  encoding  from  a file. Returns the read encoding, or
209              none if no valid encoding is found.
210
211              Option in_comment_only is true by default, which is correct  for
212              Erlang  source  files. If set to false, the encoding string does
213              not necessarily have to occur in a comment.
214
215       read_encoding_from_binary(Binary) -> source_encoding() | none
216
217       read_encoding_from_binary(Binary, Options) ->
218                                    source_encoding() | none
219
220              Types:
221
222                 Binary = binary()
223                 Options = [Option]
224                 Option = {in_comment_only, boolean()}
225
226              Read the encoding from a binary. Returns the read  encoding,  or
227              none if no valid encoding is found.
228
229              Option  in_comment_only is true by default, which is correct for
230              Erlang source files. If set to false, the encoding  string  does
231              not necessarily have to occur in a comment.
232
233       set_encoding(File) -> source_encoding() | none
234
235              Types:
236
237                 File = io:device()
238
239              Reads  the  encoding from an I/O device and sets the encoding of
240              the device accordingly. The position of the  I/O  device  refer‐
241              enced  by File is not affected. If no valid encoding can be read
242              from the I/O device, the encoding of the I/O device  is  set  to
243              the default encoding.
244
245              Returns  the  read  encoding,  or  none  if no valid encoding is
246              found.
247
248       set_encoding(File, Default) -> source_encoding() | none
249
250              Types:
251
252                 Default = source_encoding()
253                 File = io:device()
254
255              Reads the encoding from an I/O device and sets the  encoding  of
256              the  device  accordingly.  The position of the I/O device refer‐
257              enced by File is not affected. If no valid encoding can be  read
258              from  the  I/O  device, the encoding of the I/O device is set to
259              the encoding specified by Default.
260
261              Returns the read encoding, or  none  if  no  valid  encoding  is
262              found.
263

ERROR INFORMATION

265       ErrorInfo is the standard ErrorInfo structure that is returned from all
266       I/O modules. The format is as follows:
267
268       {ErrorLine, Module, ErrorDescriptor}
269
270       A string describing the error is obtained with the following call:
271
272       Module:format_error(ErrorDescriptor)
273

SEE ALSO

275       erl_parse(3)
276
277
278
279Ericsson AB                       stdlib 3.10                           epp(3)
Impressum