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() = [atom() | {atom(), term()}]
30 epp_handle() = pid()
32 Handle to the epp server.
34 source_encoding() = latin1 | utf8
36
38 close(Epp) -> ok
39 Types:
41 Epp = epp_handle()
43 Closes the preprocessing of a file.
45 default_encoding() -> source_encoding()
47 Returns the default encoding of Erlang source files.
49 encoding_to_string(Encoding) -> string()
51 Types:
53 Encoding = source_encoding()
55 Returns a string representation of an encoding. The string is
57 recognized by read_encoding/1,2, read_encoding_from_binary/1,2,
58 and set_encoding/1,2 as a valid encoding.
59 format_error(ErrorDescriptor) -> io_lib:chars()
61 Types:
63 ErrorDescriptor = term()
65 Takes an ErrorDescriptor and returns a string that describes the
67 error or warning. This function is usually called implicitly
68 when processing an ErrorInfo structure (see section Error Infor‐
69 mation).
70 open(Options) ->
72 {ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
73 Types:
75 Options =
77 [{default_encoding, DefEncoding :: source_encoding()} |
78 {includes, IncludePath :: [DirectoryName ::
79 file:name()]} |
80 {source_name, SourceName :: file:name()} |
81 {macros, PredefMacros :: macros()} |
82 {name, FileName :: file:name()} |
83 extra]
84 Epp = epp_handle()
85 Extra = [{encoding, source_encoding() | none}]
86 ErrorDescriptor = term()
87 Opens a file for preprocessing.
89 If you want to change the file name of the implicit -file()
91 attributes inserted during preprocessing, you can do with
92 {source_name, SourceName}. If unset it will default to the name
93 of the opened file.
94 If extra is specified in Options, the return value is {ok, Epp,
96 Extra} instead of {ok, Epp}.
97 open(FileName, IncludePath) ->
99 {ok, Epp} | {error, ErrorDescriptor}
100 Types:
102 FileName = file:name()
104 IncludePath = [DirectoryName :: file:name()]
105 Epp = epp_handle()
106 ErrorDescriptor = term()
107 Equivalent to epp:open([{name, FileName}, {includes, Include‐
109 Path}]).
110 open(FileName, IncludePath, PredefMacros) ->
112 {ok, Epp} | {error, ErrorDescriptor}
113 Types:
115 FileName = file:name()
117 IncludePath = [DirectoryName :: file:name()]
118 PredefMacros = macros()
119 Epp = epp_handle()
120 ErrorDescriptor = term()
121 Equivalent to epp:open([{name, FileName}, {includes, Include‐
123 Path}, {macros, PredefMacros}]).
124 parse_erl_form(Epp) ->
126 {ok, AbsForm} |
127 {error, ErrorInfo} |
128 {warning, WarningInfo} |
129 {eof, Line}
130 Types:
132 Epp = epp_handle()
134 AbsForm = erl_parse:abstract_form()
135 Line = erl_anno:line()
136 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
137 WarningInfo = warning_info()
138 warning_info() = {erl_anno:location(), module(), term()}
139 Returns the next Erlang form from the opened Erlang source file.
141 Tuple {eof, Line} is returned at the end of the file. The first
142 form corresponds to an implicit attribute -file(File,1)., where
143 File is the file name.
144 parse_file(FileName, Options) ->
146 {ok, [Form]} |
147 {ok, [Form], Extra} |
148 {error, OpenError}
149 Types:
151 FileName = file:name()
153 Options =
154 [{includes, IncludePath :: [DirectoryName ::
155 file:name()]} |
156 {source_name, SourceName :: file:name()} |
157 {macros, PredefMacros :: macros()} |
158 {default_encoding, DefEncoding :: source_encoding()} |
159 extra]
160 Form =
161 erl_parse:abstract_form() | {error, ErrorInfo} | {eof,
162 Line}
163 Line = erl_anno:line()
164 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
165 Extra = [{encoding, source_encoding() | none}]
166 OpenError = file:posix() | badarg | system_limit
167 Preprocesses and parses an Erlang source file. Notice that tuple
169 {eof, Line} returned at the end of the file is included as a
170 "form".
171 If you want to change the file name of the implicit -file()
173 attributes inserted during preprocessing, you can do with
174 {source_name, SourceName}. If unset it will default to the name
175 of the opened file.
176 If extra is specified in Options, the return value is {ok,
178 [Form], Extra} instead of {ok, [Form]}.
179 parse_file(FileName, IncludePath, PredefMacros) ->
181 {ok, [Form]} | {error, OpenError}
182 Types:
184 FileName = file:name()
186 IncludePath = [DirectoryName :: file:name()]
187 Form =
188 erl_parse:abstract_form() | {error, ErrorInfo} | {eof,
189 Line}
190 PredefMacros = macros()
191 Line = erl_anno:line()
192 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
193 OpenError = file:posix() | badarg | system_limit
194 Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
196 {macros, PredefMacros}]).
197 read_encoding(FileName) -> source_encoding() | none
199 read_encoding(FileName, Options) -> source_encoding() | none
201 Types:
203 FileName = file:name()
205 Options = [Option]
206 Option = {in_comment_only, boolean()}
207 Read the encoding from a file. Returns the read encoding, or
209 none if no valid encoding is found.
210 Option in_comment_only is true by default, which is correct for
212 Erlang source files. If set to false, the encoding string does
213 not necessarily have to occur in a comment.
214 read_encoding_from_binary(Binary) -> source_encoding() | none
216 read_encoding_from_binary(Binary, Options) ->
218 source_encoding() | none
219 Types:
221 Binary = binary()
223 Options = [Option]
224 Option = {in_comment_only, boolean()}
225 Read the encoding from a binary. Returns the read encoding, or
227 none if no valid encoding is found.
228 Option in_comment_only is true by default, which is correct for
230 Erlang source files. If set to false, the encoding string does
231 not necessarily have to occur in a comment.
232 set_encoding(File) -> source_encoding() | none
234 Types:
236 File = io:device()
238 Reads the encoding from an I/O device and sets the encoding of
240 the device accordingly. The position of the I/O device refer‐
241 enced by File is not affected. If no valid encoding can be read
242 from the I/O device, the encoding of the I/O device is set to
243 the default encoding.
244 Returns the read encoding, or none if no valid encoding is
246 found.
247 set_encoding(File, Default) -> source_encoding() | none
249 Types:
251 Default = source_encoding()
253 File = io:device()
254 Reads the encoding from an I/O device and sets the encoding of
256 the device accordingly. The position of the I/O device refer‐
257 enced by File is not affected. If no valid encoding can be read
258 from the I/O device, the encoding of the I/O device is set to
259 the encoding specified by Default.
260 Returns the read encoding, or none if no valid encoding is
262 found.
263
265 ErrorInfo is the standard ErrorInfo structure that is returned from all
266 I/O modules. The format is as follows:
267 {ErrorLine, Module, ErrorDescriptor}
269 A string describing the error is obtained with the following call:
271 Module:format_error(ErrorDescriptor)
273
275 erl_parse(3)
276Ericsson AB stdlib 3.14.1 epp(3)