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() =
30           [atom() | {atom(), term()} | {atom(), term(), redefine}]
31
32       epp_handle() = pid()
33
34              Handle to the epp server.
35
36       source_encoding() = latin1 | utf8
37
38       warning_info() = {erl_anno:location(), module(), term()}
39

EXPORTS

41       close(Epp) -> ok
42
43              Types:
44
45                 Epp = epp_handle()
46
47              Closes the preprocessing of a file.
48
49       default_encoding() -> source_encoding()
50
51              Returns the default encoding of Erlang source files.
52
53       encoding_to_string(Encoding) -> string()
54
55              Types:
56
57                 Encoding = source_encoding()
58
59              Returns a string representation of an encoding.  The  string  is
60              recognized  by read_encoding/1,2, read_encoding_from_binary/1,2,
61              and set_encoding/1,2 as a valid encoding.
62
63       format_error(ErrorDescriptor) -> io_lib:chars()
64
65              Types:
66
67                 ErrorDescriptor = term()
68
69              Takes an ErrorDescriptor and returns a string that describes the
70              error  or  warning.  This  function is usually called implicitly
71              when processing an ErrorInfo structure (see section Error Infor‐
72              mation).
73
74       open(Options) ->
75               {ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
76
77              Types:
78
79                 Options =
80                     [{default_encoding, DefEncoding :: source_encoding()} |
81                      {includes,     IncludePath    ::    [DirectoryName    ::
82                 file:name()]} |
83                      {source_name, SourceName :: file:name()} |
84                      {deterministic, Enabled :: boolean()} |
85                      {macros, PredefMacros :: macros()} |
86                      {name, FileName :: file:name()} |
87                      {location, StartLocation :: erl_anno:location()} |
88                      {fd, FileDescriptor :: file:io_device()} |
89                      extra]
90                 Epp = epp_handle()
91                 Extra = [{encoding, source_encoding() | none}]
92                 ErrorDescriptor = term()
93
94              Opens a file for preprocessing.
95
96              If you want to change the file name of the implicit -file()  at‐
97              tributes   inserted   during  preprocessing,  you  can  do  with
98              {source_name, SourceName}. If unset it will default to the  name
99              of the opened file.
100
101              Setting  {deterministic,  Enabled}  will additionally reduce the
102              file name of the implicit  -file()  attributes  inserted  during
103              preprocessing to only the basename of the path.
104
105              If  extra is specified in Options, the return value is {ok, Epp,
106              Extra} instead of {ok, Epp}.
107
108              The option location is forwarded to the  Erlang  token  scanner,
109              see erl_scan:tokens/3,4.
110
111       open(FileName, IncludePath) ->
112               {ok, Epp} | {error, ErrorDescriptor}
113
114              Types:
115
116                 FileName = file:name()
117                 IncludePath = [DirectoryName :: file:name()]
118                 Epp = epp_handle()
119                 ErrorDescriptor = term()
120
121              Equivalent  to  epp:open([{name,  FileName}, {includes, Include‐
122              Path}]).
123
124       open(FileName, IncludePath, PredefMacros) ->
125               {ok, Epp} | {error, ErrorDescriptor}
126
127              Types:
128
129                 FileName = file:name()
130                 IncludePath = [DirectoryName :: file:name()]
131                 PredefMacros = macros()
132                 Epp = epp_handle()
133                 ErrorDescriptor = term()
134
135              Equivalent to epp:open([{name,  FileName},  {includes,  Include‐
136              Path}, {macros, PredefMacros}]).
137
138       parse_erl_form(Epp) ->
139                         {ok, AbsForm} |
140                         {error, ErrorInfo} |
141                         {warning, WarningInfo} |
142                         {eof, Location}
143
144              Types:
145
146                 Epp = epp_handle()
147                 AbsForm = erl_parse:abstract_form()
148                 Location = erl_anno:location()
149                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
150                 WarningInfo = warning_info()
151
152              Returns the next Erlang form from the opened Erlang source file.
153              Tuple {eof, Location} is returned at the end of  the  file.  The
154              first  form corresponds to an implicit attribute -file(File,1).,
155              where File is the file name.
156
157       parse_file(FileName, Options) ->
158                     {ok, [Form]} |
159                     {ok, [Form], Extra} |
160                     {error, OpenError}
161
162              Types:
163
164                 FileName = file:name()
165                 Options =
166                     [{includes,    IncludePath    ::    [DirectoryName     ::
167                 file:name()]} |
168                      {source_name, SourceName :: file:name()} |
169                      {macros, PredefMacros :: macros()} |
170                      {default_encoding, DefEncoding :: source_encoding()} |
171                      {location, StartLocation :: erl_anno:location()} |
172                      {reserved_word_fun, Fun :: fun((atom()) -> boolean())} |
173                      {features, [Feature :: atom()]} |
174                      extra]
175                 Form =
176                     erl_parse:abstract_form() |
177                     {error, ErrorInfo} |
178                     {eof, Location}
179                 Location = erl_anno:location()
180                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
181                 Extra = [{encoding, source_encoding() | none}]
182                 OpenError = file:posix() | badarg | system_limit
183
184              Preprocesses and parses an Erlang source file. Notice that tuple
185              {eof, Location} returned at the end of the file is included as a
186              "form".
187
188              If  you want to change the file name of the implicit -file() at‐
189              tributes  inserted  during  preprocessing,  you  can   do   with
190              {source_name,  SourceName}. If unset it will default to the name
191              of the opened file.
192
193              If extra is specified in  Options,  the  return  value  is  {ok,
194              [Form], Extra} instead of {ok, [Form]}.
195
196              The  option  location  is forwarded to the Erlang token scanner,
197              see erl_scan:tokens/3,4.
198
199       parse_file(FileName, IncludePath, PredefMacros) ->
200                     {ok, [Form]} | {error, OpenError}
201
202              Types:
203
204                 FileName = file:name()
205                 IncludePath = [DirectoryName :: file:name()]
206                 Form =
207                     erl_parse:abstract_form() |
208                     {error, ErrorInfo} |
209                     {eof, Location}
210                 PredefMacros = macros()
211                 Location = erl_anno:location()
212                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
213                 OpenError = file:posix() | badarg | system_limit
214
215              Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
216              {macros, PredefMacros}]).
217
218       read_encoding(FileName) -> source_encoding() | none
219
220       read_encoding(FileName, Options) -> source_encoding() | none
221
222              Types:
223
224                 FileName = file:name()
225                 Options = [Option]
226                 Option = {in_comment_only, boolean()}
227
228              Read  the  encoding  from  a file. Returns the read encoding, or
229              none if no valid encoding is found.
230
231              Option in_comment_only is true by default, which is correct  for
232              Erlang  source  files. If set to false, the encoding string does
233              not necessarily have to occur in a comment.
234
235       read_encoding_from_binary(Binary) -> source_encoding() | none
236
237       read_encoding_from_binary(Binary, Options) ->
238                                    source_encoding() | none
239
240              Types:
241
242                 Binary = binary()
243                 Options = [Option]
244                 Option = {in_comment_only, boolean()}
245
246              Read the encoding from a binary. Returns the read  encoding,  or
247              none if no valid encoding is found.
248
249              Option  in_comment_only is true by default, which is correct for
250              Erlang source files. If set to false, the encoding  string  does
251              not necessarily have to occur in a comment.
252
253       scan_erl_form(Epp) ->
254                        {ok, Tokens} |
255                        {error, ErrorInfo} |
256                        {warning, WarningInfo} |
257                        {eof, Line}
258
259              Types:
260
261                 Epp = epp_handle()
262                 Tokens = erl_scan:tokens()
263                 Line = erl_anno:line()
264                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
265                 WarningInfo = warning_info()
266
267              Returns  the  raw tokens of the next Erlang form from the opened
268              Erlang source file. A tuple {eof, Line} is returned at  the  end
269              of the file. The first form corresponds to an implicit attribute
270              -file(File,1)., where File is the file name.
271
272       scan_file(FileName, Options) ->
273                    {ok, [Form], Extra} | {error, OpenError}
274
275              Types:
276
277                 FileName = file:name()
278                 Options =
279                     [{includes,    IncludePath    ::    [DirectoryName     ::
280                 file:name()]} |
281                      {source_name, SourceName :: file:name()} |
282                      {macros, PredefMacros :: macros()} |
283                      {default_encoding, DefEncoding :: source_encoding()}]
284                 Form = erl_scan:tokens() | {error, ErrorInfo} | {eof, Loc}
285                 Loc = erl_anno:location()
286                 ErrorInfo = erl_scan:error_info()
287                 Extra = [{encoding, source_encoding() | none}]
288                 OpenError = file:posix() | badarg | system_limit
289
290              Preprocesses an Erlang source file returning a list of the lists
291              of raw tokens of each form. Notice that the  tuple  {eof,  Line}
292              returned at the end of the file is included as a "form", and any
293              failures to scan a form are included in the list as tuples  {er‐
294              ror, ErrorInfo}.
295
296       set_encoding(File) -> source_encoding() | none
297
298              Types:
299
300                 File = io:device()
301
302              Reads  the  encoding from an I/O device and sets the encoding of
303              the device accordingly. The position of the  I/O  device  refer‐
304              enced  by File is not affected. If no valid encoding can be read
305              from the I/O device, the encoding of the I/O device  is  set  to
306              the default encoding.
307
308              Returns  the  read  encoding,  or  none  if no valid encoding is
309              found.
310
311       set_encoding(File, Default) -> source_encoding() | none
312
313              Types:
314
315                 Default = source_encoding()
316                 File = io:device()
317
318              Reads the encoding from an I/O device and sets the  encoding  of
319              the  device  accordingly.  The position of the I/O device refer‐
320              enced by File is not affected. If no valid encoding can be  read
321              from  the  I/O  device, the encoding of the I/O device is set to
322              the encoding specified by Default.
323
324              Returns the read encoding, or  none  if  no  valid  encoding  is
325              found.
326

ERROR INFORMATION

328       ErrorInfo is the standard ErrorInfo structure that is returned from all
329       I/O modules. The format is as follows:
330
331       {ErrorLine, Module, ErrorDescriptor}
332
333       A string describing the error is obtained with the following call:
334
335       Module:format_error(ErrorDescriptor)
336

SEE ALSO

338       erl_parse(3)
339
340
341
342Ericsson AB                     stdlib 4.3.1.3                          epp(3)
Impressum