dom-iterator

Feature-rich, well-tested Iterator for traversing DOM nodes. A better version of NodeIterator. Travels in both directions.

Can be used in node.js with mini-html-parser.

Installation

Install with component(1):

$ component install matthewmueller/dom-iterator

With node.js:

$ npm install dom-iterator

Example

``js
var it = iterator(node);
var next;

while (next = it.next(Node.TEXT_NODE)) {
console.log(next.nodeValue) // next textnodes after node
}
`

API

$3

Initialize an iterator starting on the node. Optionally you can
specify a root to limit your traversal to a particular subtree.
root must be either a parent or an ancestor of node.

`js
var it = iterator(el.firstChild, el)
`

$3

Gets the next DOM node. If no node exists, return null.
You may pass an expression expr, to grab the first node that
matches expr.

Additionally, you can pass a number to select the nth node.
Defaults to 1 or the 1st node.

`js
var node = it.next()
// select the 2nd element node we come across
var next = it.next(Node.ELEMENT_NODE, 2)
`

Here's a look at how the DOM is traversed:

!next

$3

Gets the previous DOM node. If no node exists, return null.
You may pass an expression expr, to grab the first node that
matches expr.

Additionally, you can pass a number to select the nth node.
Defaults to 1 or the 1st node.

`js
var node = it.prev()
// select the 2nd element node we come across
var prev = it.prev(Node.ELEMENT_NODE, 2)
`

Here's a look at how the DOM is traversed:

!prev

$3

iterate over nodes that pass the expression expr. The expr can be an
enum, number, string or function. If it's a number, the nodeType is compared.

This function can be chained where all expressions are OR-ed.

`js
it.select(Node.ELEMENT_NODE)
.select(8)
.select('nodeValue == "sloth"')
.select(fn)
`

This is saying:

> select all element nodes or comment nodes
> or nodes with the nodeValue "sloth" or
> nodes that pass the function fn.

$3

iterate over nodes that do not pass the expression expr. The expr can be an
enum, number, string or function. If it's a number, the nodeType is compared.

This function can be chained where all expressions are AND-ed.

`js
it.reject(Node.ELEMENT_NODE)
.reject(8)
.reject('nodeValue == "sloth"')
.reject(fn)
`

This is saying:

> reject all element nodes and comment nodes
> and nodes with the nodeValue sloth and
> nodes that pass the function fn".

$3

You can also skip over elements you already visited, by setting revisit to false. By default, revisit is set to true.

`js
it.revisit(false);
`

Here's how that would change the iterator:

it.next():

!next

it.prev()

!prev

$3

Jump to the opening tag of an element. This is the default.

`js
var dom = domify('hi');
var it = it(dom).opening()
it.next() // 'hi'
`

$3

Jump to the closing tag of an element

`js
var dom = domify('hi');
var it = it(dom).closing()
it.prev() // 'hi'
`

$3

Sometimes you want to peek on the following or previous node without actually visiting it. With peek you can peek forward or backwards n steps. If no n is given, peek forward 1 step.

Peaking forward:

`js
it.peek(); // peek forward 1
it.peek(3); // peek forward 3 steps
`

Peaking backwards:

`js
it.peek(Node.ELEMENT_NODE, -3) // peek backwards 3 steps, only selecting element nodes
`

$3

Reset the iterator to the original node. Optionally pass a newNode to start at.

`js
it.reset();
`

$3

Add a plugin to the iterator.

Run Tests

On the server:

`js
npm install
make test
`

Or in the browser:

`js
npm install
make test-browser
``

License

MIT