Debian Codegraph @

closure-library/closure/goog/dom/tagiterator.js

raw
1 // Copyright 2008 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Iterator subclass for DOM tree traversal.
17 *
18 * @author [email protected] (Robby Walker)
19 */
20
21 goog.provide('goog.dom.TagIterator');
22 goog.provide('goog.dom.TagWalkType');
23
24 goog.require('goog.dom');
25 goog.require('goog.dom.NodeType');
26 goog.require('goog.iter.Iterator');
27 goog.require('goog.iter.StopIteration');
28
29
30 /**
31 * There are three types of token:
32 * <ol>
33 * <li>{@code START_TAG} - The beginning of a tag.
34 * <li>{@code OTHER} - Any non-element node position.
35 * <li>{@code END_TAG} - The end of a tag.
36 * </ol>
37 * Users of this enumeration can rely on {@code START_TAG + END_TAG = 0} and
38 * that {@code OTHER = 0}.
39 *
40 * @enum {number}
41 */
42 goog.dom.TagWalkType = {
43 START_TAG: 1,
44 OTHER: 0,
45 END_TAG: -1
46 };
47
48
49
50 /**
51 * A DOM tree traversal iterator.
52 *
53 * Starting with the given node, the iterator walks the DOM in order, reporting
54 * events for the start and end of Elements, and the presence of text nodes. For
55 * example:
56 *
57 * <pre>
58 * &lt;div&gt;1&lt;span&gt;2&lt;/span&gt;3&lt;/div&gt;
59 * </pre>
60 *
61 * Will return the following nodes:
62 *
63 * <code>[div, 1, span, 2, span, 3, div]</code>
64 *
65 * With the following states:
66 *
67 * <code>[START, OTHER, START, OTHER, END, OTHER, END]</code>
68 *
69 * And the following depths
70 *
71 * <code>[1, 1, 2, 2, 1, 1, 0]</code>
72 *
73 * Imagining <code>|</code> represents iterator position, the traversal stops at
74 * each of the following locations:
75 *
76 * <pre>
77 * &lt;div&gt;|1|&lt;span&gt;|2|&lt;/span&gt;|3|&lt;/div&gt;|
78 * </pre>
79 *
80 * The iterator can also be used in reverse mode, which will return the nodes
81 * and states in the opposite order. The depths will be slightly different
82 * since, like in normal mode, the depth is computed *after* the given node.
83 *
84 * Lastly, it is possible to create an iterator that is unconstrained, meaning
85 * that it will continue iterating until the end of the document instead of
86 * until exiting the start node.
87 *
88 * @param {Node=} opt_node The start node. If unspecified or null, defaults to
89 * an empty iterator.
90 * @param {boolean=} opt_reversed Whether to traverse the tree in reverse.
91 * @param {boolean=} opt_unconstrained Whether the iterator is not constrained
92 * to the starting node and its children.
93 * @param {goog.dom.TagWalkType?=} opt_tagType The type of the position.
94 * Defaults to the start of the given node for forward iterators, and
95 * the end of the node for reverse iterators.
96 * @param {number=} opt_depth The starting tree depth.
97 * @constructor
98 * @extends {goog.iter.Iterator<Node>}
99 */
100 goog.dom.TagIterator = function(
101 opt_node, opt_reversed, opt_unconstrained, opt_tagType, opt_depth) {
102 /**
103 * Whether the node iterator is moving in reverse.
104 * @type {boolean}
105 */
106 this.reversed = !!opt_reversed;
107
108 /**
109 * The node this position is located on.
110 * @type {Node}
111 */
112 this.node = null;
113
114 /**
115 * The type of this position.
116 * @type {goog.dom.TagWalkType}
117 */
118 this.tagType = goog.dom.TagWalkType.OTHER;
119
120 /**
121 * The tree depth of this position relative to where the iterator started.
122 * The depth is considered to be the tree depth just past the current node,
123 * so if an iterator is at position
124 * <pre>
125 * <div>|</div>
126 * </pre>
127 * (i.e. the node is the div and the type is START_TAG) its depth will be 1.
128 * @type {number}
129 */
130 this.depth;
131
132 /**
133 * Whether iteration has started.
134 * @private {boolean}
135 */
136 this.started_ = false;
137
138 /**
139 * Whether the iterator is constrained to the starting node and its children.
140 * @type {boolean}
141 */
142 this.constrained = !opt_unconstrained;
143
144 if (opt_node) {
145 this.setPosition(opt_node, opt_tagType);
146 }
147 this.depth = opt_depth != undefined ? opt_depth : this.tagType || 0;
148 if (this.reversed) {
149 this.depth *= -1;
150 }
151 };
152 goog.inherits(goog.dom.TagIterator, goog.iter.Iterator);
153
154
155 /**
156 * Set the position of the iterator. Overwrite the tree node and the position
157 * type which can be one of the {@link goog.dom.TagWalkType} token types.
158 * Only overwrites the tree depth when the parameter is specified.
159 * @param {Node} node The node to set the position to.
160 * @param {goog.dom.TagWalkType?=} opt_tagType The type of the position
161 * Defaults to the start of the given node.
162 * @param {number=} opt_depth The tree depth.
163 */
164 goog.dom.TagIterator.prototype.setPosition = function(
165 node, opt_tagType, opt_depth) {
166 this.node = node;
167
168 if (node) {
169 if (goog.isNumber(opt_tagType)) {
170 this.tagType = opt_tagType;
171 } else {
172 // Auto-determine the proper type
173 this.tagType = this.node.nodeType != goog.dom.NodeType.ELEMENT ?
174 goog.dom.TagWalkType.OTHER :
175 this.reversed ? goog.dom.TagWalkType.END_TAG :
176 goog.dom.TagWalkType.START_TAG;
177 }
178 }
179
180 if (goog.isNumber(opt_depth)) {
181 this.depth = opt_depth;
182 }
183 };
184
185
186 /**
187 * Replace this iterator's values with values from another. The two iterators
188 * must be of the same type.
189 * @param {goog.dom.TagIterator} other The iterator to copy.
190 * @protected
191 */
192 goog.dom.TagIterator.prototype.copyFrom = function(other) {
193 this.node = other.node;
194 this.tagType = other.tagType;
195 this.depth = other.depth;
196 this.reversed = other.reversed;
197 this.constrained = other.constrained;
198 };
199
200
201 /**
202 * @return {!goog.dom.TagIterator} A copy of this iterator.
203 */
204 goog.dom.TagIterator.prototype.clone = function() {
205 return new goog.dom.TagIterator(
206 this.node, this.reversed, !this.constrained, this.tagType, this.depth);
207 };
208
209
210 /**
211 * Skip the current tag.
212 */
213 goog.dom.TagIterator.prototype.skipTag = function() {
214 var check = this.reversed ? goog.dom.TagWalkType.END_TAG :
215 goog.dom.TagWalkType.START_TAG;
216 if (this.tagType == check) {
217 this.tagType = /** @type {goog.dom.TagWalkType} */ (check * -1);
218 this.depth += this.tagType * (this.reversed ? -1 : 1);
219 }
220 };
221
222
223 /**
224 * Restart the current tag.
225 */
226 goog.dom.TagIterator.prototype.restartTag = function() {
227 var check = this.reversed ? goog.dom.TagWalkType.START_TAG :
228 goog.dom.TagWalkType.END_TAG;
229 if (this.tagType == check) {
230 this.tagType = /** @type {goog.dom.TagWalkType} */ (check * -1);
231 this.depth += this.tagType * (this.reversed ? -1 : 1);
232 }
233 };
234
235
236 /**
237 * Move to the next position in the DOM tree.
238 * @return {Node} Returns the next node, or throws a goog.iter.StopIteration
239 * exception if the end of the iterator's range has been reached.
240 * @override
241 */
242 goog.dom.TagIterator.prototype.next = function() {
243 var node;
244
245 if (this.started_) {
246 if (!this.node || this.constrained && this.depth == 0) {
247 throw goog.iter.StopIteration;
248 }
249 node = this.node;
250
251 var startType = this.reversed ? goog.dom.TagWalkType.END_TAG :
252 goog.dom.TagWalkType.START_TAG;
253
254 if (this.tagType == startType) {
255 // If we have entered the tag, test if there are any children to move to.
256 var child = this.reversed ? node.lastChild : node.firstChild;
257 if (child) {
258 this.setPosition(child);
259 } else {
260 // If not, move on to exiting this tag.
261 this.setPosition(
262 node,
263 /** @type {goog.dom.TagWalkType} */ (startType * -1));
264 }
265 } else {
266 var sibling = this.reversed ? node.previousSibling : node.nextSibling;
267 if (sibling) {
268 // Try to move to the next node.
269 this.setPosition(sibling);
270 } else {
271 // If no such node exists, exit our parent.
272 this.setPosition(
273 node.parentNode,
274 /** @type {goog.dom.TagWalkType} */ (startType * -1));
275 }
276 }
277
278 this.depth += this.tagType * (this.reversed ? -1 : 1);
279 } else {
280 this.started_ = true;
281 }
282
283 // Check the new position for being last, and return it if it's not.
284 node = this.node;
285 if (!this.node) {
286 throw goog.iter.StopIteration;
287 }
288 return node;
289 };
290
291
292 /**
293 * @return {boolean} Whether next has ever been called on this iterator.
294 * @protected
295 */
296 goog.dom.TagIterator.prototype.isStarted = function() {
297 return this.started_;
298 };
299
300
301 /**
302 * @return {boolean} Whether this iterator's position is a start tag position.
303 */
304 goog.dom.TagIterator.prototype.isStartTag = function() {
305 return this.tagType == goog.dom.TagWalkType.START_TAG;
306 };
307
308
309 /**
310 * @return {boolean} Whether this iterator's position is an end tag position.
311 */
312 goog.dom.TagIterator.prototype.isEndTag = function() {
313 return this.tagType == goog.dom.TagWalkType.END_TAG;
314 };
315
316
317 /**
318 * @return {boolean} Whether this iterator's position is not at an element node.
319 */
320 goog.dom.TagIterator.prototype.isNonElement = function() {
321 return this.tagType == goog.dom.TagWalkType.OTHER;
322 };
323
324
325 /**
326 * Test if two iterators are at the same position - i.e. if the node and tagType
327 * is the same. This will still return true if the two iterators are moving in
328 * opposite directions or have different constraints.
329 * @param {goog.dom.TagIterator} other The iterator to compare to.
330 * @return {boolean} Whether the two iterators are at the same position.
331 */
332 goog.dom.TagIterator.prototype.equals = function(other) {
333 // Nodes must be equal, and we must either have reached the end of our tree
334 // or be at the same position.
335 return other.node == this.node &&
336 (!this.node || other.tagType == this.tagType);
337 };
338
339
340 /**
341 * Replace the current node with the list of nodes. Reset the iterator so that
342 * it visits the first of the nodes next.
343 * @param {...Object} var_args A list of nodes to replace the current node with.
344 * If the first argument is array-like, it will be used, otherwise all the
345 * arguments are assumed to be nodes.
346 */
347 goog.dom.TagIterator.prototype.splice = function(var_args) {
348 // Reset the iterator so that it iterates over the first replacement node in
349 // the arguments on the next iteration.
350 var node = this.node;
351 this.restartTag();
352 this.reversed = !this.reversed;
353 goog.dom.TagIterator.prototype.next.call(this);
354 this.reversed = !this.reversed;
355
356 // Replace the node with the arguments.
357 var arr = goog.isArrayLike(arguments[0]) ? arguments[0] : arguments;
358 for (var i = arr.length - 1; i >= 0; i--) {
359 goog.dom.insertSiblingAfter(arr[i], node);
360 }
361 goog.dom.removeNode(node);
362 };