1epp(3) Erlang Module Definition epp(3)
2
3
4
6 epp - An Erlang code preprocessor.
7
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
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
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 {compiler_internal, [term()]}]
91 Epp = epp_handle()
92 Extra = [{encoding, source_encoding() | none}]
93 ErrorDescriptor = term()
94
95 Opens a file for preprocessing.
96
97 If you want to change the file name of the implicit -file() at‐
98 tributes inserted during preprocessing, you can do with
99 {source_name, SourceName}. If unset it will default to the name
100 of the opened file.
101
102 Setting {deterministic, Enabled} will additionally reduce the
103 file name of the implicit -file() attributes inserted during
104 preprocessing to only the basename of the path.
105
106 If extra is specified in Options, the return value is {ok, Epp,
107 Extra} instead of {ok, Epp}.
108
109 The option location is forwarded to the Erlang token scanner,
110 see erl_scan:tokens/3,4.
111
112 The {compiler_internal,term()} option is forwarded to the Erlang
113 token scanner, see {compiler_internal,term()}.
114
115 open(FileName, IncludePath) ->
116 {ok, Epp} | {error, ErrorDescriptor}
117
118 Types:
119
120 FileName = file:name()
121 IncludePath = [DirectoryName :: file:name()]
122 Epp = epp_handle()
123 ErrorDescriptor = term()
124
125 Equivalent to epp:open([{name, FileName}, {includes, Include‐
126 Path}]).
127
128 open(FileName, IncludePath, PredefMacros) ->
129 {ok, Epp} | {error, ErrorDescriptor}
130
131 Types:
132
133 FileName = file:name()
134 IncludePath = [DirectoryName :: file:name()]
135 PredefMacros = macros()
136 Epp = epp_handle()
137 ErrorDescriptor = term()
138
139 Equivalent to epp:open([{name, FileName}, {includes, Include‐
140 Path}, {macros, PredefMacros}]).
141
142 parse_erl_form(Epp) ->
143 {ok, AbsForm} |
144 {error, ErrorInfo} |
145 {warning, WarningInfo} |
146 {eof, Location}
147
148 Types:
149
150 Epp = epp_handle()
151 AbsForm = erl_parse:abstract_form()
152 Location = erl_anno:location()
153 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
154 WarningInfo = warning_info()
155
156 Returns the next Erlang form from the opened Erlang source file.
157 Tuple {eof, Location} is returned at the end of the file. The
158 first form corresponds to an implicit attribute -file(File,1).,
159 where File is the file name.
160
161 parse_file(FileName, Options) ->
162 {ok, [Form]} |
163 {ok, [Form], Extra} |
164 {error, OpenError}
165
166 Types:
167
168 FileName = file:name()
169 Options =
170 [{includes, IncludePath :: [DirectoryName ::
171 file:name()]} |
172 {source_name, SourceName :: file:name()} |
173 {macros, PredefMacros :: macros()} |
174 {default_encoding, DefEncoding :: source_encoding()} |
175 {location, StartLocation :: erl_anno:location()} |
176 {reserved_word_fun, Fun :: fun((atom()) -> boolean())} |
177 {features, [Feature :: atom()]} |
178 extra |
179 {compiler_internal, [term()]}]
180 Form =
181 erl_parse:abstract_form() |
182 {error, ErrorInfo} |
183 {eof, Location}
184 Location = erl_anno:location()
185 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
186 Extra = [{encoding, source_encoding() | none}]
187 OpenError = file:posix() | badarg | system_limit
188
189 Preprocesses and parses an Erlang source file. Notice that tuple
190 {eof, Location} returned at the end of the file is included as a
191 "form".
192
193 If you want to change the file name of the implicit -file() at‐
194 tributes inserted during preprocessing, you can do with
195 {source_name, SourceName}. If unset it will default to the name
196 of the opened file.
197
198 If extra is specified in Options, the return value is {ok,
199 [Form], Extra} instead of {ok, [Form]}.
200
201 The option location is forwarded to the Erlang token scanner,
202 see erl_scan:tokens/3,4.
203
204 The {compiler_internal,term()} option is forwarded to the Erlang
205 token scanner, see {compiler_internal,term()}.
206
207 parse_file(FileName, IncludePath, PredefMacros) ->
208 {ok, [Form]} | {error, OpenError}
209
210 Types:
211
212 FileName = file:name()
213 IncludePath = [DirectoryName :: file:name()]
214 Form =
215 erl_parse:abstract_form() |
216 {error, ErrorInfo} |
217 {eof, Location}
218 PredefMacros = macros()
219 Location = erl_anno:location()
220 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
221 OpenError = file:posix() | badarg | system_limit
222
223 Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
224 {macros, PredefMacros}]).
225
226 read_encoding(FileName) -> source_encoding() | none
227
228 read_encoding(FileName, Options) -> source_encoding() | none
229
230 Types:
231
232 FileName = file:name()
233 Options = [Option]
234 Option = {in_comment_only, boolean()}
235
236 Read the encoding from a file. Returns the read encoding, or
237 none if no valid encoding is found.
238
239 Option in_comment_only is true by default, which is correct for
240 Erlang source files. If set to false, the encoding string does
241 not necessarily have to occur in a comment.
242
243 read_encoding_from_binary(Binary) -> source_encoding() | none
244
245 read_encoding_from_binary(Binary, Options) ->
246 source_encoding() | none
247
248 Types:
249
250 Binary = binary()
251 Options = [Option]
252 Option = {in_comment_only, boolean()}
253
254 Read the encoding from a binary. Returns the read encoding, or
255 none if no valid encoding is found.
256
257 Option in_comment_only is true by default, which is correct for
258 Erlang source files. If set to false, the encoding string does
259 not necessarily have to occur in a comment.
260
261 scan_erl_form(Epp) ->
262 {ok, Tokens} |
263 {error, ErrorInfo} |
264 {warning, WarningInfo} |
265 {eof, Line}
266
267 Types:
268
269 Epp = epp_handle()
270 Tokens = erl_scan:tokens()
271 Line = erl_anno:line()
272 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
273 WarningInfo = warning_info()
274
275 Returns the raw tokens of the next Erlang form from the opened
276 Erlang source file. A tuple {eof, Line} is returned at the end
277 of the file. The first form corresponds to an implicit attribute
278 -file(File,1)., where File is the file name.
279
280 scan_file(FileName, Options) ->
281 {ok, [Form], Extra} | {error, OpenError}
282
283 Types:
284
285 FileName = file:name()
286 Options =
287 [{includes, IncludePath :: [DirectoryName ::
288 file:name()]} |
289 {source_name, SourceName :: file:name()} |
290 {macros, PredefMacros :: macros()} |
291 {default_encoding, DefEncoding :: source_encoding()}]
292 Form = erl_scan:tokens() | {error, ErrorInfo} | {eof, Loc}
293 Loc = erl_anno:location()
294 ErrorInfo = erl_scan:error_info()
295 Extra = [{encoding, source_encoding() | none}]
296 OpenError = file:posix() | badarg | system_limit
297
298 Preprocesses an Erlang source file returning a list of the lists
299 of raw tokens of each form. Notice that the tuple {eof, Line}
300 returned at the end of the file is included as a "form", and any
301 failures to scan a form are included in the list as tuples {er‐
302 ror, ErrorInfo}.
303
304 set_encoding(File) -> source_encoding() | none
305
306 Types:
307
308 File = io:device()
309
310 Reads the encoding from an I/O device and sets the encoding of
311 the device accordingly. The position of the I/O device refer‐
312 enced by File is not affected. If no valid encoding can be read
313 from the I/O device, the encoding of the I/O device is set to
314 the default encoding.
315
316 Returns the read encoding, or none if no valid encoding is
317 found.
318
319 set_encoding(File, Default) -> source_encoding() | none
320
321 Types:
322
323 Default = source_encoding()
324 File = io:device()
325
326 Reads the encoding from an I/O device and sets the encoding of
327 the device accordingly. The position of the I/O device refer‐
328 enced by File is not affected. If no valid encoding can be read
329 from the I/O device, the encoding of the I/O device is set to
330 the encoding specified by Default.
331
332 Returns the read encoding, or none if no valid encoding is
333 found.
334
336 ErrorInfo is the standard ErrorInfo structure that is returned from all
337 I/O modules. The format is as follows:
338
339 {ErrorLine, Module, ErrorDescriptor}
340
341 A string describing the error is obtained with the following call:
342
343 Module:format_error(ErrorDescriptor)
344
346 erl_parse(3)
347
348
349
350Ericsson AB stdlib 5.1.1 epp(3)