File: io_lib.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (439 lines) | stat: -rw-r--r-- 10,890 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<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> can be used for
flattening deep lists.
</DIV>

<H3>DATA TYPES</H3>
<DIV CLASS=REFBODY>

<PRE>
chars() = [char() | chars()]
    
</PRE>

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="nl/0"><STRONG><CODE>nl() -&#62; chars()</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) -&#62;</CODE></STRONG></A><BR>
<A NAME="write/2"><STRONG><CODE>write(Term, Depth) -&#62; chars()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Term = term()</CODE></STRONG><BR>
<STRONG><CODE>Depth = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<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>
1&#62; <STRONG>lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).</STRONG>
&#34;{1,[2],[3],[4,5],6,7,8,9}&#34;
2&#62; <STRONG>lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).</STRONG>
&#34;{1,[2],[3],[...]|...}&#34;
        
</PRE>

</DIV>

<P><A NAME="print/1"><STRONG><CODE>print(Term) -&#62;</CODE></STRONG></A><BR>
<A NAME="print/4"><STRONG><CODE>print(Term, Column, LineLength, Depth) -&#62; chars()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Term = term()</CODE></STRONG><BR>
<STRONG><CODE>Column = LineLenght = Depth = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<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> (-1) the maximum print depth.
</DIV>

<P><A NAME="fwrite/2"><STRONG><CODE>fwrite(Format, Data) -&#62;</CODE></STRONG></A><BR>
<A NAME="format/2"><STRONG><CODE>format(Format, Data) -&#62; chars()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Format = string()</CODE></STRONG><BR>
<STRONG><CODE>Data = [term()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a character list which represents <CODE>Data</CODE>
         formatted in accordance with <CODE>Format</CODE>. See
         <A HREF="io.html#fwrite/1">io:fwrite/1,2,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) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Format = String = string()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok, InputList, LeftOverChars} |
         {more, RestFormat, Nchars, InputStack} | {error, What}</CODE></STRONG><BR>
<STRONG><CODE>InputList = chars()</CODE></STRONG><BR>
<STRONG><CODE>LeftOverChars = string()</CODE></STRONG><BR>
<STRONG><CODE>RestFormat = string()</CODE></STRONG><BR>
<STRONG><CODE>Nchars = int()</CODE></STRONG><BR>
<STRONG><CODE>InputStack = chars()</CODE></STRONG><BR>
<STRONG><CODE>What = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Tries to read <CODE>String</CODE> in accordance with the control
sequences in <CODE>Format</CODE>. See
         <A HREF="io.html#fread/3">io:fread/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>
 The read operation failed and the parameter <CODE>What</CODE>
         gives a hint about the error.<BR>

         
</DD>

</DL>

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

</DIV>

<P><A NAME="fread/3"><STRONG><CODE>fread(Continuation, String, Format) -&#62; Return</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Continuation = see below</CODE></STRONG><BR>
<STRONG><CODE>String = Format = string()</CODE></STRONG><BR>
<STRONG><CODE>Return = {done, Result, LeftOverChars} | {more, Continuation}
        </CODE></STRONG><BR>
<STRONG><CODE>Result = {ok, InputList} | eof | {error, What}</CODE></STRONG><BR>
<STRONG><CODE>InputList = chars()</CODE></STRONG><BR>
<STRONG><CODE>What = term()()</CODE></STRONG><BR>
<STRONG><CODE>LeftOverChars = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This is the re-entrant formatted reader. The continuation of
         the first call to the 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.
<P>The function 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 and the parameter <CODE>What</CODE> gives
                 a hint about the error.<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>fread/3</CODE>,
         when more data becomes available.<BR>

         
</DD>

</DL>

</DIV>

<P><A NAME="write_atom/1"><STRONG><CODE>write_atom(Atom) -&#62; chars()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Atom = atom()</CODE></STRONG><BR>

  </DIV>
</DIV>

<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) -&#62; chars()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<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) -&#62; chars()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Integer = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<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) -&#62; int()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = string()</CODE></STRONG><BR>
<STRONG><CODE>StartIndent = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

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

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Term = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

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

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Term = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

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

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Term = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

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

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