<?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) 1999-2011 - amaury darsch                            = -->
<!-- ====================================================================== -->

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

  <!-- =================================================================== -->
  <!-- = 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 -->
    <ctors>
      <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>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<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>
      </meth>
      
      <meth>
	<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>
      </meth>

      <meth>
	<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>
      </meth>

      <meth>
	<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>
      </meth>

      <meth>
	<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>
      </meth>

      <meth>
	<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>
      </meth>

      <meth>
	<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
	  sub-directories. The list contains all valid names at the time of
	  the call, including the current directory and the parent directory.
	</p>
      </meth>

      <meth>
	<name>next-name</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>next-name</code> method returns the next available
	  name from the directory stream. This method is useful when
	  operating with a large number of elements.
	</p>
      </meth>

      <meth>
	<name>next-path</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>next-path</code> method returns the next available
	  path name from the directory stream. This method is useful when
	  operating with a large number of elements.
	</p>
      </meth>

      <meth>
	<name>next-file-name</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>next-file-name</code> method returns the next available
	  file name from the directory stream. This method is useful when
	  operating with a large number of elements.
	</p>
      </meth>

      <meth>
	<name>next-file-path</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>next-file-path</code> method returns the next available
	  file path name from the directory stream. This method is useful when
	  operating with a large number of elements.
	</p>
      </meth>

      <meth>
	<name>next-dir-name</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>next-dir-name</code> method returns the next available
	  directory name from the directory stream. This method is useful when
	  operating with a large number of elements.
	</p>
      </meth>

      <meth>
	<name>next-dir-path</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>next-dir-path</code> method returns the next available
	  directory path name from the directory stream. This method is useful when
	  operating with a large number of elements.
	</p>
      </meth>
    </methods>
  </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 -->
    <ctors>
      <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>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<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>
      </meth>
      
      <meth>
	<name>get-output-stream</name>
	<retn>Output</retn>
	<args>none</args>
	<p>
	  The <code>get-output-stream</code> method returns the logtee
	  output stream.
	</p>
      </meth>

      <meth>
	<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>
      </meth>

      <meth>
	<name>get-tee</name>
	<retn>Boolean</retn>
	<args>none</args>
	<p>
	  The <code>get-tee</code> method returns the logtee output stream.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = named fifo object                                              = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>NameFifo</code> class is a string vector designed to
      operate as a stream fifo object. The class provides the facility
      to read or write the fifo content from a stream. The stream can be
      created by name for writing, in which case the named fifo operates
      as a backup object.
    </p>
    
    <!-- predicate -->
    <pred>named-fifo-p</pred>

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

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>NamedFifo</name>
	<args>none</args>
	<p>
	  The <code>NamedFifo</code> constructor creates a default named
	  fifo without a backing name. In this case the fifo cannot be
	  read or written by stream.
	</p>
      </ctor>

      <ctor>
	<name>NamedFifo</name>
	<args>String</args>
	<p>
	  The <code>NamedFifo</code> constructor creates a named fifo by
	  name. The name is used as a file name for reading or writing the
	  fifo.
	</p>
      </ctor>

      <ctor>
	<name>NamedFifo</name>
	<args>String Boolean</args>
	<p>
	  The <code>NamedFifo</code> constructor creates a named fifo by
	  name. The name is used as a file name for reading or writing the
	  fifo.If the boolean argument is true, the fifo is read.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>read</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>read</code> method reads the fifo file name and fill
	  the fifo.
	</p>
      </meth>
      
      <meth>
	<name>write</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>write</code> method writes the fifo contents to the
	  fifo file name.
	</p>
      </meth>

      <meth>
	<name>set-name</name>
	<retn>none</retn>
	<args>String</args>
	<p>
	  The <code>set-name</code> method sets the fifo file name.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = file info object                                                = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>FileInfo</code> is a file information class that holds
      the primary information related to a file, such like its size or
      its modification time. The file information is set at construction
      but can be updated with the help of the <code>update</code> method.
    </p>
    
    <!-- predicate -->
    <pred>file-info-p</pred>

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

    <!-- constructors -->
    <ctors>
      <ctor>
	<name></name>
	<args>String</args>
	<p>
	  The <code>FileInfo</code> constructor creates a file information
	  by name. The string argument is the file name to query.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>length</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>length</code> method returns the file size information.
	</p>
      </meth>
      
      <meth>
	<name>get-modification-time</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-modification-time</code> method returns the file
	  modification time. The time can be used as an argument to
	  the <code>Time</code> or <code>Date</code> object.
	</p>
      </meth>

      <meth>
	<name>update</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>update</code> method the file information data.
	</p>
      </meth>
    </methods>
  </object>
</appendix>
