<?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-2011 - 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>InputStream</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>InputStream</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 InputStream</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 vector 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>
