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

<!-- ====================================================================== -->
<!-- = appendix-ii.xml                                                    = -->
<!-- = standard i/o module guide - appendix ii                            = -->
<!-- ====================================================================== -->
<!-- = 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-2006 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="sio" number="ii">
  <title>Special i/o objects reference</title>

  <p>
  This appendix is a reference of the <afnix/> standard i/o module
  special objects subsystem.
  </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>

  <!-- =================================================================== -->
  <!-- = directory object                                                = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
    The <code>Directory</code> class provides some facilities to
    access a directory. By default, a directory object is constructed
    to represent the current  directory. With one argument, the object
    is constructed from the directory name. Once the object is
    constructed, it is possible to retrieve its content.
    </p>
    
    <!-- predicate -->
    <pred>directory-p</pred>

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

    <!-- constructors -->
    <ctor>
      <name>Directory</name>
      <args>none</args>
      <p>
      The <code>Directory</code> constructor creates a directory object
      those location is the current directory. If the directory cannot
      be opened, an exception is raised.
      </p>
    </ctor>

    <ctor>
      <name>Directory</name>
      <args>String</args>
      <p>
      The <code>Directory</code> constructor create a directory object
      by name. If the directory cannot be opened, an exception is
      raised. The first argument is the directory name to open.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>mkdir</name>
      <retn>Directory</retn>
      <args>String</args>
      <p>
      The <code>mkdir</code> method creates a new directory in the
      current one. The full path is constructed by taking the
      directory name and adding the argument. Once the directory is
      created, the method returns a directory object of the newly
      constructed directory. An exception is thrown if the directory
      cannot be created.
      </p>
    </method>
      
    <method>
      <name>rmdir</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>rmdir</code> method removes an empty directory. The
      full path is constructed by taking the directory name and adding
      the argument. An exception is thrown if the directory cannot be
      removed.
      </p>
    </method>

    <method>
      <name>rmfile</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>rmfile</code> method removes a file in the current
      directory. The full path is constructed by taking the directory
      name and adding the argument. An exception is thrown if the file
      cannot be removed.
      </p>
    </method>

    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the directory name. If
      the default directory was created, the method returns the full
      directory path.
      </p>
    </method>

    <method>
      <name>get-list</name>
      <retn>List</retn>
      <args>none</args>
      <p>
      The <code>get-list</code> method returns the directory
      contents. The method returns a list of strings. The list
      contains all valid names at the time of the call, including the
      current directory and the parent directory.
      </p>
    </method>

    <method>
      <name>get-files</name>
      <retn>List</retn>
      <args>none</args>
      <p>
      The <code>get-files</code> method returns the directory
      contents. The method returns a list of strings of files. The
      list contains all valid names at the time of the call.
      </p>
    </method>

    <method>
      <name>get-subdirs</name>
      <retn>List</retn>
      <args>none</args>
      <p>
      The <code>get-subdirs</code> method returns the sub
      directories. The method returns a list of strings of
      subdirectories. The list contains all valid names at the time of
      the call, including the current directory and the parent directory.
      </p>
    </method>
  </object>

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

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

    <!-- synopsis -->
    <p>
    The <code>Logtee</code> class is a message logger facility
    associated with an output stream. When a message is added to the
    logger object, the message is also sent to the output stream,
    depending on the controlling flags. The name "logtee" comes from
    the contraction of "logger" and "tee". One particularity of the
    class is that without a stream, the class behaves like a regular
    logger.
    </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 object with
      a specific size without an output stream.
      </p>
    </ctor>

    <ctor>
      <name>Logtee</name>
      <args>Output</args>
      <p>
      The <code>Logtee</code> constructor creates a logger object with
      an output stream.
      </p>
    </ctor>

    <ctor>
      <name>Logtee</name>
      <args>Integer Output</args>
      <p>
      The <code>Logtee</code> constructor creates a logger object with
      a specific size and an output stream. The first argument is the
      logger window 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 object with
      a specific size, an information string and an output stream. The
      first argument is the logger window size. The second argument is
      the logger 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 attaches the output
      stream to the logtee object.
      </p>
    </method>
      
    <method>
      <name>get-output-stream</name>
      <retn>Output</retn>
      <args>none</args>
      <p>
      The <code>get-output-stream</code> returns the logtee output stream.
      </p>
    </method>

    <method>
      <name>set-tee</name>
      <retn>none</retn>
      <args>Boolean</args>
      <p>
      The <code>set-tee</code> method sets the logtee control
      flag. The control flag controls the message display to 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 logtee output stream.
      </p>
    </method>
  </object>
</appendix>
