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 {macros, PredefMacros :: macros()} |
81 {name, FileName :: file:name()} |
82 extra]
83 Epp = epp_handle()
84 Extra = [{encoding, source_encoding() | none}]
85 ErrorDescriptor = term()
86 Opens a file for preprocessing.
88 If extra is specified in Options, the return value is {ok, Epp,
90 Extra} instead of {ok, Epp}.
91 open(FileName, IncludePath) ->
93 {ok, Epp} | {error, ErrorDescriptor}
94 Types:
96 FileName = file:name()
98 IncludePath = [DirectoryName :: file:name()]
99 Epp = epp_handle()
100 ErrorDescriptor = term()
101 Equivalent to epp:open([{name, FileName}, {includes, Include‐
103 Path}]).
104 open(FileName, IncludePath, PredefMacros) ->
106 {ok, Epp} | {error, ErrorDescriptor}
107 Types:
109 FileName = file:name()
111 IncludePath = [DirectoryName :: file:name()]
112 PredefMacros = macros()
113 Epp = epp_handle()
114 ErrorDescriptor = term()
115 Equivalent to epp:open([{name, FileName}, {includes, Include‐
117 Path}, {macros, PredefMacros}]).
118 parse_erl_form(Epp) ->
120 {ok, AbsForm} |
121 {error, ErrorInfo} |
122 {warning, WarningInfo} |
123 {eof, Line}
124 Types:
126 Epp = epp_handle()
128 AbsForm = erl_parse:abstract_form()
129 Line = erl_anno:line()
130 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
131 WarningInfo = warning_info()
132 warning_info() = {erl_anno:location(), module(), term()}
133 Returns the next Erlang form from the opened Erlang source file.
135 Tuple {eof, Line} is returned at the end of the file. The first
136 form corresponds to an implicit attribute -file(File,1)., where
137 File is the file name.
138 parse_file(FileName, Options) ->
140 {ok, [Form]} |
141 {ok, [Form], Extra} |
142 {error, OpenError}
143 Types:
145 FileName = file:name()
147 Options =
148 [{includes, IncludePath :: [DirectoryName ::
149 file:name()]} |
150 {macros, PredefMacros :: macros()} |
151 {default_encoding, DefEncoding :: source_encoding()} |
152 extra]
153 Form =
154 erl_parse:abstract_form() | {error, ErrorInfo} | {eof,
155 Line}
156 Line = erl_anno:line()
157 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
158 Extra = [{encoding, source_encoding() | none}]
159 OpenError = file:posix() | badarg | system_limit
160 Preprocesses and parses an Erlang source file. Notice that tuple
162 {eof, Line} returned at the end of the file is included as a
163 "form".
164 If extra is specified in Options, the return value is {ok,
166 [Form], Extra} instead of {ok, [Form]}.
167 parse_file(FileName, IncludePath, PredefMacros) ->
169 {ok, [Form]} | {error, OpenError}
170 Types:
172 FileName = file:name()
174 IncludePath = [DirectoryName :: file:name()]
175 Form =
176 erl_parse:abstract_form() | {error, ErrorInfo} | {eof,
177 Line}
178 PredefMacros = macros()
179 Line = erl_anno:line()
180 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
181 OpenError = file:posix() | badarg | system_limit
182 Equivalent to epp:parse_file(FileName, [{includes, IncludePath},
184 {macros, PredefMacros}]).
185 read_encoding(FileName) -> source_encoding() | none
187 read_encoding(FileName, Options) -> source_encoding() | none
189 Types:
191 FileName = file:name()
193 Options = [Option]
194 Option = {in_comment_only, boolean()}
195 Read the encoding from a file. Returns the read encoding, or
197 none if no valid encoding is found.
198 Option in_comment_only is true by default, which is correct for
200 Erlang source files. If set to false, the encoding string does
201 not necessarily have to occur in a comment.
202 read_encoding_from_binary(Binary) -> source_encoding() | none
204 read_encoding_from_binary(Binary, Options) ->
206 source_encoding() | none
207 Types:
209 Binary = binary()
211 Options = [Option]
212 Option = {in_comment_only, boolean()}
213 Read the encoding from a binary. Returns the read encoding, or
215 none if no valid encoding is found.
216 Option in_comment_only is true by default, which is correct for
218 Erlang source files. If set to false, the encoding string does
219 not necessarily have to occur in a comment.
220 set_encoding(File) -> source_encoding() | none
222 Types:
224 File = io:device()
226 Reads the encoding from an I/O device and sets the encoding of
228 the device accordingly. The position of the I/O device refer‐
229 enced by File is not affected. If no valid encoding can be read
230 from the I/O device, the encoding of the I/O device is set to
231 the default encoding.
232 Returns the read encoding, or none if no valid encoding is
234 found.
235 set_encoding(File, Default) -> source_encoding() | none
237 Types:
239 Default = source_encoding()
241 File = io:device()
242 Reads the encoding from an I/O device and sets the encoding of
244 the device accordingly. The position of the I/O device refer‐
245 enced by File is not affected. If no valid encoding can be read
246 from the I/O device, the encoding of the I/O device is set to
247 the encoding specified by Default.
248 Returns the read encoding, or none if no valid encoding is
250 found.
251
253 ErrorInfo is the standard ErrorInfo structure that is returned from all
254 I/O modules. The format is as follows:
255 {ErrorLine, Module, ErrorDescriptor}
257 A string describing the error is obtained with the following call:
259 Module:format_error(ErrorDescriptor)
261
263 erl_parse(3)
264Ericsson AB stdlib 3.4.5.1 epp(3)