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 |
28 based |
29 character |
30 float |
31 format |
32 input |
33 integer |
34 string |
35 unsigned
36 fread_item() = string() | atom() | integer() | float()
38 latin1_string() = [unicode:latin1_char()]
40 format_spec() =
42 #{control_char := char(),
43 args := [any()],
44 width := none | integer(),
45 adjust := left | right,
46 precision := none | integer(),
47 pad_char := char(),
48 encoding := unicode | latin1,
49 strings := boolean()}
50 Where:
52 * control_char is the type of control sequence: $P, $w, and so
54 on.
55 * args is a list of the arguments used by the control
57 sequence, or an empty list if the control sequence does not
58 take any arguments.
59 * width is the field width.
61 * adjust is the adjustment.
63 * precision is the precision of the printed argument.
65 * pad_char is the padding character.
67 * encoding is set to true if translation modifier t is
69 present.
70 * strings is set to false if modifier l is present.
72
74 build_text(FormatList) -> chars()
75 Types:
77 FormatList = [char() | format_spec()]
79 For details, see scan_format/2.
81 char_list(Term) -> boolean()
83 Types:
85 Term = term()
87 Returns true if Term is a flat list of characters in the Unicode
89 range, otherwise false.
90 deep_char_list(Term) -> boolean()
92 Types:
94 Term = term()
96 Returns true if Term is a, possibly deep, list of characters in
98 the Unicode range, otherwise false.
99 deep_latin1_char_list(Term) -> boolean()
101 Types:
103 Term = term()
105 Returns true if Term is a, possibly deep, list of characters in
107 the ISO Latin-1 range, otherwise false.
108 format(Format, Data) -> chars()
110 fwrite(Format, Data) -> chars()
112 Types:
114 Format = io:format()
116 Data = [term()]
117 Returns a character list that represents Data formatted in
119 accordance with Format. For a detailed description of the avail‐
120 able formatting options, see io:fwrite/1,2,3. If the format
121 string or argument list contains an error, a fault is generated.
122 If and only if the Unicode translation modifier is used in the
124 format string (that is, ~ts or ~tc), the resulting list can con‐
125 tain characters beyond the ISO Latin-1 character range (that is,
126 numbers > 255). If so, the result is still an ordinary Erlang
127 string(), and can well be used in any context where Unicode data
128 is allowed.
129 format(Format, Data, Options) -> chars()
131 fwrite(Format, Data, Options) -> chars()
133 Types:
135 Format = io:format()
137 Data = [term()]
138 Options = [Option]
139 Option = {chars_limit, CharsLimit}
140 CharsLimit = chars_limit()
141 Returns a character list that represents Data formatted in
143 accordance with Format in the same way as fwrite/2 and format/2,
144 but takes an extra argument, a list of options.
145 Valid option:
147 {chars_limit, CharsLimit}:
149 A soft limit on the number of characters returned. When the
150 number of characters is reached, remaining structures are
151 replaced by "...". CharsLimit defaults to -1, which means no
152 limit on the number of characters returned.
153 fread(Format, String) -> Result
155 Types:
157 Format = String = string()
159 Result =
160 {ok, InputList :: [fread_item()], LeftOverChars ::
161 string()} |
162 {more,
163 RestFormat :: string(),
164 Nchars :: integer() >= 0,
165 InputStack :: chars()} |
166 {error, {fread, What :: fread_error()}}
167 Tries to read String in accordance with the control sequences in
169 Format. For a detailed description of the available formatting
170 options, see io:fread/3. It is assumed that String contains
171 whole lines.
172 The function returns:
174 {ok, InputList, LeftOverChars}:
176 The string was read. InputList is the list of successfully
177 matched and read items, and LeftOverChars are the input
178 characters not used.
179 {more, RestFormat, Nchars, InputStack}:
181 The string was read, but more input is needed to complete
182 the original format string. RestFormat is the remaining for‐
183 mat string, Nchars is the number of characters scanned, and
184 InputStack is the reversed list of inputs matched up to that
185 point.
186 {error, What}:
188 The read operation failed and parameter What gives a hint
189 about the error.
190 Example:
192 3> io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5").
194 {ok,[15.6,1.73e-5,24.5],[]}
195 fread(Continuation, CharSpec, Format) -> Return
197 Types:
199 Continuation = continuation() | []
201 CharSpec = string() | eof
202 Format = string()
203 Return =
204 {more, Continuation1 :: continuation()} |
205 {done, Result, LeftOverChars :: string()}
206 Result =
207 {ok, InputList :: [fread_item()]} |
208 eof |
209 {error, {fread, What :: fread_error()}}
210 This is the re-entrant formatted reader. The continuation of the
212 first call to the functions must be []. For a complete descrip‐
213 tion of how the re-entrant input scheme works, see Armstrong,
214 Virding, Williams: 'Concurrent Programming in Erlang', Chapter
215 13.
216 The function returns:
218 {done, Result, LeftOverChars}:
220 The input is complete. The result is one of the following:
221 {ok, InputList}:
223 The string was read. InputList is the list of successfully
224 matched and read items, and LeftOverChars are the remain‐
225 ing characters.
226 eof:
228 End of file was encountered. LeftOverChars are the input
229 characters not used.
230 {error, What}:
232 An error occurred and parameter What gives a hint about
233 the error.
234 {more, Continuation}:
236 More data is required to build a term. Continuation must be
237 passed to fread/3 when more data becomes available.
238 indentation(String, StartIndent) -> integer()
240 Types:
242 String = string()
244 StartIndent = integer()
245 Returns the indentation if String has been printed, starting at
247 StartIndent.
248 latin1_char_list(Term) -> boolean()
250 Types:
252 Term = term()
254 Returns true if Term is a flat list of characters in the ISO
256 Latin-1 range, otherwise false.
257 nl() -> string()
259 Returns a character list that represents a new line character.
261 print(Term) -> chars()
263 print(Term, Column, LineLength, Depth) -> chars()
265 Types:
267 Term = term()
269 Column = LineLength = integer() >= 0
270 Depth = depth()
271 Returns a list of characters that represents Term, but breaks
273 representations longer than one line into many lines and indents
274 each line sensibly. Also tries to detect and output lists of
275 printable characters as strings.
276 * Column is the starting column; defaults to 1.
278 * LineLength is the maximum line length; defaults to 80.
280 * Depth is the maximum print depth; defaults to -1, which
282 means no limitation.
283 printable_latin1_list(Term) -> boolean()
285 Types:
287 Term = term()
289 Returns true if Term is a flat list of printable ISO Latin-1
291 characters, otherwise false.
292 printable_list(Term) -> boolean()
294 Types:
296 Term = term()
298 Returns true if Term is a flat list of printable characters,
300 otherwise false.
301 What is a printable character in this case is determined by
303 startup flag +pc to the Erlang VM; see io:printable_range/0 and
304 erl(1).
305 printable_unicode_list(Term) -> boolean()
307 Types:
309 Term = term()
311 Returns true if Term is a flat list of printable Unicode charac‐
313 ters, otherwise false.
314 scan_format(Format, Data) -> FormatList
316 Types:
318 Format = io:format()
320 Data = [term()]
321 FormatList = [char() | format_spec()]
322 Returns a list corresponding to the specified format string,
324 where control sequences have been replaced with corresponding
325 tuples. This list can be passed to:
326 * build_text/1 to have the same effect as format(Format, Args)
328 * unscan_format/1 to get the corresponding pair of Format and
330 Args (with every * and corresponding argument expanded to
331 numeric values)
332 A typical use of this function is to replace unbounded-size con‐
334 trol sequences like ~w and ~p with the depth-limited variants ~W
335 and ~P before formatting to text in, for example, a logger.
336 unscan_format(FormatList) -> {Format, Data}
338 Types:
340 FormatList = [char() | format_spec()]
342 Format = io:format()
343 Data = [term()]
344 For details, see scan_format/2.
346 write(Term) -> chars()
348 write(Term, Depth) -> chars()
350 write(Term, Options) -> chars()
352 Types:
354 Term = term()
356 Options = [Option]
357 Option =
358 {chars_limit, CharsLimit} |
359 {depth, Depth} |
360 {encoding, latin1 | utf8 | unicode}
361 CharsLimit = chars_limit()
362 Depth = depth()
363 Returns a character list that represents Term. Option Depth con‐
365 trols the depth of the structures written. When the specified
366 depth is reached, everything below this level is replaced by
367 "...". Depth defaults to -1, which means no limitation. Option
368 CharsLimit puts a soft limit on the number of characters
369 returned. When the number of characters is reached, remaining
370 structures are replaced by "...". CharsLimit defaults to -1,
371 which means no limit on the number of characters returned.
372 Example:
374 1> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).
376 "{1,[2],[3],[4,5],6,7,8,9}"
377 2> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
378 "{1,[2],[3],[...],...}"
379 3> lists:flatten(io_lib:write({[1,2,3],[4,5],6,7,8,9}, [{chars_limit,20}])).
380 "{[1,2|...],[4|...],...}"
381 write_atom(Atom) -> chars()
383 Types:
385 Atom = atom()
387 Returns the list of characters needed to print atom Atom.
389 write_atom_as_latin1(Atom) -> latin1_string()
391 Types:
393 Atom = atom()
395 Returns the list of characters needed to print atom Atom. Non-
397 Latin-1 characters are escaped.
398 write_char(Char) -> chars()
400 Types:
402 Char = char()
404 Returns the list of characters needed to print a character con‐
406 stant in the Unicode character set.
407 write_char_as_latin1(Char) -> latin1_string()
409 Types:
411 Char = char()
413 Returns the list of characters needed to print a character con‐
415 stant in the Unicode character set. Non-Latin-1 characters are
416 escaped.
417 write_latin1_char(Latin1Char) -> latin1_string()
419 Types:
421 Latin1Char = unicode:latin1_char()
423 Returns the list of characters needed to print a character con‐
425 stant in the ISO Latin-1 character set.
426 write_latin1_string(Latin1String) -> latin1_string()
428 Types:
430 Latin1String = latin1_string()
432 Returns the list of characters needed to print Latin1String as a
434 string.
435 write_string(String) -> chars()
437 Types:
439 String = string()
441 Returns the list of characters needed to print String as a
443 string.
444 write_string_as_latin1(String) -> latin1_string()
446 Types:
448 String = string()
450 Returns the list of characters needed to print String as a
452 string. Non-Latin-1 characters are escaped.
453Ericsson AB stdlib 3.8.2.1 io_lib(3)