1io_lib(3) Erlang Module Definition io_lib(3)
2
6 io_lib - I/O library functions.
7
9 This module contains functions for converting to and from strings
10 (lists of characters). They are used for implementing the functions in
11 the io module. There is no guarantee that the character lists returned
12 from some of the functions are flat, they can be deep lists. Function
13 lists:flatten/1 can be used for flattening deep lists.
14
16 chars() = [char() | chars()]
17 continuation()
19 A continuation as returned by fread/3.
21 chars_limit() = integer()
23 depth() = -1 | integer() >= 0
25 fread_error() =
27 atom | based | character | float | format | input | integer |
28 string | unsigned
29 fread_item() = string() | atom() | integer() | float()
31 latin1_string() = [unicode:latin1_char()]
33 format_spec() =
35 #{control_char := char(),
36 args := [any()],
37 width := none | integer(),
38 adjust := left | right,
39 precision := none | integer(),
40 pad_char := char(),
41 encoding := unicode | latin1,
42 strings := boolean()}
43 Where:
45 * control_char is the type of control sequence: $P, $w, and so
47 on.
48 * args is a list of the arguments used by the control se‐
50 quence, or an empty list if the control sequence does not
51 take any arguments.
52 * width is the field width.
54 * adjust is the adjustment.
56 * precision is the precision of the printed argument.
58 * pad_char is the padding character.
60 * encoding is set to true if translation modifier t is
62 present.
63 * strings is set to false if modifier l is present.
65
67 build_text(FormatList) -> chars()
68 Types:
70 FormatList = [char() | format_spec()]
72 For details, see scan_format/2.
74 char_list(Term) -> boolean()
76 Types:
78 Term = term()
80 Returns true if Term is a flat list of characters in the Unicode
82 range, otherwise false.
83 deep_char_list(Term) -> boolean()
85 Types:
87 Term = term()
89 Returns true if Term is a, possibly deep, list of characters in
91 the Unicode range, otherwise false.
92 deep_latin1_char_list(Term) -> boolean()
94 Types:
96 Term = term()
98 Returns true if Term is a, possibly deep, list of characters in
100 the ISO Latin-1 range, otherwise false.
101 format(Format, Data) -> chars()
103 fwrite(Format, Data) -> chars()
105 Types:
107 Format = io:format()
109 Data = [term()]
110 Returns a character list that represents Data formatted in ac‐
112 cordance with Format. For a detailed description of the avail‐
113 able formatting options, see io:fwrite/1,2,3. If the format
114 string or argument list contains an error, a fault is generated.
115 If and only if the Unicode translation modifier is used in the
117 format string (that is, ~ts or ~tc), the resulting list can con‐
118 tain characters beyond the ISO Latin-1 character range (that is,
119 numbers > 255). If so, the result is still an ordinary Erlang
120 string(), and can well be used in any context where Unicode data
121 is allowed.
122 format(Format, Data, Options) -> chars()
124 fwrite(Format, Data, Options) -> chars()
126 Types:
128 Format = io:format()
130 Data = [term()]
131 Options = [Option]
132 Option = {chars_limit, CharsLimit}
133 CharsLimit = chars_limit()
134 Returns a character list that represents Data formatted in ac‐
136 cordance with Format in the same way as fwrite/2 and format/2,
137 but takes an extra argument, a list of options.
138 Valid option:
140 {chars_limit, CharsLimit}:
142 A soft limit on the number of characters returned. When the
143 number of characters is reached, remaining structures are
144 replaced by "...". CharsLimit defaults to -1, which means no
145 limit on the number of characters returned.
146 fread(Format, String) -> Result
148 Types:
150 Format = String = string()
152 Result =
153 {ok, InputList :: [fread_item()], LeftOverChars ::
154 string()} |
155 {more,
156 RestFormat :: string(),
157 Nchars :: integer() >= 0,
158 InputStack :: chars()} |
159 {error, {fread, What :: fread_error()}}
160 Tries to read String in accordance with the control sequences in
162 Format. For a detailed description of the available formatting
163 options, see io:fread/3. It is assumed that String contains
164 whole lines.
165 The function returns:
167 {ok, InputList, LeftOverChars}:
169 The string was read. InputList is the list of successfully
170 matched and read items, and LeftOverChars are the input
171 characters not used.
172 {more, RestFormat, Nchars, InputStack}:
174 The string was read, but more input is needed to complete
175 the original format string. RestFormat is the remaining for‐
176 mat string, Nchars is the number of characters scanned, and
177 InputStack is the reversed list of inputs matched up to that
178 point.
179 {error, What}:
181 The read operation failed and parameter What gives a hint
182 about the error.
183 Example:
185 3> io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5").
187 {ok,[15.6,1.73e-5,24.5],[]}
188 fread(Continuation, CharSpec, Format) -> Return
190 Types:
192 Continuation = continuation() | []
194 CharSpec = string() | eof
195 Format = string()
196 Return =
197 {more, Continuation1 :: continuation()} |
198 {done, Result, LeftOverChars :: string()}
199 Result =
200 {ok, InputList :: [fread_item()]} |
201 eof |
202 {error, {fread, What :: fread_error()}}
203 This is the re-entrant formatted reader. The continuation of the
205 first call to the functions must be []. For a complete descrip‐
206 tion of how the re-entrant input scheme works, see Armstrong,
207 Virding, Williams: 'Concurrent Programming in Erlang', Chapter
208 13.
209 The function returns:
211 {done, Result, LeftOverChars}:
213 The input is complete. The result is one of the following:
214 {ok, InputList}:
216 The string was read. InputList is the list of successfully
217 matched and read items, and LeftOverChars are the remain‐
218 ing characters.
219 eof:
221 End of file was encountered. LeftOverChars are the input
222 characters not used.
223 {error, What}:
225 An error occurred and parameter What gives a hint about
226 the error.
227 {more, Continuation}:
229 More data is required to build a term. Continuation must be
230 passed to fread/3 when more data becomes available.
231 indentation(String, StartIndent) -> integer()
233 Types:
235 String = string()
237 StartIndent = integer()
238 Returns the indentation if String has been printed, starting at
240 StartIndent.
241 latin1_char_list(Term) -> boolean()
243 Types:
245 Term = term()
247 Returns true if Term is a flat list of characters in the ISO
249 Latin-1 range, otherwise false.
250 nl() -> string()
252 Returns a character list that represents a new line character.
254 print(Term) -> chars()
256 print(Term, Column, LineLength, Depth) -> chars()
258 Types:
260 Term = term()
262 Column = LineLength = integer() >= 0
263 Depth = depth()
264 Returns a list of characters that represents Term, but breaks
266 representations longer than one line into many lines and indents
267 each line sensibly. Also tries to detect and output lists of
268 printable characters as strings.
269 * Column is the starting column; defaults to 1.
271 * LineLength is the maximum line length; defaults to 80.
273 * Depth is the maximum print depth; defaults to -1, which
275 means no limitation.
276 printable_latin1_list(Term) -> boolean()
278 Types:
280 Term = term()
282 Returns true if Term is a flat list of printable ISO Latin-1
284 characters, otherwise false.
285 printable_list(Term) -> boolean()
287 Types:
289 Term = term()
291 Returns true if Term is a flat list of printable characters,
293 otherwise false.
294 What is a printable character in this case is determined by
296 startup flag +pc to the Erlang VM; see io:printable_range/0 and
297 erl(1).
298 printable_unicode_list(Term) -> boolean()
300 Types:
302 Term = term()
304 Returns true if Term is a flat list of printable Unicode charac‐
306 ters, otherwise false.
307 scan_format(Format, Data) -> FormatList
309 Types:
311 Format = io:format()
313 Data = [term()]
314 FormatList = [char() | format_spec()]
315 Returns a list corresponding to the specified format string,
317 where control sequences have been replaced with corresponding
318 tuples. This list can be passed to:
319 * build_text/1 to have the same effect as format(Format, Args)
321 * unscan_format/1 to get the corresponding pair of Format and
323 Args (with every * and corresponding argument expanded to
324 numeric values)
325 A typical use of this function is to replace unbounded-size con‐
327 trol sequences like ~w and ~p with the depth-limited variants ~W
328 and ~P before formatting to text in, for example, a logger.
329 unscan_format(FormatList) -> {Format, Data}
331 Types:
333 FormatList = [char() | format_spec()]
335 Format = io:format()
336 Data = [term()]
337 For details, see scan_format/2.
339 write(Term) -> chars()
341 write(Term, Depth) -> chars()
343 write(Term, Options) -> chars()
345 Types:
347 Term = term()
349 Options = [Option]
350 Option =
351 {chars_limit, CharsLimit} |
352 {depth, Depth} |
353 {encoding, latin1 | utf8 | unicode}
354 CharsLimit = chars_limit()
355 Depth = depth()
356 Returns a character list that represents Term. Option Depth con‐
358 trols the depth of the structures written. When the specified
359 depth is reached, everything below this level is replaced by
360 "...". Depth defaults to -1, which means no limitation. Option
361 CharsLimit puts a soft limit on the number of characters re‐
362 turned. When the number of characters is reached, remaining
363 structures are replaced by "...". CharsLimit defaults to -1,
364 which means no limit on the number of characters returned.
365 Example:
367 1> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).
369 "{1,[2],[3],[4,5],6,7,8,9}"
370 2> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
371 "{1,[2],[3],[...],...}"
372 3> lists:flatten(io_lib:write({[1,2,3],[4,5],6,7,8,9}, [{chars_limit,20}])).
373 "{[1,2|...],[4|...],...}"
374 write_atom(Atom) -> chars()
376 Types:
378 Atom = atom()
380 Returns the list of characters needed to print atom Atom.
382 write_atom_as_latin1(Atom) -> latin1_string()
384 Types:
386 Atom = atom()
388 Returns the list of characters needed to print atom Atom. Non-
390 Latin-1 characters are escaped.
391 write_char(Char) -> chars()
393 Types:
395 Char = char()
397 Returns the list of characters needed to print a character con‐
399 stant in the Unicode character set.
400 write_char_as_latin1(Char) -> latin1_string()
402 Types:
404 Char = char()
406 Returns the list of characters needed to print a character con‐
408 stant in the Unicode character set. Non-Latin-1 characters are
409 escaped.
410 write_latin1_char(Latin1Char) -> latin1_string()
412 Types:
414 Latin1Char = unicode:latin1_char()
416 Returns the list of characters needed to print a character con‐
418 stant in the ISO Latin-1 character set.
419 write_latin1_string(Latin1String) -> latin1_string()
421 Types:
423 Latin1String = latin1_string()
425 Returns the list of characters needed to print Latin1String as a
427 string.
428 write_string(String) -> chars()
430 Types:
432 String = string()
434 Returns the list of characters needed to print String as a
436 string.
437 write_string_as_latin1(String) -> latin1_string()
439 Types:
441 String = string()
443 Returns the list of characters needed to print String as a
445 string. Non-Latin-1 characters are escaped.
446Ericsson AB stdlib 4.3.1.3 io_lib(3)