File: io_lib.html

package info (click to toggle)
erlang-doc-html 1%3A10.b.1a-1
links: PTS
area: main
in suites: sarge
size: 22,488 kB
ctags: 9,933
sloc: erlang: 505; ansic: 323; perl: 61; sh: 45; makefile: 39
file content (335 lines) | stat: -rw-r--r-- 7,978 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
  <TITLE>io_lib</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>io_lib</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
io_lib
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
IO Library Functions
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>This module contains functions for converting to and from strings (lists of characters). They are used for implementing the functions in the <CODE>io</CODE> module. There is
no guarantee that the character lists returned from some of the functions are flat, they can be deep lists. <CODE>lists:flatten/1</CODE> is used for generating flat lists.

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="nl/0"><STRONG><CODE>nl()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns a character list which represents a new line character.

</DIV>

<P><A NAME="write/1"><STRONG><CODE>write(Term)</CODE></STRONG></A><BR>
<A NAME="write/2"><STRONG><CODE>write(Term, Depth)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns a character list which represents <CODE>Term</CODE>. The
<CODE>Depth</CODE> (-1) argument controls the depth of the
structures written. When the specified depth is reached,
everything below this level is replaced by &#34;...&#34;. For
example:
<PRE>
&#62; lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).        
&#34;{1,[2],[3],[4,5],6,7,8,9}&#34;
&#62; lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).
&#34;{1,[2],[3],[4|...],6|...}&#34;
</PRE>

</DIV>

<P><A NAME="print/1"><STRONG><CODE>print(Term)</CODE></STRONG></A><BR>
<A NAME="print/4"><STRONG><CODE>print(Term, Column, LineLength, Depth)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Also returns a list of characters which represents <CODE>Term</CODE>,
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. <CODE>Column</CODE> is the starting column
(1), <CODE>LineLength</CODE> the maximum line length (80), and
<CODE>Depth</CODE> the maximum print depth.

</DIV>

<P><A NAME="fwrite/2"><STRONG><CODE>fwrite(Format, Data)</CODE></STRONG></A><BR>
<A NAME="format/2"><STRONG><CODE>format(Format, Data)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns a character list which represents <CODE>Data</CODE> formatted
in accordance with <CODE>Format</CODE>. Refer to <A HREF="io.html">io(3)</A> 
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.

</DIV>

<P><A NAME="fread/2"><STRONG><CODE>fread(Format, String)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Tries to read <CODE>String</CODE> in accordance with the control
sequences in <CODE>Format</CODE>. Refer to <A HREF="io.html">io(3)</A> 
for a detailed description of the
available formatting options. It is assumed that
<CODE>String</CODE> contains whole lines. It returns:

<P>
<DL>

<DT>
<CODE>{ok, InputList, LeftOverChars}</CODE>
</DT>

<DD>
 The string was read. <CODE>InputList</CODE> is the list
of successfully matched and read items, and
<CODE>LeftOverChars</CODE> are the input characters not used.
<BR>

</DD>

<DT>
<CODE>{more, RestFormat, Nchars, InputStack}</CODE>
</DT>

<DD>
 The string was read, but more input is needed in
order to complete the original format
string. <CODE>RestFormat</CODE> is the remaining format string,
<CODE>NChars</CODE> the number of characters scanned, and
<CODE>InputStack</CODE> is the reversed list of inputs matched
up to that point.
<BR>

</DD>

<DT>
<CODE>{error,What}</CODE>
</DT>

<DD>
 An error occurred which can be formatted with the call
<CODE>format_error/1</CODE>.
<BR>

</DD>

</DL>

<P>Example:
<PRE>
&#62; io_lib:fread(&#34;~f~f~f&#34;, &#34;15.6 17.3e-6 24.5&#34;).
{ok, [15.6000, 1.73000e-5, 24.5000], []}
</PRE>

</DIV>

<P><A NAME="fread/3"><STRONG><CODE>fread(Continuation, CharList, Format)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>This is the re-entrant formatted reader. It returns:

<P>
<DL>

<DT>
<CODE>{done, Result, LeftOverChars}</CODE>
</DT>

<DD>
 The input is complete. The result is one of the following:
<BR>

<DL>

<DT>
<CODE>{ok, InputList}</CODE>
</DT>

<DD>
 The string was read. <CODE>InputList</CODE> is the
list of successfully matched and read items, and
<CODE>LeftOverChars</CODE> are the remaining characters.
<BR>

</DD>

<DT>
<CODE>eof</CODE>
</DT>

<DD>
 End of file has been encountered.
<CODE>LeftOverChars</CODE> are the input characters not
used.
<BR>

</DD>

<DT>
<CODE>{error,What}</CODE>
</DT>

<DD>
 An error occurred, which can be formatted with the
call <CODE>format_error/1</CODE>.
<BR>

</DD>

</DL>


</DD>

<DT>
<CODE>{more, Continuation}</CODE>
</DT>

<DD>
 More data is required to build a term. <CODE>Continuation</CODE> must be passed to <CODE>&#60;c&#62;fread/3</CODE>, when more data becomes available.<BR>

</DD>

</DL>

</DIV>

<P><A NAME="write_atom/1"><STRONG><CODE>write_atom(Atom)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the list of characters needed to print the atom
<CODE>Atom</CODE>.

</DIV>

<P><A NAME="write_string/1"><STRONG><CODE>write_string(String)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the list of characters needed to print
<CODE>String</CODE> as a string.

</DIV>

<P><A NAME="write_char/1"><STRONG><CODE>write_char(Integer)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

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

</DIV>

<P><A NAME="indentation/2"><STRONG><CODE>indentation(String, StartIndent)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the indentation if <CODE>String</CODE> has been printed,
starting at <CODE>Indentation</CODE>.

</DIV>

<P><A NAME="char_list/1"><STRONG><CODE>char_list(CharList) -&#62; bool()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns <CODE>true</CODE> if CharList is a list of characters,
otherwise it returns <CODE>false</CODE>.

</DIV>

<P><A NAME="deep_char_list/1"><STRONG><CODE>deep_char_list(CharList)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns <CODE>true</CODE> if CharList is a deep list of
characters, otherwise it returns <CODE>false</CODE>.

</DIV>

<P><A NAME="printable_list/1"><STRONG><CODE>printable_list(CharList)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns <CODE>true</CODE> if CharList is a list of printable
characters, otherwise it returns <CODE>false</CODE>.

</DIV>

<H3>Notes</H3>
<DIV CLASS=REFBODY>

<P>The module <CODE>io_lib</CODE> also uses the extra modules
<CODE>io_lib_format</CODE>, <CODE>io_lib_fread</CODE>, and
<CODE>io_lib_pretty</CODE>. All external interfaces exist in
<CODE>io_lib</CODE>.


<P><STRONG>Users are strongly advised not to access the
other modules directly.</STRONG>

<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>Any undocumented functions in <CODE>io_lib</CODE> should not be used.
    </TD>
  </TR>
</TABLE>

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

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Robert Virding - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.13.2<BR>
Copyright &copy; 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>