# io_lib

### MODULE

io_lib

### MODULE SUMMARY

IO 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. `lists:flatten/1` is used for generating flat lists.

### EXPORTS

`nl()`

Returns a character list which represents a new line character.

`write(Term)`
`write(Term, Depth)`

Returns a character list which represents `Term`. The `Depth` (-1) argument controls the depth of the structures written. When the specified depth is reached, everything below this level is replaced by "...". For example:

    > lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).
    "{1,[2],[3],[4,5],6,7,8,9}"
    > lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
    "{1,[2],[3],[4|...],6|...}"

`print(Term)`
`print(Term, Column, LineLength, Depth)`

Also returns a list of characters which represents `Term`, but breaks representations which are longer than one line into many lines and indents each line sensibly. It also tries to detect and output lists of printable characters as strings. `Column` is the starting column (1), `LineLength` the maximum line length (80), and `Depth` the maximum print depth.

`fwrite(Format, Data)`
`format(Format, Data)`

Returns a character list which represents `Data` formatted in accordance with `Format`. Refer to io(3) for a detailed description of the available formatting options. A fault is generated if there is an error in the format string or argument list.

`fread(Format, String)`

Tries to read `String` in accordance with the control sequences in `Format`. Refer to io(3) for a detailed description of the available formatting options. It is assumed that `String` contains whole lines. It 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 in order to complete the original format string. `RestFormat` is the remaining format string, `NChars` the number of characters scanned, and `InputStack` is the reversed list of inputs matched up to that point.
`{error,What}`
  An error occurred which can be formatted with the call `format_error/1`.

Example:

    > io_lib:fread("~f~f~f", "15.6 17.3e-6 24.5").
    {ok, [15.6000, 1.73000e-5, 24.5000], []}

`fread(Continuation, CharList, Format)`

This is the re-entrant formatted reader. It 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 has been encountered. `LeftOverChars` are the input characters not used.
  `{error,What}`
    An error occurred, which can be formatted with the call `format_error/1`.
`{more, Continuation}`
  More data is required to build a term. `Continuation` must be passed to `<c>fread/3`, when more data becomes available.

`write_atom(Atom)`

Returns the list of characters needed to print the atom `Atom`.

`write_string(String)`

Returns the list of characters needed to print `String` as a string.

`write_char(Integer)`

Returns the list of characters needed to print a character constant.

`indentation(String, StartIndent)`

Returns the indentation if `String` has been printed, starting at `Indentation`.

`char_list(CharList) -> bool()`

Returns `true` if CharList is a list of characters, otherwise it returns `false`.

`deep_char_list(CharList)`

Returns `true` if CharList is a deep list of characters, otherwise it returns `false`.

`printable_list(CharList)`

Returns `true` if CharList is a list of printable characters, otherwise it returns `false`.

### Notes

The module `io_lib` also uses the extra modules `io_lib_format`, `io_lib_fread`, and `io_lib_pretty`. All external interfaces exist in `io_lib`.

Users are strongly advised not to access the other modules directly.

| Any undocumented functions in `io_lib` should not be used.

The continuation of the first call to the re-entrant input functions must be `[]`. Refer to Armstrong, Virding, Williams, 'Concurrent Programming in Erlang', Chapter 13 for a complete description of how the re-entrant input scheme works

### AUTHORS

Robert Virding - support@erlang.ericsson.se

stdlib 1.13.8
Copyright © 1991-2005 Ericsson AB