dom3.h

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

    Level 1 method, such as @c createElement from the @c Document interface, this is always @c null.
  */
  virtual const DOMString* namespaceURI() const = 0;

  //! Returns the prefix as a DOMString
  /*!
    Returns the namespace prefix of this node, of @c null if it is unspecified.

    Note that setting this attribute, when permitted, changes the @c nodeName attribute, which holds
    the qualified name, as well as the @c tagName and @c name attributes of the @c Element and @c Attr 
    interfaces when applicable.

    Note also that changing the prefix of an attribute that is known to have a default value, does not
    make a new attribute with the default value and the original prefix appear, since the @c namespaceURI
    and @c localName do not change.

    For nodes of any type other than @c ELEMENT_NODE and @c ATTRIBUTE_NODE and nodes created with a DOM
    Level 1 method, such as @c createElement from the @c Document interface, this is always @c null.    
  */
  virtual const DOMString* prefix() const = 0;

  //! Sets the prefix
  /*!
    Sets the namespace prefix to the specified @c DOMString.
    @param newPrefix The prefix to set
  */
  virtual void setPrefix(
                         const DOMString& newPrefix) = 0;

  //! Returns the local name as a DOMString
  /*!
    Returns the local part of the qualified name of this node.  

    For nodes of any type other than @c ELEMENT_NODE and @c ATTRIBUTE_NODE and nodes created with a DOM
    Level 1 method, such as @c createElement from the @c Document interface, this is always @c null.
  */
  virtual const DOMString* localName() const = 0;

  // Introduced in DOM Level 3:

  //! Determines if object has attributes
  /*!
    Returns whether this node (if it is an element) has any attributes.
  */
  virtual bool hasAttributes() const = 0;

  //! Returns the base URI as a DOMString
  /*!
    Returns the absolute base URI of this node.  This value is computed according to XML Base.
  */
  virtual const DOMString* baseURI() const = 0;

  //! An enumeration of the different orders the node can be in
  /*!
    The @c DocumentOrder is a type to hold the document order of a node relative to another node.
  */
  enum DocumentOrder {
    DOCUMENT_ORDER_PRECEDING, //!< The node precedes the reference node in document order
    DOCUMENT_ORDER_FOLLOWING, //!< The node follows the reference node in document order
    DOCUMENT_ORDER_SAME,      //!< The two nodes have the same document order
    DOCUMENT_ORDER_UNORDERED  //!< The two nodes are unordered, they do not have any common ancestor
  };

  //! Compares the document order with another node
  /*!
    Compares a node with this node with regard to document order.
    @param other The node to compare against this node
  */
  virtual DocumentOrder compareDocumentOrder(
                                             const Node* other) const = 0;

  //! An enumeration of the different orders the node can be in
  /*!
    The @c TreePosition is a type to hold the relative tree position of a node with respect to another node.
  */
  enum TreePosition {
    TREE_POSITION_PRECEDING,  //!< The node precedes the reference node
    TREE_POSITION_FOLLOWING,  //!< The node follows the reference node
    TREE_POSITION_ANCESTOR,   //!< The node is an ancestor of the reference node
    TREE_POSITION_DESCENDANT, //!< The node is a descendant of the reference node
    TREE_POSITION_SAME,       //!< The two nodes have the same position
    TREE_POSITION_UNORDERED   //!< The two nodes are unordered, they do not have any common ancestor
  };

  //! Compares the tree position with another node
  /*!
    Compares a node with this node with regard to their position in the tree.
    @param other The node to compare against this node
  */
  virtual TreePosition compareTreePosition(
                                           const Node* other) const = 0;

  //! Returns the text content
  /*!
    Returns the text content of this node and its descendants.  When set, any possible children this node
    may have are removed and replaced by a single @c Text node containing the string this attribute is set to.
    On getting, no serialisation is performed, the returned string does not contain any markup.  Similarly,
    on setting, no parsing is performed either, the input string is taken as pure textual content.

    The string returned is made of the text content of this node depending on its type, as defined below
    <table>
    <tr>
    <th>Node type</th> <th>Content</th>
    </tr>
    <tr>
    <td>ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_NODE, DOCUMENT_FRAGMENT_NODE</td>
    <td>concatenation of the @c textContent attribute value of every child node, excluding COMMENT_NODE and 
    PROCESSING_INSTRUCTION_NODE nodes</td>
    </tr>
    <tr>
    <td>ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE</td>
    <td>@c nodeValue</td>
    </tr>
    <tr>
    <td>DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
    <td>empty string</td>
    </tr>
    </table>
  */
  virtual const DOMString* textContent(
                                       const bool& deep) const = 0;

  //! Sets the text content
  /*!
    Sets the text content to the @c DOMString specified.
    @param newTextContent The text content to be set for the node
  */
  virtual void setTextContent(
                              const DOMString& newTextContent) = 0;

  //! Determines if the current node is the same as other node
  /*!
    Returns whether this node is the same node as the given one.
    @param other The node to test against
  */
  virtual bool isSameNode(
                          const Node* other) const = 0;

  //! Looks up the namespace prefix
  /*!
    Look up the prefix associated to the given namespace URI, starting from this node.
    @param namespaceURI The namespace URI to look for
  */
  virtual const DOMString* lookupNamespacePrefix(
                                                 const DOMString& namespaceURI) const = 0;

  //! Looks up the namespace URI
  /*!
    Look up the namespace URI associcated to the given prefix, starting from this node.
    @param prefix The prefix to look for
  */
  virtual const DOMString* lookupNamespaceURI(
                                              const DOMString& prefix) const = 0;

  //! Adds namespace declarations so that every namespace is properly declared
  /*!
    This method walks down the tree, starting from this node, and adds namespace declarations
    where needed so that every namespace being used is properly declared.  It also changes
    or assigns prefixes when needed.  This effectively makes this node subtree is "namespace wellformed".
  */
  virtual void normalizeNS() = 0;

  //! Returns the key
  /*!
    Ths returns a key identifying this node.  This key is unique within the document this node was
    creted from and is valid for the lifetime of that document.
  */
  virtual DOMKey key() const = 0;

  //! Determines if node equals argument node
  /*!
    Tests whether two nodes are equal.

    This method tests for equality of nodes, not sameness (i.e., whether the two nodes are exactly
    the same object) which can be tested with @c Node.isSameNode.  All objects that are the same will also
    be equal, though the reverse may not be true.
    
    @param arg The node to compare equality with
    @param deep If @c true, recursively compare the subtrees; if @c false, compare only the nodes themselves,
    (and its attributes, if it is an @c Element)
  */
  virtual bool equalsNode(
                          const Node* arg,
                          bool deep) const = 0;

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

  //! Determines if node is read only
  /*!
    Returns @c true if the node is read only.  Not specified in the DOM Level 3.
  */
  virtual bool readOnly() const = 0;

  //! Sets node read only
  /*!
    Sets the node read only attribute.  Not specified in the DOM Level 3.
    @param newReadOnly Boolean specifying @c true for read only, @c false otherwise
    @param deep If @c true, then sets the attribute recursively for the subtrees, if @c false, then
    only sets the attribute for the current node
  */
  virtual void setReadOnly(
                           const bool& newReadOnly,
                           const bool& deep) = 0;
};

