--- name: "io_lib" section: "3erl" platform: "linux" package: "erlang-manpages" version: "1:25.2.3+dfsg-1+deb12u4" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/io_lib" --- # io\_lib(3erl) I/O library functions. ## NAME io\_lib - I/O library functions. ## DESCRIPTION This module contains functions for converting to and from strings (lists of characters). They are used for implementing the functions in the *io* module. There is no guarantee that the character lists returned from some of the functions are flat, they can be deep lists. Function *lists:flatten/1* can be used for flattening deep lists. ## DATA TYPES ``` chars() = [char() | chars()] ``` ``` continuation() ``` A continuation as returned by *fread/3*. ``` chars_limit() = integer() ``` ``` depth() = -1 | integer() >= 0 ``` ``` fread_error() = atom | based | character | float | format | input | integer | string | unsigned ``` ``` fread_item() = string() | atom() | integer() | float() ``` ``` latin1_string() = [unicode:latin1_char()] ``` ``` format_spec() = #{control_char := char(), args := [any()], width := none | integer(), adjust := left | right, precision := none | integer(), pad_char := char(), encoding := unicode | latin1, strings := boolean()} ``` Where: - \* *control\_char* is the type of control sequence: *$P*, *$w*, and so on. - \* *args* is a list of the arguments used by the control sequence, or an empty list if the control sequence does not take any arguments. - \* *width* is the field width. - \* *adjust* is the adjustment. - \* *precision* is the precision of the printed argument. - \* *pad\_char* is the padding character. - \* *encoding* is set to *true* if translation modifier *t* is present. - \* *strings* is set to *false* if modifier *l* is present. ## EXPORTS ``` build_text(FormatList) -> chars() ``` Types: FormatList = \[char() \| format\_spec()\]\ For details, see *scan\_format/2*. ``` char_list(Term) -> boolean() ``` Types: Term = term()\ Returns *true* if *Term* is a flat list of characters in the Unicode range, otherwise *false*. ``` deep_char_list(Term) -> boolean() ``` Types: Term = term()\ Returns *true* if *Term* is a, possibly deep, list of characters in the Unicode range, otherwise *false*. ``` deep_latin1_char_list(Term) -> boolean() ``` Types: Term = term()\ Returns *true* if *Term* is a, possibly deep, list of characters in the ISO Latin-1 range, otherwise *false*. ``` format(Format, Data) -> chars() ``` ``` fwrite(Format, Data) -> chars() ``` Types: Format = io:format()\ Data = \[term()\]\ Returns a character list that represents *Data* formatted in accordance with *Format*. For a detailed description of the available formatting options, see *io:fwrite/1,2,3*. If the format string or argument list contains an error, a fault is generated. If and only if the Unicode translation modifier is used in the format string (that is, *~ts* or *~tc*), the resulting list can contain characters beyond the ISO Latin-1 character range (that is, numbers \> 255). If so, the result is still an ordinary Erlang *string()*, and can well be used in any context where Unicode data is allowed. ``` format(Format, Data, Options) -> chars() ``` ``` fwrite(Format, Data, Options) -> chars() ``` Types: Format = io:format()\ Data = \[term()\]\ Options = \[Option\]\ Option = {chars\_limit, CharsLimit}\ CharsLimit = chars\_limit()\ Returns a character list that represents *Data* formatted in accordance with *Format* in the same way as *fwrite/2* and *format/2*, but takes an extra argument, a list of options. Valid option: - ***{chars\_limit, CharsLimit}*:** A soft limit on the number of characters returned. When the number of characters is reached, remaining structures are replaced by "*...*". *CharsLimit* defaults to -1, which means no limit on the number of characters returned. ``` fread(Format, String) -> Result ``` Types: Format = String = string()\ Result = \ \ {ok, InputList :: \[fread\_item()\], LeftOverChars :: string()} \|\ \ {more,\ \ RestFormat :: string(),\ \ Nchars :: integer() \>= 0,\ \ InputStack :: chars()} \|\ \ {error, {fread, What :: fread\_error()}}\ Tries to read *String* in accordance with the control sequences in *Format*. For a detailed description of the available formatting options, see *io:fread/3*. It is assumed that *String* contains whole lines. The function returns: - ***{ok, InputList, LeftOverChars}*:** The string was read. *InputList* is the list of successfully matched and read items, and *LeftOverChars* are the input characters not used. - ***{more, RestFormat, Nchars, InputStack}*:** The string was read, but more input is needed to complete the original format string. *RestFormat* is the remaining format string, *Nchars* is the number of characters scanned, and *InputStack* is the reversed list of inputs matched up to that point. - ***{error, What}*:** The read operation failed and parameter *What* gives a hint about the error. *Example:* ``` 3> io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5"). {ok,[15.6,1.73e-5,24.5],[]} ``` ``` fread(Continuation, CharSpec, Format) -> Return ``` Types: Continuation = continuation() \| \[\]\ CharSpec = string() \| eof\ Format = string()\ Return = \ \ {more, Continuation1 :: continuation()} \|\ \ {done, Result, LeftOverChars :: string()}\ Result = \ \ {ok, InputList :: \[fread\_item()\]} \|\ \ eof \|\ \ {error, {fread, What :: fread\_error()}}\ This is the re-entrant formatted reader. The continuation of the first call to the functions must be *\[\]*. For a complete description of how the re-entrant input scheme works, see Armstrong, Virding, Williams: 'Concurrent Programming in Erlang', Chapter 13. The function returns: - ***{done, Result, LeftOverChars}*:** The input is complete. The result is one of the following: - ***{ok, InputList}*:** The string was read. *InputList* is the list of successfully matched and read items, and *LeftOverChars* are the remaining characters. - ***eof*:** End of file was encountered. *LeftOverChars* are the input characters not used. - ***{error, What}*:** An error occurred and parameter *What* gives a hint about the error. - ***{more, Continuation}*:** More data is required to build a term. *Continuation* must be passed to *fread/3* when more data becomes available. ``` indentation(String, StartIndent) -> integer() ``` Types: String = string()\ StartIndent = integer()\ Returns the indentation if *String* has been printed, starting at *StartIndent*. ``` latin1_char_list(Term) -> boolean() ``` Types: Term = term()\ Returns *true* if *Term* is a flat list of characters in the ISO Latin-1 range, otherwise *false*. ``` nl() -> string() ``` Returns a character list that represents a new line character. ``` print(Term) -> chars() ``` ``` print(Term, Column, LineLength, Depth) -> chars() ``` Types: Term = term()\ Column = LineLength = integer() \>= 0\ Depth = depth()\ Returns a list of characters that represents *Term*, but breaks representations longer than one line into many lines and indents each line sensibly. Also tries to detect and output lists of printable characters as strings. - \* *Column* is the starting column; defaults to 1. - \* *LineLength* is the maximum line length; defaults to 80. - \* *Depth* is the maximum print depth; defaults to -1, which means no limitation. ``` printable_latin1_list(Term) -> boolean() ``` Types: Term = term()\ Returns *true* if *Term* is a flat list of printable ISO Latin-1 characters, otherwise *false*. ``` printable_list(Term) -> boolean() ``` Types: Term = term()\ Returns *true* if *Term* is a flat list of printable characters, otherwise *false*. What is a printable character in this case is determined by startup flag *+pc* to the Erlang VM; see *io:printable\_range/0* and *[erl(1)](/erl/1.md)*. ``` printable_unicode_list(Term) -> boolean() ``` Types: Term = term()\ Returns *true* if *Term* is a flat list of printable Unicode characters, otherwise *false*. ``` scan_format(Format, Data) -> FormatList ``` Types: Format = io:format()\ Data = \[term()\]\ FormatList = \[char() \| format\_spec()\]\ Returns a list corresponding to the specified format string, where control sequences have been replaced with corresponding tuples. This list can be passed to: - \* *build\_text/1* to have the same effect as *format(Format, Args)* - \* *unscan\_format/1* to get the corresponding pair of *Format* and *Args* (with every *\** and corresponding argument expanded to numeric values) A typical use of this function is to replace unbounded-size control sequences like *~w* and *~p* with the depth-limited variants *~W* and *~P* before formatting to text in, for example, a logger. ``` unscan_format(FormatList) -> {Format, Data} ``` Types: FormatList = \[char() \| format\_spec()\]\ Format = io:format()\ Data = \[term()\]\ For details, see *scan\_format/2*. ``` write(Term) -> chars() ``` ``` write(Term, Depth) -> chars() ``` ``` write(Term, Options) -> chars() ``` Types: Term = term()\ Options = \[Option\]\ Option = \ \ {chars\_limit, CharsLimit} \|\ \ {depth, Depth} \|\ \ {encoding, latin1 \| utf8 \| unicode}\ CharsLimit = chars\_limit()\ Depth = depth()\ Returns a character list that represents *Term*. Option *Depth* controls the depth of the structures written. When the specified depth is reached, everything below this level is replaced by "*...*". *Depth* defaults to -1, which means no limitation. Option *CharsLimit* puts a soft limit on the number of characters returned. When the number of characters is reached, remaining structures are replaced by "*...*". *CharsLimit* defaults to -1, which means no limit on the number of characters returned. *Example:* ``` 1> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})). "{1,[2],[3],[4,5],6,7,8,9}" 2> lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)). "{1,[2],[3],[...],...}" 3> lists:flatten(io_lib:write({[1,2,3],[4,5],6,7,8,9}, [{chars_limit,20}])). "{[1,2|...],[4|...],...}" ``` ``` write_atom(Atom) -> chars() ``` Types: Atom = atom()\ Returns the list of characters needed to print atom *Atom*. ``` write_atom_as_latin1(Atom) -> latin1_string() ``` Types: Atom = atom()\ Returns the list of characters needed to print atom *Atom*. Non-Latin-1 characters are escaped. ``` write_char(Char) -> chars() ``` Types: Char = char()\ Returns the list of characters needed to print a character constant in the Unicode character set. ``` write_char_as_latin1(Char) -> latin1_string() ``` Types: Char = char()\ Returns the list of characters needed to print a character constant in the Unicode character set. Non-Latin-1 characters are escaped. ``` write_latin1_char(Latin1Char) -> latin1_string() ``` Types: Latin1Char = unicode:latin1\_char()\ Returns the list of characters needed to print a character constant in the ISO Latin-1 character set. ``` write_latin1_string(Latin1String) -> latin1_string() ``` Types: Latin1String = latin1\_string()\ Returns the list of characters needed to print *Latin1String* as a string. ``` write_string(String) -> chars() ``` Types: String = string()\ Returns the list of characters needed to print *String* as a string. ``` write_string_as_latin1(String) -> latin1_string() ``` Types: String = string()\ Returns the list of characters needed to print *String* as a string. Non-Latin-1 characters are escaped.