NAME

       afnix-us-xpe - xml processing environment service

XML PROCESSING ENVIRONMENT SERVICE

       The  XML  Processing  Environment  service is an original implementation that provides the
       support for processing xml document  that  could  be  accessed  locally  or  remotely.  In
       particular, the processing environment supports the XML include facility.

       XML content
       The  XmlContent class is an extension of the XML document object that provides the service
       for loading a XML document locally or from the Internet. The class operates with  an  uri,
       which permits to selects the appropriate loader from the uri scheme.

       Content creation
       The  XmlContent operates with an uri that permits to select the appropriate loader. If the
       uri scheme is a file scheme, the content is retrieved locally. If the uri scheme is  http,
       the content is retrieved by establishing a http connection over the Internet.

       # create a document from a local file
       const xdoc (
         afnix:xpe:XmlContent "file:///home/afnix/file.xml")

       When  the  uri  scheme is a file, the uri authority is empty (hence the double //) and the
       path indicates the file to parse. The XmlContent object is derived  from  the  XmlDocument
       object which contains the parsed tree with the XmlRoot object.

       # create a document from a http connection
       const xdoc (
         afnix:xpe:XmlContent
         "http://www.afnix.org/index.xht")

       When  the  uri scheme is a http scheme, the document is downloaded by establishing an http
       connection with the uri authority. When the http header is received, the content is parsed
       to  create  a  valid xml document. If the http response header indicates that the page has
       moved and a new location is provided, the object  manages  automatically  to  follow  such
       location.

       Content and document name
       Since  the  XmlContent object is derived from the XmlContent object, the content object is
       defined with a uri name and a document name. Under normal circumstances, the document name
       is  derived  from  the  content  name  by  normalizing  it. The content name is the object
       constructor name, while the document name is the normalized document  name.  The  get-name
       method  returns  the  content name while the get-document-name method returns the document
       name.

       # create a document by name
       const xdoc (afnix:xpe:XmlContent "file" "file.xml")

       In the previous example, a xml content object is created by name with a document name.  It
       is the document name that gets normalized. Therefore in the previous example, the file.xml
       document name is normalized into a file uri. The normalization rule always favor the  file
       scheme. This means that without a scheme, the file scheme is automatically added.

       Content type
       Many  times,  the  content  type cannot be detected from the uri name. Once opened, if the
       content header provides a clue about  the  content  type,  the  opened  input  stream  get
       adjusted automatically to reflect this fact. However, this situation does not occurs often
       and with http scheme, the content  type  header  response  does  not  often  provides  the
       character encoding associated with the stream. For this reason, the XmlContent constructor
       provides a mechanism to accept the encoding mode.

       # create a new content by name and encoding mode
       const xdoc (
         afnix:xpe:XmlContent "file" "file.xml" "UTF-8")

XML PROCESSING ENVIRONMENT SERVICE REFERENCE

       XmlContent
       The XmlContent 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.

       Predicate

              xml-content-p

       Inheritance

              XmlDocumentMime

       Constructors

              XmlContent (String)
              The XmlContent 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.

              XmlContent (String String)
              The  XmlContent  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.

              XmlContent (String String String)
              The  XmlContent  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.

       Methods

              get-document-uri -> String (none)
              The get-document-uri method returns the document normalized uri.

              get-document-name -> String (none)
              The  get-document-name  method  returns  the  object  document  name.  This  method
              complements the get-name method which returns the object name.

       XmlFeature
       The  XmlFeature  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.

       Predicate

              xhtml-feature-p

       Inheritance

              Nameable

       Methods

              get-info -> String (none)
              The get-info method returns the xml feature information string. The feature name is
              available from the get-name provided by the Nameable base class.

              set-processing-level -> none (Integer)
              The  set-processing-level  method  sets  the  feature processing level. The integer
              argument is the level to set.

              get-processing-level -> Integer (none)
              The get-processing-level method returns the feature processing level.

              processing-level-p -> Boolean (Integer)
              The processing-level-p predicate returns true if the  integer  argument  equal  the
              feature processing level.

              process -> XmlContent (XmlContent)
              The process method process the input xml content and returns a new xml content. The
              method is automatically called by the xml processor.

       XmlProcessor
       The XmlProcessor 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.

       Predicate

              xml-processor-p

       Inheritance

              Object

       Constructors

              XmlProcessor (none)
              The XmlProcessor constructor creates a default xml processor without any feature.

       Methods

              feature-length -> Integer (none)
              The  feature-length  method  returns  the  number  of  features  defined in the xml
              processor.

              add-feature -> none (XmlFeature)
              The add-feature 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.

              get-feature -> XmlFeature (Integer)
              The get-feature method return a processor feature by index.

              process -> XmlFeature (XmlFeature)
              The process 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 process method  is  equivalent  to
              call the XmlFeature same method.

       XmlInclude
       The  XmlInclude  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.

       Predicate

              xml-include-p

       Inheritance

              XmlFeature

       Constructors

              XmlInclude (none)
              The XmlInclude constructor creates a  default  xml  include  feature.  The  default
              feature processing level is 10.

              XmlInclude (Integer)
              The  XmlInclude  constructor creates a xml include feature with a processing level.
              The integer argument is the feature processing level to set.