1
0
mirror of https://github.com/pocoproject/poco.git synced 2024-12-27 03:28:49 +01:00
poco/XML/include/Poco/DOM/TreeWalker.h
Roger Meier b0581433a7 LICENSE: add info about SPDX-License-Identifier usage and use it
fix: remove executable flag and change back to 100644 (was 100755)

Signed-off-by: Roger Meier <r.meier@siemens.com>
2014-05-14 08:38:09 +02:00

214 lines
7.1 KiB
C++

//
// TreeWalker.h
//
// $Id: //poco/1.4/XML/include/Poco/DOM/TreeWalker.h#1 $
//
// Library: XML
// Package: DOM
// Module: TreeWalker
//
// Definition of the DOM TreeWalker class.
//
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// SPDX-License-Identifier: BSL-1.0
//
#ifndef DOM_TreeWalker_INCLUDED
#define DOM_TreeWalker_INCLUDED
#include "Poco/XML/XML.h"
#include "Poco/XML/XMLString.h"
namespace Poco {
namespace XML {
class Node;
class NodeFilter;
class XML_API TreeWalker
/// 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.
///
/// A TreeWalker can be directly instantiated using one of its constructors -
/// the DocumentTraversal interface is not needed and therefore not implemented.
/// Unlike most other DOM classes, TreeWalker supports value semantics.
///
/// If the TreeWalker's current node is removed from the document, the
/// result of calling any of the movement methods is undefined. This behavior
/// does not conform to the DOM Level 2 Traversal specification.
{
public:
TreeWalker(Node* root, unsigned long whatToShow, NodeFilter* pFilter = 0);
/// Creates a TreeWalker over the subtree rooted at the specified node.
TreeWalker(const TreeWalker& walker);
/// Creates a TreeWalker by copying another TreeWalker.
TreeWalker& operator = (const TreeWalker& walker);
/// Assignment operator.
~TreeWalker();
/// Destroys the TreeWalker.
Node* root() const;
/// The root node of the TreeWalker, as specified when it was created.
unsigned long whatToShow() const;
/// 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.
NodeFilter* filter() const;
/// The NodeFilter used to screen nodes.
bool expandEntityReferences() const;
/// 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.
///
/// This implementation does not support entity reference expansion and
/// thus always returns false.
Node* currentNode() const;
/// 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.
Node* getCurrentNode() const;
/// See currentNode().
void setCurrentNode(Node* pNode);
/// Sets the current node.
Node* parentNode();
/// 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.
Node* firstChild();
/// 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.
Node* lastChild();
/// 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.
Node* previousSibling();
/// 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.
Node* nextSibling();
/// 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.
Node* previousNode();
/// 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.
Node* nextNode();
/// 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.
protected:
int accept(Node* pNode) const;
Node* next(Node* pNode) const;
Node* previous(Node* pNode) const;
private:
TreeWalker();
Node* _pRoot;
unsigned long _whatToShow;
NodeFilter* _pFilter;
Node* _pCurrent;
};
//
// inlines
//
inline Node* TreeWalker::root() const
{
return _pRoot;
}
inline unsigned long TreeWalker::whatToShow() const
{
return _whatToShow;
}
inline NodeFilter* TreeWalker::filter() const
{
return _pFilter;
}
inline bool TreeWalker::expandEntityReferences() const
{
return false;
}
inline Node* TreeWalker::currentNode() const
{
return _pCurrent;
}
inline Node* TreeWalker::getCurrentNode() const
{
return _pCurrent;
}
} } // namespace Poco::XML
#endif // DOM_TreeWalker_INCLUDED