1epp(3) Erlang Module Definition epp(3)
2
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 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 Examples:
21 %% coding: utf-8
23 %% For this file we have chosen encoding = Latin-1
25 %% -*- coding: latin-1 -*-
27
29 macros() =
30 [atom() | {atom(), term()} | {atom(), term(), redefine}]
31 epp_handle() = pid()
33 Handle to the epp server.
35 source_encoding() = latin1 | utf8
37 warning_info() = {erl_anno:location(), module(), term()}
39
41 close(Epp) -> ok
42 Types:
44 Epp = epp_handle()
46 Closes the preprocessing of a file.
48 default_encoding() -> source_encoding()
50 Returns the default encoding of Erlang source files.
52 encoding_to_string(Encoding) -> string()
54 Types:
56 Encoding = source_encoding()
58 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 format_error(ErrorDescriptor) -> io_lib:chars()
64 Types:
66 ErrorDescriptor = term()
68 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 open(Options) ->
75 {ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
76 Types:
78 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 Opens a file for preprocessing.
95 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 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 If extra is specified in Options, the return value is {ok, Epp,
106 Extra} instead of {ok, Epp}.
107 The option location is forwarded to the Erlang token scanner,
109 see erl_scan:tokens/3,4.
110 open(FileName, IncludePath) ->
112 {ok, Epp} | {error, ErrorDescriptor}
113 Types:
115 FileName = file:name()
117 IncludePath = [DirectoryName :: file:name()]
118 Epp = epp_handle()
119 ErrorDescriptor = term()
120 Equivalent to epp:open([{name, FileName}, {includes, Include‐
122 Path}]).
123 open(FileName, IncludePath, PredefMacros) ->
125 {ok, Epp} | {error, ErrorDescriptor}
126 Types:
128 FileName = file:name()
130 IncludePath = [DirectoryName :: file:name()]
131 PredefMacros = macros()
132 Epp = epp_handle()
133 ErrorDescriptor = term()
134 Equivalent to epp:open([{name, FileName}, {includes, Include‐
136 Path}, {macros, PredefMacros}]).
137 parse_erl_form(Epp) ->
139 {ok, AbsForm} |
140 {error, ErrorInfo} |
141 {warning, WarningInfo} |
142 {eof, Location}
143 Types:
145 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 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 parse_file(FileName, Options) ->
158 {ok, [Form]} |
159 {ok, [Form], Extra} |
160 {error, OpenError}
161 Types:
163 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 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 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 If extra is specified in Options, the return value is {ok,
194 [Form], Extra} instead of {ok, [Form]}.
195 The option location is forwarded to the Erlang token scanner,
197 see erl_scan:tokens/3,4.
198 parse_file(FileName, IncludePath, PredefMacros) ->
200 {ok, [Form]} | {error, OpenError}
201 Types:
203 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 Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
216 {macros, PredefMacros}]).
217 read_encoding(FileName) -> source_encoding() | none
219 read_encoding(FileName, Options) -> source_encoding() | none
221 Types:
223 FileName = file:name()
225 Options = [Option]
226 Option = {in_comment_only, boolean()}
227 Read the encoding from a file. Returns the read encoding, or
229 none if no valid encoding is found.
230 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 read_encoding_from_binary(Binary) -> source_encoding() | none
236 read_encoding_from_binary(Binary, Options) ->
238 source_encoding() | none
239 Types:
241 Binary = binary()
243 Options = [Option]
244 Option = {in_comment_only, boolean()}
245 Read the encoding from a binary. Returns the read encoding, or
247 none if no valid encoding is found.
248 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 scan_erl_form(Epp) ->
254 {ok, Tokens} |
255 {error, ErrorInfo} |
256 {warning, WarningInfo} |
257 {eof, Line}
258 Types:
260 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 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 scan_file(FileName, Options) ->
273 {ok, [Form], Extra} | {error, OpenError}
274 Types:
276 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 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 set_encoding(File) -> source_encoding() | none
297 Types:
299 File = io:device()
301 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 Returns the read encoding, or none if no valid encoding is
309 found.
310 set_encoding(File, Default) -> source_encoding() | none
312 Types:
314 Default = source_encoding()
316 File = io:device()
317 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 Returns the read encoding, or none if no valid encoding is
325 found.
326
328 ErrorInfo is the standard ErrorInfo structure that is returned from all
329 I/O modules. The format is as follows:
330 {ErrorLine, Module, ErrorDescriptor}
332 A string describing the error is obtained with the following call:
334 Module:format_error(ErrorDescriptor)
336
338 erl_parse(3)
339Ericsson AB stdlib 4.2 epp(3)