<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = appendix-i.xml                                                     = -->
<!-- = standard i/o module guide - appendix i                             = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="sio" number="i">
  <title>Standard i/o reference</title>

  <p>
  This appendix is a reference of the <afnix/> standard i/o module.
  </p>

  <table>
    <title>Standard i/o module</title>
    <thead>
      <tr><td>Symbol</td> <td>Description</td></tr>
    </thead>
    <tbody>
      <tr><td>afnix-sio</td><td>module</td></tr>
      <tr><td>afnix:sio</td><td>nameset</td></tr>
    </tbody>
  </table>

  <!-- =================================================================== -->
  <!-- = transcoder object                                               = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>Transcoder</name>

    <!-- synopsis -->
    <p>
    The <code>Transcoder</code> class is a codeset transcoder
    class. The class is responsible to map a byte character in a given
    codeset into its associated unicode character. It should be
    noted that not all characters can be transcoded.
    </p>

    <!-- predicate -->
    <pred>transcoder-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constants -->
    <constant>
      <name>DEFAULT</name>
      <p>
      The <code>DEFAULT</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode. In default mode, each character is not
      transcoded. This mode is the identity mode.
      </p>
    </constant>

    <constant>
      <name>I8859-01</name>
      <p>
      The <code>I8859-01</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-6 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-02</name>
      <p>
      The <code>I8859-02</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-2 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-03</name>
      <p>
      The <code>I8859-03</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-3 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-04</name>
      <p>
      The <code>I8859-04</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-4 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-05</name>
      <p>
      The <code>I8859-05</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-5 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-06</name>
      <p>
      The <code>I8859-06</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-6 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-07</name>
      <p>
      The <code>I8859-07</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-7 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-08</name>
      <p>
      The <code>I8859-08</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-8 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-09</name>
      <p>
      The <code>I8859-09</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-9 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-10</name>
      <p>
      The <code>I8859-10</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-10 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-11</name>
      <p>
      The <code>I8859-11</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-11 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-13</name>
      <p>
      The <code>I8859-13</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-13 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-14</name>
      <p>
      The <code>I8859-14</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-14 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-15</name>
      <p>
      The <code>I8859-15</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-15 codeset.
      </p>
    </constant>

    <constant>
      <name>I8859-16</name>
      <p>
      The <code>I8859-16</code> constant is used by the
      <code>set-transcoding-mode</code> method to specify the class
      transcoding mode that corresponds to the ISO-8859-16 codeset.
      </p>
    </constant>

    <!-- constructors -->
    <ctor>
      <name>Transcoder</name>
      <args>none</args>
      <p>
      The <code>Transcoder</code> constructor creates a default transcoder
      that operates in default mode by using the identity function.
      </p>
    </ctor>

    <ctor>
      <name>Transcoder</name>
      <args>constant</args>
      <p>
      The <code>Transcoder</code> constructor creates a transcoder
      with the argument mode.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-transcoding-mode</name>
      <retn>none</retn>
      <args>constant</args>
      <p>
      The <code>set-transcoding-mode</code> method sets the class
      transcoding mode.
      </p>
    </method>

    <method>
      <name>get-transcoding-mode</name>
      <retn>constant</retn>
      <args>none</args>
      <p>
      The <code>get-transcoding-mode</code> method returns the class
      transcoding mode. 
      </p>
    </method>

    <method>
      <name>valid-p</name>
      <retn>Byte|Character</retn>
      <args>Boolean</args>
      <p>
      The <code>valid-p</code> predicate returns true if character can
      be transcoded. If the argument is a byte, the method returns
      true if the byte can be transcoded to a character. If the
      argument is a character, the method returns true if the
      character can be transcoded to a byte.
      </p>
    </method>

    <method>
      <name>encode</name>
      <retn>Byte</retn>
      <args>Character</args>
      <p>
      The <code>encode</code> method encodes a byte into a character.
      If the character cannot be encoded, an exception is raised.
      </p>
    </method>

    <method>
      <name>decode</name>
      <retn>Character</retn>
      <args>Byte</args>
      <p>
      The <code>decode</code> method decodes a character into a byte.
      If the character cannot be decoded, an exception is raised.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = stream object                                                    = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>Stream</name>

    <!-- synopsis -->
    <p>
    The <code>Stream</code> class is a base class for the <afnix/>
    standard streams. The class is automatically constructed by a
    derived class and provides the common methods for all streams.
    </p>

    <!-- predicate -->
    <pred>stream-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Transcoder</name>
    </inherit>

    <!-- constants -->
    <constant>
      <name>BYTE</name>
      <p>
      The <code>BYTE</code> constant is used by the
      <code>set-coding-mode</code> method to specify the stream coding mode.
      In byte mode, each character is assumed to be coded with one
      byte. This value affects the <code>rduc</code> and
      <code>write</code> methods
      </p>
    </constant>

    <constant>
      <name>UTF-8</name>
      <p>
      The <code>UTF-8</code> constant is used by the
      <code>set-coding-mode</code> method to specify the stream coding mode.
      In utf-8 mode, each character is assumed to be coded in the
      UTF-8 representation. This value affects the <code>rduc</code> and
      <code>write</code> methods
      </p>
    </constant>

    <!-- methods -->
    <method>
      <name>set-encoding-mode</name>
      <retn>none</retn>
      <args>constant|String</args>
      <p>
      The <code>set-encoding-mode</code> method sets the stream coding mode
      that affects how characters are read or written. In the
      enumeration form, the method only sets the stream coding mode
      which is either byte or UTF-8 mode. In the string mode, the
      method sets the stream encoding mode and the transcoding mode.
      </p>
    </method>

    <method>
      <name>get-encoding-mode</name>
      <retn>constant</retn>
      <args>none</args>
      <p>
      The <code>get-coding-mode</code> method returns the stream coding mode
      which affects how characters are read or written.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = input object                                                    = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>Input</name>

    <!-- synopsis -->
    <p>
    The <code>Input</code> class is a base class for the <afnix/>
    standard i/o module. The class is automatically constructed by a
    derived class and provides the common methods for all input streams.
    </p>

    <!-- predicate -->
    <pred>input-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Stream</name>
    </inherit>

    <!-- methods -->
    <method>
      <name>read</name>
      <retn>Byte</retn>
      <args>none</args>
      <p>
      The <code>read</code> method returns the next byte available
      from the input stream. If the stream has been closed or
      consumed, the <tt>eof</tt> byte is returned.
      </p>
    </method>

    <method>
      <name>read</name>
      <retn>Buffer</retn>
      <args>Integer</args>
      <p>
      The <code>read</code> method returns a buffer object with at
      most the number of bytes specified as an argument. The
      buffer <code>length</code> method should be used to check how
      many bytes have been placed in the buffer.
      </p>
    </method>
      
    <method>
      <name>readln</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>readln</code> method returns the next line available
      from the input stream. If the stream has been closed or
      consumed, the <tt>eof</tt> byte is returned.
      </p>
    </method>
      
    <method>
      <name>rduc</name>
      <retn>Character</retn>
      <args>none</args>
      <p>
      The <code>rduc</code> method returns the next available Unicode
      character from the input stream. If the stream has been closed or
      consumed, the <tt>eof</tt> byte is returned. During the read
      process, if the character decoding operation fails, an exception
      is raised.
      </p>
    </method>

    <method>
      <name>valid-p</name>
      <retn>Boolean</retn>
      <args>none|Integer</args>
      <p>
      The <code>valid-p</code> method returns true if the input stream
      is in a valid state. By valid state, we mean that the input
      stream can return a byte with a call to the read
      method. With one argument, the method timeout after the
      specified time in milliseconds. If the timeout is null, the
      method returns immediately. With -1, the method blocks
      indefinitely if no byte is available.
      </p>
    </method>

    <method>
      <name>eof-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>eof-p</code> method returns true if the input stream
      has been closed or all bytes consumed.
      </p>
    </method>

    <method>
      <name>pushback</name>
      <retn>none</retn>
      <args>Byte|Character|String</args>
      <p>
      The <code>pushback</code> method push-back a byte, an Unicode
      character or a string in the input stream. Subsequent calls to
      read will return the last pushed bytes. Pushing a string is
      equivalent to push each bytes of the string.
      </p>
    </method>

    <method>
      <name>get-buffer-length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-buffer-length</code> method returns the length of
      the push-back buffer.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = input file object                                               = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>InputFile</name>

    <!-- synopsis -->
    <p>
    The <code>InputFile</code> class provide the facility for an input
    file stream. An input file instance is created with a file
    name. If the file does not exist or cannot be opened, an exception
    is raised. The <code>InputFile</code> class is derived from the
    <code>Input</code> class. 
    </p>

    <!-- predicate -->
    <pred>input-file-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Input</name>
      <name>Nameable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>InputFile</name>
      <args>String</args>
      <p>
      The <code>InputFile</code> constructor create an input file by
      name. If the file cannot be created, an exception is raised. The
      first argument is the file name to open.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>close</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>close</code> method close the input file and returns
      true on success, false otherwise. In case of success, multiple
      calls return true. 
      </p>
    </method>

    <method>
      <name>lseek</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>lseek</code> set the input file position to the
      integer argument. Note that the push-back buffer is reset after
      this call.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the length of the input
      file. The length is expressed in bytes.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = input mapped object                                             = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>InputMapped</name>

    <!-- synopsis -->
    <p>
    The <code>InputMapped</code> class provide the facility for an
    input file stream with offset and size. The class is similar to
    the <code>InputFile</code> class except that the constructor can
    also accepts an integer offset and size argument. If the file
    offset or size are out of range, the class behaves like an input
    file. If the file does not exist or cannot be opened, an exception
    is raised.
    </p>

    <!-- predicate -->
    <pred>input-mapped-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Input</name>
      <name>Nameable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>InputMapped</name>
      <args>String</args>
      <p>
      The <code>InputFile</code> constructor create an input mapped
      file by name. If the file cannot be created, an exception is
      raised. The first argument is the file name to open.
      </p>
    </ctor>

    <ctor>
      <name>InputMapped</name>
      <args>String Integer Integer</args>
      <p>
      The <code>InputFile</code> constructor create an input mapped
      file by name and offset. If the file cannot be created, an
      exception is raised. The first argument is the file name to
      open. The second argument is the offset inside that file. The
      third argument is the size that should be used for this mapped
      file.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>lseek</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>lseek</code> set the input mapped file position to the
      integer argument. Note that the push-back buffer is reset after
      this call.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the length of the input
      mapped file. The length is expressed in bytes.
      </p>
    </method>

    <method>
      <name>get-offset</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the input mapped file offset.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = input string object                                             = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>InputString</name>

    <!-- synopsis -->
    <p>
    The <code>InputString</code> class provide the facility for an
    input string stream. The class is initialized or set with a string
    and then behaves like a stream. This class is very useful to
    handle generic stream method without knowing what kind of stream
    is behind it.
    </p>

    <!-- predicate -->
    <pred>input-string-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Input</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>InputString</name>
      <args>none</args>
      <p>
      The <code>InputString</code> constructor creates an empty input
      string.
      </p>
    </ctor>

    <ctor>
      <name>InputString</name>
      <args>String</args>
      <p>
      The <code>InputString</code> constructor creates an input string by
      value.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get</name>
      <retn>Byte</retn>
      <args>none</args>
      <p>
      The <code>get</code> method returns the next available byte
      from the input stream but do not remove it.
      </p>
    </method>

    <method>
      <name>set</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set</code> method sets the input string by first
      resetting the push-back buffer and then initializing the input
      string with the argument value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = input terminal object                                           = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>InputTerm</name>

    <!-- synopsis -->
    <p>
    The <code>InputTerm</code> class provide the facility for an input
    terminal stream. The input terminal reads byte from the
    standard input stream. No line editing facility is provided with
    this class This is a low level class, and normally, the
    <code>Terminal</code> class should be used instead.
    </p>

    <!-- predicate -->
    <pred>input-term-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Input</name>
      <name>Output</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>InputTerm</name>
      <args>none</args>
      <p>
      The <code>InputTerm</code> constructor creates a default input
      terminal.
      </p>
    </ctor>

    <!-- methods-->
    <method>
      <name>set-eof-ignore</name>
      <retn>none</retn>
      <args>Boolean</args>
      <p>
      The <code>set-eof-ignore</code> method set the input terminal
      <tt>ctrl-d</tt> ignore flag. When the flag is on, any byte
      that match a <tt>ctrl-d</tt> is changed to the re-mapped
      byte and returned by a read. This method is useful to
      prevent a reader to exit when the <tt>ctrl-d</tt> byte is
      generated. 
      </p>
    </method>

    <method>
      <name>set-eof-byte</name>
      <retn>none</retn>
      <args>Byte</args>
      <p>
      The <code>set-eof-byte</code> method set the input terminal
      <tt>ctrl-d</tt> re-mapping byte. By default the byte is
      set to the <tt>end-of-line</tt> byte. This method should be
      used in conjunction with the <code>set-eof-ignore</code> method.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = output object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>Output</name>

    <!-- synopsis -->
    <p>
    The <code>Output</code> class is a base class for the <afnix/>
    standard i/o module. The class is automatically constructed by a
    derived class and provide the common methods for all output
    streams.
    </p>

    <!-- predicate -->
    <pred>output-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Stream</name>
    </inherit>

    <!-- methods -->
    <method>
      <name>write</name>
      <retn>none</retn>
      <args>Literal+</args>
      <p>
      The <code>write</code> method write one or more literal
      arguments on the output stream. This method returns nil;
      </p>
    </method>

    <method>
      <name>writeln</name>
      <retn>none</retn>
      <args>Literal+</args>
      <p>
      The <code>writeln</code> method write one or more literal
      argument to the output stream and finish with a newline. This
      method return nil.
      </p>
    </method>

    <method>
      <name>errorln</name>
      <retn>none</retn>
      <args>Literal+</args>
      <p>
      The <code>errorln</code> method write one or more literal
      argument to the associated output error stream and finish with a
      newline. Most of the time, the output stream and error stream
      are the same except for an output terminal.
      </p>
    </method>

    <method>
      <name>newline</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>newline</code> method writes a new line byte to
      the output stream. The method returns nil.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = output file object                                              = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>OutputFile</name>

    <!-- synopsis -->
    <p>
    The <code>OutputFile</code> class provide the facility for an
    output file stream. An output file instance is created with a file
    name. If the file does not exist, it is created. If the file
    cannot be created, an exception is raised. Once the file is
    created, it is possible to write literals. The class is derived
    from the <code>Output</code> class. By default an output file is
    created if it does not exist. If the file already exist, the file
    is truncated to 0. Another constructor for the output file gives
    more control about this behavior. It takes two boolean flags that
    defines the truncate and append mode. The <tt>t-flag</tt> is
    the truncate flag. The <tt>a-flag</tt> is the append flag.
    </p>

    <!-- predicate -->
    <pred>output-file-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Output</name>
      <name>Nameable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>OutputFile</name>
      <args>String</args>
      <p>
      The <code>OutputFile</code> constructor create an output file by
      name. If the file cannot be created, an exception is raised. The
      first argument is the file name to create.
      </p>
    </ctor>

    <ctor>
      <name>OutputFile</name>
      <args>String Boolean Boolean</args>
      <p>
      The <code>OutputFile</code> constructor create an output file by
      name. If the file cannot be created, an exception is raised. The
      first argument is the file name to create. The second argument
      is the truncate flag. If the file already exists and the
      truncate flag is set, the file is truncated to 0. The third
      argument is the append mode. If set to true, the file is open in
      append mode.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>close</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>close</code> method closes the output file and returns
      true on success, false otherwise. In case of success, multiple
      calls returns true. 
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = output string object                                            = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>OutputString</name>

    <!-- synopsis -->
    <p>
    The <code>OutputString</code> class provide the facility for an
    output string stream. The class is initially empty and acts as a
    buffer which accumulate the write method bytes. The
    <code>to-string</code> method can be used to retrieve the buffer
    content.
    </p>

    <!-- predicate -->
    <pred>output-string-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Output</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>OutputString</name>
      <args>none</args>
      <p>
      The <code>OutputString</code> constructor creates a default output
      string.
      </p>
    </ctor>

    <ctor>
      <name>OutputString</name>
      <args>String</args>
      <p>
      The <code>OutputString</code> constructor creates an output string by
      value. The output string stream is initialized with the string
      value.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>flush</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>flush</code> method flushes the output string stream
      by resetting the string buffer.
      </p>
    </method>

    <method>
      <name>to-string</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>to-string</code> method returns a string
      representation of the output string buffer.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = output terminal object                                          = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>OutputTerm</name>

    <!-- synopsis -->
    <p>
    The <code>OutputTerm</code> class provide the facility for an
    output terminal. The output terminal is defined as the standard
    output stream. If the standard error stream needs to be used, the
    <code>ErrorTerm</code> class is more appropriate.
    </p>

    <!-- predicate -->
    <pred>output-term-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Output</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>OutputTerm</name>
      <args>none</args>
      <p>
      The <code>OutputTerm</code> constructor creates a default output
      terminal
      </p>
    </ctor>

    <ctor>
      <name>ErrorTerm</name>
      <args>none</args>
      <p>
      The <code>ErrorTerm</code> constructor creates a default error
      terminal
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = terminal object                                                 = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>Terminal</name>

    <!-- synopsis -->
    <p>
    The <code>Terminal</code> class provides the facility for an
    i/o terminal with line editing capability. The class combines 
    the <code>InputTerm</code> and <code>OutputTerm</code> methods.
    </p>

    <!-- predicate -->
    <pred>terminal-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>InputTerm</name>
      <name>OutputTerm</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Terminal</name>
      <args>none</args>
      <p>
      The <code>Terminal</code> constructor creates a default terminal
      which combines an input and output terminal with line editing
      capabilities.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-primary-prompt</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-primary-prompt</code> method sets the terminal primary
      prompt which is used when the <code>read-line</code> method is 
      called. 
      </p>
    </method>

    <method>
      <name>set-secondary-prompt</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-secondary-prompt</code> method sets the terminal
      secondary prompt which is used when the <code>read-line</code>
      method is called.
      </p>
    </method>

    <method>
      <name>get-primary-prompt</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-primary-prompt</code> method returns the terminal primary
      prompt.
      </p>
    </method>

    <method>
      <name>get-secondary</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-secondary-prompt</code> method returns the terminal
      secondary prompt.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = selector object                                                 = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>Selector</name>

    <!-- synopsis -->
    <p>
    The <code>Selector</code> class provides some facilities to
    perform i/o multiplexing. The constructor takes 0 or several
    stream arguments.The class manages automatically to differentiate
    between <code>Input</code> and <code>Output</code> streams. Once
    the class is constructed, it is possible to get the first stream
    ready for reading or writing or all of them. It is also possible
    to add more steams after construction with the <code>add</code>
    method. When used with several input streams in a multi-threaded
    context, the selector behavior can becomes quite
    complicated. Either <code>wait</code> and <code>wait-all</code>
    methods check first the input streams push-back buffer. If one or 
    several buffer are not empty, the method returns with these
    streams. During this operation, the input streams are locked, so
    no other thread can push-back a byte. The selector then
    checks for status change and unlock the streams. Note that the
    output streams are not locked. Note also that a thread which rely
    on the input stream push-back method to release a selector will
    result in a dead-lock.
    </p>

    <!-- predicate -->
    <pred>selector</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Selector</name>
      <args>none</args>
      <p>
      The <code>Selector</code> constructor creates a default stream
      selector.
      </p>
    </ctor>

    <ctor>
      <name>Selector</name>
      <args>[Input|Output]*</args>
      <p>
      The <code>Selector</code> constructor creates a stream selector
      with 0 or more stream arguments.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>Input|Output</args>
      <p>
      The <code>add</code> method adds an input or output stream to
      the selector.
      </p>
    </method>

    <method>
      <name>wait</name>
      <retn>Object</retn>
      <args>none|Integer</args>
      <p>
      The <code>wait</code> method waits for a status change in the
      selector and returns the first stream that has change
      status. With one argument, the selector time-out after the
      specified time in milliseconds. Note that at the time of the
      return, several streams may have changed status.
      </p>
    </method>

    <method>
      <name>wait-all</name>
      <retn>Vector</retn>
      <args>none|Integer</args>
      <p>
      The <code>wait</code> method waits for a status change in the
      selector and returns all streams that has change status in a
      vector object. With one argument, the selector time-out after
      the specified time in milliseconds. If the selector has
      timed-out, the vector is empty.
      </p>
    </method>

    <method>
      <name>input-get</name>
      <retn>Input</retn>
      <args>Integer</args>
      <p>
      The <code>input-get</code> method returns the input streams in
      the selector by index. If the index is out of bound, an
      exception is raised.
      </p>
    </method>

    <method>
      <name>output-get</name>
      <retn>Output</retn>
      <args>Integer</args>
      <p>
      The <code>output-get</code> method returns the output streams in
      the selector by index. If the index is out of bound, an
      exception is raised.
      </p>
    </method>

    <method>
      <name>input-length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>input-length</code> method returns the number of input
      streams in the selector.
      </p>
    </method>

    <method>
      <name>output-length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>output-length</code> method returns the number of
      output streams in the selector.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = logtee object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:sio">
    <name>Logtee</name>

    <!-- synopsis -->
    <p>
    The <code>Logtee</code> class provides the facility of a logger
    object associated with an output stream. When a message is added,
    the message is written to the output stream depending on an
    internal flag.
    </p>

    <!-- predicate -->
    <pred>logtee-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Logger</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Logtee</name>
      <args>none</args>
      <p>
      The <code>Logtee</code> constructor creates a default logger
      without an output stream.
      </p>
    </ctor>

    <ctor>
      <name>Logtee</name>
      <args>Integer</args>
      <p>
      The <code>Logtee</code> constructor creates a logger with a
      specific size without an output stream.
      terminal
      </p>
    </ctor>

    <ctor>
      <name>Logtee</name>
      <args>Output</args>
      <p>
      The <code>Logtee</code> constructor creates a logger with an
      output stream. The object is initialized to operate in write
      mode.
      </p>
    </ctor>

   <ctor>
      <name>Logtee</name>
      <args>Integer Output</args>
      <p>
      The <code>Logtee</code> constructor creates a logger with a
      specific size with an output stream. The first argument is the
      logger size. The second argument is the output stream.
      </p>
    </ctor>

    <ctor>
      <name>Logtee</name>
      <args>Integer String Output</args>
      <p>
      The <code>Logtee</code> constructor creates a logger with a
      specific size, an information string and an output stream. The
      first argument is the logger size. The second argument is
      information string. The third argument is the output stream.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set-output-stream</name>
      <retn>none</retn>
      <args>Output</args>
      <p>
      The <code>set-output-stream</code> method sets the object output
      stream.
      </p>
    </method>

    <method>
      <name>get-output-stream</name>
      <retn>Output</retn>
      <args>none</args>
      <p>
      The <code>get-output-stream</code> method returns the object
      output stream.
      </p>
    </method>

    <method>
      <name>set-tee</name>
      <retn>none</retn>
      <args>Boolean</args>
      <p>
      The <code>set-tee</code> method sets the object tee flag. When
      the flag is true, the logger writes the added message on the
      output stream.
      </p>
    </method>

    <method>
      <name>get-tee</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>get-tee</code> method returns the object tee flag. When
      the flag is true, the logger writes the added message on the
      output stream.
      </p>
    </method>
  </object>
  <p/>

  <!-- =================================================================== -->
  <!-- = global functions                                                = -->
  <!-- =================================================================== -->
  
  <function nameset="afnix:sio">
    <name>dir-p</name>
    <retn>Boolean</retn>
    <args>String</args>
    <p>
    The <code>dir-p</code> function returns true if the argument name
    is a directory name, false otherwise.
    </p>
  </function>
  <p/>

  <function nameset="afnix:sio">
    <name>file-p</name>
    <retn>Boolean</retn>
    <args>String</args>
    <p>
    The <code>file-p</code> function returns true if the argument name
    is a regular file name, false otherwise.
    </p>
  </function>
  <p/>

  <function nameset="afnix:sio">
    <name>tmp-name</name>
    <retn>String</retn>
    <args>String?</args>
    <p>
    The <code>tmp-name</code> function returns a name suitable for the use
    as a temporary file name. Without argument, a default prefix is
    used to build the name. An optional string prefix can control the
    original name.
    </p>
  </function>
  <p/>

  <function nameset="afnix:sio">
    <name>tmp-path</name>
    <retn>String</retn>
    <args>String?</args>
    <p>
    The <code>tmp-path</code> function returns a path suitable for the use
    as a temporary file name. Without argument, a default prefix is
    used to build the path. An optional string prefix can control the
    original name.
    </p>
  </function>
  <p/>

  <function nameset="afnix:sio">
    <name>absolute-path</name>
    <retn>String</retn>
    <args>String+</args>
    <p>
    The <code>absolute-path</code> function returns an absolute path
    name from an argument list. Without argument, the command returns
    the root directory name. With one or several argument, the
    absolute path is computed from the root directory.
    </p>
  </function>
  <p/>

  <function nameset="afnix:sio">
    <name>relative-path</name>
    <retn>String</retn>
    <args>String+</args>
    <p>
    The <code>relative-path</code> function returns a relative path
    name from an argument list. With one argument, the function
    returns it. With two or more arguments, the relative path is
    computed by joining each argument with the previous one.
    </p>
  </function>
  <p/>

  <function nameset="afnix:sio">
    <name>rmfile</name>
    <retn>none</retn>
    <args>String+</args>
    <p>
    The <code>rmfile</code> function removes one or several files
    specified as the arguments. If one file fails to be removed, an
    exception is raised.
    </p>
  </function>
  <p/>

  <function nameset="afnix:sio">
    <name>rmdir</name>
    <retn>none</retn>
    <args>String+</args>
    <p>
    The <code>rmdir</code> function removes one or several directories
    specified as the arguments. If one directory fails to be removed,
    an exception is raised.
    </p>
  </function>
</appendix>
