dom3.h

XMDS is a code generator that integrates equations. You write them down in human readable form in a

/*
  Copyright (C) 2000-2004

  Code contributed by Greg Collecutt, Joseph Hope and Paul Cochrane

  This file is part of xmds.
 
  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.

  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.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*/

/*
  $Id: dom3.h,v 1.11 2004/04/28 00:29:49 paultcochrane Exp $
*/

/*! @file dom3.h
  @brief Provides the abstracted Document Object Model (DOM) level 3 
  interface as specified in the W3C Working Draft as of 05 June 2001.
  
  Most of the documentation of this file is taken directly from the 
  W3C Working Draft of 05 June 2001.
*/

/* This header file provides the abstracted DOM level 3
   interface as specified in the W3C Working Draft as of 05 June 2001.
   (http://www.w3.org/TR/2001/WD-DOM-level-3-core-20010605)
   My (GC) implementation of this is in the files "kissdom.h" and "kissdom.cc".*/

using namespace std;

typedef XMLString DOMString; //!< Defines a DOMString

const DOMString EMPTY_STRING = "";  //!< The empty string
const DOMString XML_PREFIX = "xml"; //!< The xml prefix string
const DOMString XML_NAMESPACEURI = "http://www.w3.org/XML/1998/namespace"; //!< The xml namespace URI
const DOMString XMLNS_PREFIX = "xmlns";  //!< The xmlns prefix, and quite possibly the xml namespace prefix
const DOMString XMLNS_NAMESPACEURI = "http://www.w3.org/2000/xmlns";  //!< The xmlns namespace uri, or the uri of the xml namespace

typedef long DOMTimeStamp;   //!< Defines the DOM time stamp
typedef long DOMKey;         //!< Defines the DOM key

// ******************************************************************************
// ******************************************************************************
//      DOMException
// ******************************************************************************
// ******************************************************************************

//! Structure containing the DOM defined exceptions
struct DOMException {

  //! Enumerator containing the DOM defined exception numbers
  /*! 
    The exception code is an integer indicating the type of error generated
  */
  enum {
    INDEX_SIZE_ERR                  =  1,  //!< If index or size is negative, or greater than the allowed value
    DOMSTRING_SIZE_ERR              =  2,  //!< If the specified range of text does not fit into a DOMString
    HIERARCHY_REQUEST_ERR           =  3,  //!< If any node is inserted somewhere it doesn't belong
    //! If a node is used in a different document than the one that created it (that doesn't support it)
    WRONG_DOCUMENT_ERR              =  4,  
    INVALID_CHARACTER_ERR           =  5,  //!< If an invalid or illegal character is specified, such as in a name
    NO_DATA_ALLOWED_ERR             =  6,  //!< If data is specified for a node which does not support data
    NO_MODIFICATION_ALLOWED_ERR     =  7,  //!< If an attempt is made to modify an object where modifications are not allowed
    NOT_FOUND_ERR                   =  8,  //!< If an attempt is made to reference a node in a context where is does not exist
    NOT_SUPPORTED_ERR               =  9,  //!< If the implementation doesn't support the requested type of object or operation
    INUSE_ATTRIBUTE_ERR             = 10,  //!< If an attempt is made to add an attribute that is already in use elsewhere

    // Introduced in DOM Level 2:
    INVALID_STATE_ERR               = 11,  //!< If an attempt is made to use an object that is not, or is not longer, usable
    SYNTAX_ERR                      = 12,  //!< If an invalid or illegal string is specified
    INVALID_MODIFICATION_ERR        = 13,  //!< If an attempt is made to modify the type of the underlying object
    //! If an attempt is made to create or change an object in a way which is incorrect with regard to namespaces
    NAMESPACE_ERR                   = 14,  
    INVALID_ACCESS_ERR              = 15   //!< If a parameter or an operation is not supported by the underlying object
  };

  //! The exception code for a DOMException
  unsigned long code;

  //! Constructor of DOMException object
  DOMException();

  //! Constructor of DOMException object where error is specified
  /*!
    @param err Error code of exception
  */
  DOMException(
               unsigned long err);

  //! Destructor
  ~DOMException();

  //! Gets an error
  /*!
    Returns the string specifying the type of error that occurred
  */
  const char* getError() const;
};

// ******************************************************************************
// ******************************************************************************
// ******************************************************************************
//      The Core Interfaces
// ******************************************************************************
// ******************************************************************************
// ******************************************************************************

// Document class
class Document;
// DocumentType class
class DocumentType;

// ******************************************************************************
// ******************************************************************************
//      DOMImplementation
// ******************************************************************************
// ******************************************************************************

//! DOMImplementation class
/*!
  The @c DOMImplementation interface provides a number of methods for performing operations
  that are independent of any particular instance of the document object model.
*/
class DOMImplementation {

public :

  //! Tests if the DOM implementation implements a specific feautre
  /*!
    @param feature The name of the feature to test (case-insensitive).  The name must be an XML name
    @param version This is the version number of the feature to test.  In DOM 
    Level 2, the string can be either "2.0" or "1.0"
  */
  virtual bool hasFeature(
                          DOMString& feature,
                          DOMString& version) const = 0;

  // Introduced in DOM Level 2:

