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.NodeIterator');
22

23
goog.require('goog.dom.TagIterator');
24

25

26

27
/**
28
 * A DOM tree traversal iterator.
29
 *
30
 * Starting with the given node, the iterator walks the DOM in order, reporting
31
 * events for each node.  The iterator acts as a prefix iterator:
32
 *
33
 * <pre>
34
 * &lt;div&gt;1&lt;span&gt;2&lt;/span&gt;3&lt;/div&gt;
35
 * </pre>
36
 *
37
 * Will return the following nodes:
38
 *
39
 * <code>[div, 1, span, 2, 3]</code>
40
 *
41
 * With the following depths
42
 *
43
 * <code>[1, 1, 2, 2, 1]</code>
44
 *
45
 * Imagining <code>|</code> represents iterator position, the traversal stops at
46
 * each of the following locations:
47
 *
48
 * <pre>&lt;div&gt;|1|&lt;span&gt;|2|&lt;/span&gt;3|&lt;/div&gt;</pre>
49
 *
50
 * The iterator can also be used in reverse mode, which will return the nodes
51
 * and states in the opposite order.  The depths will be slightly different
52
 * since, like in normal mode, the depth is computed *after* the last move.
53
 *
54
 * Lastly, it is possible to create an iterator that is unconstrained, meaning
55
 * that it will continue iterating until the end of the document instead of
56
 * until exiting the start node.
57
 *
58
 * @param {Node=} opt_node The start node.  Defaults to an empty iterator.
59
 * @param {boolean=} opt_reversed Whether to traverse the tree in reverse.
60
 * @param {boolean=} opt_unconstrained Whether the iterator is not constrained
61
 *     to the starting node and its children.
62
 * @param {number=} opt_depth The starting tree depth.
63
 * @constructor
64
 * @extends {goog.dom.TagIterator}
65
 * @final
66
 */
67
goog.dom.NodeIterator = function(
68
    opt_node, opt_reversed, opt_unconstrained, opt_depth) {
69
  goog.dom.TagIterator.call(
70
      this, opt_node, opt_reversed, opt_unconstrained, null, opt_depth);
71
};
72
goog.inherits(goog.dom.NodeIterator, goog.dom.TagIterator);
73

74

75
/**
76
 * Moves to the next position in the DOM tree.
77
 * @return {Node} Returns the next node, or throws a goog.iter.StopIteration
78
 *     exception if the end of the iterator's range has been reached.
79
 * @override
80
 */
81
goog.dom.NodeIterator.prototype.next = function() {
82
  do {
83
    goog.dom.NodeIterator.superClass_.next.call(this);
84
  } while (this.isEndTag());
85

86
  return this.node;
87
};
88

89