class Element;
class Attr;
class DocumentFragment;
class Text;
class Comment;
class CDATASection;
class ProcessingInstruction;
class EntityReference;

// ******************************************************************************
// ******************************************************************************
//      Document
// ******************************************************************************
// ******************************************************************************

//! Document class
/*!
  The Document interface represents the entire XML document.  Conceptually it is the
  root of the document tree, and provides the primary access to the document's data.
*/
class Document : public virtual Node {

public :
        
  //! Returns the @c DOMKey
  /*!
    A method which returns the @c DOMKey.  This is a utility method defined by 
    Greg Collecutt, and is not part of the W3C DOM specification.
  */
  virtual DOMKey getDOMKey() const = 0; // Mine!

  //! Returns the document type
  /*!
    Returns the Document Type Declaration (DTD) associated with this document.  Returns
    @c null if the document is without a document type.
  */
  virtual const DocumentType* doctype() const = 0;

  //! Returns the DOM implementation
  /*!
    Returns the @c DOMImplementation object that handles this document.  A DOM application
    may use objects from multiple implementations.
  */
  virtual const DOMImplementation* implementation() const = 0;

  //! Returns the document element
  /*!
    This is a convenience attribute that allows direct access to the child node that is 
    the root element of the document.
  */
  virtual Element* documentElement() const = 0;

  //! Creates an element of tagName
  /*!
    Creates an element of the type specified.  Note that the instance returned implements
    the @c Element interface, so attributes can be specified directly on the returned object.
    In addition, if there are known attributes with default values, @c Attr nodes representing
    them are automatically created and attached to the element.  To create an element with
    a qualified name and namespace URI, use the @c createElementNS method.
    @param tagName The name of the element to instantiate.  For XML this is case-sensitive.
  */
  virtual Element* createElement(
                                 const DOMString& tagName) = 0;

  //! Creates a document fragment
  /*!
    Creates an empty document fragment object
  */
  virtual DocumentFragment* createDocumentFragment() = 0;

  //! Creates a text node
  /*!
    Creates a @c Text node given the specified string
    @param data The data for the node.
  */
  virtual Text* createTextNode(
                               const DOMString& data) = 0;

  //! Creates a comment
  /*!
    Creates a @c Comment node given the specified string.
    @param data The data for the node.
  */
  virtual Comment* createComment(
                                 const DOMString& data) = 0;

  //! Creates a CDATA section
  /*!
    Creates a @c CDATASection node whose value is the specified string.
    @param data The data for the @c CDATASection
  */
  virtual CDATASection* createCDATASection(
                                           const DOMString& data) = 0;

  //! Creates a processing instruction
  /*!
    Creates a @c ProcessingInstruction node given the specified name and data strings.
    @param target The target part of the processing instruction
    @param data The data for the node
  */
  virtual ProcessingInstruction* createProcessingInstruction(
                                                             const DOMString& target,