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 {compiler_internal, [term()]}]
91 Epp = epp_handle()
92 Extra = [{encoding, source_encoding() | none}]
93 ErrorDescriptor = term()
94 Opens a file for preprocessing.
96 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 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 If extra is specified in Options, the return value is {ok, Epp,
107 Extra} instead of {ok, Epp}.
108 The option location is forwarded to the Erlang token scanner,
110 see erl_scan:tokens/3,4.
111 The {compiler_internal,term()} option is forwarded to the Erlang
113 token scanner, see {compiler_internal,term()}.
114 open(FileName, IncludePath) ->
116 {ok, Epp} | {error, ErrorDescriptor}
117 Types:
119 FileName = file:name()
121 IncludePath = [DirectoryName :: file:name()]
122 Epp = epp_handle()
123 ErrorDescriptor = term()
124 Equivalent to epp:open([{name, FileName}, {includes, Include‐
126 Path}]).
127 open(FileName, IncludePath, PredefMacros) ->
129 {ok, Epp} | {error, ErrorDescriptor}
130 Types:
132 FileName = file:name()
134 IncludePath = [DirectoryName :: file:name()]
135 PredefMacros = macros()
136 Epp = epp_handle()
137 ErrorDescriptor = term()
138 Equivalent to epp:open([{name, FileName}, {includes, Include‐
140 Path}, {macros, PredefMacros}]).
141 parse_erl_form(Epp) ->
143 {ok, AbsForm} |
144 {error, ErrorInfo} |
145 {warning, WarningInfo} |
146 {eof, Location}
147 Types:
149 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 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 parse_file(FileName, Options) ->
162 {ok, [Form]} |
163 {ok, [Form], Extra} |
164 {error, OpenError}
165 Types:
167 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 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 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 If extra is specified in Options, the return value is {ok,
199 [Form], Extra} instead of {ok, [Form]}.
200 The option location is forwarded to the Erlang token scanner,
202 see erl_scan:tokens/3,4.
203 The {compiler_internal,term()} option is forwarded to the Erlang
205 token scanner, see {compiler_internal,term()}.
206 parse_file(FileName, IncludePath, PredefMacros) ->
208 {ok, [Form]} | {error, OpenError}
209 Types:
211 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 Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
224 {macros, PredefMacros}]).
225 read_encoding(FileName) -> source_encoding() | none
227 read_encoding(FileName, Options) -> source_encoding() | none
229 Types:
231 FileName = file:name()
233 Options = [Option]
234 Option = {in_comment_only, boolean()}
235 Read the encoding from a file. Returns the read encoding, or
237 none if no valid encoding is found.
238 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 read_encoding_from_binary(Binary) -> source_encoding() | none
244 read_encoding_from_binary(Binary, Options) ->
246 source_encoding() | none
247 Types:
249 Binary = binary()
251 Options = [Option]
252 Option = {in_comment_only, boolean()}
253 Read the encoding from a binary. Returns the read encoding, or
255 none if no valid encoding is found.
256 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 scan_erl_form(Epp) ->
262 {ok, Tokens} |
263 {error, ErrorInfo} |
264 {warning, WarningInfo} |
265 {eof, Line}
266 Types:
268 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 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 scan_file(FileName, Options) ->
281 {ok, [Form], Extra} | {error, OpenError}
282 Types:
284 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 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 set_encoding(File) -> source_encoding() | none
305 Types:
307 File = io:device()
309 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 Returns the read encoding, or none if no valid encoding is
317 found.
318 set_encoding(File, Default) -> source_encoding() | none
320 Types:
322 Default = source_encoding()
324 File = io:device()
325 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 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 {ErrorLine, Module, ErrorDescriptor}
340 A string describing the error is obtained with the following call:
342 Module:format_error(ErrorDescriptor)
344
346 erl_parse(3)
347Ericsson AB stdlib 5.1.1 epp(3)