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

<!-- ====================================================================== -->
<!-- = chapter-4.xml                                                      = -->
<!-- = afnix reference manual - chapter 4                                 = -->
<!-- ====================================================================== -->
<!-- = 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                            = -->
<!-- ====================================================================== -->

<chapter volume="2" number="4">
  <title>Special objects</title>

  <p>
  This chapter is a reference of the <afnix/> reserved special objects
  with their respective built-in methods. Special objects are those
  objects which interact with the interpreter.
  </p>

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

  <object type="reserved">
    <name>Object</name>

    <p>
    The base object <code>Object</code> provides several methods which are
    common to all objects.
    </p>

    <!-- methods -->
    <method>
      <name>repr</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>repr</code> method returns the object name in the form of
      a string. The result string is called the <em>representation
      string</em>.
      </p>
    </method>

    <method>
      <name>rdlock</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>rdlock</code> method try to acquire the object in
      read-lock mode. If the object is currently locked in write mode by
      another thread, the calling thread is suspended until the lock is
      released.
      </p>
    </method>

    <method>
      <name>wrlock</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>wrlock</code> method try to acquire the object in
      write-lock mode. If the object is currently locked by another
      thread, the calling thread is suspended until the lock is released.
      </p>
    </method>

    <method>
      <name>unlock</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>unlock</code> method try to unlock an object. An object
      will be unlocked if and only if the calling thread is the one who
      acquired the lock.
      </p>
    </method>

    <method>
      <name>shared-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>shared-p</code> method returns true if the object is
      shared, false otherwise.
      </p>
    </method>

    <method>
      <name>clone</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>clone</code> method returns a clone of the calling
      object. If the object cannot be cloned, an exception is raised.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = interp object                                                   = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Interp</name>

    <p>
    The <code>Interp</code> is the interpreter object which is
    automatically bounded for each executable program. There is no
    constructor for this object. The current interpreter is bounded to
    the <code>interp</code> reserved symbol.
    </p>

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

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

    <!-- members -->
    <constant>
      <name>argv</name>
      <p>
      The <code>argv</code> data member holds the interpreter argument vector.
      The vector is initialized when the interpreter is created. Each
      argument is stored as a string object.
      </p>
    </constant>

    <constant>
      <name>os-name</name>
      <p>
      The <code>os-name</code> data member holds the operating system
      name. The data member evaluates as a string.
      </p>
    </constant>
      
    <constant>
      <name>os-type</name>
      <p>
      The <code>os-type</code> data member holds the operating system
      type. The data member evaluates as a string.
      </p>
    </constant>

    <constant>
      <name>version</name>
      <p>
      The <code>version</code> data member holds the full <afnix/> version.
      The data member evaluates as a string.
      </p>
    </constant>

    <constant>
      <name>program-name</name>
      <p>
      The <code>program-name</code> data member holds the interpreter
      program name. The data member evaluates as a string.
      </p>
    </constant>

    <constant>
      <name>major-version</name>
      <p>
      The <code>major-version</code> data member holds the interpreter
      major revision number. The data member evaluates as an integer.
      </p>
    </constant>

    <constant>
      <name>minor-version</name>
      <p>
      The <code>minor-version</code> data member holds the interpreter
      minor revision number. The data member evaluates as an integer.
      </p>
    </constant>

    <constant>
      <name>patch-version</name>
      <p>
      The <code>patch-version</code> data member holds the interpreter
      patch revision number. The data member evaluates as an integer.
      </p>
    </constant>

    <constant>
      <name>afnix-url</name>
      <p>
      The <code>afnix-url</code> data member holds the official <afnix/>
      url name. The data member evaluates as a string.
      </p>
    </constant>

    <!-- methods -->
    <method>
      <name>load</name>
      <retn>Boolean</retn>
      <args>String</args>
      <p>
      The <code>loop</code> method opens a file those name is the method
      argument and execute each form in the file by doing a read-eval
      loop. When all forms have been executed, the file is closed and the
      method return true. In case of exception, the file is closed and the
      method returns false. 
      </p>
    </method>

    <method>
      <name>library</name>
      <retn>Library</retn>
      <args>String</args>
      <p>
      The <code>library</code> method opens a shared library and a returns
      a shared library object.
      </p>
    </method>

    <method>
      <name>launch</name>
      <retn>Thread</retn>
      <args>form</args>
      <p>
      The <code>launch</code> method executes the form argument in a
      normal thread. The normal thread is created by cloning the current
      interpreter.
      </p>
    </method>

    <method>
      <name>daemon</name>
      <retn>Thread</retn>
      <args>form</args>
      <p>
      The <code>daemon</code> method executes the form argument in a
      daemon thread. The normal thread is created by cloning the current
      interpreter.
      </p>
    </method>

    <method>
      <name>set-epsilon</name>
      <retn>none</retn>
      <args>Real</args>
      <p>
      The <code>set-epsilon</code> method sets the interpreter epsilon
      which corresponds to the real precision. The <em>real precision</em>
      is used by the <code>?=</code> operator to compare real values.
      </p>
    </method>

    <method>
      <name>get-epsilon</name>
      <retn>Real</retn>
      <args>none</args>
      <p>
      The <code>get-real precision</code> method returns the interpreter
      epsilon which correspond to the real precision. The
      <em>real-precision</em> is used by the <code>?=</code> operator to
      compare real values.
      </p>
    </method>

    <method>
      <name>dup</name>
      <retn>Interp</retn>
      <args>none|Terminal</args>
      <p>
      The <code>dup</code> method returns a clone of the current
      interpreter by binding the terminal steam argument. Without
      argument, a new terminal object is automatically created and
      bound to the newly created interpreter.
      </p>
    </method>

    <method>
      <name>loop</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>loop</code> method executes the interpreter main loop
      by reading the interpreter input stream. The loop is finished
      when the end-of-stream is reached with the input stream. The
      method returns a boolean flag to indicate whether or not the
      loop was successful.
      </p>
    </method>

    <method>
      <name>set-primary-prompt</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-primary-prompt</code> method sets the interpreter
      terminal primary prompt which is used during the interpreter
      main loop.
      </p>
    </method>

    <method>
      <name>set-secondary-prompt</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-secondary-prompt</code> method sets the
      interpreter terminal secondary prompt which is used during the
      interpreter main loop.
      </p>
    </method>

    <method>
      <name>get-primary-prompt</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-primary-prompt</code> method returns the
      interpreter 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
      interpreter terminal secondary prompt.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = thread object                                                   = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Thread</name>

    <p>
    The <code>Thread</code> object is a special object which acts as a
    thread descriptor. Such object is created with the <code>launch</code>
    or <code>daemon</code> reserved keywords. Note that the thread
    object does not have a constructor.
    </p>

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

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

    <!-- members -->
    <constant>
      <name>result</name>
      <p>
      The <code>result</code> data member holds the thread result
      which is set at the thread termination. The data member evaluates as
      an object. 
      </p>
    </constant>

    <!-- methods -->
    <method>
      <name>wait</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>wait</code> method suspends the calling thread until the
      thread argument as completed. The <code>wait</code> method is the
      primary mechanism to detect a thread completion.
      </p>
    </method>

    <method>
      <name>normal-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>normal-p</code> method returns true if the thread argument
      is a normal thread.
      </p>
    </method>

    <method>
      <name>daemon-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>daemon-p</code> method returns true if the thread argument
      is a normal thread.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = condvar object                                                  = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Condvar</name>
    
    <p>
    The condition variable <code>Condvar</code> object is a special
    object which provides a mean of synchronization between one and
    several threads. The condition is said to be false unless it has
    been marked. When a condition is marked, all threads waiting for
    that condition to become true are notified and one thread is
    activated with that condition.
    </p>

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

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

    <!-- constructors -->
    <ctor>
      <name>Condvar</name>
      <args>none</args>
      <p>
      The <code>Condvar</code> constructor creates a default condition
      variable.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>lock</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>lock</code> method locks the condition variable mutex. If
      the mutex is already locked, the calling thread is suspended until
      the lock is released. When the method returns, the resumed thread
      owns the condition variable lock. It is the thread responsibility to
      reset the condition variable and unlock it.
      </p>
    </method>

    <method>
      <name>mark</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>mark</code> method marks the condition variable and notify
      all pending threads of such change. The mark method is the basic
      notification mechanism.
      </p>
    </method>

    <method>
      <name>wait</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>wait</code> method waits for a condition variable to be
      marked. When such condition occurs, the suspended thread is
      run. When the method returns, the resumed thread owns the condition
      variable lock. It is the thread responsibility to reset the
      condition variable and unlock it.
      </p>
    </method>

    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method acquires the condition variable mutex,
      reset the mark, and unlock it. If the lock has been taken, the
      calling thread is suspended.
      </p>
    </method>

    <method>
      <name>unlock</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>unlock</code> method unlock the condition variable
      mutex. This method should be used after a call to <code>lock</code>
      or <code>wait</code>.
      </p>
    </method>

    <method>
      <name>wait-unlock</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>wait-unlock</code> method wait until a condition variable
      is marked.  When such condition occurs, the suspended thread is
      run. Before the method returns, the condition variable is reset and
      the mutex unlocked. With two threads to synchronize, this is the
      preferred method compared to <code>wait</code>. 
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = lexical object                                                  = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Lexical</name>

    <p>
    The <code>Lexical</code> object is a special object built by the
    <afnix/> reader. A lexical name is also a literal object. Although
    the best way to create a lexical name is with a form, the lexical
    object can also be constructed with a string name. A lexical name
    can be mapped to a symbol by using the <code>map</code> method.
    </p>

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

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

    <!-- constructors -->
    <ctor>
      <name>Lexical</name>
      <args>none</args>
      <p>
      The <code>Lexical</code> constructor create an empty lexical object
      which evaluates to <code>nil</code>.
      </p>
    </ctor>

    <ctor>
      <name>Lexical</name>
      <args>String</args>
      <p>
      The <code>Lexical</code> constructor create a lexical object using
      the string argument as the lexical name.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>map</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>map</code> method returns the object that is mapped by the
      lexical name. Most of the time, a symbol object is returned since it
      is the kind of object stored in a nameset. Eventually the mapping
      might returns an argument object if used inside a closure.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = qualified object                                                = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Qualified</name>

    <p>
    The <code>Qualified</code> object is a special object built by the
    <afnix/> reader. A qualified object is similar to a lexical
    object. It is also a literal object. Like a lexical name, a
    qualified name can be created with a form or by direct construction
    with a name. Like a lexical name, the <code>map</code> method can be
    used to retrieve the symbol associated with that name.
    </p>

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

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

    <!-- constructors -->
    <ctor>
      <name>Qualified</name>
      <args>none</args>
      <p>
      The <code>Qualifed</code> constructor create an empty qualified name
      object which evaluates to <code>nil</code>.
      </p>
    </ctor>

    <ctor>
      <name>Qualified</name>
      <args>String</args>
      <p>
      The <code>Qualified</code> constructor create a qualified name
      object using the string argument as the qualified name. The name is
      parse for qualified name syntax adherence.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>map</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>map</code> method returns the object that is mapped by the
      qualified name. Most of the time, a symbol object is returned since
      it is the kind of object stored in a nameset. Eventually the mapping
      might returns an argument object if used inside a closure.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = symbol object                                                   = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Symbol</name>

    <p>
    The <code>Symbol</code> object is a special object used by nameset
    to map a name with an object. Generally a symbol is obtained by
    mapping a lexical or qualified name. As an object, the symbol holds
    a name, an object and a <em>constant flag</em>. The symbol name
    cannot be changed since it might introduce inconsistencies in the
    containing nameset. On the other hand, the <em>constant flag</em>
    and the object can be changed. A symbol is a literal object. A
    symbol that is not bounded to a nameset can be constructed
    dynamically. Such symbol is said to be <em>not interned</em>.
    </p>

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

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

    <!-- constructors -->
    <ctor>
      <name>Symbol</name>
      <args>String</args>
      <p>
      The <code>Symbol</code> constructor create a symbol by name. The
      associated object is marked as <code>nil</code>.
      </p>
    </ctor>

    <ctor>
      <name>Symbol</name>
      <args>String Object</args>
      <p>
      The <code>Symbol</code> constructor create a symbol by name and bind
      the object argument to the symbol.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get-const</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>get-const</code> method returns the symbol const flag. If
      the flag is true, the symbol object cannot be changed unless that
      flags is reset with the <code>set-const</code> method.
      </p>
    </method>

    <method>
      <name>set-const</name>
      <retn>none</retn>
      <args>Boolean</args>
      <p>
      The <code>set-const</code> method set the symbol const flag. This
      method is useful to mark a symbol as const or to make a const symbol
      mutable.
      </p>
    </method>

    <method>
      <name>get-object</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>get-object</code> method returns the symbol object.
      </p>
    </method>

    <method>
      <name>set-object</name>
      <retn>none</retn>
      <args>Object</args>
      <p>
      The <code>set-object</code> method set the symbol object. The object
      can be obtained by evaluating the symbol.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = closure object                                                  = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Closure</name>

    <p>
    The <code>Closure</code> object is a special object that represents
    a lambda or gamma expression. A closure is represented by a set of
    arguments, a set of closed variables and a form to execute. A
    boolean flag determines the type of closure. The closure predicate
    <code>lambda-p</code> returns true if the closure is a lambda
    expression. Closed variables can be defines and evaluated with the
    use of the qualified name mechanism. Closure mutation is achieved
    with the <code>add-argument</code> and <code>set-form</code>
    method. An empty closure can be defined at construction as well.
    </p>

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

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

    <!-- constructors -->
    <ctor>
      <name>Closure</name>
      <args>none</args>
      <p>
      The <code>Closure</code> constructor create a default closure. When
      the closure is created, a local set of arguments and closed
      variables is generated. Note that such local set is dynamic. There
      is no restriction to reconfigure a particular lambda at
      run-time. The difference between a lambda and a gamma expression
      resides in the nameset binding when the closure is called. With a
      lambda, the closure nameset parent is the calling nameset. With a
      gamma expression, the parent nameset is always the top-level
      interpreter nameset. Note also, that the symbol <code>self</code> is
      automatically bounded for this closure.
      </p>
    </ctor>

    <ctor>
      <name>Closure</name>
      <args>Boolean</args>
      <p>
      The <code>Closure</code> constructor create a closure which acts as
      lambda expression if the boolean argument is true. If the boolean
      argument is false, the closure will behave like a gamma expression.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>gamma-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>gamma-p</code> predicate returns true if the closure is a
      gamma expression. The predicate returns true for a lambda expression.
      </p>
    </method>

    <method>
      <name>lambda-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>lambda-p</code> predicate returns true if the closure is a
      lambda expression. The predicate returns false for a gamma expression.
      </p>
    </method>

    <method>
      <name>get-form</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>get-form</code> method returns the closure form object.
      </p>
    </method>

    <method>
      <name>set-form</name>
      <retn>none</retn>
      <args>Object</args>
      <p>
      The <code>set-form</code> method sets the closure form object.
      </p>
    </method>

    <method>
      <name>add-argument</name>
      <retn>none</retn>
      <args>String|Lexical|form</args>
      <p>
      The <code>add-argument</code> method adds an argument to the
      closure. The argument object can be either a string, a lexical
      object of a simple form that defines a constant lexical name.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = librarian object                                                = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Librarian</name>

    <p>
    The <code>Librarian</code> object is a special object that read or
    write a librarian. Without argument, a librarian is created for
    writing purpose. With one file name argument, the librarian is
    created for reading.
    </p>

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

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

    <!-- constructors -->
    <ctor>
      <name>Librarian</name>
      <args>none</args>
      <p>
      The <code>Librarian</code> constructor creates a librarian for
      writing. Initially, the librarian is empty and files must be added
      with the <code>add</code> method.
      </p>
    </ctor>

    <ctor>
      <name>Librarian</name>
      <args>String</args>
      <p>
      The <code>Librarian</code> constructor creates a librarian for
      reading using the name as the librarian file name.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>add</code> method adds a file into the librarian. The
      librarian must have been opened in write mode.
      </p>
    </method>

    <method>
      <name>write</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>write</code> method writes a librarian to a file those
      name is the argument.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the number of file in the
      librarian. This method work, no matter how the librarian has been
      opened.
      </p>
    </method>

    <method>
      <name>exists-p</name>
      <retn>Boolean</retn>
      <args>String</args>
      <p>
      The <code>exists-p</code> predicate returns true if the file
      argument exists in the librarian.
      </p>
    </method>

    <method>
      <name>extract</name>
      <retn>InputMapped</retn>
      <args>String</args>
      <p>
      The <code>extract</code> method returns an input stream mapped to
      the file name argument.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = resolver object                                                 = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Resolver</name>

    <p>
    The <code>Resolver</code> object is a special object that gives the
    ability to open a file based on a file path resolver. The resolver
    maintains a list of valid path and returns an input stream for a
    file on demand.
    </p>

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

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

    <!-- constructors -->
    <ctor>
      <name>Resolver</name>
      <args>none</args>
      <p>
      The <code>Resolver</code> constructor creates a default
      resolver. Once created, the <code>add</code> method can be used to
      add path to the resolver.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>add</code> method adds a path into the resolver. The path
      can points either to a directory or a librarian.
      </p>
    </method>

    <method>
      <name>lookup</name>
      <retn>Input</retn>
      <args>String</args>
      <p>
      The <code>lookup</code> method resolves the file name argument and
      returns an input stream for that file.
      </p>
    </method>

    <method>
      <name>valid-p</name>
      <retn>Boolean</retn>
      <args>String</args>
      <p>
      The <code>valid-p</code> predicate returns true if the file name
      argument can be resolved. If the file name can be resolved, the
      <code>lookup</code> method can be called to get an input stream.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = print-table object                                              = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>PrintTable</name>

    <p>
    The PrintTable class is a formatting class for tables. The table is
    constructed with the number of columns -- default to 1 -- and
    eventually the number of rows. Once the table is created, element
    are added to the table with the <code>add</code> method. Specific
    table element can be set with the <code>set</code> method. The class
    provide a <code>format</code> method those default is to print the
    table on the interpreter standard output. With an output stream
    argument or a buffer, the table is formatted to these objects. The
    table formatting includes an optional column width, a filling
    character and a filling direction flag. By default, the column width
    is 0. This means that the column width is computed as the maximum
    length of all column elements. If the column width is set with the
    <code>set-column-size</code> method, the string element might be
    truncated to the left or right -- depending on the filling flag --
    to fit the column width. 
    </p>

    <!-- predicate -->
    <pred>print-table-p</pred>

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

    <!-- constructors -->
    <ctor>
      <name>PrintTable</name>
      <args>none</args>
      <p>
      The <code>PrintTable</code> constructor creates a default
      table with one column.
      </p>
    </ctor>

    <ctor>
      <name>PrintTable</name>
      <args>Integer</args>
      <p>
      The <code>PrintTable</code> constructor creates a table with a
      pre-defined number of columns specified in the constructor argument.
      </p>
    </ctor>

    <ctor>
      <name>PrintTable</name>
      <args>Integer Integer</args>
      <p>
      The <code>PrintTable</code> constructor creates a table with a
      pre-defined number of columns and rows specified in the constructor
      arguments. 
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none|Integer</retn>
      <args>none|[Literal...]</args>
      <p>
      The <code>add</code> method serves several purposes. Without
      argument, a new row is added and the row index is returned. The
      row index can be later used with the <code>set</code> method to
      set a particular table element. With one or several literal
      arguments, those length must match the number of columns, a new
      row is created and those arguments added to the table. In that
      later case, the method returns the nil object.
      </p>
    </method>

    <method>
      <name>get</name>
      <retn>String</retn>
      <args>Integer Integer</args>
      <p>
      The <code>get</code> method returns a particular table element by
      row and column. The first argument is the table row index and the
      second is the table column index.
      </p>
    </method>

    <method>
      <name>set</name>
      <retn>none</retn>
      <args>Integer Integer Literal</args>
      <p>
      The <code>set</code> method sets a particular table element by row
      and column. The first argument is the table row index and the second
      is the table column index. The last argument is a literal object
      that is converted to a string prior its insertion.
      </p>
    </method>

    <method>
      <name>dump</name>
      <retn>none|String</retn>
      <args>none|Integer|Output|Buffer</args>
      <p>
      The <code>dump</code> method dumps the table to an output stream
      or a buffer. Without argument, the default interpreter output
      stream is used. With an integer argument, the specified row is
      used and a string is returned. With a buffer or an output
      stream, the whole table is written and nothing is returned.
      </p>
    </method>

    <method>
      <name>format</name>
      <retn>none|String</retn>
      <args>none|Integer|Output|Buffer</args>
      <p>
      The <code>format</code> method writes the formatted table to an
      output stream or a buffer. Without argument, the default interpreter
      output stream is used. With an integer argument, the specified row is
      used and a string is returned. With a buffer or an output
      stream, the whole table is written and nothing is returned.
      </p>
    </method>

    <method>
      <name>get-rows</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-rows</code> method returns the number of rows in the
      table.
      </p>
    </method>

    <method>
      <name>get-columns</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-columns</code> method returns the number of columns in
      the table.
      </p>
    </method>
  
    <method>
      <name>set-column-size</name>
      <retn>none</retn>
      <args>Integer Integer</args>
      <p>
      The <code>set-column-size</code> method sets the desired width for a
      particular column. The first argument is the column index and the
      second argument is the column width.If 0 is given, the column width
      is computed as the maximum of the column elements.
      </p>
    </method>

    <method>
      <name>get-column-size</name>
      <retn>Integer</retn>
      <args>Integer</args>
      <p>
      The <code>get-column-size</code> method returns the desired width
      for a particular column.
      </p>
    </method>

    <method>
      <name>set-column-fill</name>
      <retn>none</retn>
      <args>Integer Character</args>
      <p>
      The <code>set-column-fill</code> method sets the filling character
      for a particular column. The first argument is the column index and
      the second argument is a character to use when filling a particular
      column element. The default filling character is the blank
      character.
      </p>
    </method>

    <method>
      <name>get-column-fill</name>
      <retn>Character</retn>
      <args>Integer</args>
      <p>
      The <code>get-column-fill</code> method returns the filling
      character for a particular column.
      </p>
    </method>

    <method>
      <name>set-column-direction</name>
      <retn>none</retn>
      <args>Integer Boolean</args>
      <p>
      The <code>set-column-direction</code> method sets the direction flag
      for a particular column. The first argument is the column index and
      the second argument is a boolean. A false value indicates a filling
      by the left while a true value indicates a filling by the right. The
      column filling character is used for this operation.
      </p>
    </method>

    <method>
      <name>get-column-direction</name>
      <retn>Boolean</retn>
      <args>Integer</args>
      <p>
      The <code>get-column-direction</code> method returns the direction
      flag for a particular column.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = logger object                                                   = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Logger</name>

    <p>
    The Looger class is a message logger that stores messages in a
    buffer with a level. The default level is the level 0. A negative level
    generally indicates a warning or an error message but this is just
    a convention which is not enforced by the class. A high level generally
    indicates a less important message. The messages are stored in a circular
    buffer. When the logger is full, a new message replace the oldest one.
    By default, the logger is initialized with a 256 messages capacity
    that can be resized.
    </p>

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

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

    <!-- constructors -->
    <ctor>
      <name>Logger</name>
      <args>none</args>
      <p>
      The <code>Logger</code> constructor creates a default logger.
      </p>
    </ctor>

    <ctor>
      <name>Logger</name>
      <args>Integer</args>
      <p>
      The <code>Logger</code> constructor creates a logger with a
      specific size specified as the constructor argument.
      </p>
    </ctor>

    <ctor>
      <name>Logger</name>
      <args>String</args>
      <p>
      The <code>Logger</code> constructor creates a logger with an
      information argument. The information string is later used to
      format the logged messages.
      </p>
    </ctor>

    <ctor>
      <name>Logger</name>
      <args>Integer String</args>
      <p>
      The <code>Logger</code> constructor creates a logger with a
      specific size and an information argument. The first argument is
      the logger size. The second argument is the information
      string. The information string is later used to format the
      logged messages.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>String|String Integer</args>
      <p>
      The <code>add</code> method adds a message in the logger. With
      one argument, the method take a single string message. with two
      arguments, the first arguments is the message and the second
      argument is the message level.
      </p>
    </method>

    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the logger class by 
      removing all messages.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the number of messages
      stored in the logger object.
      </p>
    </method>

    <method>
      <name>resize</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>resize</code> method resize the logger class by
      increasing the size of the message buffer. The old messages are
      kept during the resizing operation.
      </p>
    </method>

    <method>
      <name>set-info</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-info</code> method sets the logger information
      string. The information string is used by the derived classes
      when a message is printed.
      </p>
    </method>

    <method>
      <name>get-info</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-info</code> method returns the logger information
      string. The information string is used by the derived classes
      when a message is printed.
      </p>
    </method>

    <method>
      <name>set-default-level</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-default-level</code> method sets the default level
      use for storing message. This parameter is used with the
      <code>add</code> method in conjunction with the message
      argument. When the message level is specified, the default
      message level is ignored.
      </p>
    </method>

    <method>
      <name>get-default-level</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-default-level</code> method returns the default
      message level used by the logger. The default message level is
      used by the <code>add</code> method when the message level is
      not specified directly.
      </p>
    </method>
  
    <method>
      <name>get-message</name>
      <retn>String</retn>
      <args>Integer</args>
      <p>
      The <code>get-message</code> method returns a logger message by
      index. The integer argument is the message index.
      </p>
    </method>

    <method>
      <name>get-message-time</name>
      <retn>Integer</retn>
      <args>Integer</args>
      <p>
      The <code>get-message-time</code> method returns the logger
      message time by index. The integer argument is the message
      index.
      </p>
    </method>

    <method>
      <name>get-message-level</name>
      <retn>Integer</retn>
      <args>Integer</args>
      <p>
      The <code>get-message-level</code> method returns the logger
      message level by index. The integer argument is the message
      index.
      </p>
    </method>
  </object>
</chapter>
