.TH io_lib 3 "stdlib  1.15.3" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
io_lib \- IO Library Functions
.SH DESCRIPTION
.LP
This module contains functions for converting to and from strings (lists of characters)\&. They are used for implementing the functions in the \fIio\fR module\&. There is no guarantee that the character lists returned from some of the functions are flat, they can be deep lists\&. \fIlists:flatten/1\fR can be used for flattening deep lists\&.

.SH DATA TYPES

.nf
chars() = [char() | chars()]
.fi
.SH EXPORTS
.LP
.B
nl() -> chars()
.br
.RS
.LP
Returns a character list which represents a new line character\&.
.RE
.LP
.B
write(Term) ->
.br
.B
write(Term, Depth) -> chars()
.br
.RS
.TP
Types
Term = term()
.br
Depth = int()
.br
.RE
.RS
.LP
Returns a character list which represents \fITerm\fR\&. The \fIDepth\fR (-1) argument controls the depth of the structures written\&. When the specified depth is reached, everything below this level is replaced by "\&.\&.\&."\&. For example:

.nf
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],[\&.\&.\&.],\&.\&.\&.}"
.fi
.RE
.LP
.B
print(Term) ->
.br
.B
print(Term, Column, LineLength, Depth) -> chars()
.br
.RS
.TP
Types
Term = term()
.br
Column = LineLenght = Depth = int()
.br
.RE
.RS
.LP
Also returns a list of characters which represents \fITerm\fR, 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\&. \fIColumn\fR is the starting column (1), \fILineLength\fR the maximum line length (80), and \fIDepth\fR (-1) the maximum print depth\&.
.RE
.LP
.B
fwrite(Format, Data) ->
.br
.B
format(Format, Data) -> chars()
.br
.RS
.TP
Types
Format = atom() | string() | binary()
.br
Data = [term()]
.br
.RE
.RS
.LP
Returns a character list which represents \fIData\fR formatted in accordance with \fIFormat\fR\&. See io:fwrite/1,2,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\&.
.RE
.LP
.B
fread(Format, String) -> Result
.br
.RS
.TP
Types
Format = String = string()
.br
Result = {ok, InputList, LeftOverChars} | {more, RestFormat, Nchars, InputStack} | {error, What}
.br
InputList = chars()
.br
LeftOverChars = string()
.br
RestFormat = string()
.br
Nchars = int()
.br
InputStack = chars()
.br
What = term()
.br
.RE
.RS
.LP
Tries to read \fIString\fR in accordance with the control sequences in \fIFormat\fR\&. See io:fread/3 for a detailed description of the available formatting options\&. It is assumed that \fIString\fR contains whole lines\&. It returns:
.RS 2
.TP 4
.B
\fI{ok, InputList, LeftOverChars}\fR:
The string was read\&. \fIInputList\fR is the list of successfully matched and read items, and \fILeftOverChars\fR are the input characters not used\&.
.TP 4
.B
\fI{more, RestFormat, Nchars, InputStack}\fR:
The string was read, but more input is needed in order to complete the original format string\&. \fIRestFormat\fR is the remaining format string, \fINChars\fR the number of characters scanned, and \fIInputStack\fR is the reversed list of inputs matched up to that point\&.
.TP 4
.B
\fI{error, What}\fR:
The read operation failed and the parameter \fIWhat\fR gives a hint about the error\&.
.RE
.LP
Example:

.nf
3> io_lib:fread("~f~f~f", "15\&.6 17\&.3e-6 24\&.5")\&.

{ok,[15\&.6,1\&.73e-5,24\&.5],[]}
.fi
.RE
.LP
.B
fread(Continuation, String, Format) -> Return
.br
.RS
.TP
Types
Continuation = see below
.br
String = Format = string()
.br
Return = {done, Result, LeftOverChars} | {more, Continuation}
.br
Result = {ok, InputList} | eof | {error, What}
.br
InputList = chars()
.br
What = term()()
.br
LeftOverChars = string()
.br
.RE
.RS
.LP
This is the re-entrant formatted reader\&. The continuation of the first call to the functions must be \fI[]\fR\&. Refer to Armstrong, Virding, Williams, \&'Concurrent Programming in Erlang\&', Chapter 13 for a complete description of how the re-entrant input scheme works\&.
.LP
The function returns:
.RS 2
.TP 4
.B
\fI{done, Result, LeftOverChars}\fR:
The input is complete\&. The result is one of the following:
.RS 4
.LP

.RS 2
.TP 4
.B
\fI{ok, InputList}\fR:
The string was read\&. \fIInputList\fR is the list of successfully matched and read items, and \fILeftOverChars\fR are the remaining characters\&.
.TP 4
.B
\fIeof\fR:
End of file has been encountered\&. \fILeftOverChars\fR are the input characters not used\&.
.TP 4
.B
\fI{error, What}\fR:
An error occurred and the parameter \fIWhat\fR gives a hint about the error\&.
.RE
.RE
.TP 4
.B
\fI{more, Continuation}\fR:
More data is required to build a term\&. \fIContinuation\fR must be passed to \fIfread/3\fR, when more data becomes available\&.
.RE
.RE
.LP
.B
write_atom(Atom) -> chars()
.br
.RS
.TP
Types
Atom = atom()
.br
.RE
.RS
.LP
Returns the list of characters needed to print the atom \fIAtom\fR\&.
.RE
.LP
.B
write_string(String) -> chars()
.br
.RS
.TP
Types
String = string()
.br
.RE
.RS
.LP
Returns the list of characters needed to print \fIString\fR as a string\&.
.RE
.LP
.B
write_char(Integer) -> chars()
.br
.RS
.TP
Types
Integer = int()
.br
.RE
.RS
.LP
Returns the list of characters needed to print a character constant\&.
.RE
.LP
.B
indentation(String, StartIndent) -> int()
.br
.RS
.TP
Types
String = string()
.br
StartIndent = int()
.br
.RE
.RS
.LP
Returns the indentation if \fIString\fR has been printed, starting at \fIStartIndent\fR\&.
.RE
.LP
.B
char_list(Term) -> bool()
.br
.RS
.TP
Types
Term = term()
.br
.RE
.RS
.LP
Returns \fItrue\fR if \fITerm\fR is a flat list of characters, otherwise it returns \fIfalse\fR\&.
.RE
.LP
.B
deep_char_list(Term) -> bool()
.br
.RS
.TP
Types
Term = term()
.br
.RE
.RS
.LP
Returns \fItrue\fR if \fITerm\fR is a, possibly deep, list of characters, otherwise it returns \fIfalse\fR\&.
.RE
.LP
.B
printable_list(Term) -> bool()
.br
.RS
.TP
Types
Term = term()
.br
.RE
.RS
.LP
Returns \fItrue\fR if \fITerm\fR is a flat list of printable characters, otherwise it returns \fIfalse\fR\&.
.RE