1//
2// TreeWalker.h
3//
4// Library: XML
5// Package: DOM
6// Module: TreeWalker
7//
8// Definition of the DOM TreeWalker class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef DOM_TreeWalker_INCLUDED
18#define DOM_TreeWalker_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/XML/XMLString.h"
23
24
25namespace Poco {
26namespace XML {
27
28
29class Node;
30class NodeFilter;
31
32
33class XML_API TreeWalker
34 /// TreeWalker objects are used to navigate a document tree or subtree using
35 /// the view of the document defined by their whatToShow flags and filter (if
36 /// any). Any function which performs navigation using a TreeWalker will automatically
37 /// support any view defined by a TreeWalker.
38 ///
39 /// Omitting nodes from the logical view of a subtree can result in a structure
40 /// that is substantially different from the same subtree in the complete, unfiltered
41 /// document. Nodes that are siblings in the TreeWalker view may be children
42 /// of different, widely separated nodes in the original view. For instance,
43 /// consider a NodeFilter that skips all nodes except for Text nodes and the
44 /// root node of a document. In the logical view that results, all text nodes
45 /// will be siblings and appear as direct children of the root node, no matter
46 /// how deeply nested the structure of the original document.
47 ///
48 /// A TreeWalker can be directly instantiated using one of its constructors -
49 /// the DocumentTraversal interface is not needed and therefore not implemented.
50 /// Unlike most other DOM classes, TreeWalker supports value semantics.
51 ///
52 /// If the TreeWalker's current node is removed from the document, the
53 /// result of calling any of the movement methods is undefined. This behavior
54 /// does not conform to the DOM Level 2 Traversal specification.
55{
56public:
57 TreeWalker(Node* root, unsigned long whatToShow, NodeFilter* pFilter = 0);
58 /// Creates a TreeWalker over the subtree rooted at the specified node.
59
60 TreeWalker(const TreeWalker& walker);
61 /// Creates a TreeWalker by copying another TreeWalker.
62
63 TreeWalker& operator = (const TreeWalker& walker);
64 /// Assignment operator.
65
66 ~TreeWalker();
67 /// Destroys the TreeWalker.
68
69 Node* root() const;
70 /// The root node of the TreeWalker, as specified when it was created.
71
72 unsigned long whatToShow() const;
73 /// This attribute determines which node types are presented via the TreeWalker.
74 /// The available set of constants is defined in the NodeFilter interface. Nodes
75 /// not accepted by whatToShow will be skipped, but their children may still
76 /// be considered. Note that this skip takes precedence over the filter, if
77 /// any.
78
79 NodeFilter* filter() const;
80 /// The NodeFilter used to screen nodes.
81
82 bool expandEntityReferences() const;
83 /// The value of this flag determines whether the children of entity reference
84 /// nodes are visible to the iterator. If false, they and their descendants
85 /// will be rejected. Note that this rejection takes precedence over whatToShow
86 /// and the filter. Also note that this is currently the only situation where
87 /// NodeIterators may reject a complete subtree rather than skipping individual
88 /// nodes.
89 ///
90 /// To produce a view of the document that has entity references expanded and
91 /// does not expose the entity reference node itself, use the whatToShow flags
92 /// to hide the entity reference node and set expandEntityReferences to true
93 /// when creating the iterator. To produce a view of the document that has entity
94 /// reference nodes but no entity expansion, use the whatToShow flags to show
95 /// the entity reference node and set expandEntityReferences to false.
96 ///
97 /// This implementation does not support entity reference expansion and
98 /// thus always returns false.
99
100 Node* currentNode() const;
101 /// The node at which the TreeWalker is currently positioned.
102 /// Alterations to the DOM tree may cause the current node to no longer be accepted
103 /// by the TreeWalker's associated filter. currentNode may also be explicitly
104 /// set to any node, whether or not it is within the subtree specified by the
105 /// root node or would be accepted by the filter and whatToShow flags. Further
106 /// traversal occurs relative to currentNode even if it is not part of the current
107 /// view, by applying the filters in the requested direction; if no traversal
108 /// is possible, currentNode is not changed.
109
110 Node* getCurrentNode() const;
111 /// See currentNode().
112
113 void setCurrentNode(Node* pNode);
114 /// Sets the current node.
115
116 Node* parentNode();
117 /// Moves to and returns the closest visible ancestor node of the current node.
118 /// If the search for parentNode attempts to step upward from the TreeWalker's
119 /// root node, or if it fails to find a visible ancestor node, this method retains
120 /// the current position and returns null.
121
122 Node* firstChild();
123 /// Moves the TreeWalker to the first visible child of the current node, and
124 /// returns the new node. If the current node has no visible children, returns
125 /// null, and retains the current node.
126
127 Node* lastChild();
128 /// Moves the TreeWalker to the last visible child of the current node, and
129 /// returns the new node. If the current node has no visible children, returns
130 /// null, and retains the current node.
131
132 Node* previousSibling();
133 /// Moves the TreeWalker to the previous sibling of the current node, and returns
134 /// the new node. If the current node has no visible previous sibling, returns
135 /// null, and retains the current node.
136
137 Node* nextSibling();
138 /// Moves the TreeWalker to the next sibling of the current node, and returns
139 /// the new node. If the current node has no visible next sibling, returns null,
140 /// and retains the current node.
141
142 Node* previousNode();
143 /// Moves the TreeWalker to the previous visible node in document order relative
144 /// to the current node, and returns the new node. If the current node has no
145 /// previous node, or if the search for previousNode attempts to step upward
146 /// from the TreeWalker's root node, returns null, and retains the current node.
147
148 Node* nextNode();
149 /// Moves the TreeWalker to the next visible node in document order relative
150 /// to the current node, and returns the new node. If the current node has no
151 /// next node, or if the search for nextNode attempts to step upward from the
152 /// TreeWalker's root node, returns null, and retains the current node.
153
154protected:
155 int accept(Node* pNode) const;
156 Node* next(Node* pNode) const;
157 Node* previous(Node* pNode) const;
158
159private:
160 TreeWalker();
161
162 Node* _pRoot;
163 unsigned long _whatToShow;
164 NodeFilter* _pFilter;
165 Node* _pCurrent;
166};
167
168
169//
170// inlines
171//
172inline Node* TreeWalker::root() const
173{
174 return _pRoot;
175}
176
177
178inline unsigned long TreeWalker::whatToShow() const
179{
180 return _whatToShow;
181}
182
183
184inline NodeFilter* TreeWalker::filter() const
185{
186 return _pFilter;
187}
188
189
190inline bool TreeWalker::expandEntityReferences() const
191{
192 return false;
193}
194
195
196inline Node* TreeWalker::currentNode() const
197{
198 return _pCurrent;
199}
200
201
202inline Node* TreeWalker::getCurrentNode() const
203{
204 return _pCurrent;
205}
206
207
208} } // namespace Poco::XML
209
210
211#endif // DOM_TreeWalker_INCLUDED
212