  //! Creates an empty DocumentType node
  /*!
    Creates an empty @c DocumentType node.  Entity declarations and notations are not made available
    Entity reference expansions and default atribute additions do not occur.
    @param qualifiedName The qualified name of the document type to be created
    @param publicId The external subset public identifier
    @param systemId The external subset system identifier
  */
  virtual DocumentType* createDocumentType(
                                           const DOMString& qualifiedName,
                                           const DOMString& publicId,
                                           const DOMString& systemId) = 0;

  //! Creates a DOM document object of the specified type with its document element
  /*!
    @param namespaceURI The namespace URI of the document to create
    @param qualifiedName The qualified name of the document element to be created
    @param doctype The type of document to be created or @c null.  When doctype 
    is not @c null, its @c Node.ownerDocument attribute is set to the document being created
  */
  virtual Document* createDocument(
                                   const DOMString& namespaceURI,
                                   const DOMString& qualifiedName,
                                   DocumentType* doctype) = 0;

  // Introduced in DOM Level 3:

  //! Makes available a @c DOMImplementation's specialised interface.
  /*!
    @param feature The name of the feature requested (case-insensitive)
  */
  virtual DOMImplementation* getAs(
                                   DOMString& feature) = 0;
};

// Node class
class Node;

// ******************************************************************************
// ******************************************************************************
//      NodeList
// ******************************************************************************
// ******************************************************************************

//! NodeList class
/*!
  The @c NodeList interface provides the abstraction of an ordered collection of 
  nodes, without defining or constraining how this collection is implemented.
  The items in the @c NodeList are accessible via an integral index, starting from 0.
*/
class NodeList {

public :
  //! Gets an item from the node list at index
  /*!
    Returns the @c index th item in the collection.  If @c index is greater than
    or eaual to the number of nodes in the list, this returns @c null.
    @param index Index into the collection
  */
  virtual Node* item(
                     unsigned long      index) const = 0;

  //! Returns the length of the node list
  /*
    Returns the number of nodes in the list.  The range of valid child node indices 
    is 0 to @c length-1 inclusive.
  */
  virtual unsigned long length() const = 0;
};

// ******************************************************************************
// ******************************************************************************
//      NamedNodeMap
// ******************************************************************************
// ******************************************************************************

//! NamedNodeMap class
/*!
  Objects implementing the @c NamedNodeMap interface are used to represent collections
  of nodes that can be accessed by name.  Note that @c NamedNodeMap does not inherit from
  @c NodeList; @c NamedNodeMaps are not maintained in any particular order.  Objects
  contained in an object implementing @c NamedNodeMap may also be accessed by an ordinal
  index, but this is simply to allow convenient enumeration of the contents of a 
  @c NamedNodeMap, and does not imply that the DOM specifies an order to these Nodes.
*/
class NamedNodeMap {

public :

  //! Gets a named item
  /*!
    Retrieves a node specified by name
    @param name The @c nodeName of a node to retrieve
  */
  virtual Node* getNamedItem(
                             const DOMString& name) const = 0;

  //! Sets a named item
  /*!
    Adds a node using its @c nodeName attribute.  If a node with that name is already
    present in this map, it is replaced by the new one.

    As the @c nodeName attribute is used to derive the name which the node must be stored
    under, multiple nodes of certain types (those that have a "special" string value) 
    cannot be stored as the names would clash.  This is seen as preferable to allowing
    nodes to be aliased.
    @param arg A node to store in this map.  The node will later be accessible using the value
    of its @c nodeName attribute.
  */
  virtual Node* setNamedItem(
                             Node& arg) = 0;

  //! Removes a named item
  /*!
    Removes a node specified by a name.  When this map contains the attributes attached
    to an element, if the removed attribute is known to have a default value, an attribute
    immediately appears containing the default value as well as the corresponding namespace
    URI, local name, and prefix when applicable.
    @param name The @c nodeName of the node to remove.
  */
  virtual Node* removeNamedItem(
                                const DOMString& name) = 0;

  //! Gets the length of the object
  /*!
    Returns the number of nodes in this map.  The range of valid child node indices
    is @c 0 to @c length-1 inclusive.
  */
  virtual unsigned long length() const = 0;

  //! Returns the node item at index
  /*!
    Returns the @c index th item in the map.  If @c index is greater than or equal to
    the number of nodes in this map, this returns @c null.
    @param index Index into this map.
  */
  virtual Node* item(
                     const unsigned long index) const = 0;

  // Introduced in DOM Level 2:

  //! Gets the named item namespace
  /*!
    Retrieves a node spcified by local name and namespace URI.  Documents which do not support the 
    "XML" feature will permit only the DOM Level 1 calls for creating/setting elements and attributes.
    Hence, if you specify a non-null namespace URI, these DOMs will never find a matching node.
    @param namespaceURI The namespace URI of the node to retrieve
    @param localname The local name of the node to retrieve
  */
  virtual Node* getNamedItemNS(
                               const DOMString& namespaceURI,
                               const DOMString& localname) const = 0;

  //! Sets the named item namespace
  /*!
    Adds a node using its @c namespaceURI and @c localname.  If a node with that namespace URI
    and that local name is already present in this map, it is replaced by the new one.
    @param arg A node to store in this map.  The node will later be accessible using the value
    of its @c namespaceURI and @c localname attributes.
  */
  virtual Node* setNamedItemNS(
                               Node& arg) = 0;