![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/src/dom/traversal.h b/src/dom/traversal.h
--- a/src/dom/traversal.h
+++ b/src/dom/traversal.h
* Authors:
* Bob Jamison
*
- * Copyright (C) 2005 Bob Jamison
+ * Copyright (C) 2005-2008 Bob Jamison
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ *
+ * ==========================================================================
+ * NOTES
+ *
+ * This interface is described here:
+ * http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113
*/
/*#########################################################################
## NodeFilter
#########################################################################*/
+
/**
- *
+ * Filters are objects that know how to "filter out" nodes. If a NodeIterator or
+ * TreeWalker is given a NodeFilter, it applies the filter before it returns the
+ * next node. If the filter says to accept the node, the traversal logic returns
+ * it; otherwise, traversal looks for the next node and pretends that the node
+ * that was rejected was not there.
+ *
+ * The DOM does not provide any filters. NodeFilter is just an interface that
+ * users can implement to provide their own filters.
+ *
+ * NodeFilters do not need to know how to traverse from node to node, nor do they
+ * need to know anything about the data structure that is being traversed. This
+ * makes it very easy to write filters, since the only thing they have to know
+ * how to do is evaluate a single node. One filter may be used with a number of
+ * different kinds of traversals, encouraging code reuse.
+ *
+ * Note:
+ * The spec is slightly vague on this interface, for instance, setting the
+ * whatToShow value.
*/
class NodeFilter
{
public:
- // Constants returned by acceptNode
+ /**
+ * The following constants are returned by the acceptNode() method
+ */
typedef enum
{
FILTER_ACCEPT = 1,
FILTER_REJECT = 2,
FILTER_SKIP = 3
- } AcceptNodeReturn;
+ } AcceptNodeType;
+ /**
+ * Test whether a specified node is visible in the logical view of a TreeWalker
+ * or NodeIterator. This function will be called by the implementation of
+ * TreeWalker and NodeIterator; it is not normally called directly from user
+ * code. (Though you could do so if you wanted to use the same filter to guide
+ * your own application logic.)
+ */
+ virtual short acceptNode(const NodePtr /*n*/)
+ {
+ return 0;
+ }
- // Constants for whatToShow
+ /**
+ * These are the available values for the whatToShow parameter used in
+ * TreeWalkers and NodeIterators. They are the same as the set of possible types
+ * for Node, and their values are derived by using a bit position corresponding
+ * to the value of nodeType for the equivalent node type. If a bit in whatToShow
+ * is set false, that will be taken as a request to skip over this type of node;
+ * the behavior in that case is similar to that of FILTER_SKIP.
+ *
+ * Note that if node types greater than 32 are ever introduced, they may not be
+ * individually testable via whatToShow. If that need should arise, it can be
+ * handled by selecting SHOW_ALL together with an appropriate NodeFilter.
+ */
typedef enum
{
SHOW_ALL = 0xFFFFFFFF,
SHOW_DOCUMENT_TYPE = 0x00000200,
SHOW_DOCUMENT_FRAGMENT = 0x00000400,
SHOW_NOTATION = 0x00000800
- } WhatToShowReturn;
+ } WhatToShowType;
- /**
- *
- */
- virtual short acceptNode(const Node *n)
- {
- return 0;
- }
/**
*
*/
- NodeFilter()
+ NodeFilter() : whatToShow(SHOW_ALL)
{}
+ /**
+ *
+ */
+ NodeFilter(int whatToShowArg) : whatToShow(whatToShowArg)
+ {}
+
+
/**
*
*/
NodeFilter(const NodeFilter &other)
{
+ whatToShow = other.whatToShow;
+ }
+
+ /**
+ *
+ */
+ NodeFilter& operator=(const NodeFilter &other)
+ {
+ whatToShow = other.whatToShow;
+ return *this;
}
/**
virtual ~NodeFilter() {}
+ int whatToShow;
+
};
+
+
/*#########################################################################
## NodeIterator
#########################################################################*/
+
/**
- *
+ * Iterators are used to step through a set of nodes, e.g. the set of nodes in a
+ * NodeList, the document subtree governed by a particular Node, the results of a
+ * query, or any other set of nodes. The set of nodes to be iterated is
+ * determined by the implementation of the NodeIterator. DOM Level 2 specifies a
+ * single NodeIterator implementation for document-order traversal of a document
+ * subtree. Instances of these iterators are created by calling
+ * DocumentTraversal .createNodeIterator().
*/
class NodeIterator
{
public:
/**
- *
+ * The root node of the NodeIterator, as specified when it was created.
*/
- virtual Node *getRoot()
+ virtual NodePtr getRoot()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * This attribute determines which node types are presented via the iterator. The
+ * available set of constants is defined in the NodeFilter interface. Nodes not
+ * accepted by whatToShow will be skipped, but their children may still be
+ * considered. Note that this skip takes precedence over the filter, if any.
*/
virtual unsigned long getWhatToShow()
{ return whatToShow; }
/**
- *
+ * The NodeFilter used to screen nodes.
*/
virtual NodeFilter getFilter()
{ return filter; }
/**
- *
+ * The value of this flag determines whether the children of entity reference
+ * nodes are visible to the iterator. If false, they and their descendants will
+ * be rejected. Note that this rejection takes precedence over whatToShow and the
+ * filter. Also note that this is currently the only situation where
+ * NodeIterators may reject a complete subtree rather than skipping individual
+ * nodes.
+ *
+ * To produce a view of the document that has entity references expanded and does
+ * not expose the entity reference node itself, use the whatToShow flags to hide
+ * the entity reference node and set expandEntityReferences to true when creating
+ * the iterator. To produce a view of the document that has entity reference
+ * nodes but no entity expansion, use the whatToShow flags to show the entity
+ * reference node and set expandEntityReferences to false.
*/
virtual bool getExpandEntityReferences()
{ return expandEntityReferences; }
/**
- *
+ * Returns the next node in the set and advances the position of the iterator in
+ * the set. After a NodeIterator is created, the first call to nextNode() returns
+ * the first node in the set.
*/
- virtual Node *nextNode() throw(dom::DOMException)
+ virtual NodePtr nextNode() throw(dom::DOMException)
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * Returns the previous node in the set and moves the position of the
+ * NodeIterator backwards in the set.
*/
- virtual Node *previousNode() throw(dom::DOMException)
+ virtual NodePtr previousNode() throw(dom::DOMException)
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * Detaches the NodeIterator from the set which it iterated over, releasing any
+ * computational resources and placing the iterator in the INVALID state. After
+ * detach has been invoked, calls to nextNode or previousNode will raise the
+ * exception INVALID_STATE_ERR.
*/
virtual void detach()
{
}
+
//##################
//# Non-API methods
//##################
protected:
unsigned long whatToShow;
- NodeFilter filter;
- bool expandEntityReferences;
+ NodeFilter filter;
+ bool expandEntityReferences;
};
#########################################################################*/
/**
- *
+ * TreeWalker objects are used to navigate a document tree or subtree using the
+ * view of the document defined by their whatToShow flags and filter (if any).
+ * Any function which performs navigation using a TreeWalker will automatically
+ * support any view defined by a TreeWalker.
+ *
+ * Omitting nodes from the logical view of a subtree can result in a structure
+ * that is substantially different from the same subtree in the complete,
+ * unfiltered document. Nodes that are siblings in the TreeWalker view may be
+ * children of different, widely separated nodes in the original view. For
+ * instance, consider a NodeFilter that skips all nodes except for Text nodes and
+ * the root node of a document. In the logical view that results, all text nodes
+ * will be siblings and appear as direct children of the root node, no matter how
+ * deeply nested the structure of the original document.
*/
class TreeWalker
{
/**
- *
+ * The root node of the TreeWalker, as specified when it was created.
*/
- virtual Node *getRoot()
+ virtual NodePtr getRoot()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * This attribute determines which node types are presented via the TreeWalker.
+ * The available set of constants is defined in the NodeFilter interface. Nodes
+ * not accepted by whatToShow will be skipped, but their children may still be
+ * considered. Note that this skip takes precedence over the filter, if any.
*/
virtual unsigned long getWhatToShow()
{ return whatToShow; }
/**
- *
+ * The filter used to screen nodes.
*/
virtual NodeFilter getFilter()
{ return filter; }
/**
- *
+ * The value of this flag determines whether the children of entity reference
+ * nodes are visible to the TreeWalker. If false, they and their descendants will
+ * be rejected. Note that this rejection takes precedence over whatToShow and the
+ * filter, if any. To produce a view of the document that has entity references
+ * expanded and does not expose the entity reference node itself, use the
+ * whatToShow flags to hide the entity reference node and set
+ * expandEntityReferences to true when creating the TreeWalker. To produce a view
+ * of the document that has entity reference nodes but no entity expansion, use
+ * the whatToShow flags to show the entity reference node and set
+ * expandEntityReferences to false.
*/
virtual bool getExpandEntityReferences()
{ return expandEntityReferences; }
/**
- *
+ * The node at which the TreeWalker is currently positioned. Alterations to the
+ * DOM tree may cause the current node to no longer be accepted by the
+ * TreeWalker's associated filter. currentNode may also be explicitly set to any
+ * node, whether or not it is within the subtree specified by the root node or
+ * would be accepted by the filter and whatToShow flags. Further traversal occurs
+ * relative to currentNode even if it is not part of the current view, by
+ * applying the filters in the requested direction; if no traversal is possible,
+ * currentNode is not changed.
*/
- virtual Node *getCurrentNode()
+ virtual NodePtr getCurrentNode()
{ return currentNode; }
/**
- *
+ * Sets the value above.
*/
- virtual void setCurrentNode(const Node *val) throw(dom::DOMException)
- { currentNode = (Node *)val; }
+ virtual void setCurrentNode(const NodePtr val) throw(dom::DOMException)
+ { currentNode = val; }
/**
- *
+ * Moves to and returns the closest visible ancestor node of the current node. If
+ * the search for parentNode attempts to step upward from the TreeWalker's root
+ * node, or if it fails to find a visible ancestor node, this method retains the
+ * current position and returns null.
*/
- virtual Node *parentNode()
+ virtual NodePtr parentNode()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * Moves the TreeWalker to the first visible child of the current node, and
+ * returns the new node. If the current node has no visible children, returns
+ * null, and retains the current node.
*/
- virtual Node *firstChild()
+ virtual NodePtr firstChild()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * Moves the TreeWalker to the last visible child of the current node, and
+ * returns the new node. If the current node has no visible children, returns
+ * null, and retains the current node.
*/
- virtual Node *lastChild()
+ virtual NodePtr lastChild()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * Moves the TreeWalker to the previous sibling of the current node, and returns
+ * the new node. If the current node has no visible previous sibling, returns
+ * null, and retains the current node.
*/
- virtual Node *previousSibling()
+ virtual NodePtr previousSibling()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * Moves the TreeWalker to the next sibling of the current node, and returns the
+ * new node. If the current node has no visible next sibling, returns null, and
+ * retains the current node.
*/
- virtual Node *nextSibling()
+ virtual NodePtr nextSibling()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * Moves the TreeWalker to the previous visible node in document order relative
+ * to the current node, and returns the new node. If the current node has no
+ * previous node, or if the search for previousNode attempts to step upward from
+ * the TreeWalker's root node, returns null, and retains the current node.
*/
- virtual Node *previousNode()
+ virtual NodePtr previousNode()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
/**
- *
+ * Moves the TreeWalker to the next visible node in document order relative to
+ * the current node, and returns the new node. If the current node has no next
+ * node, or if the search for nextNode attempts to step upward from the
+ * TreeWalker's root node, returns null, and retains the current node.
*/
- virtual Node *nextNode()
+ virtual NodePtr nextNode()
{
- return NULL;
+ NodePtr ptr;
+ return ptr;
}
protected:
unsigned long whatToShow;
- NodeFilter filter;
- bool expandEntityReferences;
- Node *currentNode;
+ NodeFilter filter;
+ bool expandEntityReferences;
+ NodePtr currentNode;
};
#########################################################################*/
/**
- *
+ * DocumentTraversal contains methods that create iterators and tree-walkers to
+ * traverse a node and its children in document order (depth first, pre-order
+ * traversal, which is equivalent to the order in which the start tags occur in
+ * the text representation of the document). In DOMs which support the Traversal
+ * feature, DocumentTraversal will be implemented by the same objects that
+ * implement the Document interface.
*/
class DocumentTraversal
{
public:
/**
- *
+ * Create a new NodeIterator over the subtree rooted at the specified node.
*/
- virtual NodeIterator createNodeIterator(const Node *root,
- unsigned long whatToShow,
- const NodeFilter *filter,
- bool entityReferenceExpansion)
- throw (dom::DOMException)
+ virtual NodeIterator createNodeIterator(const NodePtr /*root*/,
+ unsigned long /*whatToShow*/,
+ const NodeFilter/*filter*/,
+ bool /*entityReferenceExpansion*/)
+ throw (dom::DOMException)
{
NodeIterator ret;
return ret;
}
/**
- *
+ * Create a new TreeWalker over the subtree rooted at the specified node.
*/
- virtual TreeWalker createTreeWalker(const Node *root,
- unsigned long whatToShow,
- const NodeFilter *filter,
- bool entityReferenceExpansion)
+ virtual TreeWalker createTreeWalker(const NodePtr/*root*/,
+ unsigned long /*whatToShow*/,
+ const NodeFilter/*filter*/,
+ bool /*entityReferenceExpansion*/)
throw (dom::DOMException)
{
TreeWalker ret;
/**
*
*/
- DocumentTraversal(const DocumentTraversal &other)
+ DocumentTraversal(const DocumentTraversal &/*other*/)
{}
/**