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

<!-- ====================================================================== -->
<!-- = appendix-i.xml                                                     = -->
<!-- = xml processing environment service guide - appendix i              = -->
<!-- ====================================================================== -->
<!-- = 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-2009 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix service="xpe" number="i">
  <title>XML Processing Environment Service Reference</title>

  <p>
  This appendix is a reference of the <afnix/> XML Processing
  Environment (xpe) service.
  </p>

  <table>
   <title>XML Processing Environment</title>
   <tr><th>Symbol</th><th>Description</th></tr>
   <tr><td>afnix-xpe</td><td>module</td></tr>
   <tr><td>afnix:xpe</td><td>nameset</td></tr>
  </table>

  <!-- =================================================================== -->
  <!-- = xml content object                                              = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xpe">
    <name>XmlContent</name>

    <!-- synopsis -->
    <p>
    The <code>XmlContent</code> class is an extension of the xml
    document class that operates at the uri level. If the uri is a
    local file the xml document is created from an input file
    stream. If the uri is an url, the content is fetched
    automatically. The class constructors permit to separate the
    content name from the document name and also to specify the
    content encoding.
    </p>

    <!-- predicate -->
    <pred>xml-content-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>XmlDocument</name>
      <name>Mime</name>
    </inherit>

    <!-- constructors -->
    <ctors>
     <ctor>
      <name>XmlContent</name>
      <args>String</args>
      <p>
      The <code>XmlContent</code> constructor creates a xml document
      by name. The document name is the normalized uri name that
      always favor a file scheme in the absence of it.
      </p>
     </ctor>

     <ctor>
      <name>XmlContent</name>
      <args>String String</args>
      <p>
      The <code>XmlContent</code> constructor creates a xml document
      by name. The first argument is the content name. The second
      argument is the document name which is normalized to form the
      uri name used to load the document.
      </p>
     </ctor>

     <ctor>
      <name>XmlContent</name>
      <args>String String String</args>
      <p>
      The <code>XmlContent</code> constructor creates a xml document
      by name and encoding mode. The first argument is the content
      name. The second argument is the document name which is
      normalized to form the uri name used to load the document. The
      third argument is the content character encoding.
      </p>
     </ctor>
    </ctors>

    <!-- methods -->
    <methods>
     <meth>
      <name>get-document-uri</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-document-uri</code> method returns the document
      normalized uri.
      </p>
     </meth>

     <meth>
      <name>get-document-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-document-name</code> method returns the object
      document name. This method complements the <code>get-name</code>
      method which returns the object name.
      </p>
     </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = xml feature object                                              = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xpe">
    <name>XmlFeature</name>

    <!-- synopsis -->
    <p>
    The <code>XmlFeature</code> class is a xml processor base class
    that defines a processing feature. A processing feature is defined
    by name and information with a processing level. The default
    processing level is null. When the processor is called, it calls
    sequentially and in ascending order all features.     
    </p>

    <!-- predicate -->
    <pred>xhtml-feature-p</pred> 

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

    <!-- methods -->
    <methods>
     <meth>
      <name>get-info</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-info</code> method returns the xml feature
      information string. The feature name is available from the
      <code>get-name</code> provided by the <code>Nameable</code> base
      class.
      </p>
     </meth>

     <meth>
      <name>set-processing-level</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-processing-level</code> method sets the feature
      processing level. The integer argument is the level to set.
      </p>
     </meth>

     <meth>
      <name>get-processing-level</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-processing-level</code> method returns the feature
      processing level.
      </p>
     </meth>

     <meth>
      <name>processing-level-p</name>
      <retn>Boolean</retn>
      <args>Integer</args>
      <p>
      The <code>processing-level-p</code> predicate returns true if
      the integer argument equal the feature processing level.
      </p>
     </meth>

     <meth>
      <name>process</name>
      <retn>XmlContent</retn>
      <args>XmlContent</args>
      <p>
      The <code>process</code> method process the input xml content
      and returns a new xml content. The method is automatically
      called by the xml processor.
      </p>
     </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = xml processor object                                            = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xpe">
    <name>XmlProcessor</name>

    <!-- synopsis -->
    <p>
    The <code>XmlProcessor</code> class is a global class designed to
    operate on a xml content. The xml processor provides several
    features that can be enabled prior the document processor. Once
    the features are defined, the 'process' method can be called and a
    new xml content can be produced.
    </p>

    <!-- predicate -->
    <pred>xml-processor-p</pred>

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

    <!-- constructors -->
    <ctors>
     <ctor>
      <name>XmlProcessor</name>
      <args>none</args>
      <p>
      The <code>XmlProcessor</code> constructor creates a default xml
      processor without any feature.
      </p>
     </ctor>
    </ctors>

    <!-- methods -->
    <methods>
     <meth>
      <name>feature-length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>feature-length</code> method returns the number of
      features defined in the xml processor.
      </p>
     </meth>

     <meth>
      <name>add-feature</name>
      <retn>none</retn>
      <args>XmlFeature</args>
      <p>
      The <code>add-feature</code> method adds a feature object to the
      processor. The feature processing level does not have to be
      sorted prior the insertion. Adding multiple feature creates a
      processor chain.
      </p>
     </meth>

     <meth>
      <name>get-feature</name>
      <retn>XmlFeature</retn>
      <args>Integer</args>
      <p>
      The <code>get-feature</code> method return a processor feature
      by index.
      </p>
     </meth>

     <meth>
      <name>process</name>
      <retn>XmlFeature</retn>
      <args>XmlFeature</args>
      <p>
      The <code>process</code> method create a new xml content by
      calling processing feature chain. The feature chain consists of
      feature object sorted in ascending order. If the processor
      contains only one feature, calling the <code>process</code>
      method is equivalent to call the <code>XmlFeature</code> same
      method.
      </p>
     </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = xml include object                                               = -->
  <!-- =================================================================== -->

  <object nameset="afnix:xpe">
    <name>XmlInclude</name>

    <!-- synopsis -->
    <p>
    The <code>XmlInclude</code> class is a xml processor feature class
    designed to handle the "XInclude" schema that permits to include
    xml document. The feature operates recursively by scanning the
    document for a "xi:include" tag and replacing the content by the
    appropriate tree. The feature operates recursively unless
    specified otherwise.
    </p>

    <!-- predicate -->
    <pred>xml-include-p</pred>

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

    <!-- constructors -->
    <ctors>
     <ctor>
      <name>XmlInclude</name>
      <args>none</args>
      <p>
      The <code>XmlInclude</code> constructor creates a default xml
      include feature. The default feature processing level is 10.
      </p>
     </ctor>

     <ctor>
      <name>XmlInclude</name>
      <args>Integer</args>
      <p>
      The <code>XmlInclude</code> constructor creates a xml
      include feature with a processing level. The integer argument is
      the feature processing level to set.
      </p>
     </ctor>
    </ctors>
  </object>
</appendix>
