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 {macros, PredefMacros :: macros()} |
85 {name, FileName :: file:name()} |
86 {location, StartLocation :: erl_anno:location()} |
87 {fd, FileDescriptor :: file:io_device()} |
88 extra]
89 Epp = epp_handle()
90 Extra = [{encoding, source_encoding() | none}]
91 ErrorDescriptor = term()
92 Opens a file for preprocessing.
94 If you want to change the file name of the implicit -file() at‐
96 tributes inserted during preprocessing, you can do with
97 {source_name, SourceName}. If unset it will default to the name
98 of the opened file.
99 If extra is specified in Options, the return value is {ok, Epp,
101 Extra} instead of {ok, Epp}.
102 The option location is forwarded to the Erlang token scanner,
104 see erl_scan:tokens/3,4.
105 open(FileName, IncludePath) ->
107 {ok, Epp} | {error, ErrorDescriptor}
108 Types:
110 FileName = file:name()
112 IncludePath = [DirectoryName :: file:name()]
113 Epp = epp_handle()
114 ErrorDescriptor = term()
115 Equivalent to epp:open([{name, FileName}, {includes, Include‐
117 Path}]).
118 open(FileName, IncludePath, PredefMacros) ->
120 {ok, Epp} | {error, ErrorDescriptor}
121 Types:
123 FileName = file:name()
125 IncludePath = [DirectoryName :: file:name()]
126 PredefMacros = macros()
127 Epp = epp_handle()
128 ErrorDescriptor = term()
129 Equivalent to epp:open([{name, FileName}, {includes, Include‐
131 Path}, {macros, PredefMacros}]).
132 parse_erl_form(Epp) ->
134 {ok, AbsForm} |
135 {error, ErrorInfo} |
136 {warning, WarningInfo} |
137 {eof, Location}
138 Types:
140 Epp = epp_handle()
142 AbsForm = erl_parse:abstract_form()
143 Location = erl_anno:location()
144 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
145 WarningInfo = warning_info()
146 Returns the next Erlang form from the opened Erlang source file.
148 Tuple {eof, Location} is returned at the end of the file. The
149 first form corresponds to an implicit attribute -file(File,1).,
150 where File is the file name.
151 parse_file(FileName, Options) ->
153 {ok, [Form]} |
154 {ok, [Form], Extra} |
155 {error, OpenError}
156 Types:
158 FileName = file:name()
160 Options =
161 [{includes, IncludePath :: [DirectoryName ::
162 file:name()]} |
163 {source_name, SourceName :: file:name()} |
164 {macros, PredefMacros :: macros()} |
165 {default_encoding, DefEncoding :: source_encoding()} |
166 {location, StartLocation :: erl_anno:location()} |
167 extra]
168 Form =
169 erl_parse:abstract_form() |
170 {error, ErrorInfo} |
171 {eof, Location}
172 Location = erl_anno:location()
173 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
174 Extra = [{encoding, source_encoding() | none}]
175 OpenError = file:posix() | badarg | system_limit
176 Preprocesses and parses an Erlang source file. Notice that tuple
178 {eof, Location} returned at the end of the file is included as a
179 "form".
180 If you want to change the file name of the implicit -file() at‐
182 tributes inserted during preprocessing, you can do with
183 {source_name, SourceName}. If unset it will default to the name
184 of the opened file.
185 If extra is specified in Options, the return value is {ok,
187 [Form], Extra} instead of {ok, [Form]}.
188 The option location is forwarded to the Erlang token scanner,
190 see erl_scan:tokens/3,4.
191 parse_file(FileName, IncludePath, PredefMacros) ->
193 {ok, [Form]} | {error, OpenError}
194 Types:
196 FileName = file:name()
198 IncludePath = [DirectoryName :: file:name()]
199 Form =
200 erl_parse:abstract_form() |
201 {error, ErrorInfo} |
202 {eof, Location}
203 PredefMacros = macros()
204 Location = erl_anno:location()
205 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
206 OpenError = file:posix() | badarg | system_limit
207 Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
209 {macros, PredefMacros}]).
210 read_encoding(FileName) -> source_encoding() | none
212 read_encoding(FileName, Options) -> source_encoding() | none
214 Types:
216 FileName = file:name()
218 Options = [Option]
219 Option = {in_comment_only, boolean()}
220 Read the encoding from a file. Returns the read encoding, or
222 none if no valid encoding is found.
223 Option in_comment_only is true by default, which is correct for
225 Erlang source files. If set to false, the encoding string does
226 not necessarily have to occur in a comment.
227 read_encoding_from_binary(Binary) -> source_encoding() | none
229 read_encoding_from_binary(Binary, Options) ->
231 source_encoding() | none
232 Types:
234 Binary = binary()
236 Options = [Option]
237 Option = {in_comment_only, boolean()}
238 Read the encoding from a binary. Returns the read encoding, or
240 none if no valid encoding is found.
241 Option in_comment_only is true by default, which is correct for
243 Erlang source files. If set to false, the encoding string does
244 not necessarily have to occur in a comment.
245 scan_erl_form(Epp) ->
247 {ok, Tokens} |
248 {error, ErrorInfo} |
249 {warning, WarningInfo} |
250 {eof, Line}
251 Types:
253 Epp = epp_handle()
255 Tokens = erl_scan:tokens()
256 Line = erl_anno:line()
257 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
258 WarningInfo = warning_info()
259 Returns the raw tokens of the next Erlang form from the opened
261 Erlang source file. A tuple {eof, Line} is returned at the end
262 of the file. The first form corresponds to an implicit attribute
263 -file(File,1)., where File is the file name.
264 scan_file(FileName, Options) ->
266 {ok, [Form], Extra} | {error, OpenError}
267 Types:
269 FileName = file:name()
271 Options =
272 [{includes, IncludePath :: [DirectoryName ::
273 file:name()]} |
274 {source_name, SourceName :: file:name()} |
275 {macros, PredefMacros :: macros()} |
276 {default_encoding, DefEncoding :: source_encoding()}]
277 Form = erl_scan:tokens() | {error, ErrorInfo} | {eof, Loc}
278 Loc = erl_anno:location()
279 ErrorInfo = erl_scan:error_info()
280 Extra = [{encoding, source_encoding() | none}]
281 OpenError = file:posix() | badarg | system_limit
282 Preprocesses an Erlang source file returning a list of the lists
284 of raw tokens of each form. Notice that the tuple {eof, Line}
285 returned at the end of the file is included as a "form", and any
286 failures to scan a form are included in the list as tuples {er‐
287 ror, ErrorInfo}.
288 set_encoding(File) -> source_encoding() | none
290 Types:
292 File = io:device()
294 Reads the encoding from an I/O device and sets the encoding of
296 the device accordingly. The position of the I/O device refer‐
297 enced by File is not affected. If no valid encoding can be read
298 from the I/O device, the encoding of the I/O device is set to
299 the default encoding.
300 Returns the read encoding, or none if no valid encoding is
302 found.
303 set_encoding(File, Default) -> source_encoding() | none
305 Types:
307 Default = source_encoding()
309 File = io:device()
310 Reads the encoding from an I/O device and sets the encoding of
312 the device accordingly. The position of the I/O device refer‐
313 enced by File is not affected. If no valid encoding can be read
314 from the I/O device, the encoding of the I/O device is set to
315 the encoding specified by Default.
316 Returns the read encoding, or none if no valid encoding is
318 found.
319
321 ErrorInfo is the standard ErrorInfo structure that is returned from all
322 I/O modules. The format is as follows:
323 {ErrorLine, Module, ErrorDescriptor}
325 A string describing the error is obtained with the following call:
327 Module:format_error(ErrorDescriptor)
329
331 erl_parse(3)
332Ericsson AB stdlib 3.16.1 epp(3)