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

<!-- ====================================================================== -->
<!-- = appendix-iii.xml                                                   = -->
<!-- = standard xml module guide - appendix iii                           = -->
<!-- ====================================================================== -->
<!-- = 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-2008 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="xml" number="iii">
  <title>Standard xne reference</title>

  <!-- =================================================================== -->
  <!-- = xsm node object                                                 = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XsmNode</name>

    <!-- synopsis -->
    <p>
    The <code>XsmNode</code> is a base class which is part of the xml
    simple model (xsm). In this model, a xml (or sgml, or html) text
    is represented by a node which can be either a tag, a text or a
    reference node. There is no concept of tree. The node content is
    stored in the form of a text string. This simple model is designed
    to parse weak data representation such like html text and later
    process it at the user discretion. The default representation is
    an empty text node.
    </p>

    <!-- predicate -->
    <pred>xsm-node-p</pred>

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

    <!-- constants -->
    <constants>
     <const>
      <name>TXT</name>
      <p>
      The <code>TXT</code> constant defines a xsm text node.
      </p>
     </const>

     <const>
      <name>TAG</name>
      <p>
      The <code>TAG</code> constant defines a xsm tag node.
      </p>
     </const>

     <const>
      <name>REF</name>
      <p>
      The <code>REF</code> constant defines a xsm reference node.
      </p>
     </const>

     <const>
      <name>END</name>
      <p>
      The <code>END</code> constant defines a xsm end node.
      </p>
     </const>
    </constants>

    <!-- constructors -->
    <ctors>
     <ctor>
      <name>XsmNode</name>
      <args>none</args>
      <p>
      The <code>XsmNode</code> constructor creates a default xsm node
      which is an empty text node.
      </p>
     </ctor>

     <ctor>
      <name>XsmNode</name>
      <args>String</args>
      <p>
      The <code>XsmNode</code> constructor creates a xsm text node by value.
      The string argument is the text node value
      </p>
     </ctor>

     <ctor>
      <name>XsmNode</name>
      <args>Item String</args>
      <p>
      The <code>XsmNode</code> constructor creates a xsm text node by
      type and value. The first argument is the node type. The second
      argument is the node text value.
      </p>
     </ctor>
    </ctors>

    <!-- methods -->
    <methods>
     <meth>
      <name>text-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>text-p</code> predicate returns true if the node is a
      text node.
      </p>
     </meth>

     <meth>
      <name>tag-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>tag-p</code> predicate returns true if the node is a
      tag node.
      </p>
     </meth>

     <meth>
      <name>ref-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>reference-p</code> predicate returns true if the node is a
      reference node.
      </p>
     </meth>

     <meth>
      <name>end-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>end-p</code> predicate returns true if the node is a
      reference node.
      </p>
     </meth>

     <meth>
      <name>normal-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>normal-p</code> predicate returns true if the node is a
      normal tag node.
      </p>
     </meth>

     <meth>
      <name>reserved-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>reserved-p</code> predicate returns true if the node is a
      reserved tag node.
      </p>
     </meth>

     <meth>
      <name>textable-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>textable-p</code> predicate returns true if the node is a
      textable node, that is a text node or a reference node.
      </p>
     </meth>

     <meth>
      <name>get-source-line</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-source-line</code> method returns the node source
      line number if any.
      </p>
     </meth>

     <meth>
      <name>set-source-line</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-source-line</code> method sets the node source
      line number.
      </p>
     </meth>

     <meth>
      <name>get-source-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-source-name</code> method returns the node source
      name if any.
      </p>
     </meth>

     <meth>
      <name>set-source-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-source-name</code> method sets the node source
      name.
      </p>
     </meth>

     <meth>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the next available name.
      name.
      </p>
     </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = xsm reader object                                               = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XsmReader</name>

    <!-- synopsis -->
    <p>
    The <code>XmlReader</code> class is the simple model node reader.
    The reader operates with the <code>parse</code> method and returns
    a node or nil if the end of stream is reached. Unlike the xml
    reader, this reader does not build a tree and the node content is
    not even parsed. In this model, the node content is to be
    interpreted at the user discretion.
    </p>

    <!-- predicate -->
    <pred>xsm-reader-p</pred>

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

    <!-- constructors -->
    <ctors>
     <ctor>
      <name>XsmReader</name>
      <args>none</args>
      <p>
      The <code>XsmReader</code> constructor creates a default xsm
      reader. The reader is not bound to any stream.
      </p>
     </ctor>

     <ctor>
      <name>XsmReader</name>
      <args>Input</args>
      <p>
      The <code>XsmReader</code> constructor creates a xsm
      reader with an input stream. The argument is the input bound to
      the reader.
      </p>
     </ctor>

     <ctor>
      <name>XsmReader</name>
      <args>String</args>
      <p>
      The <code>XsmReader</code> constructor creates a xsm
      reader with an input string stream. The argument is a string
      which is used to create an input string stream bound to the reader.
      </p>
     </ctor>
    </ctors>

    <!-- methods -->
    <methods>
     <meth>
      <name>set-input-stream</name>
      <retn>none</retn>
      <args>Input</args>
      <p>
      The <code>set-input-stream</code> method bind a new input stream
      to the reader. Subsequent read will use the newly bound stream
      </p>
     </meth>

     <meth>
      <name>get-node</name>
      <retn>XsmNode</retn>
      <args>none</args>
      <p>
      The <code>get-node</code> method parses the input stream and
      returns the available node.
      </p>
     </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = xsm document object                                             = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xml">
    <name>XsmDocument</name>

    <!-- synopsis -->
    <p>
    The <code>XsmDocument</code> class is the document class that
    maintains a xsm document along with its associated list of nodes
    and other useful information. Generally the class is constructed
    with a file name or a name and an input stream that is used for
    parsing the input data. When the input stream has been parsed, the
    nodes are stored in a vector which can be access by index.
    </p>

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

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

    <!-- constructors -->
    <ctors>
     <ctor>
      <name>XsmDocument</name>
      <args>none</args>
      <p>
      The <code>XsmDocument</code> constructor creates a default xsm
      document.
      </p>
     </ctor>

     <ctor>
      <name>XsmDocument</name>
      <args>String</args>
      <p>
      The <code>XsmDocument</code> constructor creates a xsm document
      by name. The string argument is the file name to parse.
      </p>
     </ctor>

     <ctor>
      <name>XsmDocument</name>
      <args>String Input</args>
      <p>
      The <code>XsmDocument</code> constructor creates a xsm document
      by name and by parsing the input stream. The first argument is
      the xsm document name. The second argument is the input stream
      to parse.
      </p>
     </ctor>
    </ctors>

    <!-- methods -->
    <methods>
     <meth>
      <name>set-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-name</code> method sets the xsm document name. The
      <code>get-name</code> method is available from the
      <code>nameable</code> base class.
      </p>
     </meth>
      
     <meth>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the xsm document
      length. The document length is the number of nodes parsed and
      stored in the document.
      </p>
     </meth>

     <meth>
      <name>get-node</name>
      <retn>XsmNode</retn>
      <args>Integer</args>
      <p>
      The <code>get-node</code> method returns a document node by
      index.
      </p>
     </meth>

     <meth>
      <name>get-info</name>
      <retn>XsoInfo</retn>
      <args>Integer [Boolean]</args>
      <p>
      The <code>get-info</code> method returns a node info object by
      index. The info object is evaluated dynamically from the
      document node. In the first form, the node name is used to find
      the node end tag in order to construct the info text value. In
      the second form, the boolean argument, if true, forces the node
      name to be converted to lower case prior any comparison.
      </p>
     </meth>

     <meth>
      <name>get-info-vector</name>
      <retn>XsoInfo</retn>
      <args>String [Boolean]</args>
      <p>
      The <code>get-info-vetcor</code> method returns an info
      object vectror by name. Each info object have their name that
      matches the string argument. The info object is evaluated
      dynamically from the document node. In the first form, the node
      name is used to match a tag node and then find the node end tag
      in order to construct the info text value. In the second form,
      the boolean argument, if true, forces the node name to be
      converted to lower case prior any comparison.
      </p>
     </meth>
    </methods>
  </object>
</appendix>
