{"_id":"traversty","_rev":"52-ee8fa7e44ed0cbe23717f617a861d674","name":"traversty","description":"Library agnostic utility for DOM collection management and traversal","dist-tags":{"latest":"1.0.5"},"versions":{"0.0.1":{"name":"traversty","description":"Library agnostic utility for traversing the DOM","version":"0.0.1","homepage":"https://github.com/rvagg/traversty","author":{"name":"Rod Vagg","email":"rod@vagg.org"},"keywords":["ender","dom","nodes"],"main":"./traversty.js","ender":"./src/ender.js","repository":{"type":"git","url":"git://github.com/rvagg/traversty.git"},"devDependencies":{},"_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"_id":"traversty@0.0.1","dependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.0.106","_nodeVersion":"v0.6.5","_defaultsLoaded":true,"dist":{"shasum":"4723b41d883008e4852d80cdf536d25deeb46158","tarball":"https://registry.npmjs.org/traversty/-/traversty-0.0.1.tgz","integrity":"sha512-CVOsBisYFxw+joEWqZFdCi/ruQnoMsFQT2ONsXDuEWU8gbqBY8fevym4uoVqH0+MD7kb5AydpU8YqnpRJHYNFQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHSgYTGbmzohjoWqniOcS+88Xr9GTDz/hpspkeiIGpDrAiB4Xai5kgqpWSrPe0WvYjiLimb8hxcvyznx3gHtgOr7WA=="}]},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"0.0.2":{"name":"traversty","description":"Library agnostic utility for traversing the DOM","version":"0.0.2","homepage":"https://github.com/rvagg/traversty","author":{"name":"Rod Vagg","email":"rod@vagg.org"},"keywords":["ender","dom","nodes"],"main":"./traversty.js","ender":"./src/ender.js","repository":{"type":"git","url":"git://github.com/rvagg/traversty.git"},"devDependencies":{},"_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"_id":"traversty@0.0.2","dependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.0.106","_nodeVersion":"v0.6.5","_defaultsLoaded":true,"dist":{"shasum":"d799ed4d9d806ea1b5db8de883c07b59e80ffe4d","tarball":"https://registry.npmjs.org/traversty/-/traversty-0.0.2.tgz","integrity":"sha512-dqF6l3WDiAk8JKH2N3nnhOCDk5Fr3Cla4eE1gSgsEXQOYZ3ZwqT+aU2JxarO0IHPSKRrnCgLjNwRJ59q3DQz6Q==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIEGPl2akRQ4VwwYN9dUCGFcmSKpGYEsiLemt6nBUqD1BAiAY9MnWpgDLTZqW3jnn3fNPA6vioqCaRrh9qS6X7qmAyg=="}]},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"0.0.3":{"name":"traversty","description":"Library agnostic utility for traversing the DOM","version":"0.0.3","homepage":"https://github.com/rvagg/traversty","author":{"name":"Rod Vagg","email":"rod@vagg.org"},"keywords":["ender","dom","nodes"],"main":"./traversty.js","ender":"./src/ender.js","repository":{"type":"git","url":"git://github.com/rvagg/traversty.git"},"devDependencies":{},"_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"_id":"traversty@0.0.3","dependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.0.106","_nodeVersion":"v0.6.5","_defaultsLoaded":true,"dist":{"shasum":"e4487fa9d7eca2cf9befd6b6ae44e71f2ad45e04","tarball":"https://registry.npmjs.org/traversty/-/traversty-0.0.3.tgz","integrity":"sha512-S7VQ4nAQTDUUDZvWwpHIjc7v6qrqaWHyv8D2Q4TbNcEo3n7A9EisA2rPgWWHi86/URUAtJHPNBCqSF1sn1lpog==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCpw9oxBH17dq4YXpldfmKW2FJezNdrxmu2Z+z6v2AhsgIhAKCPvotlfrtFWLIhLvtGPXFXzdQ9smuhv0NyeF/5LdEG"}]},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"0.0.4":{"name":"traversty","description":"Library agnostic utility for traversing the DOM","version":"0.0.4","homepage":"https://github.com/rvagg/traversty","author":{"name":"Rod Vagg","email":"rod@vagg.org"},"keywords":["ender","dom","nodes"],"main":"./traversty.js","ender":"./src/ender.js","repository":{"type":"git","url":"git://github.com/rvagg/traversty.git"},"devDependencies":{},"_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"_id":"traversty@0.0.4","dependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.0.106","_nodeVersion":"v0.6.6","_defaultsLoaded":true,"dist":{"shasum":"87219f0e4986f0c8508a3696288dbaafbcb4da36","tarball":"https://registry.npmjs.org/traversty/-/traversty-0.0.4.tgz","integrity":"sha512-iRyDbfAATpJQmQDoM3s3W2k1KGjKpR8GFrihVumddxxkY5P4adYMScMK0orxpILWWgA1f0qj02l6qk2gK3/stQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDUQjJPSkcYQD4rLYXaHUE5Or5v9ysDAmSwuH2jb+1bgQIgDweT2RZWaj4eADiXufAxVattBnCHpJZVLzR2M8Mgjp4="}]},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"0.0.5":{"name":"traversty","description":"Library agnostic utility for traversing the DOM","version":"0.0.5","homepage":"https://github.com/rvagg/traversty","author":{"name":"Rod Vagg","email":"rod@vagg.org"},"keywords":["ender","dom","nodes"],"main":"./traversty.js","ender":"./src/ender.js","repository":{"type":"git","url":"git://github.com/rvagg/traversty.git"},"devDependencies":{},"_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"_id":"traversty@0.0.5","dependencies":{},"optionalDependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.1.1","_nodeVersion":"v0.6.10","_defaultsLoaded":true,"dist":{"shasum":"d38ff3bc6a6867fac7f76a73da1378608ffe2c15","tarball":"https://registry.npmjs.org/traversty/-/traversty-0.0.5.tgz","integrity":"sha512-3gVtwQVwOXGukB7epNcjOPVNEoZFd45pgayo9vhZFxD4267pd2u+myxg/1FKRC1GhPrszNGnizSVcLRgqUk2mQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIGGd3UC5wkJpAuA2iB3hBxlLKVtFnuGP/qr0w+/ZvPw2AiEA2UzsjnZsWp6g9YLLvX0jn2nIfVJfeY1WdlWuXgQd29w="}]},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"0.0.6":{"name":"traversty","description":"Library agnostic utility for traversing the DOM","version":"0.0.6","homepage":"https://github.com/rvagg/traversty","author":{"name":"Rod Vagg","email":"rod@vagg.org"},"keywords":["ender","dom","nodes"],"main":"./traversty.js","ender":"./src/ender.js","repository":{"type":"git","url":"git://github.com/rvagg/traversty.git"},"devDependencies":{},"_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"_id":"traversty@0.0.6","dependencies":{},"optionalDependencies":{},"engines":{"node":"*"},"_engineSupported":true,"_npmVersion":"1.1.2","_nodeVersion":"v0.6.12-pre","_defaultsLoaded":true,"dist":{"shasum":"e8ba5b7bead99ae904ba55738f51fafabce3ebe2","tarball":"https://registry.npmjs.org/traversty/-/traversty-0.0.6.tgz","integrity":"sha512-AhKxB/PUZCIPQCuJopGEZ9rPW4UWTjV1gjx1Bap4y4WSCJ9MtMaPBT4nJoll1Nx/D2vAN5M3RCpzuqFRNzk6AA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIAKDcVJZOJen3HEZrqkrFFFTi7kTj8lTlW7acQLvRXCeAiEA2+YFjJ1Mvc9DhjzibM16V3z0IDByBl5VP0p6wgUGvaw="}]},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"0.0.7":{"name":"traversty","description":"Traversty &mdash; headache-free DOM traversal =============================================","version":"0.0.7","homepage":"https://github.com/rvagg/traversty","author":{"name":"Rod Vagg","email":"rod@vagg.org"},"keywords":["ender","dom","nodes"],"main":"./traversty.js","ender":"./src/ender.js","repository":{"type":"git","url":"https://github.com/rvagg/traversty.git"},"devDependencies":{"buster":"*"},"readme":"Traversty &mdash; headache-free DOM traversal\n=============================================\n\nTraversty is a library-agnostic DOM traversal utility giving you 4 flexible methods for moving around the DOM.\n\nInspired by [Prototype](http://prototypejs.org)'s excelent \"DOM traversal toolkit\", you get `up()`, `down()`, `next()` and `previous()` with optional `selector` and `index` arguments, all in a multi-element environment (jQuery-like rather than Prototype's single-element implementation).\n\nTraversty is designed primarily to be integrated in an [Ender](http://ender.no.de/) build, to augment what's already available in [Bonzo](https://github.com/ded/bonzo) but can just as easily be used as a stand-alone utility. \n\nExample usage\n-------------\n\n*This code is used Traversty Ender integration tests and depends on Bonzo*\n\n```js\n$('#root > ul') // can match multiple elements\n  .down(0).css('color', 'red')\n  .next('li', 1).css('color', 'green')\n  .next().down('li', 2).css('color', 'blue')\n  .next().down().css('color', 'yellow')\n  .up(2).next().css('color', 'purple');\n```\n\n\nAPI\n---\n\n### Main: `traversty(elements || selector)` ###\n\nGives you a new Traversty instance containing the DOM elements you provide, allowing you to call any of the following methods. You can give a single DOM element or an array of DOM elements. If you provide a string argument it will be used as a selector to either query the DOM via the browser's native `querySelectorAll()` implementation or use a selector engine which you provide (see below).\n\nIndividual elements are available with array accessors, e.g. `traversty(document.body)[0] // → document.body` \n\nWhen included in an Ender build, `$(elements || selector)` does the same thing.\n\n### Next: `traversty(elements).next([selector = \"*\"[, index = 0]])` ###\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match all elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nReturns a new Traversty instance wrapped around the resulting DOM elements. You will get elements that match the given *selector* (or '*') starting from the *nextSibling* of the starting element(s), all the way across to the last *nextSibling*.\n\nIf no `index` or `selector` is given then you get just the *nextSibling*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *nextSibling*s of the element(s). i.e. `index` is 0-based, like arrays, 0 is *nextSibling* and 1 is *nextSibling.nextSibling*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching *nextSibling* elements.\n\n#### Examples ####\n\n```js\ntraversty('li:first-child').next(); // →  returns the second `<li>` of every list in the document\ntraversty('li.allstarts').next('li', 1); // →  returns the `nextSibling` of the `nextSibling` of the starting elements\ntraversty('li:first-child').next('li'); // →  returns all `<li>` elements, except for the first-children of every lits in the document\n```\n\n\n### Previous: `traversty(elements).previous([selector = \"*\"[, index = 0]])` ###\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match all elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nExactly the same as `.next()` except it works on *previousSibling*, so you move backwards amongst sibling elements.\n\n#### Examples ####\n\n```js\ntraversty('li:nth-child(20)').previous(); // →  returns 19th child of the every list in the document (where it exists)\ntraversty('li.allstarts').previous('li', 1); // →  returns the `previousSibling` of the `previousSibling` of the starting element\ntraversty('li:nth-child(20)').previous('.interesting'); // →  returns all `<li>` elements with class \"interesting\" up to the 19th child of every list in the document where there are at least 20 children.\n```\n\n### Up: `traversty(elements).up([selector = \"*\"[, index = 0]])` ###\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match all elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nSimilar to `next()` and `previous()` except that it works on *parentNode*s and will continue all the up to the document root depending on what you're asking for.\n\nIf no `index` or `selector` is given then you get just the `parentNode*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *parentNode*s of the element. i.e. `index` is 0-based, like arrays, 0 is *parentNode* and 1 is *parentNode.parentNode*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching ancestor elements.\n\n\n#### Examples ####\n\n```js\ntraversty('li#start').up(); // →  returns the `<ul>` parent element\ntraversty('li.allstarts').up('ul', 1); // →  returns the grandparent `<ul>` elements if the start elements are nested at two levels\ntraversty('li.allstarts').up('ul'); // →  returns all ancestor `<ul>` elements, no matter how deep the nesting\n```\n\n### Down: `traversty(elements).down([selector = \"*\"[, index = 0]])` ###\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match all elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nWhile `down()` is very similar to the other methods, it's perhaps best to think of it as what you might get with a `find()` method from a selector engine.\n\n`down()` works on elements **in document-order**, so it operates on child elements and children of children but it also moves through child-siblings on the way to children of children.\n\nThe following fragment should illustrate the `index`ing you get when you use `down()`:\n\n```html\n<ul id=\"root\">\n  <li>fisrt</li>   <!-- 0 -->\n  <li>second</li>  <!-- 1 -->\n  <li>third        <!-- 2 -->\n    <ul>           <!-- 3 -->\n      <li>i</li>   <!-- 4 -->\n      <li>ii</li>  <!-- 5 -->\n      <li>iii</li> <!-- 6 -->\n    </ul>\n  </ul>\n  <li>fourth</li>  <!-- 7 -->\n</ul>\n```\n\nSo\n\n```js\ntraversty('#root').down(5) // →  will give you `<li>ii</li>`\ntraversty('#root').down('li', 5) // →  will give you `<li>i</li>` because the `<ul>` is ignored:w\n```\n\nOf course `down()` works on multiple elements simultaneously just like the other methods.\n\n\nI want a demo!\n--------------\n\nYou'll have to make do with the integration tests. [Here](http://rvagg.github.com/traversty/test/integration/ender_qwery.html) is Traversty running in an Ender build with Qwery and Bonzo. You can also see it running with [Sel](http://rvagg.github.com/traversty/test/integration/ender_sel.html), [Sizzle](http://rvagg.github.com/traversty/test/integration/ender_sizzle.html), [NWMatcher](http://rvagg.github.com/traversty/test/integration/ender_nwmatcher.html) and [without a selector engine](http://rvagg.github.com/traversty/test/integration/ender_sel.html) (works in modern browsers, including IE9+).\n\nView-source to see what it's doing, note that it's operating on 2 lists at the same time.\n\n\nThings to note\n--------------\n\n * Traversty always does a **uniqueness** check on its collection of elements so you should never end up with duplicates. If you did a `traversty('body,ul').down('li')` you would still only get a unique list of all *<li>* elements in the document.\n\n * Traversty ignores text and comment nodes and should only ever operate on the DOM element nodes you would expect (i.e. with *nodeType==1*).\n\n * Traversty currently orders results (for each element in the starting list) in document-order, so `previous('*')` will give you results starting from the *firstChild* of the parent element up to the *previousSibling* of the starting element, rather than starting with the *previousSibling* and listing backwards (this doesn't impact on indexing, which still works backwards, only the order of result lists). This may change, I haven't decided yet!\n\n### Supported browsers ###\n\nTraversty is tested with IE6+, Firefox 3+, Safari 4+, Opera current and Chrome current. You'll need a supported selector engine to operate on some of these older browsers. See below.\n\n\nSelector engines\n----------------\n\nTraversty should work out-of-the-box on modern browsers as it leverages native `querySelectorAll()` and `matchesSelector()` where they exist. This means that you should be able to use Traversty without a selector engine on most smartphone browsers without any problems.\n\nUnfortunately, this doesn't work with older browsers, particularly IE8 and below. While IE8 has a CSS2-compliant `querySelectorAll()`, it doesn't have a `matchesSelector()` which Traversty makes heavy use of.\n\n### `traversty.setSelectorEngine(engine)` ###\n\nTraversty allows you to plug in your favourite selector engine so it can work on whatever browser your engine supports. Out of the box, Traversty is tested to support [Qwery](https://github.com/ded/qwery), [Sel](https://github.com/amccollum/sel), [Sizzle](https://github.com/jquery/sizzle) and [NWMatcher](https://github.com/dperini/nwmatcher).\n\nTraversty uses *feature detection* to figure out how to use your selector engine, it tries to find the method used to *find* elements given a element root and the method used to determine if an element *matches* a given selector. If it can't figure out how to use your selector engine then you just need to pretend that it works like one of the supported ones and it should be OK.\n\nFor example:\n\n```js\ntraversty.setSelectorEngine({\n    select: function(selector, root) {\n      return MyEngine(selector, root);\n    }\n  , is: function(selector, root) {\n      return MyEngine(root).isTheSameAs(selector);\n    }\n});\n```\n\nTraversty will also do some trickery to make up for deficiencies in some selector engines, such as out-of-order results when selecting on groups ('a,b').\n\nIf you have a new selector engine that you want Traversty to support then either let me know or fork, patch and submit.\n\n\nEnder integration\n-----------------\n\nTraversty is designed to be inserted into an Ender build. It's in NPM so simply include it in your build command, something like: `ender build sel bonzo traversty`\n\nTraversty will attempt to use whatever selector engine you've included in your Ender build.\n\n### What about Bonzo? ###\n\nTraversty is designed to add to the goodness you get in Bonzo, although Bonzo isn't a dependency. Bonzo has `next()` and `previous()` already and it is intended that Traversty replace these in your ender build. Argument-less they should do exactly the same thing but Traversty adds the extra arguments for greater flexibility. If you are using Bonzo in Ender along with Traversty then you should make sure Traversty is included *after* Bonzo. Unfortunately, [Ender doesn't guarantee order](https://github.com/ender-js/Ender/issues/63) so you may have to fiddle a bit. \n\n### Additional sugar ###\n\nIn addition to `up()`, `down()`, `next()`, and `previous()` you'll also get aliases which take the same argument types: `parent()` (same as `up()`), `prev()` (same as `previous()`).\n\nContributing\n------------\n\nAwesome! Just do it, fork and submit your pull requests and they will be promptly considered.\n\nI'd also love it if you could contribute tests for bugs you find or features you add.\n\nWhile I'm not a coding-style nazi but I do like consistency. I've chosen a particular style for this project (not my usual style, I have a Java background, I'm experimenting with style!) and I'd prefer to keep it consistent.\n\n### Tests ###\n\nTraversty uses [Buster](http://busterjs.org) for unit testing.\n\n#### Client/server ####\n\nThis works by running a server for you to attach browsers to so you can submit all tests to be run in all of the attached browsers right from the command-line.\n\nSimply do this:\n\n```\n$ sudo npm install buster -g  # install Buster if you haven't already got it\n$ make server                 # will start the Buster server for you on port 1111.\n$                             # point a bunch of browsers to that server, including older versions of IE (start your VMs!)\n$ make test                   # will submit the tests to the Buster server to be run on those browsers\n```\n\nYou'll see a nice output with the results of the tests as they happen.\n\n#### Static ####\n\nSince Buster is still in Beta, the capture-server is a bit buggy and can be frustrating. So, an alternative testing method is to simply run the *index.html* file in the *tests* directory in each of the browsers you need to test. It'll load and run the same tests as the capture-server approach.\n\n### Where are your semi-colons? ###\n\nOh, you noticed that? Just think of this as my [The Cat in the Hat](http://en.wikipedia.org/wiki/The_Cat_in_the_Hat) project. It's an experiment in how difficult it is to write valid JavaScript devoid of semi-colons. There's only a couple of awkward constructions that could do with a `for` loop, but I don't think it's a big deal. \n\n\nCredits\n-------\n\n * Firstly, much credit should go to the awesome Prototype guys and their excellent API that I've ripped off.\n * Thanks to [@ded](http://github.com/ded) and [@fat](http://github.com/fat) for Ender, particularly @ded for Bonzo, upon which Traversty is designed to build.\n\nThe bulk of the work is done by me, Rod Vagg, [@rvagg](http://twitter.com/rvagg)\n\nLicence\n-------\n\nBlah, Blah, MIT\n","_id":"traversty@0.0.7","dist":{"shasum":"580fb1b513754e48da5d2095c23c37c498663906","tarball":"https://registry.npmjs.org/traversty/-/traversty-0.0.7.tgz","integrity":"sha512-v4lLjpd2kTn3Zn1v9Ms45rr9yu1aIMm5ZElZONPrDB9//zET84Ib10Ww+Wr0rrB+Pm7OXcJjC2Mu28qoILYuAg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCw+jPCvAO93bOB9d9smODdrRuypBQ2h+qeepZcS+xS6AIgbTErFy1lZhCMbMqe+KhprUY+WMnF9ws8+R7qiYXsCVc="}]},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"1.0.0":{"name":"traversty","description":"Library agnostic utility for DOM collection management and traversal","version":"1.0.0","homepage":"https://github.com/rvagg/traversty","authors":["Rod Vagg @rvagg <rod@vagg.org> (https://github.com/rvagg)"],"keywords":["ender","dom","nodes","traversal"],"main":"./traversty.js","ender":"./ender_bridge.js","repository":{"type":"git","url":"https://github.com/rvagg/traversty.git"},"devDependencies":{"buster":"*"},"license":"MIT","readme":"# Traversty &mdash; headache-free DOM collection management and traversal\n\nTraversty is a library-agnostic DOM utility for traversal and element collection manipulation. Traversty doesn't provide any DOM manipulation features, instead, Traversty is used for managing collections of DOM elements and navigating the DOM.\n\n<a href=\"#api\"><i>Just show me the API!</i></a>\n\n## Traversal\n\nThe core DOM traversal methods are inspired by [Prototype](http://prototypejs.org)'s excelent \"DOM traversal toolkit\", you get <a href=\"#up\"><code>up()</code></a>, <a href=\"#down\"><code>down()</code></a>, <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> with optional `selector` and `index` arguments, all in a multi-element environment&mdash;jQuery-like rather than Prototype's single-element implementation.\n\nIn addition, jQuery-compatible traversal methods extend this functionality: <a href=\"#parents\"><code>parents()</code></a>, <a href=\"#closest\"><code>closest()</code></a>, <a href=\"#children\"><code>children()</code></a>, <a href=\"#siblings\"><code>siblings()</code></a> and <a href=\"#prev\"><code>prev()</code></a> a simple alias for <a href=\"#previous\"><code>previous()</code></a>.\n\n## Collection filtering\n\nTraversty operates on DOM element collections, jQuery-style, so it also gives you methods to filter and manipulate that collection. The filtering methods are designed to be jQuery-compatible. You get: <a href=\"#first\"><code>first()</code></a>, <a href=\"#last\"><code>last()</code></a>, <a href=\"#eq\"><code>eq()</code></a>, <a href=\"#not\"><code>not()</code></a>, <a href=\"#slice\"><code>slice()</code></a>, <a href=\"#filter\"><code>filter()</code></a>, <a href=\"#has\"><code>has()</code></a> and <a href=\"#is\"><code>is()</code></a> (this last method returns a boolean rather than a collection).\n\nTraversty emulates an Array and includes additional methods to help you manage it as if it were one: <a href=\"#get\"><code>get()</code></a>, <a href=\"#toArray\"><code>toArray()</code></a>, <a href=\"#size\"><code>size()</code></a>, <a href=\"#push\"><code>push()</code></a>, <a href=\"#sort\"><code>sort()</code></a>, <a href=\"#splice\"><code>splice()</code></a>.\n\nTraversty is designed to be integrated in an [Ender](http://ender.no.de/) build, to augment what's already available in [Bonzo](https://github.com/ded/bonzo) but can just as easily be used as a stand-alone utility.\n\n## Example usage\n\nThis bit of crazyness comes from Traversty's integration tests. The bulk of this code is used to test Traversty's integration with Ender where the `css()` method is provided by [Bonzo](https://github.com/ded/bonzo) but there is also a [vanilla version](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) with only [Qwery](https://github.com/ded/qwery) for the selector engine and a `css()` method added using Traversty's <a href=\"#aug\"><code>aug()</code></a> method (see the [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) file for how this is done).\n\n```js\nvar $ = traversty\n$.setSelectorEngine(qwery)\n$('#fixtures > ul') // Traversty operates on collecitons of elements\n  .down(0).css('color', 'red')\n  .next('li', 1).css('color', 'green')\n  .next().down('li', 2).css('color', 'blue')\n  .next().down().css('color', 'yellow')\n  .up(2).next().css('color', 'purple')\n  .siblings(3).css('fontWeight', 'bold')\n  .children().css('textDecoration', 'underline')\n  .children(1).css('borderLeft', 'solid 5px red')\n  .parents('*').filter('ul').css('borderTop', 'dashed 2px green')\n  .not('.second').css('borderBottom', 'solid 3px blue')\n  .down('.second li').has('span').css('marginTop', '10px')\n  .up('ul').eq(-1).css('borderLeft', 'solid 5px orange')\n  .closest('#fixtures').down('li').slice(-10,-9).css('fontSize', '25px')\n  // Note: the css() method is not native to Traversty but is added with aug()\n```\n\nThe return type from the `traversty()` method is not a true `Array` but can be used like an array in almost all respects, it has `.length` and `[]` subscript element access and other standard `Array` methods.\n\n<a href=\"#api\"></a>\n## API\n\n  * <a href=\"#ctor\"><code><b>traversty()</b></code></a>\n  * <a href=\"#next\"><code>traversty().<b>next()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>previous()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>prev()</b></code></a>\n  * <a href=\"#up\"><code>traversty().<b>up()</b></code></a>\n  * <a href=\"#parents\"><code>traversty().<b>parents()</b></code></a>\n  * <a href=\"#closest\"><code>traversty().<b>closest()</b></code></a>\n  * <a href=\"#down\"><code>traversty().<b>down()</b></code></a>\n  * <a href=\"#children\"><code>traversty().<b>children()</b></code></a>\n  * <a href=\"#siblings\"><code>traversty().<b>siblings()</b></code></a>\n  * <a href=\"#first\"><code>traversty().<b>first()</b></code></a>\n  * <a href=\"#last\"><code>traversty().<b>last()</b></code></a>\n  * <a href=\"#eq\"><code>traversty().<b>eq()</b></code></a>\n  * <a href=\"#slice\"><code>traversty().<b>slice()</b></code></a>\n  * <a href=\"#filter\"><code>traversty().<b>filter()</b></code></a>\n  * <a href=\"#not\"><code>traversty().<b>not()</b></code></a>\n  * <a href=\"#has\"><code>traversty().<b>has()</b></code></a>\n  * <a href=\"#is\"><code>traversty().<b>is()</b></code></a>\n  * <a href=\"#get\"><code>traversty().<b>get()</b></code></a>\n  * <a href=\"#each\"><code>traversty().<b>each()</b></code></a>\n  * <a href=\"#toArray\"><code>traversty().<b>toArray()</b></code></a>\n  * <a href=\"#size\"><code>traversty().<b>size()</b></code></a>\n  * <a href=\"#push\"><code>traversty().<b>push()</b></code></a>\n  * <a href=\"#sort\"><code>traversty().<b>sort()</b></code></a>\n  * <a href=\"#splice\"><code>traversty().<b>splice()</b></code></a>\n  * <a href=\"#aug\"><code>traversty.<b>aug()</b></code></a>\n  * <a href=\"#setSelectorEngine\"><code>traversty.<b>setSelectorEngine()</b></code></a>\n  * <a href=\"#noConflict\"><code>traversty.<b>noConflict()</b></code></a>\n\n--------------------------------------------------------\n<a name=\"ctor\"></a>\n### traversty(element | elements | selector)\n<code>traversty()</code> gives you a new Traversty instance containing the elements you provide.\n\nOnce you have a collection, you can call any of the Traversty methods on that collection. You can give a single DOM element or an array of DOM elements. If you provide a string argument it will be used as a selector to either query the DOM via the browser's native `querySelectorAll()` implementation or use a selector engine which you provide (see <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a>).\n\nYou can pluck individual elements with array accessors (subscript), e.g. `traversty(document.body)[0] // → document.body` \n\nWhen included in an Ender build, `$(element | elements | selector)` does the same thing and all the Traversty methods will be available on the resulting Ender object.\n\n--------------------------------------------------------\n<a name=\"next\"></a>\n### next([selector [, index = 0]])\n<code>traversty(elements).next()</code> returns a new Traversty instance containing *nextSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nYou will get elements that match the given *selector* (if provided) starting from the *nextSibling* of the starting element(s), all the way across to the last *nextSibling*.\n\nIf no `index` or `selector` is given then you get just the *nextSibling*s of the elements; i.e. you shift *across* by one.\n\nIf just an `index` is provided then you'll get the `index+1` *nextSibling*s of the element(s). i.e. `index` is 0-based, like arrays, 0 is *nextSibling* and 1 is *nextSibling.nextSibling*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching *nextSibling* elements.\n\n#### Examples ####\n\n```js\ntraversty('li:first-child').next();\n  // →  returns the second `<li>` of every list in the document\ntraversty('li.allstarts').next('li', 1);\n  // →  returns the `nextSibling` of the `nextSibling` of the starting elements\ntraversty('li:first-child').next('li');\n  // →  returns all `<li>` elements, except for the first-children of every lits in the document\n```\n\n--------------------------------------------------------\n<a name=\"previous\"></a>\n### previous([selector [, index = 0]])\n<code>traversty(elements).previous()</code> returns a new Traversty instance containing *previousSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nExactly the same as <a href=\"#next\"><code>next()</code></a> except it works on *previousSibling*, so you move *backwards* amongst sibling elements.\n\n#### Examples ####\n\n```js\ntraversty('li:nth-child(20)').previous();\n  // →  returns 19th child of the every list in the document (where it exists)\ntraversty('li.allstarts').previous('li', 1);\n  // →  returns the `previousSibling` of the `previousSibling` of the starting element\ntraversty('li:nth-child(20)').previous('.interesting');\n  // →  returns all `<li>` elements with class \"interesting\" up to the 19th child of every list\n  //     in the document where there are at least 20 children.\n```\n\n--------------------------------------------------------\n<a name=\"prev\"></a>\n### prev([selector [, index = 0]])\n<code>traversty(elements).prev()</code> is a simple alias for <a href=\"#previous\"><code>previous()</code></a>, provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"up\"></a>\n### up([selector [, index = 0]])\n<code>traversty(elements).up()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nSimilar to <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> except that it works on *parentNode*s and will continue all the up to the document root depending on what you're asking for.\n\nIf no `index` or `selector` is given then you get just the `parentNode*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *parentNode*s of the element. i.e. `index` is 0-based, like arrays, 0 is *parentNode* and 1 is *parentNode.parentNode*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching ancestor elements.\n\n#### Examples ####\n\n```js\ntraversty('li#start').up();\n  // →  returns the `<ul>` parent element\ntraversty('li.allstarts').up('ul', 1);\n  // →  returns the grandparent `<ul>` elements if the start elements are nested at two levels\ntraversty('li.allstarts').up('ul');\n  // →  returns all ancestor `<ul>` elements, no matter how deep the nesting\n```\n\n--------------------------------------------------------\n<a name=\"parents\"></a>\n### parents([selector = '*' [, index ]])\n<code>traversty(elements).parents()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#up\"><code>up()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nPerforms exactly the same as <a href=\"#up\"><code>up()</code></a>, *except*, the `'selector'` argument defaults to `'*'` which has the effect of matching *all* ancestor elements, not just the first one. `parents()` will return exactly the same collection as `up('*')`. Provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"closest\"></a>\n### closest([selector = '*' [, index = 0]])\n<code>traversty(elements).closest()</code> returns a new Traversty instance containing the elements and/or *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#parents\"><code>parents()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. the current element)\n\nPerforms exactly the same operation as <a href=\"#parents\"><code>parents()</code></a> except for two important differences:\n\n * Matching starts at the **current** elements rather than the direct parent elements. So a `closest('*')` will return the current elements because they match the selector `'*'`.\n * The `index` argument defaults to `0`, just like <a href=\"#up\"><code>up()</code></a>, so you will only get the first match. An index of `n`, you will get the *nth* match, start with the current elements.\n\n--------------------------------------------------------\n<a name=\"down\"></a>\n### down([selector [, index = 0]])\n<code>traversty(elements).down()</code> returns a new Traversty instance containing descendent elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nWhile `down()` is very similar to the other methods, it's perhaps best to think of it as what you might get with a `find()` method from a selector engine.\n\n`down()` works on elements **in document-order**, so it operates on child elements and children of children but it also moves through child-siblings on the way to children of children.\n\nThe following fragment should illustrate the `index`ing you get when you use `down()`:\n\n```html\n<ul id=\"root\">\n  <li>first</li>   <!-- 0 -->\n  <li>second</li>  <!-- 1 -->\n  <li>third        <!-- 2 -->\n    <ul>           <!-- 3 -->\n      <li>i</li>   <!-- 4 -->\n      <li>ii</li>  <!-- 5 -->\n      <li>iii</li> <!-- 6 -->\n    </ul>\n  </li>\n  <li>fourth</li>  <!-- 7 -->\n</ul>\n```\n\nSo\n\n```js\ntraversty('#root').down(5)\n  // →  will give you `<li>ii</li>`\ntraversty('#root').down('li', 5)\n  // →  will give you `<li>i</li>` because the `<ul>` is ignored\n```\n\nOf course `down()` works on multiple elements simultaneously just like the other methods.\n\n\n--------------------------------------------------------\n<a name=\"children\"></a>\n### children([selector [, index = 0]])\n<code>traversty(elements).children()</code> returns a new Traversty instance containing direct descendent (child) elements according to the arguments provided.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\ntraversty('#root > li').children()\n  // →  will give you *only* the second level `<ul>` element as it's\n  //    the only direct descendent of the top `<li>` elements\ntraversty('#root > li').children().children()\n  // →  will give you *only* the second level `<li>` elements and none\n  //    of their children\n```\n\n--------------------------------------------------------\n<a name=\"siblings\"></a>\n### siblings([selector [, index = 0]])\n<code>traversty(elements).siblings()</code> returns a new Traversty instance containing *previousSibling* and *nextSibling* elements according to the arguments provided. It's important to note that the resulting collection **will not** include the original elements unless they are siblings of each other. To illustrate:\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root :nth-child(2)').siblings()\n  // →  will give you all `<li>` elements except the second\ntraversty('#root :nth-child(2n)').siblings()\n  // →  will give you all `<li>` elements because they are all siblings of\n  //    the original collection's elements\n```\n\n`siblings()` is the only method in Traversty that is not guaranteed to return a collection of elements in document-order (i.e. in the order they appear in the HTML). If you call `siblings()` on elements that are already siblings then the collection mechanism may mean that the results are out of order. Generally this shouldn't matter but you are warned if order matters to you for some reason.\n\n\n--------------------------------------------------------\n<a name=\"first\"></a>\n### first()\n<code>traversty(elements).first()</code> returns a new Traversty instance containing *only* the first element in the original collection.\n\n--------------------------------------------------------\n<a name=\"last\"></a>\n### last()\n<code>traversty(elements).last()</code> returns a new Traversty instance containing *only* the last element in the original collection.\n\n--------------------------------------------------------\n<a name=\"eq\"></a>\n### eq(index)\n<code>traversty(elements).eq()</code> returns a new Traversty instance containing *only* the element at the index specified.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection.\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root li').eq(1)\n  // →  will give you `<li>second</li>`\ntraversty('#root li').eq(-2)\n  // →  will give you `<li>third</li>`\n```\n\n--------------------------------------------------------\n<a name=\"slice\"></a>\n### slice(start [, end])\n<code>traversty(elements).slice()</code> returns a new Traversty instance containing *only* the elements between the `start` and `end` indexes. The `end` is optional, if left out then elements from `start` to the end of the collection are included.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection. See the example above for <a href=\"#eq\"><code>eq()</code></a> for how this works.\n\n--------------------------------------------------------\n<a name=\"filter\"></a>\n### filter(selector | function | element)\n<code>traversty(elements).filter()</code> returns a new Traversty instance containing *only* the elements that satisfy the filter condition.\n\nA `selector` string argument will simply check each element against the selector and return only elements that match.\n\nA `function` argument will execute that function for each element in the collection and return only elements for which it receives a *truthy* response from the function. `this` within the function will be the element being checked and the single argument to the function will be the index within the collection.\n\nAn `element` argument will return a collection containing only that DOM element *only if * it exists within the collection.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendent elements under #root\nels = els.filter('li')\n  // →  returns only the 8 `<li>` elements within the collection\nels = els.filter(function () { return /^i/.test(this.innerHTML) })\n  // →  returns only the 3 `<li>` elements start have content starting with 'i'\n  //    i.e. only 'ii', 'iii' and 'iv' (not 'i')\nels = els.filter(traversty('#root ul > li')[1])\n  // →  we're using `traversty()` here as a simple selector to fetch the 'iii' element\n  //    which we pass in to `filter()`. Because this element is in the collection we get\n  //    back a collection with only this element.\n```\n\n--------------------------------------------------------\n<a name=\"not\"></a>\n### not(selector | function | element)\n<code>traversty(elements).not()</code> returns a new Traversty instance containing *only* the elements that **do not** satisfy the filter condition.\n\n`not()` is the exact inverse of <a href=\"#filter\"><code>filter()</code></a>, it takes the same arguments but returns only elements that don't match your conditions.\n\n--------------------------------------------------------\n<a name=\"has\"></a>\n### has(selector | element)\n<code>traversty(elements).has()</code> returns a new Traversty instance containing *only* the elements that have descendent elements that match the provided `selector` argument, or have `element` as a descendent element.\n\nIf a `selector` string argument is provided, each element in the collection effectively has a `find(selector)`-type operation performed on it, if any matching descendent elements are found, the parent element is retained for the new collection; otherwise it is not included.\n\nIf an `element` argument is provided then the only element included in the resulting collection is an ancestor of that `element`, if the `element` is not a descendent of any of the elements in the collection then the resulting collection will be empty.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendent elements under #root\nels = els.has('li')\n  // →  returns a collection of 4 elements which have `<li>` descendents: the 'first' `<li>`,\n  //    the `<ul>` directly under it, the 'ii' `<li>` and the `<ul>` directly under that.\nels.has(traversty('#root a')[0])\n  // →  we're using `traversty()` here as a simple selector to fetch the `<a>` element\n  //    which we pass in to `has()`. There are two elements that have this single element\n  //    as a descendent, the 'first' `<li>` element and the `<ul>` directly under it.\n```\n\n--------------------------------------------------------\n<a name=\"is\"></a>\n### is(selector | function | element)\n<code>traversty(elements).is()</code> returns a **boolean** indicating whether at least one of the elements within the collection matches the condition. The method should be thought of as a version of <a href=\"#filter\"><code>filter()</code></a> that returns a boolean if the resulting collection has at least one element; i.e. `traversty(elements).filter(condition).length > 0`.\n\n\n--------------------------------------------------------\n<a name=\"each\"></a>\n### each(function [, thisContext])\n<code>traversty(elements).each()</code> will execute the provided `function` on each of the elements in the current collection. `each()` will return the original collection so you can continue chaining method calls.\n\nYour `function` will be called with `this` equal to the individual elements or the `thisContext` argument if supplied. The arguments provided to the function are:\n\n1. `element`: the current element in the collection\n2. `index`: the index of the current element in the collection\n3. `collection`: the entire Traversty object for this collection\n\nNote the ordering of arguments 1 and 2 are different to the <a href=\"http://api.jquery.com/each/\"><code>jQuery().each()</code></a>, instead Traversty is closer to ES5 <a href=\"https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/forEach\"><code>Array.prototype.forEach</code></a>.\n\n```js\ntraversty('li').each(function (el, i) {\n  this.innerHTML += ' (I am ' + i + ')'\n})\n```\n\n--------------------------------------------------------\n<a name=\"get\"></a>\n### get(index)\n<code>traversty(elements).get()</code> returns a single DOM element at the specified index of the collection. Indexes are zero-based and can be negative. See <a href=\"#eq\"><code>eq()</code></a> for specifics.\n\n\n--------------------------------------------------------\n<a name=\"toArray\"></a>\n### toArray()\n<code>traversty(elements).toArray()</code> returns a true `Array` object containing elements within the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array) for details on what you get.\n\n\n--------------------------------------------------------\n<a name=\"size\"></a>\n### size()\n<code>traversty(elements).size()</code> returns an number indicating the number of elements in the collection. Works exactly the same as `.length` on an `Array` (indeed, you can call `.length` on a Traversty object and get the same value).\n\n\n--------------------------------------------------------\n<a name=\"push\"></a>\n### push(element1 [, element2 [...]])\n<code>traversty(elements).push()</code> reuses `Array.prototype.push`. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/push) for details.\n\nBeware of pushing non-DOM elements onto a Traversty object! This is not supported behaviour.\n\n\n--------------------------------------------------------\n<a name=\"sort\"></a>\n### sort([compareFunction])\n<code>traversty(elements).sort()</code> reuses `Array.prototype.sort` to sort the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort) for details.\n\n\n--------------------------------------------------------\n<a name=\"splice\"></a>\n### splice(index, howMany [, element1 [...]])\n<code>traversty(elements).splice()</code> reuses `Array.prototype.splice` to splice the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/splice) for details.\n\n\n--------------------------------------------------------\n<a name=\"aug\"></a>\n### aug(methodMap)\n<code>traversty.aug()</code> extends Traversty's functionality with custom methods off the main Traversty prototype. The `methodMap` is simply a map of method names to functions. The functions will respond when called off a collection: `traversty().method(args)`.\n\n```js\ntraversty.aug({ append: function (element) {\n  // make sure we return 'this', which we can get from each()\n  return this.each(function (el, i) {\n    // append original to first element, append a clone to the rest\n    el.appendChild(i > 0 ? element.cloneNode(true) : element)\n  })\n}})\n\nvar span = document.createElement('span')\nspan.innerHTML = 'BOOM!'\ntraversty('li').append(span)\n```\n\n\n--------------------------------------------------------\n<a name=\"setSelectorEngine\"></a>\n### setSelectorEngine(selectorEngine)\n<code>traversty.setSelectorEngine()</code> injects a selector engine for Traversty to use. See the next section for details.\n\n## Selector engines\n\nTraversty should work out-of-the-box on modern browsers as it leverages native `querySelectorAll()` and `matchesSelector()` where they exist. This means that you should be able to use Traversty without a selector engine on most smartphone browsers without any problems.\n\nUnfortunately, this doesn't work with older browsers, particularly IE8 and below. While IE8 has a CSS2-compliant `querySelectorAll()`, it doesn't have a `matchesSelector()` which Traversty makes heavy use of.\n\nTraversty allows you to plug in your favourite selector engine so it can work on whatever browsers your engine supports. Traversty is tested to support [Qwery](https://github.com/ded/qwery), [Sel](https://github.com/amccollum/sel), [Sizzle](https://github.com/jquery/sizzle) and [NWMatcher](https://github.com/dperini/nwmatcher).\n\nTraversty uses *feature detection* to figure out how to use your selector engine, it tries to find the method used to *find* elements given a element root and the method used to determine if an element *matches* a given selector. If it can't figure out how to use your selector engine then you just need to pretend that it works like one of the supported ones and it should be OK.\n\nFor example:\n\n```js\ntraversty.setSelectorEngine({\n    select: function(selector, root) {\n      return MyEngine(selector, root);\n    }\n  , is: function(selector, root) {\n      return MyEngine(root).isTheSameAs(selector);\n    }\n});\n```\n\nTraversty will also do some trickery to make up for deficiencies in some selector engines, such as out-of-order results when selecting on groups ('a,b').\n\nIf you have a new selector engine that you want Traversty to support then either let me know or fork, patch and submit.\n\n\n## I want a demo!\n\nYou'll have to make do with the integration tests. [Here](http://rvagg.github.com/traversty/test/integration/ender_qwery.html) is Traversty running in an Ender build with Qwery and Bonzo. You can also see it running with [Sel](http://rvagg.github.com/traversty/test/integration/ender_sel.html), [Sizzle](http://rvagg.github.com/traversty/test/integration/ender_sizzle.html), [NWMatcher](http://rvagg.github.com/traversty/test/integration/ender_nwmatcher.html) and [without a selector engine](http://rvagg.github.com/traversty/test/integration/ender_sel.html) (works in modern browsers, including IE9+).\n\nView-source to see what it's doing, note that it's operating on 2 lists at the same time.\n\n\n## Things to note\n\n * Traversty always does a **uniqueness** check on its collection of elements so you should never end up with duplicates. If you do a `traversty('body,ul').down('li')` you would still only get a unique list of all *<li>* elements in the document.\n\n * Traversty ignores text and comment nodes and should only ever operate on the DOM element nodes you would expect (i.e. with `.nodeType === 1`).\n\n * Traversty currently orders results (for each element in the starting list) in document-order, so `previous('*')` will give you results starting from the *firstChild* of the parent element up to the *previousSibling* of the starting element, rather than starting with the *previousSibling* and listing backwards (this doesn't impact on indexing, which still works backwards, only the order of result lists). The single **exception** to this is <a href=\"#siblings\"><code>siblings()</code></a>, see the note in that section for details.\n\n## Supported browsers\n\nTraversty is tested with IE6+, Firefox 3+, Safari 4+, Opera current and Chrome current. You'll need a supported selector engine to operate on some of these older browsers.\n\n\n## Ender integration\n\nTraversty is designed to be inserted into an Ender build. It's in npm so simply include it in your build command, something like: `ender build sel bonzo traversty`\n\nTraversty will attempt to use whatever selector engine you've included in your Ender build.\n\n### What about Bonzo?\n\nTraversty is designed to add to the goodness you get in Bonzo, although Bonzo isn't a dependency. Bonzo has `next()` and `previous()` and a few other methods already and it is intended that Traversty replace these in your Ender build (because they are way-better!). Argument-less they should do exactly the same thing but Traversty adds the extra arguments for greater flexibility. If you are using Bonzo in Ender along with Traversty then you should make sure Traversty is included *after* Bonzo. Unfortunately, [Ender doesn't guarantee order](https://github.com/ender-js/Ender/issues/63) so you may have to fiddle a bit. The Ender 1.0 CLI does correct ordering but that's not formally released yet, you can use it by installing ender via npm with `npm install ender@dev`.\n\n\n## Contributing\n\nAwesome! Just do it, fork and submit your pull requests and they will be promptly considered.\n\nI'd also love it if you could contribute tests for bugs you find or features you add.\n\n### Tests\n\nTraversty uses [Buster](http://busterjs.org) for unit testing.\n\nSince Buster is still in Beta, the capture-server/client is a bit buggy and can be frustrating. So, instead, simply run *index.html* file in the *tests* directory in each of the browsers you need to test. It'll load and run all of the tests.\n\n\n## Credits\n\n * Firstly, much credit should go to the awesome Prototype guys and their excellent API that I've ripped off.\n * Thanks to [@ded](http://github.com/ded) and [@fat](http://github.com/fat) for Ender, particularly @ded for Bonzo, upon which Traversty is designed to build.\n\n\n## Licence\n\nTraversty is Copyright (c) 2012 Rod Vagg [@rvagg](https://twitter.com/rvagg) and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.","readmeFilename":"README.md","_id":"traversty@1.0.0","dist":{"shasum":"63d8fb8c545898ef819a4e6e007fa1085292a65e","tarball":"https://registry.npmjs.org/traversty/-/traversty-1.0.0.tgz","integrity":"sha512-+dZM8amvQrm5fhuOFklWzwfSyNveMP7JuiIY92kf44ssVWxyP7nUljKxLAXzySqs54YZ2ZFeiwAg1ADVL0FSvQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCyAzzVykhte2I6Llif0bvLGsOqQkn+FSVynfmcrqWlewIgEYVX1DhPulf5wgmrqwGSWEsi+DmArElXnzWJ3CZYGRM="}]},"_npmVersion":"1.1.65","_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"1.0.1":{"name":"traversty","description":"Library agnostic utility for DOM collection management and traversal","version":"1.0.1","homepage":"https://github.com/rvagg/traversty","authors":["Rod Vagg @rvagg <rod@vagg.org> (https://github.com/rvagg)"],"keywords":["ender","dom","nodes","traversal"],"main":"./traversty.js","ender":"./ender_bridge.js","repository":{"type":"git","url":"https://github.com/rvagg/traversty.git"},"devDependencies":{"buster":"*"},"license":"MIT","readme":"# Traversty &mdash; headache-free DOM collection management and traversal\n\nTraversty is a library-agnostic DOM utility for traversal and element collection manipulation. Traversty doesn't provide any DOM manipulation features, instead, Traversty is used for managing collections of DOM elements and navigating the DOM.\n\n<a href=\"#api\"><i>Just show me the API!</i></a>\n\n## Traversal\n\nThe core DOM traversal methods are inspired by [Prototype](http://prototypejs.org)'s excelent \"DOM traversal toolkit\", you get <a href=\"#up\"><code>up()</code></a>, <a href=\"#down\"><code>down()</code></a>, <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> with optional `selector` and `index` arguments, all in a multi-element environment&mdash;jQuery-like rather than Prototype's single-element implementation.\n\nIn addition, jQuery-compatible traversal methods extend this functionality: <a href=\"#parents\"><code>parents()</code></a>, <a href=\"#closest\"><code>closest()</code></a>, <a href=\"#children\"><code>children()</code></a>, <a href=\"#siblings\"><code>siblings()</code></a> and <a href=\"#prev\"><code>prev()</code></a> a simple alias for <a href=\"#previous\"><code>previous()</code></a>.\n\n## Collection filtering\n\nTraversty operates on DOM element collections, jQuery-style, so it also gives you methods to filter and manipulate that collection. The filtering methods are designed to be jQuery-compatible. You get: <a href=\"#first\"><code>first()</code></a>, <a href=\"#last\"><code>last()</code></a>, <a href=\"#eq\"><code>eq()</code></a>, <a href=\"#not\"><code>not()</code></a>, <a href=\"#slice\"><code>slice()</code></a>, <a href=\"#filter\"><code>filter()</code></a>, <a href=\"#has\"><code>has()</code></a> and <a href=\"#is\"><code>is()</code></a> (this last method returns a boolean rather than a collection).\n\nTraversty emulates an Array and includes additional methods to help you manage it as if it were one: <a href=\"#get\"><code>get()</code></a>, <a href=\"#toArray\"><code>toArray()</code></a>, <a href=\"#size\"><code>size()</code></a>, <a href=\"#push\"><code>push()</code></a>, <a href=\"#sort\"><code>sort()</code></a>, <a href=\"#splice\"><code>splice()</code></a>.\n\nTraversty is designed to be integrated in an [Ender](http://ender.no.de/) build, to augment what's already available in [Bonzo](https://github.com/ded/bonzo) but can just as easily be used as a stand-alone utility.\n\n## Example usage\n\nThis bit of crazyness comes from Traversty's integration tests. The bulk of this code is used to test Traversty's integration with Ender where the `css()` method is provided by [Bonzo](https://github.com/ded/bonzo) but there is also a [vanilla version](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) with only [Qwery](https://github.com/ded/qwery) for the selector engine and a `css()` method added using Traversty's <a href=\"#aug\"><code>aug()</code></a> method (see the [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) file for how this is done).\n\n```js\nvar $ = traversty\n$.setSelectorEngine(qwery)\n$('#fixtures > ul') // Traversty operates on collecitons of elements\n  .down(0).css('color', 'red')\n  .next('li', 1).css('color', 'green')\n  .next().down('li', 2).css('color', 'blue')\n  .next().down().css('color', 'yellow')\n  .up(2).next().css('color', 'purple')\n  .siblings(3).css('fontWeight', 'bold')\n  .children().css('textDecoration', 'underline')\n  .children(1).css('borderLeft', 'solid 5px red')\n  .parents('*').filter('ul').css('borderTop', 'dashed 2px green')\n  .not('.second').css('borderBottom', 'solid 3px blue')\n  .down('.second li').has('span').css('marginTop', '10px')\n  .up('ul').eq(-1).css('borderLeft', 'solid 5px orange')\n  .closest('#fixtures').down('li').slice(-10,-9).css('fontSize', '25px')\n  // Note: the css() method is not native to Traversty but is added with aug()\n```\n\nThe return type from the `traversty()` method is not a true `Array` but can be used like an array in almost all respects, it has `.length` and `[]` subscript element access and other standard `Array` methods.\n\n<a href=\"#api\"></a>\n## API\n\n  * <a href=\"#ctor\"><code><b>traversty()</b></code></a>\n  * <a href=\"#next\"><code>traversty().<b>next()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>previous()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>prev()</b></code></a>\n  * <a href=\"#up\"><code>traversty().<b>up()</b></code></a>\n  * <a href=\"#parents\"><code>traversty().<b>parents()</b></code></a>\n  * <a href=\"#closest\"><code>traversty().<b>closest()</b></code></a>\n  * <a href=\"#down\"><code>traversty().<b>down()</b></code></a>\n  * <a href=\"#children\"><code>traversty().<b>children()</b></code></a>\n  * <a href=\"#siblings\"><code>traversty().<b>siblings()</b></code></a>\n  * <a href=\"#first\"><code>traversty().<b>first()</b></code></a>\n  * <a href=\"#last\"><code>traversty().<b>last()</b></code></a>\n  * <a href=\"#eq\"><code>traversty().<b>eq()</b></code></a>\n  * <a href=\"#slice\"><code>traversty().<b>slice()</b></code></a>\n  * <a href=\"#filter\"><code>traversty().<b>filter()</b></code></a>\n  * <a href=\"#not\"><code>traversty().<b>not()</b></code></a>\n  * <a href=\"#has\"><code>traversty().<b>has()</b></code></a>\n  * <a href=\"#is\"><code>traversty().<b>is()</b></code></a>\n  * <a href=\"#get\"><code>traversty().<b>get()</b></code></a>\n  * <a href=\"#each\"><code>traversty().<b>each()</b></code></a>\n  * <a href=\"#toArray\"><code>traversty().<b>toArray()</b></code></a>\n  * <a href=\"#size\"><code>traversty().<b>size()</b></code></a>\n  * <a href=\"#push\"><code>traversty().<b>push()</b></code></a>\n  * <a href=\"#sort\"><code>traversty().<b>sort()</b></code></a>\n  * <a href=\"#splice\"><code>traversty().<b>splice()</b></code></a>\n  * <a href=\"#aug\"><code>traversty.<b>aug()</b></code></a>\n  * <a href=\"#setSelectorEngine\"><code>traversty.<b>setSelectorEngine()</b></code></a>\n  * <a href=\"#noConflict\"><code>traversty.<b>noConflict()</b></code></a>\n\n--------------------------------------------------------\n<a name=\"ctor\"></a>\n### traversty(element | elements | selector)\n<code>traversty()</code> gives you a new Traversty instance containing the elements you provide.\n\nOnce you have a collection, you can call any of the Traversty methods on that collection. You can give a single DOM element or an array of DOM elements. If you provide a string argument it will be used as a selector to either query the DOM via the browser's native `querySelectorAll()` implementation or use a selector engine which you provide (see <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a>).\n\nYou can pluck individual elements with array accessors (subscript), e.g. `traversty(document.body)[0] // → document.body` \n\nWhen included in an Ender build, `$(element | elements | selector)` does the same thing and all the Traversty methods will be available on the resulting Ender object.\n\n--------------------------------------------------------\n<a name=\"next\"></a>\n### next([selector [, index = 0]])\n<code>traversty(elements).next()</code> returns a new Traversty instance containing *nextSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nYou will get elements that match the given *selector* (if provided) starting from the *nextSibling* of the starting element(s), all the way across to the last *nextSibling*.\n\nIf no `index` or `selector` is given then you get just the *nextSibling*s of the elements; i.e. you shift *across* by one.\n\nIf just an `index` is provided then you'll get the `index+1` *nextSibling*s of the element(s). i.e. `index` is 0-based, like arrays, 0 is *nextSibling* and 1 is *nextSibling.nextSibling*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching *nextSibling* elements.\n\n#### Examples ####\n\n```js\ntraversty('li:first-child').next();\n  // →  returns the second `<li>` of every list in the document\ntraversty('li.allstarts').next('li', 1);\n  // →  returns the `nextSibling` of the `nextSibling` of the starting elements\ntraversty('li:first-child').next('li');\n  // →  returns all `<li>` elements, except for the first-children of every lits in the document\n```\n\n--------------------------------------------------------\n<a name=\"previous\"></a>\n### previous([selector [, index = 0]])\n<code>traversty(elements).previous()</code> returns a new Traversty instance containing *previousSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nExactly the same as <a href=\"#next\"><code>next()</code></a> except it works on *previousSibling*, so you move *backwards* amongst sibling elements.\n\n#### Examples ####\n\n```js\ntraversty('li:nth-child(20)').previous();\n  // →  returns 19th child of the every list in the document (where it exists)\ntraversty('li.allstarts').previous('li', 1);\n  // →  returns the `previousSibling` of the `previousSibling` of the starting element\ntraversty('li:nth-child(20)').previous('.interesting');\n  // →  returns all `<li>` elements with class \"interesting\" up to the 19th child of every list\n  //     in the document where there are at least 20 children.\n```\n\n--------------------------------------------------------\n<a name=\"prev\"></a>\n### prev([selector [, index = 0]])\n<code>traversty(elements).prev()</code> is a simple alias for <a href=\"#previous\"><code>previous()</code></a>, provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"up\"></a>\n### up([selector [, index = 0]])\n<code>traversty(elements).up()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nSimilar to <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> except that it works on *parentNode*s and will continue all the up to the document root depending on what you're asking for.\n\nIf no `index` or `selector` is given then you get just the `parentNode*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *parentNode*s of the element. i.e. `index` is 0-based, like arrays, 0 is *parentNode* and 1 is *parentNode.parentNode*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching ancestor elements.\n\n#### Examples ####\n\n```js\ntraversty('li#start').up();\n  // →  returns the `<ul>` parent element\ntraversty('li.allstarts').up('ul', 1);\n  // →  returns the grandparent `<ul>` elements if the start elements are nested at two levels\ntraversty('li.allstarts').up('ul');\n  // →  returns all ancestor `<ul>` elements, no matter how deep the nesting\n```\n\n--------------------------------------------------------\n<a name=\"parents\"></a>\n### parents([selector = '*' [, index ]])\n<code>traversty(elements).parents()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#up\"><code>up()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nPerforms exactly the same as <a href=\"#up\"><code>up()</code></a>, *except*, the `'selector'` argument defaults to `'*'` which has the effect of matching *all* ancestor elements, not just the first one. `parents()` will return exactly the same collection as `up('*')`. Provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"closest\"></a>\n### closest([selector = '*' [, index = 0]])\n<code>traversty(elements).closest()</code> returns a new Traversty instance containing the elements and/or *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#parents\"><code>parents()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. the current element)\n\nPerforms exactly the same operation as <a href=\"#parents\"><code>parents()</code></a> except for two important differences:\n\n * Matching starts at the **current** elements rather than the direct parent elements. So a `closest('*')` will return the current elements because they match the selector `'*'`.\n * The `index` argument defaults to `0`, just like <a href=\"#up\"><code>up()</code></a>, so you will only get the first match. An index of `n`, you will get the *nth* match, start with the current elements.\n\n--------------------------------------------------------\n<a name=\"down\"></a>\n### down([selector [, index = 0]])\n<code>traversty(elements).down()</code> returns a new Traversty instance containing descendent elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nWhile `down()` is very similar to the other methods, it's perhaps best to think of it as what you might get with a `find()` method from a selector engine.\n\n`down()` works on elements **in document-order**, so it operates on child elements and children of children but it also moves through child-siblings on the way to children of children.\n\nThe following fragment should illustrate the `index`ing you get when you use `down()`:\n\n```html\n<ul id=\"root\">\n  <li>first</li>   <!-- 0 -->\n  <li>second</li>  <!-- 1 -->\n  <li>third        <!-- 2 -->\n    <ul>           <!-- 3 -->\n      <li>i</li>   <!-- 4 -->\n      <li>ii</li>  <!-- 5 -->\n      <li>iii</li> <!-- 6 -->\n    </ul>\n  </li>\n  <li>fourth</li>  <!-- 7 -->\n</ul>\n```\n\nSo\n\n```js\ntraversty('#root').down(5)\n  // →  will give you `<li>ii</li>`\ntraversty('#root').down('li', 5)\n  // →  will give you `<li>i</li>` because the `<ul>` is ignored\n```\n\nOf course `down()` works on multiple elements simultaneously just like the other methods.\n\n\n--------------------------------------------------------\n<a name=\"children\"></a>\n### children([selector [, index = 0]])\n<code>traversty(elements).children()</code> returns a new Traversty instance containing direct descendent (child) elements according to the arguments provided.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\ntraversty('#root > li').children()\n  // →  will give you *only* the second level `<ul>` element as it's\n  //    the only direct descendent of the top `<li>` elements\ntraversty('#root > li').children().children()\n  // →  will give you *only* the second level `<li>` elements and none\n  //    of their children\n```\n\n--------------------------------------------------------\n<a name=\"siblings\"></a>\n### siblings([selector [, index = 0]])\n<code>traversty(elements).siblings()</code> returns a new Traversty instance containing *previousSibling* and *nextSibling* elements according to the arguments provided. It's important to note that the resulting collection **will not** include the original elements unless they are siblings of each other. To illustrate:\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root :nth-child(2)').siblings()\n  // →  will give you all `<li>` elements except the second\ntraversty('#root :nth-child(2n)').siblings()\n  // →  will give you all `<li>` elements because they are all siblings of\n  //    the original collection's elements\n```\n\n`siblings()` is the only method in Traversty that is not guaranteed to return a collection of elements in document-order (i.e. in the order they appear in the HTML). If you call `siblings()` on elements that are already siblings then the collection mechanism may mean that the results are out of order. Generally this shouldn't matter but you are warned if order matters to you for some reason.\n\n\n--------------------------------------------------------\n<a name=\"first\"></a>\n### first()\n<code>traversty(elements).first()</code> returns a new Traversty instance containing *only* the first element in the original collection.\n\n--------------------------------------------------------\n<a name=\"last\"></a>\n### last()\n<code>traversty(elements).last()</code> returns a new Traversty instance containing *only* the last element in the original collection.\n\n--------------------------------------------------------\n<a name=\"eq\"></a>\n### eq(index)\n<code>traversty(elements).eq()</code> returns a new Traversty instance containing *only* the element at the index specified.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection.\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root li').eq(1)\n  // →  will give you `<li>second</li>`\ntraversty('#root li').eq(-2)\n  // →  will give you `<li>third</li>`\n```\n\n--------------------------------------------------------\n<a name=\"slice\"></a>\n### slice(start [, end])\n<code>traversty(elements).slice()</code> returns a new Traversty instance containing *only* the elements between the `start` and `end` indexes. The `end` is optional, if left out then elements from `start` to the end of the collection are included.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection. See the example above for <a href=\"#eq\"><code>eq()</code></a> for how this works.\n\n--------------------------------------------------------\n<a name=\"filter\"></a>\n### filter(selector | function | element)\n<code>traversty(elements).filter()</code> returns a new Traversty instance containing *only* the elements that satisfy the filter condition.\n\nA `selector` string argument will simply check each element against the selector and return only elements that match.\n\nA `function` argument will execute that function for each element in the collection and return only elements for which it receives a *truthy* response from the function. `this` within the function will be the element being checked and the single argument to the function will be the index within the collection.\n\nAn `element` argument will return a collection containing only that DOM element *only if * it exists within the collection.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendent elements under #root\nels = els.filter('li')\n  // →  returns only the 8 `<li>` elements within the collection\nels = els.filter(function () { return /^i/.test(this.innerHTML) })\n  // →  returns only the 3 `<li>` elements start have content starting with 'i'\n  //    i.e. only 'ii', 'iii' and 'iv' (not 'i')\nels = els.filter(traversty('#root ul > li')[1])\n  // →  we're using `traversty()` here as a simple selector to fetch the 'iii' element\n  //    which we pass in to `filter()`. Because this element is in the collection we get\n  //    back a collection with only this element.\n```\n\n--------------------------------------------------------\n<a name=\"not\"></a>\n### not(selector | function | element)\n<code>traversty(elements).not()</code> returns a new Traversty instance containing *only* the elements that **do not** satisfy the filter condition.\n\n`not()` is the exact inverse of <a href=\"#filter\"><code>filter()</code></a>, it takes the same arguments but returns only elements that don't match your conditions.\n\n--------------------------------------------------------\n<a name=\"has\"></a>\n### has(selector | element)\n<code>traversty(elements).has()</code> returns a new Traversty instance containing *only* the elements that have descendent elements that match the provided `selector` argument, or have `element` as a descendent element.\n\nIf a `selector` string argument is provided, each element in the collection effectively has a `find(selector)`-type operation performed on it, if any matching descendent elements are found, the parent element is retained for the new collection; otherwise it is not included.\n\nIf an `element` argument is provided then the only element included in the resulting collection is an ancestor of that `element`, if the `element` is not a descendent of any of the elements in the collection then the resulting collection will be empty.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendent elements under #root\nels = els.has('li')\n  // →  returns a collection of 4 elements which have `<li>` descendents: the 'first' `<li>`,\n  //    the `<ul>` directly under it, the 'ii' `<li>` and the `<ul>` directly under that.\nels.has(traversty('#root a')[0])\n  // →  we're using `traversty()` here as a simple selector to fetch the `<a>` element\n  //    which we pass in to `has()`. There are two elements that have this single element\n  //    as a descendent, the 'first' `<li>` element and the `<ul>` directly under it.\n```\n\n--------------------------------------------------------\n<a name=\"is\"></a>\n### is(selector | function | element)\n<code>traversty(elements).is()</code> returns a **boolean** indicating whether at least one of the elements within the collection matches the condition. The method should be thought of as a version of <a href=\"#filter\"><code>filter()</code></a> that returns a boolean if the resulting collection has at least one element; i.e. `traversty(elements).filter(condition).length > 0`.\n\n\n--------------------------------------------------------\n<a name=\"each\"></a>\n### each(function [, thisContext])\n<code>traversty(elements).each()</code> will execute the provided `function` on each of the elements in the current collection. `each()` will return the original collection so you can continue chaining method calls.\n\nYour `function` will be called with `this` equal to the individual elements or the `thisContext` argument if supplied. The arguments provided to the function are:\n\n1. `element`: the current element in the collection\n2. `index`: the index of the current element in the collection\n3. `collection`: the entire Traversty object for this collection\n\nNote the ordering of arguments 1 and 2 are different to the <a href=\"http://api.jquery.com/each/\"><code>jQuery().each()</code></a>, instead Traversty is closer to ES5 <a href=\"https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/forEach\"><code>Array.prototype.forEach</code></a>.\n\n```js\ntraversty('li').each(function (el, i) {\n  this.innerHTML += ' (I am ' + i + ')'\n})\n```\n\n--------------------------------------------------------\n<a name=\"get\"></a>\n### get(index)\n<code>traversty(elements).get()</code> returns a single DOM element at the specified index of the collection. Indexes are zero-based and can be negative. See <a href=\"#eq\"><code>eq()</code></a> for specifics.\n\n\n--------------------------------------------------------\n<a name=\"toArray\"></a>\n### toArray()\n<code>traversty(elements).toArray()</code> returns a true `Array` object containing elements within the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array) for details on what you get.\n\n\n--------------------------------------------------------\n<a name=\"size\"></a>\n### size()\n<code>traversty(elements).size()</code> returns an number indicating the number of elements in the collection. Works exactly the same as `.length` on an `Array` (indeed, you can call `.length` on a Traversty object and get the same value).\n\n\n--------------------------------------------------------\n<a name=\"push\"></a>\n### push(element1 [, element2 [...]])\n<code>traversty(elements).push()</code> reuses `Array.prototype.push`. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/push) for details.\n\nBeware of pushing non-DOM elements onto a Traversty object! This is not supported behaviour.\n\n\n--------------------------------------------------------\n<a name=\"sort\"></a>\n### sort([compareFunction])\n<code>traversty(elements).sort()</code> reuses `Array.prototype.sort` to sort the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort) for details.\n\n\n--------------------------------------------------------\n<a name=\"splice\"></a>\n### splice(index, howMany [, element1 [...]])\n<code>traversty(elements).splice()</code> reuses `Array.prototype.splice` to splice the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/splice) for details.\n\n\n--------------------------------------------------------\n<a name=\"aug\"></a>\n### aug(methodMap)\n<code>traversty.aug()</code> extends Traversty's functionality with custom methods off the main Traversty prototype. The `methodMap` is simply a map of method names to functions. The functions will respond when called off a collection: `traversty().method(args)`.\n\n```js\ntraversty.aug({ append: function (element) {\n  // make sure we return 'this', which we can get from each()\n  return this.each(function (el, i) {\n    // append original to first element, append a clone to the rest\n    el.appendChild(i > 0 ? element.cloneNode(true) : element)\n  })\n}})\n\nvar span = document.createElement('span')\nspan.innerHTML = 'BOOM!'\ntraversty('li').append(span)\n```\n\n\n--------------------------------------------------------\n<a name=\"setSelectorEngine\"></a>\n### setSelectorEngine(selectorEngine)\n<code>traversty.setSelectorEngine()</code> injects a selector engine for Traversty to use. See the next section for details.\n\n## Selector engines\n\nTraversty should work out-of-the-box on modern browsers as it leverages native `querySelectorAll()` and `matchesSelector()` where they exist. This means that you should be able to use Traversty without a selector engine on most smartphone browsers without any problems.\n\nUnfortunately, this doesn't work with older browsers, particularly IE8 and below. While IE8 has a CSS2-compliant `querySelectorAll()`, it doesn't have a `matchesSelector()` which Traversty makes heavy use of.\n\nTraversty allows you to plug in your favourite selector engine so it can work on whatever browsers your engine supports. Traversty is tested to support [Qwery](https://github.com/ded/qwery), [Sel](https://github.com/amccollum/sel), [Sizzle](https://github.com/jquery/sizzle), [NWMatcher](https://github.com/dperini/nwmatcher) and [Zest](https://github.com/chjj/zest).\n\nTraversty uses *feature detection* to figure out how to use your selector engine, it tries to find the method used to *find* elements given a element root and the method used to determine if an element *matches* a given selector. If it can't figure out how to use your selector engine then you just need to pretend that it works like one of the supported ones and it should be OK.\n\nFor example:\n\n```js\ntraversty.setSelectorEngine({\n    select: function(selector, root) {\n      return MyEngine(selector, root);\n    }\n  , is: function(selector, root) {\n      return MyEngine(root).isTheSameAs(selector);\n    }\n});\n```\n\nTraversty will also do some trickery to make up for deficiencies in some selector engines, such as out-of-order results when selecting on groups ('a,b').\n\nIf you have a new selector engine that you want Traversty to support then either let me know or fork, patch and submit.\n\n\n## I want a demo!\n\nYou'll have to make do with the integration tests:\n\n### Ender\n\n[Here](http://rvagg.github.com/traversty/test/integration/ender_qwery.html) is Traversty running in an Ender build with Qwery and Bonzo. You can also see it running with [Sel](http://rvagg.github.com/traversty/test/integration/ender_sel.html), [Sizzle](http://rvagg.github.com/traversty/test/integration/ender_sizzle.html), [NWMatcher](http://rvagg.github.com/traversty/test/integration/ender_nwmatcher.html) and [without a selector engine](http://rvagg.github.com/traversty/test/integration/ender_sel.html) (works in modern browsers, including IE9+).\n\nView-source to see what it's doing, note that it's operating on 2 lists at the same time.\n\n### Vanilla\n\n[Here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) is Traversty bundled with Qwery as the selector engine and the `css()` augmenting example code [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) performing the same integration tests. There is also the same example using Zest instead [here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_zest.html)\n\n## Things to note\n\n * Traversty always does a **uniqueness** check on its collection of elements so you should never end up with duplicates. If you do a `traversty('body,ul').down('li')` you would still only get a unique list of all *<li>* elements in the document.\n\n * Traversty ignores text and comment nodes and should only ever operate on the DOM element nodes you would expect (i.e. with `.nodeType === 1`).\n\n * Traversty currently orders results (for each element in the starting list) in document-order, so `previous('*')` will give you results starting from the *firstChild* of the parent element up to the *previousSibling* of the starting element, rather than starting with the *previousSibling* and listing backwards (this doesn't impact on indexing, which still works backwards, only the order of result lists). The single **exception** to this is <a href=\"#siblings\"><code>siblings()</code></a>, see the note in that section for details.\n\n## Supported browsers\n\nTraversty is tested with IE6+, Firefox 3+, Safari 4+, Opera current and Chrome current. You'll need a supported selector engine to operate on some of these older browsers.\n\n\n## Ender integration\n\nTraversty is designed to be inserted into an Ender build. It's in npm so simply include it in your build command, something like: `ender build sel bonzo traversty`\n\nTraversty will attempt to use whatever selector engine you've included in your Ender build.\n\n### What about Bonzo?\n\nTraversty is designed to add to the goodness you get in Bonzo, although Bonzo isn't a dependency. Bonzo has `next()` and `previous()` and a few other methods already and it is intended that Traversty replace these in your Ender build (because they are way-better!). Argument-less they should do exactly the same thing but Traversty adds the extra arguments for greater flexibility. If you are using Bonzo in Ender along with Traversty then you should make sure Traversty is included *after* Bonzo. Unfortunately, [Ender doesn't guarantee order](https://github.com/ender-js/Ender/issues/63) so you may have to fiddle a bit. The Ender 1.0 CLI does correct ordering but that's not formally released yet, you can use it by installing ender via npm with `npm install ender@dev`.\n\n\n## Contributing\n\nAwesome! Just do it, fork and submit your pull requests and they will be promptly considered.\n\nI'd also love it if you could contribute tests for bugs you find or features you add.\n\n### Tests\n\nTraversty uses [Buster](http://busterjs.org) for unit testing.\n\nSince Buster is still in Beta, the capture-server/client is a bit buggy and can be frustrating. So, instead, simply run *index.html* file in the *tests* directory in each of the browsers you need to test. It'll load and run all of the tests.\n\n\n## Credits\n\n * Firstly, much credit should go to the awesome Prototype guys and their excellent API that I've ripped off.\n * Thanks to [@ded](http://github.com/ded) and [@fat](http://github.com/fat) for Ender, particularly @ded for Bonzo, upon which Traversty is designed to build.\n\n\n## Licence\n\nTraversty is Copyright (c) 2012 Rod Vagg [@rvagg](https://twitter.com/rvagg) and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.","readmeFilename":"README.md","_id":"traversty@1.0.1","dist":{"shasum":"043ac1087e742549a2b7a758fc3139676c3f278f","tarball":"https://registry.npmjs.org/traversty/-/traversty-1.0.1.tgz","integrity":"sha512-0ygIQ7JF+MzrGITNm2h/2o/YNMalshFJr+AR8PzaA/km/Ed3bMVNOPtfx7fsPVt0z8GnhsRaNUdDUs7PlgnssA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIB4nQHfBTX8mdglYjQmY47z7VjcHGmIIVtjSf62dMcpHAiA7Hf6NAj1dJOggoHWc/r1UBiOzk2geuT8812wyHlHGhg=="}]},"_npmVersion":"1.1.65","_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"1.0.2":{"name":"traversty","description":"Library agnostic utility for DOM collection management and traversal","version":"1.0.2","homepage":"https://github.com/rvagg/traversty","authors":["Rod Vagg @rvagg <rod@vagg.org> (https://github.com/rvagg)"],"keywords":["ender","dom","nodes","traversal"],"main":"./traversty.js","ender":"./ender_bridge.js","repository":{"type":"git","url":"https://github.com/rvagg/traversty.git"},"devDependencies":{"buster":"*"},"license":"MIT","readme":"# Traversty &mdash; headache-free DOM collection management and traversal\n\nTraversty is a library-agnostic DOM utility for traversal and element collection manipulation. Traversty doesn't provide any DOM manipulation features, instead, Traversty is used for managing collections of DOM elements and navigating the DOM.\n\n<a href=\"#api\"><i>Just show me the API!</i></a>\n\n## Traversal\n\nThe core DOM traversal methods are inspired by [Prototype](http://prototypejs.org)'s excelent \"DOM traversal toolkit\", you get <a href=\"#up\"><code>up()</code></a>, <a href=\"#down\"><code>down()</code></a>, <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> with optional `selector` and `index` arguments, all in a multi-element environment&mdash;jQuery-like rather than Prototype's single-element implementation.\n\nIn addition, jQuery-compatible traversal methods extend this functionality: <a href=\"#parents\"><code>parents()</code></a>, <a href=\"#closest\"><code>closest()</code></a>, <a href=\"#children\"><code>children()</code></a>, <a href=\"#siblings\"><code>siblings()</code></a> and <a href=\"#prev\"><code>prev()</code></a> a simple alias for <a href=\"#previous\"><code>previous()</code></a>.\n\n## Collection filtering\n\nTraversty operates on DOM element collections, jQuery-style, so it also gives you methods to filter and manipulate that collection. The filtering methods are designed to be jQuery-compatible. You get: <a href=\"#first\"><code>first()</code></a>, <a href=\"#last\"><code>last()</code></a>, <a href=\"#eq\"><code>eq()</code></a>, <a href=\"#not\"><code>not()</code></a>, <a href=\"#slice\"><code>slice()</code></a>, <a href=\"#filter\"><code>filter()</code></a>, <a href=\"#has\"><code>has()</code></a> and <a href=\"#is\"><code>is()</code></a> (this last method returns a boolean rather than a collection).\n\nTraversty emulates an Array and includes additional methods to help you manage it as if it were one: <a href=\"#get\"><code>get()</code></a>, <a href=\"#toArray\"><code>toArray()</code></a>, <a href=\"#size\"><code>size()</code></a>, <a href=\"#push\"><code>push()</code></a>, <a href=\"#sort\"><code>sort()</code></a>, <a href=\"#splice\"><code>splice()</code></a>.\n\n### Ender integration\n\nTraversty is designed to be integrated in an [Ender](http://ender.no.de/) build, to augment what's already available in [Bonzo](https://github.com/ded/bonzo) but can just as easily be used as a stand-alone utility.\n\n```\n$ ender build jeesh traversty\n```\n\n### Component integration\n\nYou can also install Traversty as a [component](https://github.com/component/component):\n\n```\n$ component install rvagg/traversty\n```\n\nWiring up a selector engine is let to you in your component build. You'll need to make one-off call to `setSelectorEngine()` once you have a selector engine to inject, otherwise Traversty will simply use native `querySelectorAll()` and `matchesSelector()` if available. See the <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a> for more details on how this works.\n\n```js\nvar zest = require('zest')\n  , $ = require('traversty').setSelectorEngine(zest)\n```\n\n## Example usage\n\nThis bit of crazyness comes from Traversty's integration tests. The bulk of this code is used to test Traversty's integration with Ender where the `css()` method is provided by [Bonzo](https://github.com/ded/bonzo) but there is also a [vanilla version](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) with only [Qwery](https://github.com/ded/qwery) for the selector engine and a `css()` method added using Traversty's <a href=\"#aug\"><code>aug()</code></a> method (see the [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) file for how this is done).\n\n```js\nvar $ = traversty\n$.setSelectorEngine(qwery)\n$('#fixtures > ul') // Traversty operates on collecitons of elements\n  .down(0).css('color', 'red')\n  .next('li', 1).css('color', 'green')\n  .next().down('li', 2).css('color', 'blue')\n  .next().down().css('color', 'yellow')\n  .up(2).next().css('color', 'purple')\n  .siblings(3).css('fontWeight', 'bold')\n  .children().css('textDecoration', 'underline')\n  .children(1).css('borderLeft', 'solid 5px red')\n  .parents('*').filter('ul').css('borderTop', 'dashed 2px green')\n  .not('.second').css('borderBottom', 'solid 3px blue')\n  .down('.second li').has('span').css('marginTop', '10px')\n  .up('ul').eq(-1).css('borderLeft', 'solid 5px orange')\n  .closest('#fixtures').down('li').slice(-10,-9).css('fontSize', '25px')\n  // Note: the css() method is not native to Traversty but is added with aug()\n```\n\nThe return type from the `traversty()` method is not a true `Array` but can be used like an array in almost all respects, it has `.length` and `[]` subscript element access and other standard `Array` methods.\n\n<a href=\"#api\"></a>\n## API\n\n  * <a href=\"#ctor\"><code><b>traversty()</b></code></a>\n  * <a href=\"#next\"><code>traversty().<b>next()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>previous()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>prev()</b></code></a>\n  * <a href=\"#up\"><code>traversty().<b>up()</b></code></a>\n  * <a href=\"#parents\"><code>traversty().<b>parents()</b></code></a>\n  * <a href=\"#closest\"><code>traversty().<b>closest()</b></code></a>\n  * <a href=\"#down\"><code>traversty().<b>down()</b></code></a>\n  * <a href=\"#children\"><code>traversty().<b>children()</b></code></a>\n  * <a href=\"#siblings\"><code>traversty().<b>siblings()</b></code></a>\n  * <a href=\"#first\"><code>traversty().<b>first()</b></code></a>\n  * <a href=\"#last\"><code>traversty().<b>last()</b></code></a>\n  * <a href=\"#eq\"><code>traversty().<b>eq()</b></code></a>\n  * <a href=\"#slice\"><code>traversty().<b>slice()</b></code></a>\n  * <a href=\"#filter\"><code>traversty().<b>filter()</b></code></a>\n  * <a href=\"#not\"><code>traversty().<b>not()</b></code></a>\n  * <a href=\"#has\"><code>traversty().<b>has()</b></code></a>\n  * <a href=\"#is\"><code>traversty().<b>is()</b></code></a>\n  * <a href=\"#get\"><code>traversty().<b>get()</b></code></a>\n  * <a href=\"#each\"><code>traversty().<b>each()</b></code></a>\n  * <a href=\"#toArray\"><code>traversty().<b>toArray()</b></code></a>\n  * <a href=\"#size\"><code>traversty().<b>size()</b></code></a>\n  * <a href=\"#push\"><code>traversty().<b>push()</b></code></a>\n  * <a href=\"#sort\"><code>traversty().<b>sort()</b></code></a>\n  * <a href=\"#splice\"><code>traversty().<b>splice()</b></code></a>\n  * <a href=\"#aug\"><code>traversty.<b>aug()</b></code></a>\n  * <a href=\"#setSelectorEngine\"><code>traversty.<b>setSelectorEngine()</b></code></a>\n  * <a href=\"#noConflict\"><code>traversty.<b>noConflict()</b></code></a>\n\n--------------------------------------------------------\n<a name=\"ctor\"></a>\n### traversty(element | elements | selector)\n<code>traversty()</code> gives you a new Traversty instance containing the elements you provide.\n\nOnce you have a collection, you can call any of the Traversty methods on that collection. You can give a single DOM element or an array of DOM elements. If you provide a string argument it will be used as a selector to either query the DOM via the browser's native `querySelectorAll()` implementation or use a selector engine which you provide (see <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a>).\n\nYou can pluck individual elements with array accessors (subscript), e.g. `traversty(document.body)[0] // → document.body` \n\nWhen included in an Ender build, `$(element | elements | selector)` does the same thing and all the Traversty methods will be available on the resulting Ender object.\n\n--------------------------------------------------------\n<a name=\"next\"></a>\n### next([selector [, index = 0]])\n<code>traversty(elements).next()</code> returns a new Traversty instance containing *nextSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nYou will get elements that match the given *selector* (if provided) starting from the *nextSibling* of the starting element(s), all the way across to the last *nextSibling*.\n\nIf no `index` or `selector` is given then you get just the *nextSibling*s of the elements; i.e. you shift *across* by one.\n\nIf just an `index` is provided then you'll get the `index+1` *nextSibling*s of the element(s). i.e. `index` is 0-based, like arrays, 0 is *nextSibling* and 1 is *nextSibling.nextSibling*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching *nextSibling* elements.\n\n#### Examples ####\n\n```js\ntraversty('li:first-child').next();\n  // →  returns the second `<li>` of every list in the document\ntraversty('li.allstarts').next('li', 1);\n  // →  returns the `nextSibling` of the `nextSibling` of the starting elements\ntraversty('li:first-child').next('li');\n  // →  returns all `<li>` elements, except for the first-children of every lits in the document\n```\n\n--------------------------------------------------------\n<a name=\"previous\"></a>\n### previous([selector [, index = 0]])\n<code>traversty(elements).previous()</code> returns a new Traversty instance containing *previousSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nExactly the same as <a href=\"#next\"><code>next()</code></a> except it works on *previousSibling*, so you move *backwards* amongst sibling elements.\n\n#### Examples ####\n\n```js\ntraversty('li:nth-child(20)').previous();\n  // →  returns 19th child of the every list in the document (where it exists)\ntraversty('li.allstarts').previous('li', 1);\n  // →  returns the `previousSibling` of the `previousSibling` of the starting element\ntraversty('li:nth-child(20)').previous('.interesting');\n  // →  returns all `<li>` elements with class \"interesting\" up to the 19th child of every list\n  //     in the document where there are at least 20 children.\n```\n\n--------------------------------------------------------\n<a name=\"prev\"></a>\n### prev([selector [, index = 0]])\n<code>traversty(elements).prev()</code> is a simple alias for <a href=\"#previous\"><code>previous()</code></a>, provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"up\"></a>\n### up([selector [, index = 0]])\n<code>traversty(elements).up()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nSimilar to <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> except that it works on *parentNode*s and will continue all the up to the document root depending on what you're asking for.\n\nIf no `index` or `selector` is given then you get just the `parentNode*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *parentNode*s of the element. i.e. `index` is 0-based, like arrays, 0 is *parentNode* and 1 is *parentNode.parentNode*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching ancestor elements.\n\n#### Examples ####\n\n```js\ntraversty('li#start').up();\n  // →  returns the `<ul>` parent element\ntraversty('li.allstarts').up('ul', 1);\n  // →  returns the grandparent `<ul>` elements if the start elements are nested at two levels\ntraversty('li.allstarts').up('ul');\n  // →  returns all ancestor `<ul>` elements, no matter how deep the nesting\n```\n\n--------------------------------------------------------\n<a name=\"parents\"></a>\n### parents([selector = '*' [, index ]])\n<code>traversty(elements).parents()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#up\"><code>up()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nPerforms exactly the same as <a href=\"#up\"><code>up()</code></a>, *except*, the `'selector'` argument defaults to `'*'` which has the effect of matching *all* ancestor elements, not just the first one. `parents()` will return exactly the same collection as `up('*')`. Provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"closest\"></a>\n### closest([selector = '*' [, index = 0]])\n<code>traversty(elements).closest()</code> returns a new Traversty instance containing the elements and/or *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#parents\"><code>parents()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. the current element)\n\nPerforms exactly the same operation as <a href=\"#parents\"><code>parents()</code></a> except for two important differences:\n\n * Matching starts at the **current** elements rather than the direct parent elements. So a `closest('*')` will return the current elements because they match the selector `'*'`.\n * The `index` argument defaults to `0`, just like <a href=\"#up\"><code>up()</code></a>, so you will only get the first match. An index of `n`, you will get the *nth* match, start with the current elements.\n\n--------------------------------------------------------\n<a name=\"down\"></a>\n### down([selector [, index = 0]])\n<code>traversty(elements).down()</code> returns a new Traversty instance containing descendent elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nWhile `down()` is very similar to the other methods, it's perhaps best to think of it as what you might get with a `find()` method from a selector engine.\n\n`down()` works on elements **in document-order**, so it operates on child elements and children of children but it also moves through child-siblings on the way to children of children.\n\nThe following fragment should illustrate the `index`ing you get when you use `down()`:\n\n```html\n<ul id=\"root\">\n  <li>first</li>   <!-- 0 -->\n  <li>second</li>  <!-- 1 -->\n  <li>third        <!-- 2 -->\n    <ul>           <!-- 3 -->\n      <li>i</li>   <!-- 4 -->\n      <li>ii</li>  <!-- 5 -->\n      <li>iii</li> <!-- 6 -->\n    </ul>\n  </li>\n  <li>fourth</li>  <!-- 7 -->\n</ul>\n```\n\nSo\n\n```js\ntraversty('#root').down(5)\n  // →  will give you `<li>ii</li>`\ntraversty('#root').down('li', 5)\n  // →  will give you `<li>i</li>` because the `<ul>` is ignored\n```\n\nOf course `down()` works on multiple elements simultaneously just like the other methods.\n\n\n--------------------------------------------------------\n<a name=\"children\"></a>\n### children([selector [, index = 0]])\n<code>traversty(elements).children()</code> returns a new Traversty instance containing direct descendent (child) elements according to the arguments provided.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\ntraversty('#root > li').children()\n  // →  will give you *only* the second level `<ul>` element as it's\n  //    the only direct descendent of the top `<li>` elements\ntraversty('#root > li').children().children()\n  // →  will give you *only* the second level `<li>` elements and none\n  //    of their children\n```\n\n--------------------------------------------------------\n<a name=\"siblings\"></a>\n### siblings([selector [, index = 0]])\n<code>traversty(elements).siblings()</code> returns a new Traversty instance containing *previousSibling* and *nextSibling* elements according to the arguments provided. It's important to note that the resulting collection **will not** include the original elements unless they are siblings of each other. To illustrate:\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root :nth-child(2)').siblings()\n  // →  will give you all `<li>` elements except the second\ntraversty('#root :nth-child(2n)').siblings()\n  // →  will give you all `<li>` elements because they are all siblings of\n  //    the original collection's elements\n```\n\n`siblings()` is the only method in Traversty that is not guaranteed to return a collection of elements in document-order (i.e. in the order they appear in the HTML). If you call `siblings()` on elements that are already siblings then the collection mechanism may mean that the results are out of order. Generally this shouldn't matter but you are warned if order matters to you for some reason.\n\n\n--------------------------------------------------------\n<a name=\"first\"></a>\n### first()\n<code>traversty(elements).first()</code> returns a new Traversty instance containing *only* the first element in the original collection.\n\n--------------------------------------------------------\n<a name=\"last\"></a>\n### last()\n<code>traversty(elements).last()</code> returns a new Traversty instance containing *only* the last element in the original collection.\n\n--------------------------------------------------------\n<a name=\"eq\"></a>\n### eq(index)\n<code>traversty(elements).eq()</code> returns a new Traversty instance containing *only* the element at the index specified.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection.\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root li').eq(1)\n  // →  will give you `<li>second</li>`\ntraversty('#root li').eq(-2)\n  // →  will give you `<li>third</li>`\n```\n\n--------------------------------------------------------\n<a name=\"slice\"></a>\n### slice(start [, end])\n<code>traversty(elements).slice()</code> returns a new Traversty instance containing *only* the elements between the `start` and `end` indexes. The `end` is optional, if left out then elements from `start` to the end of the collection are included.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection. See the example above for <a href=\"#eq\"><code>eq()</code></a> for how this works.\n\n--------------------------------------------------------\n<a name=\"filter\"></a>\n### filter(selector | function | element)\n<code>traversty(elements).filter()</code> returns a new Traversty instance containing *only* the elements that satisfy the filter condition.\n\nA `selector` string argument will simply check each element against the selector and return only elements that match.\n\nA `function` argument will execute that function for each element in the collection and return only elements for which it receives a *truthy* response from the function. `this` within the function will be the element being checked and the single argument to the function will be the index within the collection.\n\nAn `element` argument will return a collection containing only that DOM element *only if * it exists within the collection.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendent elements under #root\nels = els.filter('li')\n  // →  returns only the 8 `<li>` elements within the collection\nels = els.filter(function () { return /^i/.test(this.innerHTML) })\n  // →  returns only the 3 `<li>` elements start have content starting with 'i'\n  //    i.e. only 'ii', 'iii' and 'iv' (not 'i')\nels = els.filter(traversty('#root ul > li')[1])\n  // →  we're using `traversty()` here as a simple selector to fetch the 'iii' element\n  //    which we pass in to `filter()`. Because this element is in the collection we get\n  //    back a collection with only this element.\n```\n\n--------------------------------------------------------\n<a name=\"not\"></a>\n### not(selector | function | element)\n<code>traversty(elements).not()</code> returns a new Traversty instance containing *only* the elements that **do not** satisfy the filter condition.\n\n`not()` is the exact inverse of <a href=\"#filter\"><code>filter()</code></a>, it takes the same arguments but returns only elements that don't match your conditions.\n\n--------------------------------------------------------\n<a name=\"has\"></a>\n### has(selector | element)\n<code>traversty(elements).has()</code> returns a new Traversty instance containing *only* the elements that have descendent elements that match the provided `selector` argument, or have `element` as a descendent element.\n\nIf a `selector` string argument is provided, each element in the collection effectively has a `find(selector)`-type operation performed on it, if any matching descendent elements are found, the parent element is retained for the new collection; otherwise it is not included.\n\nIf an `element` argument is provided then the only element included in the resulting collection is an ancestor of that `element`, if the `element` is not a descendent of any of the elements in the collection then the resulting collection will be empty.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendent elements under #root\nels = els.has('li')\n  // →  returns a collection of 4 elements which have `<li>` descendents: the 'first' `<li>`,\n  //    the `<ul>` directly under it, the 'ii' `<li>` and the `<ul>` directly under that.\nels.has(traversty('#root a')[0])\n  // →  we're using `traversty()` here as a simple selector to fetch the `<a>` element\n  //    which we pass in to `has()`. There are two elements that have this single element\n  //    as a descendent, the 'first' `<li>` element and the `<ul>` directly under it.\n```\n\n--------------------------------------------------------\n<a name=\"is\"></a>\n### is(selector | function | element)\n<code>traversty(elements).is()</code> returns a **boolean** indicating whether at least one of the elements within the collection matches the condition. The method should be thought of as a version of <a href=\"#filter\"><code>filter()</code></a> that returns a boolean if the resulting collection has at least one element; i.e. `traversty(elements).filter(condition).length > 0`.\n\n\n--------------------------------------------------------\n<a name=\"each\"></a>\n### each(function [, thisContext])\n<code>traversty(elements).each()</code> will execute the provided `function` on each of the elements in the current collection. `each()` will return the original collection so you can continue chaining method calls.\n\nYour `function` will be called with `this` equal to the individual elements or the `thisContext` argument if supplied. The arguments provided to the function are:\n\n1. `element`: the current element in the collection\n2. `index`: the index of the current element in the collection\n3. `collection`: the entire Traversty object for this collection\n\nNote the ordering of arguments 1 and 2 are different to the <a href=\"http://api.jquery.com/each/\"><code>jQuery().each()</code></a>, instead Traversty is closer to ES5 <a href=\"https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/forEach\"><code>Array.prototype.forEach</code></a>.\n\n```js\ntraversty('li').each(function (el, i) {\n  this.innerHTML += ' (I am ' + i + ')'\n})\n```\n\n--------------------------------------------------------\n<a name=\"get\"></a>\n### get(index)\n<code>traversty(elements).get()</code> returns a single DOM element at the specified index of the collection. Indexes are zero-based and can be negative. See <a href=\"#eq\"><code>eq()</code></a> for specifics.\n\n\n--------------------------------------------------------\n<a name=\"toArray\"></a>\n### toArray()\n<code>traversty(elements).toArray()</code> returns a true `Array` object containing elements within the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array) for details on what you get.\n\n\n--------------------------------------------------------\n<a name=\"size\"></a>\n### size()\n<code>traversty(elements).size()</code> returns an number indicating the number of elements in the collection. Works exactly the same as `.length` on an `Array` (indeed, you can call `.length` on a Traversty object and get the same value).\n\n\n--------------------------------------------------------\n<a name=\"push\"></a>\n### push(element1 [, element2 [...]])\n<code>traversty(elements).push()</code> reuses `Array.prototype.push`. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/push) for details.\n\nBeware of pushing non-DOM elements onto a Traversty object! This is not supported behaviour.\n\n\n--------------------------------------------------------\n<a name=\"sort\"></a>\n### sort([compareFunction])\n<code>traversty(elements).sort()</code> reuses `Array.prototype.sort` to sort the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort) for details.\n\n\n--------------------------------------------------------\n<a name=\"splice\"></a>\n### splice(index, howMany [, element1 [...]])\n<code>traversty(elements).splice()</code> reuses `Array.prototype.splice` to splice the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/splice) for details.\n\n\n--------------------------------------------------------\n<a name=\"aug\"></a>\n### aug(methodMap)\n<code>traversty.aug()</code> extends Traversty's functionality with custom methods off the main Traversty prototype. The `methodMap` is simply a map of method names to functions. The functions will respond when called off a collection: `traversty().method(args)`.\n\n```js\ntraversty.aug({ append: function (element) {\n  // make sure we return 'this', which we can get from each()\n  return this.each(function (el, i) {\n    // append original to first element, append a clone to the rest\n    el.appendChild(i > 0 ? element.cloneNode(true) : element)\n  })\n}})\n\nvar span = document.createElement('span')\nspan.innerHTML = 'BOOM!'\ntraversty('li').append(span)\n```\n\n\n--------------------------------------------------------\n<a name=\"setSelectorEngine\"></a>\n### setSelectorEngine(selectorEngine)\n<code>traversty.setSelectorEngine()</code> injects a selector engine for Traversty to use. See the next section for details. Returns the main `Traversty` object for chainability, e.g.: `var $ = traversty.setSelectorEngine(qwery)`.\n\n## Selector engines\n\nTraversty should work out-of-the-box on modern browsers as it leverages native `querySelectorAll()` and `matchesSelector()` where they exist. This means that you should be able to use Traversty without a selector engine on most smartphone browsers without any problems.\n\nUnfortunately, this doesn't work with older browsers, particularly IE8 and below. While IE8 has a CSS2-compliant `querySelectorAll()`, it doesn't have a `matchesSelector()` which Traversty makes heavy use of.\n\nTraversty allows you to plug in your favourite selector engine so it can work on whatever browsers your engine supports. Traversty is tested to support [Qwery](https://github.com/ded/qwery), [Sel](https://github.com/amccollum/sel), [Sizzle](https://github.com/jquery/sizzle), [NWMatcher](https://github.com/dperini/nwmatcher) and [Zest](https://github.com/chjj/zest).\n\nTraversty uses *feature detection* to figure out how to use your selector engine, it tries to find the method used to *find* elements given a element root and the method used to determine if an element *matches* a given selector. If it can't figure out how to use your selector engine then you just need to pretend that it works like one of the supported ones and it should be OK.\n\nFor example:\n\n```js\ntraversty.setSelectorEngine({\n    select: function(selector, root) {\n      return MyEngine(selector, root);\n    }\n  , is: function(selector, root) {\n      return MyEngine(root).isTheSameAs(selector);\n    }\n});\n```\n\nTraversty will also do some trickery to make up for deficiencies in some selector engines, such as out-of-order results when selecting on groups ('a,b').\n\nIf you have a new selector engine that you want Traversty to support then either let me know or fork, patch and submit.\n\n\n## I want a demo!\n\nYou'll have to make do with the integration tests:\n\n### Ender\n\n[Here](http://rvagg.github.com/traversty/test/integration/ender_qwery.html) is Traversty running in an Ender build with Qwery and Bonzo. You can also see it running with [Sel](http://rvagg.github.com/traversty/test/integration/ender_sel.html), [Sizzle](http://rvagg.github.com/traversty/test/integration/ender_sizzle.html), [NWMatcher](http://rvagg.github.com/traversty/test/integration/ender_nwmatcher.html) and [without a selector engine](http://rvagg.github.com/traversty/test/integration/ender_sel.html) (works in modern browsers, including IE9+).\n\nView-source to see what it's doing, note that it's operating on 2 lists at the same time.\n\n### Vanilla\n\n[Here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) is Traversty bundled with Qwery as the selector engine and the `css()` augmenting example code [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) performing the same integration tests. There is also the same example using Zest instead [here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_zest.html)\n\n## Things to note\n\n * Traversty always does a **uniqueness** check on its collection of elements so you should never end up with duplicates. If you do a `traversty('body,ul').down('li')` you would still only get a unique list of all *<li>* elements in the document.\n\n * Traversty ignores text and comment nodes and should only ever operate on the DOM element nodes you would expect (i.e. with `.nodeType === 1`).\n\n * Traversty currently orders results (for each element in the starting list) in document-order, so `previous('*')` will give you results starting from the *firstChild* of the parent element up to the *previousSibling* of the starting element, rather than starting with the *previousSibling* and listing backwards (this doesn't impact on indexing, which still works backwards, only the order of result lists). The single **exception** to this is <a href=\"#siblings\"><code>siblings()</code></a>, see the note in that section for details.\n\n## Supported browsers\n\nTraversty is tested with IE6+, Firefox 3+, Safari 4+, Opera current and Chrome current. You'll need a supported selector engine to operate on some of these older browsers.\n\n\n## Ender integration\n\nTraversty is designed to be inserted into an Ender build. It's in npm so simply include it in your build command, something like: `ender build sel bonzo traversty`\n\nTraversty will attempt to use whatever selector engine you've included in your Ender build.\n\n### What about Bonzo?\n\nTraversty is designed to add to the goodness you get in Bonzo, although Bonzo isn't a dependency. Bonzo has `next()` and `previous()` and a few other methods already and it is intended that Traversty replace these in your Ender build (because they are way-better!). Argument-less they should do exactly the same thing but Traversty adds the extra arguments for greater flexibility. If you are using Bonzo in Ender along with Traversty then you should make sure Traversty is included *after* Bonzo. Unfortunately, [Ender doesn't guarantee order](https://github.com/ender-js/Ender/issues/63) so you may have to fiddle a bit. The Ender 1.0 CLI does correct ordering but that's not formally released yet, you can use it by installing ender via npm with `npm install ender@dev`.\n\n\n## Contributing\n\nAwesome! Just do it, fork and submit your pull requests and they will be promptly considered.\n\nI'd also love it if you could contribute tests for bugs you find or features you add.\n\n### Tests\n\nTraversty uses [Buster](http://busterjs.org) for unit testing.\n\nSince Buster is still in Beta, the capture-server/client is a bit buggy and can be frustrating. So, instead, simply run *index.html* file in the *tests* directory in each of the browsers you need to test. It'll load and run all of the tests.\n\n\n## Credits\n\n * Firstly, much credit should go to the awesome Prototype guys and their excellent API that I've ripped off.\n * Thanks to [@ded](http://github.com/ded) and [@fat](http://github.com/fat) for Ender, particularly @ded for Bonzo, upon which Traversty is designed to build.\n\n\n## Licence\n\nTraversty is Copyright (c) 2012 Rod Vagg [@rvagg](https://twitter.com/rvagg) and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.\n","readmeFilename":"README.md","_id":"traversty@1.0.2","dist":{"shasum":"c92a055e16314df2de874230c77137e2cbd00cb7","tarball":"https://registry.npmjs.org/traversty/-/traversty-1.0.2.tgz","integrity":"sha512-wqrvlcA2xj/AE/W9Unn8iAV9HfarDzfO0xpSxC37VcfFtZXiYTlmgIU9+ZZygzftv55YPKaaxcYGOdJjcNnTMQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIGe895Ol5eh9JSE0SL82hBr4na4oGqxRlpm0cje6Qc9hAiEAxzu9U5Ne7yAUBDEUc13vwgasrMfWb0Ssu54aFi01kUw="}]},"_npmVersion":"1.1.65","_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"1.0.3":{"name":"traversty","description":"Library agnostic utility for DOM collection management and traversal","version":"1.0.3","homepage":"https://github.com/rvagg/traversty","authors":["Rod Vagg @rvagg <rod@vagg.org> (https://github.com/rvagg)"],"keywords":["ender","dom","nodes","traversal"],"main":"./traversty.js","ender":"./ender_bridge.js","repository":{"type":"git","url":"https://github.com/rvagg/traversty.git"},"devDependencies":{"buster":"*","uglify-js":"*","colors-tmpl":"*"},"license":"MIT","readme":"# Traversty &mdash; headache-free DOM collection management and traversal\n\nTraversty is a library-agnostic DOM utility for traversal and element collection manipulation. Traversty doesn't provide any DOM manipulation features; instead, Traversty is used for managing collections of DOM elements and navigating the DOM.\n\n**Current file size:** 15.7 kB raw, 5.7 kB min, **2.1 kB gzip**\n\n<a href=\"#api\"><i>Just show me the API!</i></a>\n\n## Traversal\n\nThe core DOM traversal methods are inspired by [Prototype](http://prototypejs.org)'s excelent \"DOM traversal toolkit\", you get <a href=\"#up\"><code>up()</code></a>, <a href=\"#down\"><code>down()</code></a>, <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> with optional `selector` and `index` arguments, all in a multi-element environment&mdash;jQuery-like rather than Prototype's single-element implementation.\n\nIn addition, jQuery-compatible traversal methods extend this functionality: <a href=\"#parents\"><code>parents()</code></a>, <a href=\"#closest\"><code>closest()</code></a>, <a href=\"#children\"><code>children()</code></a>, <a href=\"#siblings\"><code>siblings()</code></a> and <a href=\"#prev\"><code>prev()</code></a> a simple alias for <a href=\"#previous\"><code>previous()</code></a>.\n\n## Collection filtering\n\nTraversty operates on DOM element collections, jQuery-style, so it also gives you methods to filter and manipulate that collection. The filtering methods are designed to be jQuery-compatible. You get: <a href=\"#first\"><code>first()</code></a>, <a href=\"#last\"><code>last()</code></a>, <a href=\"#eq\"><code>eq()</code></a>, <a href=\"#not\"><code>not()</code></a>, <a href=\"#slice\"><code>slice()</code></a>, <a href=\"#filter\"><code>filter()</code></a>, <a href=\"#has\"><code>has()</code></a> and <a href=\"#is\"><code>is()</code></a> (this last method returns a boolean rather than a collection).\n\nTraversty emulates an Array and includes additional methods to help you manage it as if it were one: <a href=\"#get\"><code>get()</code></a>, <a href=\"#toArray\"><code>toArray()</code></a>, <a href=\"#size\"><code>size()</code></a>, <a href=\"#push\"><code>push()</code></a>, <a href=\"#sort\"><code>sort()</code></a>, <a href=\"#splice\"><code>splice()</code></a>.\n\n### Ender integration\n\nTraversty is designed to be integrated in an [Ender](http://ender.no.de/) build, to augment what's already available in [Bonzo](https://github.com/ded/bonzo) but can just as easily be used as a stand-alone utility.\n\n```\n$ ender build jeesh traversty\n```\n\n### Component integration\n\nYou can also install Traversty as a [component](https://github.com/component/component):\n\n```\n$ component install rvagg/traversty\n```\n\nWiring in a selector engine is up to you in your component build. You'll need to make one-off call to `setSelectorEngine()` once you have a selector engine to inject, otherwise Traversty will simply use native `querySelectorAll()` and `matchesSelector()` if available. See the <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a> for more details on how this works.\n\n```js\nvar zest = require('zest')\n  , $ = require('traversty').setSelectorEngine(zest)\n```\n\n## Example usage\n\nThis bit of craziness comes from Traversty's integration tests. The bulk of this code is used to test Traversty's integration with Ender where the `css()` method is provided by [Bonzo](https://github.com/ded/bonzo) but there is also a [vanilla version](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) with only [Qwery](https://github.com/ded/qwery) for the selector engine and a `css()` method added using Traversty's <a href=\"#aug\"><code>aug()</code></a> method (see the [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) file for how this is done).\n\n```js\nvar $ = traversty\n$.setSelectorEngine(qwery)\n$('#fixtures > ul') // Traversty operates on collections of elements\n  .down(0).css('color', 'red')\n  .next('li', 1).css('color', 'green')\n  .next().down('li', 2).css('color', 'blue')\n  .next().down().css('color', 'yellow')\n  .up(2).next().css('color', 'purple')\n  .siblings(3).css('fontWeight', 'bold')\n  .children().css('textDecoration', 'underline')\n  .children(1).css('borderLeft', 'solid 5px red')\n  .parents('*').filter('ul').css('borderTop', 'dashed 2px green')\n  .not('.second').css('borderBottom', 'solid 3px blue')\n  .down('.second li').has('span').css('marginTop', '10px')\n  .up('ul').eq(-1).css('borderLeft', 'solid 5px orange')\n  .closest('#fixtures').down('li').slice(-10,-9).css('fontSize', '25px')\n  // Note: the css() method is not native to Traversty but is added with aug()\n```\n\nThe return type from the `traversty()` method is not a true `Array` but can be used like an array in almost all respects, it has `.length` and `[]` subscript element access and other standard `Array` methods.\n\n<a href=\"#api\"></a>\n## API\n\n  * <a href=\"#ctor\"><code><b>traversty()</b></code></a>\n  * <a href=\"#next\"><code>traversty().<b>next()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>previous()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>prev()</b></code></a>\n  * <a href=\"#up\"><code>traversty().<b>up()</b></code></a>\n  * <a href=\"#parents\"><code>traversty().<b>parents()</b></code></a>\n  * <a href=\"#closest\"><code>traversty().<b>closest()</b></code></a>\n  * <a href=\"#down\"><code>traversty().<b>down()</b></code></a>\n  * <a href=\"#children\"><code>traversty().<b>children()</b></code></a>\n  * <a href=\"#siblings\"><code>traversty().<b>siblings()</b></code></a>\n  * <a href=\"#first\"><code>traversty().<b>first()</b></code></a>\n  * <a href=\"#last\"><code>traversty().<b>last()</b></code></a>\n  * <a href=\"#eq\"><code>traversty().<b>eq()</b></code></a>\n  * <a href=\"#slice\"><code>traversty().<b>slice()</b></code></a>\n  * <a href=\"#filter\"><code>traversty().<b>filter()</b></code></a>\n  * <a href=\"#not\"><code>traversty().<b>not()</b></code></a>\n  * <a href=\"#has\"><code>traversty().<b>has()</b></code></a>\n  * <a href=\"#is\"><code>traversty().<b>is()</b></code></a>\n  * <a href=\"#get\"><code>traversty().<b>get()</b></code></a>\n  * <a href=\"#each\"><code>traversty().<b>each()</b></code></a>\n  * <a href=\"#toArray\"><code>traversty().<b>toArray()</b></code></a>\n  * <a href=\"#size\"><code>traversty().<b>size()</b></code></a>\n  * <a href=\"#push\"><code>traversty().<b>push()</b></code></a>\n  * <a href=\"#sort\"><code>traversty().<b>sort()</b></code></a>\n  * <a href=\"#splice\"><code>traversty().<b>splice()</b></code></a>\n  * <a href=\"#aug\"><code>traversty.<b>aug()</b></code></a>\n  * <a href=\"#setSelectorEngine\"><code>traversty.<b>setSelectorEngine()</b></code></a>\n  * <a href=\"#noConflict\"><code>traversty.<b>noConflict()</b></code></a>\n\n--------------------------------------------------------\n<a name=\"ctor\"></a>\n### traversty(element | elements | selector)\n<code>traversty()</code> gives you a new Traversty instance containing the elements you provide.\n\nOnce you have a collection, you can call any of the Traversty methods on that collection. You can give a single DOM element or an array of DOM elements. If you provide a string argument it will be used as a selector to either query the DOM via the browser's native `querySelectorAll()` implementation or use a selector engine which you provide (see <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a>).\n\nYou can pluck individual elements with array accessors (subscript), e.g. `traversty(document.body)[0] // → document.body` \n\nWhen included in an Ender build, `$(element | elements | selector)` does the same thing and all the Traversty methods will be available on the resulting Ender object.\n\n--------------------------------------------------------\n<a name=\"next\"></a>\n### next([selector [, index = 0]])\n<code>traversty(elements).next()</code> returns a new Traversty instance containing *nextSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nYou will get elements that match the given *selector* (if provided) starting from the *nextSibling* of the starting element(s), all the way across to the last *nextSibling*.\n\nIf no `index` or `selector` is given then you get just the *nextSibling*s of the elements; i.e. you shift *across* by one.\n\nIf just an `index` is provided then you'll get the `index+1` *nextSibling*s of the element(s). i.e. `index` is 0-based, like arrays, 0 is *nextSibling* and 1 is *nextSibling.nextSibling*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching *nextSibling* elements.\n\n#### Examples ####\n\n```js\ntraversty('li:first-child').next()\n  // →  returns the second `<li>` of every list in the document\ntraversty('li.allstarts').next('li', 1)\n  // →  returns the `nextSibling` of the `nextSibling` of the starting elements\ntraversty('li:first-child').next('li')\n  // →  returns all `<li>` elements, except for the first-children of every lits in the document\n```\n\n--------------------------------------------------------\n<a name=\"previous\"></a>\n### previous([selector [, index = 0]])\n<code>traversty(elements).previous()</code> returns a new Traversty instance containing *previousSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nExactly the same as <a href=\"#next\"><code>next()</code></a> except it works on *previousSibling*, so you move *backwards* amongst sibling elements.\n\n#### Examples ####\n\n```js\ntraversty('li:nth-child(20)').previous()\n  // →  returns 19th child of the every list in the document (where it exists)\ntraversty('li.allstarts').previous('li', 1)\n  // →  returns the `previousSibling` of the `previousSibling` of the starting element\ntraversty('li:nth-child(20)').previous('.interesting')\n  // →  returns all `<li>` elements with class \"interesting\" up to the 19th child of every list\n  //     in the document where there are at least 20 children.\n```\n\n--------------------------------------------------------\n<a name=\"prev\"></a>\n### prev([selector [, index = 0]])\n<code>traversty(elements).prev()</code> is a simple alias for <a href=\"#previous\"><code>previous()</code></a>, provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"up\"></a>\n### up([selector [, index = 0]])\n<code>traversty(elements).up()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nSimilar to <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> except that it works on *parentNode*s and will continue all the up to the document root depending on what you're asking for.\n\nIf no `index` or `selector` is given then you get just the `parentNode*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *parentNode*s of the element. i.e. `index` is 0-based, like arrays, 0 is *parentNode* and 1 is *parentNode.parentNode*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching ancestor elements.\n\n#### Examples ####\n\n```js\ntraversty('li#start').up()\n  // →  returns the `<ul>` parent element\ntraversty('li.allstarts').up('ul', 1)\n  // →  returns the grandparent `<ul>` elements if the start elements are nested at two levels\ntraversty('li.allstarts').up('ul')\n  // →  returns all ancestor `<ul>` elements, no matter how deep the nesting\n```\n\n--------------------------------------------------------\n<a name=\"parents\"></a>\n### parents([selector = '*' [, index ]])\n<code>traversty(elements).parents()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#up\"><code>up()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nPerforms exactly the same as <a href=\"#up\"><code>up()</code></a>, *except*, the `'selector'` argument defaults to `'*'` which has the effect of matching *all* ancestor elements, not just the first one. `parents()` will return exactly the same collection as `up('*')`. Provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"closest\"></a>\n### closest([selector = '*' [, index = 0]])\n<code>traversty(elements).closest()</code> returns a new Traversty instance containing the elements and/or *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#parents\"><code>parents()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. the current element)\n\nPerforms exactly the same operation as <a href=\"#parents\"><code>parents()</code></a> except for two important differences:\n\n * Matching starts at the **current** elements rather than the direct parent elements. So a `closest('*')` will return the current elements because they match the selector `'*'`.\n * The `index` argument defaults to `0`, just like <a href=\"#up\"><code>up()</code></a>, so you will only get the first match. An index of `n`, you will get the *nth* match, start with the current elements.\n\n--------------------------------------------------------\n<a name=\"down\"></a>\n### down([selector [, index = 0]])\n<code>traversty(elements).down()</code> returns a new Traversty instance containing descendant elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nWhile `down()` is very similar to the other methods, it's perhaps best to think of it as what you might get with a `find()` method from a selector engine.\n\n`down()` works on elements **in document-order**, so it operates on child elements and children of children but it also moves through child-siblings on the way to children of children.\n\nThe following fragment should illustrate the `index`ing you get when you use `down()`:\n\n```html\n<ul id=\"root\">\n  <li>first</li>   <!-- 0 -->\n  <li>second</li>  <!-- 1 -->\n  <li>third        <!-- 2 -->\n    <ul>           <!-- 3 -->\n      <li>i</li>   <!-- 4 -->\n      <li>ii</li>  <!-- 5 -->\n      <li>iii</li> <!-- 6 -->\n    </ul>\n  </li>\n  <li>fourth</li>  <!-- 7 -->\n</ul>\n```\n\nSo\n\n```js\ntraversty('#root').down(5)\n  // →  will give you `<li>ii</li>`\ntraversty('#root').down('li', 5)\n  // →  will give you `<li>i</li>` because the `<ul>` is ignored\n```\n\nOf course `down()` works on multiple elements simultaneously just like the other methods.\n\n\n--------------------------------------------------------\n<a name=\"children\"></a>\n### children([selector [, index = 0]])\n<code>traversty(elements).children()</code> returns a new Traversty instance containing direct descendant (child) elements according to the arguments provided.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\ntraversty('#root > li').children()\n  // →  will give you *only* the second level `<ul>` element as it's\n  //    the only direct descendant of the top `<li>` elements\ntraversty('#root > li').children().children()\n  // →  will give you *only* the second level `<li>` elements and none\n  //    of their children\n```\n\n--------------------------------------------------------\n<a name=\"siblings\"></a>\n### siblings([selector [, index = 0]])\n<code>traversty(elements).siblings()</code> returns a new Traversty instance containing *previousSibling* and *nextSibling* elements according to the arguments provided. It's important to note that the resulting collection **will not** include the original elements unless they are siblings of each other. To illustrate:\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root :nth-child(2)').siblings()\n  // →  will give you all `<li>` elements except the second\ntraversty('#root :nth-child(2n)').siblings()\n  // →  will give you all `<li>` elements because they are all siblings of\n  //    the original collection's elements\n```\n\n`siblings()` is the only method in Traversty that is not guaranteed to return a collection of elements in document-order (i.e. in the order they appear in the HTML). If you call `siblings()` on elements that are already siblings then the collection mechanism may mean that the results are out of order. Generally this shouldn't matter but you are warned if order matters to you for some reason.\n\n\n--------------------------------------------------------\n<a name=\"first\"></a>\n### first()\n<code>traversty(elements).first()</code> returns a new Traversty instance containing *only* the first element in the original collection.\n\n--------------------------------------------------------\n<a name=\"last\"></a>\n### last()\n<code>traversty(elements).last()</code> returns a new Traversty instance containing *only* the last element in the original collection.\n\n--------------------------------------------------------\n<a name=\"eq\"></a>\n### eq(index)\n<code>traversty(elements).eq()</code> returns a new Traversty instance containing *only* the element at the index specified.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection.\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root li').eq(1)\n  // →  will give you `<li>second</li>`\ntraversty('#root li').eq(-2)\n  // →  will give you `<li>third</li>`\n```\n\n--------------------------------------------------------\n<a name=\"slice\"></a>\n### slice(start [, end])\n<code>traversty(elements).slice()</code> returns a new Traversty instance containing *only* the elements between the `start` and `end` indexes. The `end` is optional, if left out then elements from `start` to the end of the collection are included.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection. See the example above for <a href=\"#eq\"><code>eq()</code></a> for how this works.\n\n--------------------------------------------------------\n<a name=\"filter\"></a>\n### filter(selector | function | element)\n<code>traversty(elements).filter()</code> returns a new Traversty instance containing *only* the elements that satisfy the filter condition.\n\nA `selector` string argument will simply check each element against the selector and return only elements that match.\n\nA `function` argument will execute that function for each element in the collection and return only elements for which it receives a *truthy* response from the function. `this` within the function will be the element being checked and the single argument to the function will be the index within the collection.\n\nAn `element` argument will return a collection containing only that DOM element *only if * it exists within the collection.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendant elements under #root\nels = els.filter('li')\n  // →  returns only the 8 `<li>` elements within the collection\nels = els.filter(function () { return /^i/.test(this.innerHTML) })\n  // →  returns only the 3 `<li>` elements start have content starting with 'i'\n  //    i.e. only 'ii', 'iii' and 'iv' (not 'i')\nels = els.filter(traversty('#root ul > li')[1])\n  // →  we're using `traversty()` here as a simple selector to fetch the 'iii' element\n  //    which we pass in to `filter()`. Because this element is in the collection we get\n  //    back a collection with only this element.\n```\n\n--------------------------------------------------------\n<a name=\"not\"></a>\n### not(selector | function | element)\n<code>traversty(elements).not()</code> returns a new Traversty instance containing *only* the elements that **do not** satisfy the filter condition.\n\n`not()` is the exact inverse of <a href=\"#filter\"><code>filter()</code></a>, it takes the same arguments but returns only elements that don't match your conditions.\n\n--------------------------------------------------------\n<a name=\"has\"></a>\n### has(selector | element)\n<code>traversty(elements).has()</code> returns a new Traversty instance containing *only* the elements that have descendant elements that match the provided `selector` argument, or have `element` as a descendant element.\n\nIf a `selector` string argument is provided, each element in the collection effectively has a `find(selector)`-type operation performed on it, if any matching descendant elements are found, the parent element is retained for the new collection; otherwise it is not included.\n\nIf an `element` argument is provided then the only element included in the resulting collection is an ancestor of that `element`, if the `element` is not a descendant of any of the elements in the collection then the resulting collection will be empty.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendant elements under #root\nels = els.has('li')\n  // →  returns a collection of 4 elements which have `<li>` descendants: the 'first' `<li>`,\n  //    the `<ul>` directly under it, the 'ii' `<li>` and the `<ul>` directly under that.\nels.has(traversty('#root a')[0])\n  // →  we're using `traversty()` here as a simple selector to fetch the `<a>` element\n  //    which we pass in to `has()`. There are two elements that have this single element\n  //    as a descendant, the 'first' `<li>` element and the `<ul>` directly under it.\n```\n\n--------------------------------------------------------\n<a name=\"is\"></a>\n### is(selector | function | element)\n<code>traversty(elements).is()</code> returns a **boolean** indicating whether at least one of the elements within the collection matches the condition. The method should be thought of as a version of <a href=\"#filter\"><code>filter()</code></a> that returns a boolean if the resulting collection has at least one element; i.e. `traversty(elements).filter(condition).length > 0`.\n\n\n--------------------------------------------------------\n<a name=\"each\"></a>\n### each(function [, thisContext])\n<code>traversty(elements).each()</code> will execute the provided `function` on each of the elements in the current collection. `each()` will return the original collection so you can continue chaining method calls.\n\nYour `function` will be called with `this` equal to the individual elements or the `thisContext` argument if supplied. The arguments provided to the function are:\n\n1. `element`: the current element in the collection\n2. `index`: the index of the current element in the collection\n3. `collection`: the entire Traversty object for this collection\n\nNote the ordering of arguments 1 and 2 are different to the <a href=\"http://api.jquery.com/each/\"><code>jQuery().each()</code></a>, instead Traversty is closer to ES5 <a href=\"https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/forEach\"><code>Array.prototype.forEach</code></a>.\n\n```js\ntraversty('li').each(function (el, i) {\n  this.innerHTML += ' (I am ' + i + ')'\n})\n```\n\n--------------------------------------------------------\n<a name=\"get\"></a>\n### get(index)\n<code>traversty(elements).get()</code> returns a single DOM element at the specified index of the collection. Indexes are zero-based and can be negative. See <a href=\"#eq\"><code>eq()</code></a> for specifics.\n\n\n--------------------------------------------------------\n<a name=\"toArray\"></a>\n### toArray()\n<code>traversty(elements).toArray()</code> returns a true `Array` object containing elements within the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array) for details on what you get.\n\n\n--------------------------------------------------------\n<a name=\"size\"></a>\n### size()\n<code>traversty(elements).size()</code> returns an number indicating the number of elements in the collection. Works exactly the same as `.length` on an `Array` (indeed, you can call `.length` on a Traversty object and get the same value).\n\n\n--------------------------------------------------------\n<a name=\"push\"></a>\n### push(element1 [, element2 [...]])\n<code>traversty(elements).push()</code> reuses `Array.prototype.push`. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/push) for details.\n\nBeware of pushing non-DOM elements onto a Traversty object! This is not supported behaviour.\n\n\n--------------------------------------------------------\n<a name=\"sort\"></a>\n### sort([compareFunction])\n<code>traversty(elements).sort()</code> reuses `Array.prototype.sort` to sort the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort) for details.\n\n\n--------------------------------------------------------\n<a name=\"splice\"></a>\n### splice(index, howMany [, element1 [...]])\n<code>traversty(elements).splice()</code> reuses `Array.prototype.splice` to splice the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/splice) for details.\n\n\n--------------------------------------------------------\n<a name=\"aug\"></a>\n### aug(methodMap)\n<code>traversty.aug()</code> extends Traversty's functionality with custom methods off the main Traversty prototype. The `methodMap` is simply a map of method names to functions. The functions will respond when called off a collection: `traversty().method(args)`.\n\n```js\ntraversty.aug({ append: function (element) {\n  // make sure we return 'this', which we can get from each()\n  return this.each(function (el, i) {\n    // append original to first element, append a clone to the rest\n    el.appendChild(i > 0 ? element.cloneNode(true) : element)\n  })\n}})\n\nvar span = document.createElement('span')\nspan.innerHTML = 'BOOM!'\ntraversty('li').append(span)\n```\n\n\n--------------------------------------------------------\n<a name=\"setSelectorEngine\"></a>\n### setSelectorEngine(selectorEngine)\n<code>traversty.setSelectorEngine()</code> injects a selector engine for Traversty to use. See the next section for details. Returns the main `Traversty` object for chainability, e.g.: `var $ = traversty.setSelectorEngine(qwery)`.\n\n## Selector engines\n\nTraversty should work out-of-the-box on modern browsers as it leverages native `querySelectorAll()` and `matchesSelector()` where they exist. This means that you should be able to use Traversty without a selector engine on most smartphone browsers without any problems.\n\nUnfortunately, this doesn't work with older browsers, particularly IE8 and below. While IE8 has a CSS2-compliant `querySelectorAll()`, it doesn't have a `matchesSelector()` which Traversty makes heavy use of.\n\nTraversty allows you to plug in your favourite selector engine so it can work on whatever browsers your engine supports. Traversty is tested to support [Qwery](https://github.com/ded/qwery), [Sel](https://github.com/amccollum/sel), [Sizzle](https://github.com/jquery/sizzle), [NWMatcher](https://github.com/dperini/nwmatcher) and [Zest](https://github.com/chjj/zest).\n\nTraversty uses *feature detection* to figure out how to use your selector engine, it tries to find the method used to *find* elements given a element root and the method used to determine if an element *matches* a given selector. If it can't figure out how to use your selector engine then you just need to pretend that it works like one of the supported ones and it should be OK.\n\nFor example:\n\n```js\ntraversty.setSelectorEngine({\n    select: function(selector, root) {\n      return MyEngine(selector, root)\n    }\n  , is: function(selector, root) {\n      return MyEngine(root).isTheSameAs(selector)\n    }\n})\n```\n\nTraversty will also do some trickery to make up for deficiencies in some selector engines, such as out-of-order results when selecting on groups ('a,b').\n\nIf you have a new selector engine that you want Traversty to support then either let me know or fork, patch and submit.\n\n\n## I want a demo!\n\nYou'll have to make do with the integration tests:\n\n### Ender\n\n[Here](http://rvagg.github.com/traversty/test/integration/ender_qwery.html) is Traversty running in an Ender build with Qwery and Bonzo. You can also see it running with [Sel](http://rvagg.github.com/traversty/test/integration/ender_sel.html), [Sizzle](http://rvagg.github.com/traversty/test/integration/ender_sizzle.html), [NWMatcher](http://rvagg.github.com/traversty/test/integration/ender_nwmatcher.html) and [without a selector engine](http://rvagg.github.com/traversty/test/integration/ender_sel.html) (works in modern browsers, including IE9+).\n\nView-source to see what it's doing, note that it's operating on 2 lists at the same time.\n\n### Vanilla\n\n[Here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) is Traversty bundled with Qwery as the selector engine and the `css()` augmenting example code [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) performing the same integration tests. There is also the same example using Zest instead [here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_zest.html)\n\n## Things to note\n\n * Traversty always does a **uniqueness** check on its collection of elements so you should never end up with duplicates. If you do a `traversty('body,ul').down('li')` you would still only get a unique list of all <code>&lt;li&gt;</code> elements in the document.\n\n * Traversty ignores text and comment nodes and should only ever operate on the DOM element nodes you would expect (i.e. with `.nodeType === 1`).\n\n * Traversty currently orders results (for each element in the starting list) in document-order, so `previous('*')` will give you results starting from the *firstChild* of the parent element up to the *previousSibling* of the starting element, rather than starting with the *previousSibling* and listing backwards (this doesn't impact on indexing, which still works backwards, only the order of result lists). The single **exception** to this is <a href=\"#siblings\"><code>siblings()</code></a>, see the note in that section for details.\n\n## Supported browsers\n\nTraversty is tested with IE6+, Firefox 3+, Safari 4+, Opera current and Chrome current. You'll need a supported selector engine to operate on some of these older browsers.\n\n\n## Ender integration\n\nTraversty is designed to be inserted into an Ender build. It's in npm so simply include it in your build command, something like: `ender build sel bonzo traversty`\n\nTraversty will attempt to use whatever selector engine you've included in your Ender build.\n\n### What about Bonzo?\n\nTraversty is designed to add to the goodness you get in Bonzo, although Bonzo isn't a dependency. Bonzo has `next()` and `previous()` and a few other methods already and it is intended that Traversty replace these in your Ender build (because they are way-better!). Argument-less they should do exactly the same thing but Traversty adds the extra arguments for greater flexibility. If you are using Bonzo in Ender along with Traversty then you should make sure Traversty is included *after* Bonzo. Unfortunately, [Ender doesn't guarantee order](https://github.com/ender-js/Ender/issues/63) so you may have to fiddle a bit. The Ender 1.0 CLI does correct ordering but that's not formally released yet, you can use it by installing ender via npm with `npm install ender@dev`.\n\n\n## Contributing\n\nAwesome! Just do it, fork and submit your pull requests and they will be promptly considered.\n\nI'd also love it if you could contribute tests for bugs you find or features you add.\n\n### Tests\n\nTraversty uses [Buster](http://busterjs.org) for unit testing.\n\nSince Buster is still in Beta, the capture-server/client is a bit buggy and can be frustrating. So, instead, simply run *index.html* file in the *tests* directory in each of the browsers you need to test. It'll load and run all of the tests.\n\n\n## Credits\n\n * Firstly, much credit should go to the awesome Prototype guys and their excellent API that I initially ripped off for Traversty 0.x.\n * Obviously, kudos goes to John Resig and the jQuery team for their traversal and filtering API that I've so shamelessly ripped off.\n * Thanks to [@ded](http://github.com/ded) and [@fat](http://github.com/fat) for Ender, particularly @ded for Bonzo, upon which Traversty is designed to build.\n\n\n## Licence\n\nTraversty is Copyright (c) 2012 Rod Vagg [@rvagg](https://twitter.com/rvagg) and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.\n","readmeFilename":"README.md","_id":"traversty@1.0.3","dist":{"shasum":"41dc68d6e494523138e5b3a9de12ab9f428a7a0a","tarball":"https://registry.npmjs.org/traversty/-/traversty-1.0.3.tgz","integrity":"sha512-bLCffA5qeac0H2TkZElfUHGSN1L4+PsGOT2nPlPF9nDQjTEKuqrgEFzzPA2xNRVuU/U8wfUGZRnD0s37RCPW4A==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIHn1c/cKhktRLm08b4FBdEcyAtQhXkXn+F/OfHOFBFWUAiEAoXlgJSflPM2clUiVBpkKAVztTaE1+G//J+7/c+cMRHA="}]},"_from":".","_npmVersion":"1.2.3","_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"1.0.4":{"name":"traversty","description":"Library agnostic utility for DOM collection management and traversal","version":"1.0.4","homepage":"https://github.com/rvagg/traversty","authors":["Rod Vagg @rvagg <rod@vagg.org> (https://github.com/rvagg)"],"keywords":["ender","dom","nodes","traversal"],"main":"./traversty.js","ender":"./ender_bridge.js","repository":{"type":"git","url":"https://github.com/rvagg/traversty.git"},"devDependencies":{"buster":"*","uglify-js":"*","colors-tmpl":"*"},"license":"MIT","readme":"# Traversty &mdash; headache-free DOM collection management and traversal\n\nTraversty is a library-agnostic DOM utility for traversal and element collection manipulation. Traversty doesn't provide any DOM manipulation features; instead, Traversty is used for managing collections of DOM elements and navigating the DOM.\n\n**Current file size:** 15.8 kB raw, 5.7 kB min, **2.1 kB gzip**\n\n<a href=\"#api\"><i>Just show me the API!</i></a>\n\n## Traversal\n\nThe core DOM traversal methods are inspired by [Prototype](http://prototypejs.org)'s excelent \"DOM traversal toolkit\", you get <a href=\"#up\"><code>up()</code></a>, <a href=\"#down\"><code>down()</code></a>, <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> with optional `selector` and `index` arguments, all in a multi-element environment&mdash;jQuery-like rather than Prototype's single-element implementation.\n\nIn addition, jQuery-compatible traversal methods extend this functionality: <a href=\"#parents\"><code>parents()</code></a>, <a href=\"#closest\"><code>closest()</code></a>, <a href=\"#children\"><code>children()</code></a>, <a href=\"#siblings\"><code>siblings()</code></a> and <a href=\"#prev\"><code>prev()</code></a> a simple alias for <a href=\"#previous\"><code>previous()</code></a>.\n\n## Collection filtering\n\nTraversty operates on DOM element collections, jQuery-style, so it also gives you methods to filter and manipulate that collection. The filtering methods are designed to be jQuery-compatible. You get: <a href=\"#first\"><code>first()</code></a>, <a href=\"#last\"><code>last()</code></a>, <a href=\"#eq\"><code>eq()</code></a>, <a href=\"#not\"><code>not()</code></a>, <a href=\"#slice\"><code>slice()</code></a>, <a href=\"#filter\"><code>filter()</code></a>, <a href=\"#has\"><code>has()</code></a> and <a href=\"#is\"><code>is()</code></a> (this last method returns a boolean rather than a collection).\n\nTraversty emulates an Array and includes additional methods to help you manage it as if it were one: <a href=\"#get\"><code>get()</code></a>, <a href=\"#toArray\"><code>toArray()</code></a>, <a href=\"#size\"><code>size()</code></a>, <a href=\"#push\"><code>push()</code></a>, <a href=\"#sort\"><code>sort()</code></a>, <a href=\"#splice\"><code>splice()</code></a>.\n\n### Ender integration\n\nTraversty is designed to be integrated in an [Ender](http://ender.no.de/) build, to augment what's already available in [Bonzo](https://github.com/ded/bonzo) but can just as easily be used as a stand-alone utility.\n\n```\n$ ender build jeesh traversty\n```\n\n### Component integration\n\nYou can also install Traversty as a [component](https://github.com/component/component):\n\n```\n$ component install rvagg/traversty\n```\n\nWiring in a selector engine is up to you in your component build. You'll need to make one-off call to `setSelectorEngine()` once you have a selector engine to inject, otherwise Traversty will simply use native `querySelectorAll()` and `matchesSelector()` if available. See the <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a> for more details on how this works.\n\n```js\nvar zest = require('zest')\n  , $ = require('traversty').setSelectorEngine(zest)\n```\n\n## Example usage\n\nThis bit of craziness comes from Traversty's integration tests. The bulk of this code is used to test Traversty's integration with Ender where the `css()` method is provided by [Bonzo](https://github.com/ded/bonzo) but there is also a [vanilla version](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) with only [Qwery](https://github.com/ded/qwery) for the selector engine and a `css()` method added using Traversty's <a href=\"#aug\"><code>aug()</code></a> method (see the [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) file for how this is done).\n\n```js\nvar $ = traversty\n$.setSelectorEngine(qwery)\n$('#fixtures > ul') // Traversty operates on collections of elements\n  .down(0).css('color', 'red')\n  .next('li', 1).css('color', 'green')\n  .next().down('li', 2).css('color', 'blue')\n  .next().down().css('color', 'yellow')\n  .up(2).next().css('color', 'purple')\n  .siblings(3).css('fontWeight', 'bold')\n  .children().css('textDecoration', 'underline')\n  .children(1).css('borderLeft', 'solid 5px red')\n  .parents('*').filter('ul').css('borderTop', 'dashed 2px green')\n  .not('.second').css('borderBottom', 'solid 3px blue')\n  .down('.second li').has('span').css('marginTop', '10px')\n  .up('ul').eq(-1).css('borderLeft', 'solid 5px orange')\n  .closest('#fixtures').down('li').slice(-10,-9).css('fontSize', '25px')\n  // Note: the css() method is not native to Traversty but is added with aug()\n```\n\nThe return type from the `traversty()` method is not a true `Array` but can be used like an array in almost all respects, it has `.length` and `[]` subscript element access and other standard `Array` methods.\n\n<a href=\"#api\"></a>\n## API\n\n  * <a href=\"#ctor\"><code><b>traversty()</b></code></a>\n  * <a href=\"#next\"><code>traversty().<b>next()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>previous()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>prev()</b></code></a>\n  * <a href=\"#up\"><code>traversty().<b>up()</b></code></a>\n  * <a href=\"#parents\"><code>traversty().<b>parents()</b></code></a>\n  * <a href=\"#closest\"><code>traversty().<b>closest()</b></code></a>\n  * <a href=\"#down\"><code>traversty().<b>down()</b></code></a>\n  * <a href=\"#children\"><code>traversty().<b>children()</b></code></a>\n  * <a href=\"#siblings\"><code>traversty().<b>siblings()</b></code></a>\n  * <a href=\"#first\"><code>traversty().<b>first()</b></code></a>\n  * <a href=\"#last\"><code>traversty().<b>last()</b></code></a>\n  * <a href=\"#eq\"><code>traversty().<b>eq()</b></code></a>\n  * <a href=\"#slice\"><code>traversty().<b>slice()</b></code></a>\n  * <a href=\"#filter\"><code>traversty().<b>filter()</b></code></a>\n  * <a href=\"#not\"><code>traversty().<b>not()</b></code></a>\n  * <a href=\"#has\"><code>traversty().<b>has()</b></code></a>\n  * <a href=\"#is\"><code>traversty().<b>is()</b></code></a>\n  * <a href=\"#get\"><code>traversty().<b>get()</b></code></a>\n  * <a href=\"#each\"><code>traversty().<b>each()</b></code></a>\n  * <a href=\"#toArray\"><code>traversty().<b>toArray()</b></code></a>\n  * <a href=\"#size\"><code>traversty().<b>size()</b></code></a>\n  * <a href=\"#push\"><code>traversty().<b>push()</b></code></a>\n  * <a href=\"#sort\"><code>traversty().<b>sort()</b></code></a>\n  * <a href=\"#splice\"><code>traversty().<b>splice()</b></code></a>\n  * <a href=\"#aug\"><code>traversty.<b>aug()</b></code></a>\n  * <a href=\"#setSelectorEngine\"><code>traversty.<b>setSelectorEngine()</b></code></a>\n  * <a href=\"#noConflict\"><code>traversty.<b>noConflict()</b></code></a>\n\n--------------------------------------------------------\n<a name=\"ctor\"></a>\n### traversty(element | elements | selector)\n<code>traversty()</code> gives you a new Traversty instance containing the elements you provide.\n\nOnce you have a collection, you can call any of the Traversty methods on that collection. You can give a single DOM element or an array of DOM elements. If you provide a string argument it will be used as a selector to either query the DOM via the browser's native `querySelectorAll()` implementation or use a selector engine which you provide (see <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a>).\n\nYou can pluck individual elements with array accessors (subscript), e.g. `traversty(document.body)[0] // → document.body` \n\nWhen included in an Ender build, `$(element | elements | selector)` does the same thing and all the Traversty methods will be available on the resulting Ender object.\n\n--------------------------------------------------------\n<a name=\"next\"></a>\n### next([selector [, index = 0]])\n<code>traversty(elements).next()</code> returns a new Traversty instance containing *nextSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nYou will get elements that match the given *selector* (if provided) starting from the *nextSibling* of the starting element(s), all the way across to the last *nextSibling*.\n\nIf no `index` or `selector` is given then you get just the *nextSibling*s of the elements; i.e. you shift *across* by one.\n\nIf just an `index` is provided then you'll get the `index+1` *nextSibling*s of the element(s). i.e. `index` is 0-based, like arrays, 0 is *nextSibling* and 1 is *nextSibling.nextSibling*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching *nextSibling* elements.\n\n#### Examples ####\n\n```js\ntraversty('li:first-child').next()\n  // →  returns the second `<li>` of every list in the document\ntraversty('li.allstarts').next('li', 1)\n  // →  returns the `nextSibling` of the `nextSibling` of the starting elements\ntraversty('li:first-child').next('li')\n  // →  returns all `<li>` elements, except for the first-children of every lits in the document\n```\n\n--------------------------------------------------------\n<a name=\"previous\"></a>\n### previous([selector [, index = 0]])\n<code>traversty(elements).previous()</code> returns a new Traversty instance containing *previousSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nExactly the same as <a href=\"#next\"><code>next()</code></a> except it works on *previousSibling*, so you move *backwards* amongst sibling elements.\n\n#### Examples ####\n\n```js\ntraversty('li:nth-child(20)').previous()\n  // →  returns 19th child of the every list in the document (where it exists)\ntraversty('li.allstarts').previous('li', 1)\n  // →  returns the `previousSibling` of the `previousSibling` of the starting element\ntraversty('li:nth-child(20)').previous('.interesting')\n  // →  returns all `<li>` elements with class \"interesting\" up to the 19th child of every list\n  //     in the document where there are at least 20 children.\n```\n\n--------------------------------------------------------\n<a name=\"prev\"></a>\n### prev([selector [, index = 0]])\n<code>traversty(elements).prev()</code> is a simple alias for <a href=\"#previous\"><code>previous()</code></a>, provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"up\"></a>\n### up([selector [, index = 0]])\n<code>traversty(elements).up()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nSimilar to <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> except that it works on *parentNode*s and will continue all the up to the document root depending on what you're asking for.\n\nIf no `index` or `selector` is given then you get just the `parentNode*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *parentNode*s of the element. i.e. `index` is 0-based, like arrays, 0 is *parentNode* and 1 is *parentNode.parentNode*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching ancestor elements.\n\n#### Examples ####\n\n```js\ntraversty('li#start').up()\n  // →  returns the `<ul>` parent element\ntraversty('li.allstarts').up('ul', 1)\n  // →  returns the grandparent `<ul>` elements if the start elements are nested at two levels\ntraversty('li.allstarts').up('ul')\n  // →  returns all ancestor `<ul>` elements, no matter how deep the nesting\n```\n\n--------------------------------------------------------\n<a name=\"parents\"></a>\n### parents([selector = '*' [, index ]])\n<code>traversty(elements).parents()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#up\"><code>up()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nPerforms exactly the same as <a href=\"#up\"><code>up()</code></a>, *except*, the `'selector'` argument defaults to `'*'` which has the effect of matching *all* ancestor elements, not just the first one. `parents()` will return exactly the same collection as `up('*')`. Provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"closest\"></a>\n### closest([selector = '*' [, index = 0]])\n<code>traversty(elements).closest()</code> returns a new Traversty instance containing the elements and/or *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#parents\"><code>parents()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. the current element)\n\nPerforms exactly the same operation as <a href=\"#parents\"><code>parents()</code></a> except for two important differences:\n\n * Matching starts at the **current** elements rather than the direct parent elements. So a `closest('*')` will return the current elements because they match the selector `'*'`.\n * The `index` argument defaults to `0`, just like <a href=\"#up\"><code>up()</code></a>, so you will only get the first match. An index of `n`, you will get the *nth* match, start with the current elements.\n\n--------------------------------------------------------\n<a name=\"down\"></a>\n### down([selector [, index = 0]])\n<code>traversty(elements).down()</code> returns a new Traversty instance containing descendant elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nWhile `down()` is very similar to the other methods, it's perhaps best to think of it as what you might get with a `find()` method from a selector engine.\n\n`down()` works on elements **in document-order**, so it operates on child elements and children of children but it also moves through child-siblings on the way to children of children.\n\nThe following fragment should illustrate the `index`ing you get when you use `down()`:\n\n```html\n<ul id=\"root\">\n  <li>first</li>   <!-- 0 -->\n  <li>second</li>  <!-- 1 -->\n  <li>third        <!-- 2 -->\n    <ul>           <!-- 3 -->\n      <li>i</li>   <!-- 4 -->\n      <li>ii</li>  <!-- 5 -->\n      <li>iii</li> <!-- 6 -->\n    </ul>\n  </li>\n  <li>fourth</li>  <!-- 7 -->\n</ul>\n```\n\nSo\n\n```js\ntraversty('#root').down(5)\n  // →  will give you `<li>ii</li>`\ntraversty('#root').down('li', 5)\n  // →  will give you `<li>i</li>` because the `<ul>` is ignored\n```\n\nOf course `down()` works on multiple elements simultaneously just like the other methods.\n\n\n--------------------------------------------------------\n<a name=\"children\"></a>\n### children([selector [, index = 0]])\n<code>traversty(elements).children()</code> returns a new Traversty instance containing direct descendant (child) elements according to the arguments provided.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\ntraversty('#root > li').children()\n  // →  will give you *only* the second level `<ul>` element as it's\n  //    the only direct descendant of the top `<li>` elements\ntraversty('#root > li').children().children()\n  // →  will give you *only* the second level `<li>` elements and none\n  //    of their children\n```\n\n--------------------------------------------------------\n<a name=\"siblings\"></a>\n### siblings([selector [, index = 0]])\n<code>traversty(elements).siblings()</code> returns a new Traversty instance containing *previousSibling* and *nextSibling* elements according to the arguments provided. It's important to note that the resulting collection **will not** include the original elements unless they are siblings of each other. To illustrate:\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root :nth-child(2)').siblings()\n  // →  will give you all `<li>` elements except the second\ntraversty('#root :nth-child(2n)').siblings()\n  // →  will give you all `<li>` elements because they are all siblings of\n  //    the original collection's elements\n```\n\n`siblings()` is the only method in Traversty that is not guaranteed to return a collection of elements in document-order (i.e. in the order they appear in the HTML). If you call `siblings()` on elements that are already siblings then the collection mechanism may mean that the results are out of order. Generally this shouldn't matter but you are warned if order matters to you for some reason.\n\n\n--------------------------------------------------------\n<a name=\"first\"></a>\n### first()\n<code>traversty(elements).first()</code> returns a new Traversty instance containing *only* the first element in the original collection.\n\n--------------------------------------------------------\n<a name=\"last\"></a>\n### last()\n<code>traversty(elements).last()</code> returns a new Traversty instance containing *only* the last element in the original collection.\n\n--------------------------------------------------------\n<a name=\"eq\"></a>\n### eq(index)\n<code>traversty(elements).eq()</code> returns a new Traversty instance containing *only* the element at the index specified.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection.\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root li').eq(1)\n  // →  will give you `<li>second</li>`\ntraversty('#root li').eq(-2)\n  // →  will give you `<li>third</li>`\n```\n\n--------------------------------------------------------\n<a name=\"slice\"></a>\n### slice(start [, end])\n<code>traversty(elements).slice()</code> returns a new Traversty instance containing *only* the elements between the `start` and `end` indexes. The `end` is optional, if left out then elements from `start` to the end of the collection are included.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection. See the example above for <a href=\"#eq\"><code>eq()</code></a> for how this works.\n\n--------------------------------------------------------\n<a name=\"filter\"></a>\n### filter(selector | function | element)\n<code>traversty(elements).filter()</code> returns a new Traversty instance containing *only* the elements that satisfy the filter condition.\n\nA `selector` string argument will simply check each element against the selector and return only elements that match.\n\nA `function` argument will execute that function for each element in the collection and return only elements for which it receives a *truthy* response from the function. `this` within the function will be the element being checked and the single argument to the function will be the index within the collection.\n\nAn `element` argument will return a collection containing only that DOM element *only if * it exists within the collection.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendant elements under #root\nels = els.filter('li')\n  // →  returns only the 8 `<li>` elements within the collection\nels = els.filter(function () { return /^i/.test(this.innerHTML) })\n  // →  returns only the 3 `<li>` elements start have content starting with 'i'\n  //    i.e. only 'ii', 'iii' and 'iv' (not 'i')\nels = els.filter(traversty('#root ul > li')[1])\n  // →  we're using `traversty()` here as a simple selector to fetch the 'iii' element\n  //    which we pass in to `filter()`. Because this element is in the collection we get\n  //    back a collection with only this element.\n```\n\n--------------------------------------------------------\n<a name=\"not\"></a>\n### not(selector | function | element)\n<code>traversty(elements).not()</code> returns a new Traversty instance containing *only* the elements that **do not** satisfy the filter condition.\n\n`not()` is the exact inverse of <a href=\"#filter\"><code>filter()</code></a>, it takes the same arguments but returns only elements that don't match your conditions.\n\n--------------------------------------------------------\n<a name=\"has\"></a>\n### has(selector | element)\n<code>traversty(elements).has()</code> returns a new Traversty instance containing *only* the elements that have descendant elements that match the provided `selector` argument, or have `element` as a descendant element.\n\nIf a `selector` string argument is provided, each element in the collection effectively has a `find(selector)`-type operation performed on it, if any matching descendant elements are found, the parent element is retained for the new collection; otherwise it is not included.\n\nIf an `element` argument is provided then the only element included in the resulting collection is an ancestor of that `element`, if the `element` is not a descendant of any of the elements in the collection then the resulting collection will be empty.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendant elements under #root\nels = els.has('li')\n  // →  returns a collection of 4 elements which have `<li>` descendants: the 'first' `<li>`,\n  //    the `<ul>` directly under it, the 'ii' `<li>` and the `<ul>` directly under that.\nels.has(traversty('#root a')[0])\n  // →  we're using `traversty()` here as a simple selector to fetch the `<a>` element\n  //    which we pass in to `has()`. There are two elements that have this single element\n  //    as a descendant, the 'first' `<li>` element and the `<ul>` directly under it.\n```\n\n--------------------------------------------------------\n<a name=\"is\"></a>\n### is(selector | function | element)\n<code>traversty(elements).is()</code> returns a **boolean** indicating whether at least one of the elements within the collection matches the condition. The method should be thought of as a version of <a href=\"#filter\"><code>filter()</code></a> that returns a boolean if the resulting collection has at least one element; i.e. `traversty(elements).filter(condition).length > 0`.\n\n\n--------------------------------------------------------\n<a name=\"each\"></a>\n### each(function [, thisContext])\n<code>traversty(elements).each()</code> will execute the provided `function` on each of the elements in the current collection. `each()` will return the original collection so you can continue chaining method calls.\n\nYour `function` will be called with `this` equal to the individual elements or the `thisContext` argument if supplied. The arguments provided to the function are:\n\n1. `element`: the current element in the collection\n2. `index`: the index of the current element in the collection\n3. `collection`: the entire Traversty object for this collection\n\nNote the ordering of arguments 1 and 2 are different to the <a href=\"http://api.jquery.com/each/\"><code>jQuery().each()</code></a>, instead Traversty is closer to ES5 <a href=\"https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/forEach\"><code>Array.prototype.forEach</code></a>.\n\n```js\ntraversty('li').each(function (el, i) {\n  this.innerHTML += ' (I am ' + i + ')'\n})\n```\n\n--------------------------------------------------------\n<a name=\"get\"></a>\n### get(index)\n<code>traversty(elements).get()</code> returns a single DOM element at the specified index of the collection. Indexes are zero-based and can be negative. See <a href=\"#eq\"><code>eq()</code></a> for specifics.\n\n\n--------------------------------------------------------\n<a name=\"toArray\"></a>\n### toArray()\n<code>traversty(elements).toArray()</code> returns a true `Array` object containing elements within the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array) for details on what you get.\n\n\n--------------------------------------------------------\n<a name=\"size\"></a>\n### size()\n<code>traversty(elements).size()</code> returns an number indicating the number of elements in the collection. Works exactly the same as `.length` on an `Array` (indeed, you can call `.length` on a Traversty object and get the same value).\n\n\n--------------------------------------------------------\n<a name=\"push\"></a>\n### push(element1 [, element2 [...]])\n<code>traversty(elements).push()</code> reuses `Array.prototype.push`. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/push) for details.\n\nBeware of pushing non-DOM elements onto a Traversty object! This is not supported behaviour.\n\n\n--------------------------------------------------------\n<a name=\"sort\"></a>\n### sort([compareFunction])\n<code>traversty(elements).sort()</code> reuses `Array.prototype.sort` to sort the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort) for details.\n\n\n--------------------------------------------------------\n<a name=\"splice\"></a>\n### splice(index, howMany [, element1 [...]])\n<code>traversty(elements).splice()</code> reuses `Array.prototype.splice` to splice the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/splice) for details.\n\n\n--------------------------------------------------------\n<a name=\"aug\"></a>\n### aug(methodMap)\n<code>traversty.aug()</code> extends Traversty's functionality with custom methods off the main Traversty prototype. The `methodMap` is simply a map of method names to functions. The functions will respond when called off a collection: `traversty().method(args)`.\n\n```js\ntraversty.aug({ append: function (element) {\n  // make sure we return 'this', which we can get from each()\n  return this.each(function (el, i) {\n    // append original to first element, append a clone to the rest\n    el.appendChild(i > 0 ? element.cloneNode(true) : element)\n  })\n}})\n\nvar span = document.createElement('span')\nspan.innerHTML = 'BOOM!'\ntraversty('li').append(span)\n```\n\n\n--------------------------------------------------------\n<a name=\"setSelectorEngine\"></a>\n### setSelectorEngine(selectorEngine)\n<code>traversty.setSelectorEngine()</code> injects a selector engine for Traversty to use. See the next section for details. Returns the main `Traversty` object for chainability, e.g.: `var $ = traversty.setSelectorEngine(qwery)`.\n\n## Selector engines\n\nTraversty should work out-of-the-box on modern browsers as it leverages native `querySelectorAll()` and `matchesSelector()` where they exist. This means that you should be able to use Traversty without a selector engine on most smartphone browsers without any problems.\n\nUnfortunately, this doesn't work with older browsers, particularly IE8 and below. While IE8 has a CSS2-compliant `querySelectorAll()`, it doesn't have a `matchesSelector()` which Traversty makes heavy use of.\n\nTraversty allows you to plug in your favourite selector engine so it can work on whatever browsers your engine supports. Traversty is tested to support [Qwery](https://github.com/ded/qwery), [Sel](https://github.com/amccollum/sel), [Sizzle](https://github.com/jquery/sizzle), [NWMatcher](https://github.com/dperini/nwmatcher) and [Zest](https://github.com/chjj/zest).\n\nTraversty uses *feature detection* to figure out how to use your selector engine, it tries to find the method used to *find* elements given a element root and the method used to determine if an element *matches* a given selector. If it can't figure out how to use your selector engine then you just need to pretend that it works like one of the supported ones and it should be OK.\n\nFor example:\n\n```js\ntraversty.setSelectorEngine({\n    select: function(selector, root) {\n      return MyEngine(selector, root)\n    }\n  , is: function(selector, root) {\n      return MyEngine(root).isTheSameAs(selector)\n    }\n})\n```\n\nTraversty will also do some trickery to make up for deficiencies in some selector engines, such as out-of-order results when selecting on groups ('a,b').\n\nIf you have a new selector engine that you want Traversty to support then either let me know or fork, patch and submit.\n\n\n## I want a demo!\n\nYou'll have to make do with the integration tests:\n\n### Ender\n\n[Here](http://rvagg.github.com/traversty/test/integration/ender_qwery.html) is Traversty running in an Ender build with Qwery and Bonzo. You can also see it running with [Sel](http://rvagg.github.com/traversty/test/integration/ender_sel.html), [Sizzle](http://rvagg.github.com/traversty/test/integration/ender_sizzle.html), [NWMatcher](http://rvagg.github.com/traversty/test/integration/ender_nwmatcher.html) and [without a selector engine](http://rvagg.github.com/traversty/test/integration/ender_sel.html) (works in modern browsers, including IE9+).\n\nView-source to see what it's doing, note that it's operating on 2 lists at the same time.\n\n### Vanilla\n\n[Here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) is Traversty bundled with Qwery as the selector engine and the `css()` augmenting example code [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) performing the same integration tests. There is also the same example using Zest instead [here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_zest.html)\n\n## Things to note\n\n * Traversty always does a **uniqueness** check on its collection of elements so you should never end up with duplicates. If you do a `traversty('body,ul').down('li')` you would still only get a unique list of all <code>&lt;li&gt;</code> elements in the document.\n\n * Traversty ignores text and comment nodes and should only ever operate on the DOM element nodes you would expect (i.e. with `.nodeType === 1`).\n\n * Traversty currently orders results (for each element in the starting list) in document-order, so `previous('*')` will give you results starting from the *firstChild* of the parent element up to the *previousSibling* of the starting element, rather than starting with the *previousSibling* and listing backwards (this doesn't impact on indexing, which still works backwards, only the order of result lists). The single **exception** to this is <a href=\"#siblings\"><code>siblings()</code></a>, see the note in that section for details.\n\n## Supported browsers\n\nTraversty is tested with IE6+, Firefox 3+, Safari 4+, Opera current and Chrome current. You'll need a supported selector engine to operate on some of these older browsers.\n\n\n## Ender integration\n\nTraversty is designed to be inserted into an Ender build. It's in npm so simply include it in your build command, something like: `ender build sel bonzo traversty`\n\nTraversty will attempt to use whatever selector engine you've included in your Ender build.\n\n### What about Bonzo?\n\nTraversty is designed to add to the goodness you get in Bonzo, although Bonzo isn't a dependency. Bonzo has `next()` and `previous()` and a few other methods already and it is intended that Traversty replace these in your Ender build (because they are way-better!). Argument-less they should do exactly the same thing but Traversty adds the extra arguments for greater flexibility. If you are using Bonzo in Ender along with Traversty then you should make sure Traversty is included *after* Bonzo. Unfortunately, [Ender doesn't guarantee order](https://github.com/ender-js/Ender/issues/63) so you may have to fiddle a bit. The Ender 1.0 CLI does correct ordering but that's not formally released yet, you can use it by installing ender via npm with `npm install ender@dev`.\n\n\n## Contributing\n\nAwesome! Just do it, fork and submit your pull requests and they will be promptly considered.\n\nI'd also love it if you could contribute tests for bugs you find or features you add.\n\n### Tests\n\nTraversty uses [Buster](http://busterjs.org) for unit testing.\n\nSince Buster is still in Beta, the capture-server/client is a bit buggy and can be frustrating. So, instead, simply run *index.html* file in the *tests* directory in each of the browsers you need to test. It'll load and run all of the tests.\n\n\n## Credits\n\n * Firstly, much credit should go to the awesome Prototype guys and their excellent API that I initially ripped off for Traversty 0.x.\n * Obviously, kudos goes to John Resig and the jQuery team for their traversal and filtering API that I've so shamelessly ripped off.\n * Thanks to [@ded](http://github.com/ded) and [@fat](http://github.com/fat) for Ender, particularly @ded for Bonzo, upon which Traversty is designed to build.\n\n\n## Licence\n\nTraversty is Copyright (c) 2012 Rod Vagg [@rvagg](https://twitter.com/rvagg) and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.\n","readmeFilename":"README.md","_id":"traversty@1.0.4","dist":{"shasum":"1e7a5c5f505d76288f2af0d8606e259111af87ee","tarball":"https://registry.npmjs.org/traversty/-/traversty-1.0.4.tgz","integrity":"sha512-aPFeGyJHnnbZ4ex9GIGL6ciR0V/7p/+BeChdbje3oCfoU0zmwK1P/O3INPKDbv9NUjvT0EKH2mWdFd3GU8iYsw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC3kNPStI+lfoxg3WK1Eeuh/sa4TIjzDjo8xDk6Ex7xZQIhAKX+/8bGTmEWV9E/KecMviyf+mb/RZCfKz6ONbuJFqlz"}]},"_from":".","_npmVersion":"1.2.4","_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"},"1.0.5":{"name":"traversty","description":"Library agnostic utility for DOM collection management and traversal","version":"1.0.5","homepage":"https://github.com/rvagg/traversty","authors":["Rod Vagg @rvagg <rod@vagg.org> (https://github.com/rvagg)"],"keywords":["ender","dom","nodes","traversal"],"main":"./traversty.js","ender":"./ender_bridge.js","repository":{"type":"git","url":"https://github.com/rvagg/traversty.git"},"devDependencies":{"bustermove":"*","qwery":"*","qwery-pseudos":"*","sizzle":"*","nwmatcher":"*","brtapsauce":"*"},"license":"MIT","scripts":{"test-local":"brtapsauce-local test/browserify.js","test":"test/sauce.js"},"readme":"# Traversty\n\n**DOM collection management and traversal**\n\nTraversty is a library-agnostic DOM utility for traversal and element collection manipulation. Traversty doesn't provide any DOM manipulation features; instead, Traversty is used for managing collections of DOM elements and navigating the DOM.\n\n[![NPM](https://nodei.co/npm/traversty.png?compact=true)](https://nodei.co/npm/traversty/)\n\n[![Build Status](https://saucelabs.com/browser-matrix/traversty-sauce.svg)](https://travis-ci.org/rvagg/traversty)\n\n*Tests run against [Qwery](https://github.com/ded/qwery), [Sizzle](http://sizzlejs.com/), [NWMatcher](http://javascript.nwbox.com/NWMatcher/) and native `querySelectorAll()` and `matchesSelector()` where available.*\n\n**Current file size:** 15.8 kB raw, 5.7 kB min, **2.1 kB gzip**\n\n<a href=\"#api\"><i>Just show me the API!</i></a>\n\n## Traversal\n\nThe core DOM traversal methods are inspired by [Prototype](http://prototypejs.org)'s excelent \"DOM traversal toolkit\", you get <a href=\"#up\"><code>up()</code></a>, <a href=\"#down\"><code>down()</code></a>, <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> with optional `selector` and `index` arguments, all in a multi-element environment&mdash;jQuery-like rather than Prototype's single-element implementation.\n\nIn addition, jQuery-compatible traversal methods extend this functionality: <a href=\"#parents\"><code>parents()</code></a>, <a href=\"#closest\"><code>closest()</code></a>, <a href=\"#children\"><code>children()</code></a>, <a href=\"#siblings\"><code>siblings()</code></a> and <a href=\"#prev\"><code>prev()</code></a> a simple alias for <a href=\"#previous\"><code>previous()</code></a>.\n\n## Collection filtering\n\nTraversty operates on DOM element collections, jQuery-style, so it also gives you methods to filter and manipulate that collection. The filtering methods are designed to be jQuery-compatible. You get: <a href=\"#first\"><code>first()</code></a>, <a href=\"#last\"><code>last()</code></a>, <a href=\"#eq\"><code>eq()</code></a>, <a href=\"#not\"><code>not()</code></a>, <a href=\"#slice\"><code>slice()</code></a>, <a href=\"#filter\"><code>filter()</code></a>, <a href=\"#has\"><code>has()</code></a> and <a href=\"#is\"><code>is()</code></a> (this last method returns a boolean rather than a collection).\n\nTraversty emulates an Array and includes additional methods to help you manage it as if it were one: <a href=\"#get\"><code>get()</code></a>, <a href=\"#toArray\"><code>toArray()</code></a>, <a href=\"#size\"><code>size()</code></a>, <a href=\"#push\"><code>push()</code></a>, <a href=\"#sort\"><code>sort()</code></a>, <a href=\"#splice\"><code>splice()</code></a>.\n\n### Ender integration\n\nTraversty is designed to be integrated in an [Ender](http://ender.no.de/) build, to augment what's already available in [Bonzo](https://github.com/ded/bonzo) but can just as easily be used as a stand-alone utility.\n\n```\n$ ender build jeesh traversty\n```\n\n### Component integration\n\nYou can also install Traversty as a [component](https://github.com/component/component):\n\n```\n$ component install rvagg/traversty\n```\n\nWiring in a selector engine is up to you in your component build. You'll need to make one-off call to `setSelectorEngine()` once you have a selector engine to inject, otherwise Traversty will simply use native `querySelectorAll()` and `matchesSelector()` if available. See the <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a> for more details on how this works.\n\n```js\nvar zest = require('zest')\n  , $ = require('traversty').setSelectorEngine(zest)\n```\n\n## Example usage\n\nThis bit of craziness comes from Traversty's integration tests. The bulk of this code is used to test Traversty's integration with Ender where the `css()` method is provided by [Bonzo](https://github.com/ded/bonzo) but there is also a [vanilla version](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) with only [Qwery](https://github.com/ded/qwery) for the selector engine and a `css()` method added using Traversty's <a href=\"#aug\"><code>aug()</code></a> method (see the [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) file for how this is done).\n\n```js\nvar $ = traversty\n$.setSelectorEngine(qwery)\n$('#fixtures > ul') // Traversty operates on collections of elements\n  .down(0).css('color', 'red')\n  .next('li', 1).css('color', 'green')\n  .next().down('li', 2).css('color', 'blue')\n  .next().down().css('color', 'yellow')\n  .up(2).next().css('color', 'purple')\n  .siblings(3).css('fontWeight', 'bold')\n  .children().css('textDecoration', 'underline')\n  .children(1).css('borderLeft', 'solid 5px red')\n  .parents('*').filter('ul').css('borderTop', 'dashed 2px green')\n  .not('.second').css('borderBottom', 'solid 3px blue')\n  .down('.second li').has('span').css('marginTop', '10px')\n  .up('ul').eq(-1).css('borderLeft', 'solid 5px orange')\n  .closest('#fixtures').down('li').slice(-10,-9).css('fontSize', '25px')\n  // Note: the css() method is not native to Traversty but is added with aug()\n```\n\nThe return type from the `traversty()` method is not a true `Array` but can be used like an array in almost all respects, it has `.length` and `[]` subscript element access and other standard `Array` methods.\n\n<a href=\"#api\"></a>\n## API\n\n  * <a href=\"#ctor\"><code><b>traversty()</b></code></a>\n  * <a href=\"#next\"><code>traversty().<b>next()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>previous()</b></code></a>\n  * <a href=\"#previous\"><code>traversty().<b>prev()</b></code></a>\n  * <a href=\"#up\"><code>traversty().<b>up()</b></code></a>\n  * <a href=\"#parents\"><code>traversty().<b>parents()</b></code></a>\n  * <a href=\"#closest\"><code>traversty().<b>closest()</b></code></a>\n  * <a href=\"#down\"><code>traversty().<b>down()</b></code></a>\n  * <a href=\"#children\"><code>traversty().<b>children()</b></code></a>\n  * <a href=\"#siblings\"><code>traversty().<b>siblings()</b></code></a>\n  * <a href=\"#first\"><code>traversty().<b>first()</b></code></a>\n  * <a href=\"#last\"><code>traversty().<b>last()</b></code></a>\n  * <a href=\"#eq\"><code>traversty().<b>eq()</b></code></a>\n  * <a href=\"#slice\"><code>traversty().<b>slice()</b></code></a>\n  * <a href=\"#filter\"><code>traversty().<b>filter()</b></code></a>\n  * <a href=\"#not\"><code>traversty().<b>not()</b></code></a>\n  * <a href=\"#has\"><code>traversty().<b>has()</b></code></a>\n  * <a href=\"#is\"><code>traversty().<b>is()</b></code></a>\n  * <a href=\"#get\"><code>traversty().<b>get()</b></code></a>\n  * <a href=\"#each\"><code>traversty().<b>each()</b></code></a>\n  * <a href=\"#toArray\"><code>traversty().<b>toArray()</b></code></a>\n  * <a href=\"#size\"><code>traversty().<b>size()</b></code></a>\n  * <a href=\"#push\"><code>traversty().<b>push()</b></code></a>\n  * <a href=\"#sort\"><code>traversty().<b>sort()</b></code></a>\n  * <a href=\"#splice\"><code>traversty().<b>splice()</b></code></a>\n  * <a href=\"#aug\"><code>traversty.<b>aug()</b></code></a>\n  * <a href=\"#setSelectorEngine\"><code>traversty.<b>setSelectorEngine()</b></code></a>\n  * <a href=\"#noConflict\"><code>traversty.<b>noConflict()</b></code></a>\n\n--------------------------------------------------------\n<a name=\"ctor\"></a>\n### traversty(element | elements | selector)\n<code>traversty()</code> gives you a new Traversty instance containing the elements you provide.\n\nOnce you have a collection, you can call any of the Traversty methods on that collection. You can give a single DOM element or an array of DOM elements. If you provide a string argument it will be used as a selector to either query the DOM via the browser's native `querySelectorAll()` implementation or use a selector engine which you provide (see <a href=\"#setSelectorEngine\"><code>setSelectorEngine()</code></a>).\n\nYou can pluck individual elements with array accessors (subscript), e.g. `traversty(document.body)[0] // → document.body` \n\nWhen included in an Ender build, `$(element | elements | selector)` does the same thing and all the Traversty methods will be available on the resulting Ender object.\n\n--------------------------------------------------------\n<a name=\"next\"></a>\n### next([selector [, index = 0]])\n<code>traversty(elements).next()</code> returns a new Traversty instance containing *nextSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nYou will get elements that match the given *selector* (if provided) starting from the *nextSibling* of the starting element(s), all the way across to the last *nextSibling*.\n\nIf no `index` or `selector` is given then you get just the *nextSibling*s of the elements; i.e. you shift *across* by one.\n\nIf just an `index` is provided then you'll get the `index+1` *nextSibling*s of the element(s). i.e. `index` is 0-based, like arrays, 0 is *nextSibling* and 1 is *nextSibling.nextSibling*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching *nextSibling* elements.\n\n#### Examples ####\n\n```js\ntraversty('li:first-child').next()\n  // →  returns the second `<li>` of every list in the document\ntraversty('li.allstarts').next('li', 1)\n  // →  returns the `nextSibling` of the `nextSibling` of the starting elements\ntraversty('li:first-child').next('li')\n  // →  returns all `<li>` elements, except for the first-children of every lits in the document\n```\n\n--------------------------------------------------------\n<a name=\"previous\"></a>\n### previous([selector [, index = 0]])\n<code>traversty(elements).previous()</code> returns a new Traversty instance containing *previousSibling* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nExactly the same as <a href=\"#next\"><code>next()</code></a> except it works on *previousSibling*, so you move *backwards* amongst sibling elements.\n\n#### Examples ####\n\n```js\ntraversty('li:nth-child(20)').previous()\n  // →  returns 19th child of the every list in the document (where it exists)\ntraversty('li.allstarts').previous('li', 1)\n  // →  returns the `previousSibling` of the `previousSibling` of the starting element\ntraversty('li:nth-child(20)').previous('.interesting')\n  // →  returns all `<li>` elements with class \"interesting\" up to the 19th child of every list\n  //     in the document where there are at least 20 children.\n```\n\n--------------------------------------------------------\n<a name=\"prev\"></a>\n### prev([selector [, index = 0]])\n<code>traversty(elements).prev()</code> is a simple alias for <a href=\"#previous\"><code>previous()</code></a>, provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"up\"></a>\n### up([selector [, index = 0]])\n<code>traversty(elements).up()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nSimilar to <a href=\"#next\"><code>next()</code></a> and <a href=\"#previous\"><code>previous()</code></a> except that it works on *parentNode*s and will continue all the up to the document root depending on what you're asking for.\n\nIf no `index` or `selector` is given then you get just the `parentNode*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *parentNode*s of the element. i.e. `index` is 0-based, like arrays, 0 is *parentNode* and 1 is *parentNode.parentNode*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching ancestor elements.\n\n#### Examples ####\n\n```js\ntraversty('li#start').up()\n  // →  returns the `<ul>` parent element\ntraversty('li.allstarts').up('ul', 1)\n  // →  returns the grandparent `<ul>` elements if the start elements are nested at two levels\ntraversty('li.allstarts').up('ul')\n  // →  returns all ancestor `<ul>` elements, no matter how deep the nesting\n```\n\n--------------------------------------------------------\n<a name=\"parents\"></a>\n### parents([selector = '*' [, index ]])\n<code>traversty(elements).parents()</code> returns a new Traversty instance containing *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#up\"><code>up()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nPerforms exactly the same as <a href=\"#up\"><code>up()</code></a>, *except*, the `'selector'` argument defaults to `'*'` which has the effect of matching *all* ancestor elements, not just the first one. `parents()` will return exactly the same collection as `up('*')`. Provided mainly for jQuery compatibility.\n\n--------------------------------------------------------\n<a name=\"closest\"></a>\n### closest([selector = '*' [, index = 0]])\n<code>traversty(elements).closest()</code> returns a new Traversty instance containing the elements and/or *parentNode* elements according to the arguments provided, similar, but not identical to <a href=\"#parents\"><code>parents()</code></a>.\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match *all* ancestor elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. the current element)\n\nPerforms exactly the same operation as <a href=\"#parents\"><code>parents()</code></a> except for two important differences:\n\n * Matching starts at the **current** elements rather than the direct parent elements. So a `closest('*')` will return the current elements because they match the selector `'*'`.\n * The `index` argument defaults to `0`, just like <a href=\"#up\"><code>up()</code></a>, so you will only get the first match. An index of `n`, you will get the *nth* match, start with the current elements.\n\n--------------------------------------------------------\n<a name=\"down\"></a>\n### down([selector [, index = 0]])\n<code>traversty(elements).down()</code> returns a new Traversty instance containing descendant elements according to the arguments provided.\n\n * `selector` *(String)* is an optional CSS selector\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nWhile `down()` is very similar to the other methods, it's perhaps best to think of it as what you might get with a `find()` method from a selector engine.\n\n`down()` works on elements **in document-order**, so it operates on child elements and children of children but it also moves through child-siblings on the way to children of children.\n\nThe following fragment should illustrate the `index`ing you get when you use `down()`:\n\n```html\n<ul id=\"root\">\n  <li>first</li>   <!-- 0 -->\n  <li>second</li>  <!-- 1 -->\n  <li>third        <!-- 2 -->\n    <ul>           <!-- 3 -->\n      <li>i</li>   <!-- 4 -->\n      <li>ii</li>  <!-- 5 -->\n      <li>iii</li> <!-- 6 -->\n    </ul>\n  </li>\n  <li>fourth</li>  <!-- 7 -->\n</ul>\n```\n\nSo\n\n```js\ntraversty('#root').down(5)\n  // →  will give you `<li>ii</li>`\ntraversty('#root').down('li', 5)\n  // →  will give you `<li>i</li>` because the `<ul>` is ignored\n```\n\nOf course `down()` works on multiple elements simultaneously just like the other methods.\n\n\n--------------------------------------------------------\n<a name=\"children\"></a>\n### children([selector [, index = 0]])\n<code>traversty(elements).children()</code> returns a new Traversty instance containing direct descendant (child) elements according to the arguments provided.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\ntraversty('#root > li').children()\n  // →  will give you *only* the second level `<ul>` element as it's\n  //    the only direct descendant of the top `<li>` elements\ntraversty('#root > li').children().children()\n  // →  will give you *only* the second level `<li>` elements and none\n  //    of their children\n```\n\n--------------------------------------------------------\n<a name=\"siblings\"></a>\n### siblings([selector [, index = 0]])\n<code>traversty(elements).siblings()</code> returns a new Traversty instance containing *previousSibling* and *nextSibling* elements according to the arguments provided. It's important to note that the resulting collection **will not** include the original elements unless they are siblings of each other. To illustrate:\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root :nth-child(2)').siblings()\n  // →  will give you all `<li>` elements except the second\ntraversty('#root :nth-child(2n)').siblings()\n  // →  will give you all `<li>` elements because they are all siblings of\n  //    the original collection's elements\n```\n\n`siblings()` is the only method in Traversty that is not guaranteed to return a collection of elements in document-order (i.e. in the order they appear in the HTML). If you call `siblings()` on elements that are already siblings then the collection mechanism may mean that the results are out of order. Generally this shouldn't matter but you are warned if order matters to you for some reason.\n\n\n--------------------------------------------------------\n<a name=\"first\"></a>\n### first()\n<code>traversty(elements).first()</code> returns a new Traversty instance containing *only* the first element in the original collection.\n\n--------------------------------------------------------\n<a name=\"last\"></a>\n### last()\n<code>traversty(elements).last()</code> returns a new Traversty instance containing *only* the last element in the original collection.\n\n--------------------------------------------------------\n<a name=\"eq\"></a>\n### eq(index)\n<code>traversty(elements).eq()</code> returns a new Traversty instance containing *only* the element at the index specified.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection.\n\n```html\n<ul id=\"root\">\n  <li>first</li>\n  <li>second</li>\n  <li>third</li>\n  <li>fourth</li>\n</ul>\n```\n\n```js\ntraversty('#root li').eq(1)\n  // →  will give you `<li>second</li>`\ntraversty('#root li').eq(-2)\n  // →  will give you `<li>third</li>`\n```\n\n--------------------------------------------------------\n<a name=\"slice\"></a>\n### slice(start [, end])\n<code>traversty(elements).slice()</code> returns a new Traversty instance containing *only* the elements between the `start` and `end` indexes. The `end` is optional, if left out then elements from `start` to the end of the collection are included.\n\nIndexes are zero-based and can also be negative. A negative index will count backwards from the end of the collection. See the example above for <a href=\"#eq\"><code>eq()</code></a> for how this works.\n\n--------------------------------------------------------\n<a name=\"filter\"></a>\n### filter(selector | function | element)\n<code>traversty(elements).filter()</code> returns a new Traversty instance containing *only* the elements that satisfy the filter condition.\n\nA `selector` string argument will simply check each element against the selector and return only elements that match.\n\nA `function` argument will execute that function for each element in the collection and return only elements for which it receives a *truthy* response from the function. `this` within the function will be the element being checked and the single argument to the function will be the index within the collection.\n\nAn `element` argument will return a collection containing only that DOM element *only if * it exists within the collection.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendant elements under #root\nels = els.filter('li')\n  // →  returns only the 8 `<li>` elements within the collection\nels = els.filter(function () { return /^i/.test(this.innerHTML) })\n  // →  returns only the 3 `<li>` elements start have content starting with 'i'\n  //    i.e. only 'ii', 'iii' and 'iv' (not 'i')\nels = els.filter(traversty('#root ul > li')[1])\n  // →  we're using `traversty()` here as a simple selector to fetch the 'iii' element\n  //    which we pass in to `filter()`. Because this element is in the collection we get\n  //    back a collection with only this element.\n```\n\n--------------------------------------------------------\n<a name=\"not\"></a>\n### not(selector | function | element)\n<code>traversty(elements).not()</code> returns a new Traversty instance containing *only* the elements that **do not** satisfy the filter condition.\n\n`not()` is the exact inverse of <a href=\"#filter\"><code>filter()</code></a>, it takes the same arguments but returns only elements that don't match your conditions.\n\n--------------------------------------------------------\n<a name=\"has\"></a>\n### has(selector | element)\n<code>traversty(elements).has()</code> returns a new Traversty instance containing *only* the elements that have descendant elements that match the provided `selector` argument, or have `element` as a descendant element.\n\nIf a `selector` string argument is provided, each element in the collection effectively has a `find(selector)`-type operation performed on it, if any matching descendant elements are found, the parent element is retained for the new collection; otherwise it is not included.\n\nIf an `element` argument is provided then the only element included in the resulting collection is an ancestor of that `element`, if the `element` is not a descendant of any of the elements in the collection then the resulting collection will be empty.\n\n```html\n<ul id=\"root\">\n  <li>first\n    <ul>\n      <li><a href=\"#\">i</a></li>\n      <li>ii\n        <ul>\n          <li>a</li>\n          <li>b</li>\n        </ul>\n      </li>\n      <li>iii</li>\n      <li>iv</li>\n    </ul>\n  </li>\n  <li>second</li>\n</ul>\n```\n\n```js\nvar els = traversty('#root *')\n  // →  start off with all 12 descendant elements under #root\nels = els.has('li')\n  // →  returns a collection of 4 elements which have `<li>` descendants: the 'first' `<li>`,\n  //    the `<ul>` directly under it, the 'ii' `<li>` and the `<ul>` directly under that.\nels.has(traversty('#root a')[0])\n  // →  we're using `traversty()` here as a simple selector to fetch the `<a>` element\n  //    which we pass in to `has()`. There are two elements that have this single element\n  //    as a descendant, the 'first' `<li>` element and the `<ul>` directly under it.\n```\n\n--------------------------------------------------------\n<a name=\"is\"></a>\n### is(selector | function | element)\n<code>traversty(elements).is()</code> returns a **boolean** indicating whether at least one of the elements within the collection matches the condition. The method should be thought of as a version of <a href=\"#filter\"><code>filter()</code></a> that returns a boolean if the resulting collection has at least one element; i.e. `traversty(elements).filter(condition).length > 0`.\n\n\n--------------------------------------------------------\n<a name=\"each\"></a>\n### each(function [, thisContext])\n<code>traversty(elements).each()</code> will execute the provided `function` on each of the elements in the current collection. `each()` will return the original collection so you can continue chaining method calls.\n\nYour `function` will be called with `this` equal to the individual elements or the `thisContext` argument if supplied. The arguments provided to the function are:\n\n1. `element`: the current element in the collection\n2. `index`: the index of the current element in the collection\n3. `collection`: the entire Traversty object for this collection\n\nNote the ordering of arguments 1 and 2 are different to the <a href=\"http://api.jquery.com/each/\"><code>jQuery().each()</code></a>, instead Traversty is closer to ES5 <a href=\"https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/forEach\"><code>Array.prototype.forEach</code></a>.\n\n```js\ntraversty('li').each(function (el, i) {\n  this.innerHTML += ' (I am ' + i + ')'\n})\n```\n\n--------------------------------------------------------\n<a name=\"get\"></a>\n### get(index)\n<code>traversty(elements).get()</code> returns a single DOM element at the specified index of the collection. Indexes are zero-based and can be negative. See <a href=\"#eq\"><code>eq()</code></a> for specifics.\n\n\n--------------------------------------------------------\n<a name=\"toArray\"></a>\n### toArray()\n<code>traversty(elements).toArray()</code> returns a true `Array` object containing elements within the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array) for details on what you get.\n\n\n--------------------------------------------------------\n<a name=\"size\"></a>\n### size()\n<code>traversty(elements).size()</code> returns an number indicating the number of elements in the collection. Works exactly the same as `.length` on an `Array` (indeed, you can call `.length` on a Traversty object and get the same value).\n\n\n--------------------------------------------------------\n<a name=\"push\"></a>\n### push(element1 [, element2 [...]])\n<code>traversty(elements).push()</code> reuses `Array.prototype.push`. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/push) for details.\n\nBeware of pushing non-DOM elements onto a Traversty object! This is not supported behaviour.\n\n\n--------------------------------------------------------\n<a name=\"sort\"></a>\n### sort([compareFunction])\n<code>traversty(elements).sort()</code> reuses `Array.prototype.sort` to sort the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort) for details.\n\n\n--------------------------------------------------------\n<a name=\"splice\"></a>\n### splice(index, howMany [, element1 [...]])\n<code>traversty(elements).splice()</code> reuses `Array.prototype.splice` to splice the collection. See [MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/splice) for details.\n\n\n--------------------------------------------------------\n<a name=\"aug\"></a>\n### aug(methodMap)\n<code>traversty.aug()</code> extends Traversty's functionality with custom methods off the main Traversty prototype. The `methodMap` is simply a map of method names to functions. The functions will respond when called off a collection: `traversty().method(args)`.\n\n```js\ntraversty.aug({ append: function (element) {\n  // make sure we return 'this', which we can get from each()\n  return this.each(function (el, i) {\n    // append original to first element, append a clone to the rest\n    el.appendChild(i > 0 ? element.cloneNode(true) : element)\n  })\n}})\n\nvar span = document.createElement('span')\nspan.innerHTML = 'BOOM!'\ntraversty('li').append(span)\n```\n\n\n--------------------------------------------------------\n<a name=\"setSelectorEngine\"></a>\n### setSelectorEngine(selectorEngine)\n<code>traversty.setSelectorEngine()</code> injects a selector engine for Traversty to use. See the next section for details. Returns the main `Traversty` object for chainability, e.g.: `var $ = traversty.setSelectorEngine(qwery)`.\n\n## Selector engines\n\nTraversty should work out-of-the-box on modern browsers as it leverages native `querySelectorAll()` and `matchesSelector()` where they exist. This means that you should be able to use Traversty without a selector engine on most smartphone browsers without any problems.\n\nUnfortunately, this doesn't work with older browsers, particularly IE8 and below. While IE8 has a CSS2-compliant `querySelectorAll()`, it doesn't have a `matchesSelector()` which Traversty makes heavy use of.\n\nTraversty allows you to plug in your favourite selector engine so it can work on whatever browsers your engine supports. Traversty is tested to support [Qwery](https://github.com/ded/qwery), [Sel](https://github.com/amccollum/sel), [Sizzle](https://github.com/jquery/sizzle), [NWMatcher](https://github.com/dperini/nwmatcher) and [Zest](https://github.com/chjj/zest).\n\nTraversty uses *feature detection* to figure out how to use your selector engine, it tries to find the method used to *find* elements given a element root and the method used to determine if an element *matches* a given selector. If it can't figure out how to use your selector engine then you just need to pretend that it works like one of the supported ones and it should be OK.\n\nFor example:\n\n```js\ntraversty.setSelectorEngine({\n    select: function(selector, root) {\n      return MyEngine(selector, root)\n    }\n  , is: function(selector, root) {\n      return MyEngine(root).isTheSameAs(selector)\n    }\n})\n```\n\nTraversty will also do some trickery to make up for deficiencies in some selector engines, such as out-of-order results when selecting on groups ('a,b').\n\nIf you have a new selector engine that you want Traversty to support then either let me know or fork, patch and submit.\n\n\n## I want a demo!\n\nYou'll have to make do with the integration tests:\n\n### Ender\n\n[Here](http://rvagg.github.com/traversty/test/integration/ender_qwery.html) is Traversty running in an Ender build with Qwery and Bonzo. You can also see it running with [Sel](http://rvagg.github.com/traversty/test/integration/ender_sel.html), [Sizzle](http://rvagg.github.com/traversty/test/integration/ender_sizzle.html), [NWMatcher](http://rvagg.github.com/traversty/test/integration/ender_nwmatcher.html) and [without a selector engine](http://rvagg.github.com/traversty/test/integration/ender_sel.html) (works in modern browsers, including IE9+).\n\nView-source to see what it's doing, note that it's operating on 2 lists at the same time.\n\n### Vanilla\n\n[Here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_qwery.html) is Traversty bundled with Qwery as the selector engine and the `css()` augmenting example code [/examples/aug-css.js](https://github.com/rvagg/traversty/blob/master/examples/aug-css.js) performing the same integration tests. There is also the same example using Zest instead [here](https://github.com/rvagg/traversty/blob/master/test/integration/traversty_css_zest.html)\n\n## Things to note\n\n * Traversty always does a **uniqueness** check on its collection of elements so you should never end up with duplicates. If you do a `traversty('body,ul').down('li')` you would still only get a unique list of all <code>&lt;li&gt;</code> elements in the document.\n\n * Traversty ignores text and comment nodes and should only ever operate on the DOM element nodes you would expect (i.e. with `.nodeType === 1`).\n\n * Traversty currently orders results (for each element in the starting list) in document-order, so `previous('*')` will give you results starting from the *firstChild* of the parent element up to the *previousSibling* of the starting element, rather than starting with the *previousSibling* and listing backwards (this doesn't impact on indexing, which still works backwards, only the order of result lists). The single **exception** to this is <a href=\"#siblings\"><code>siblings()</code></a>, see the note in that section for details.\n\n## Supported browsers\n\nTraversty is tested with IE6+, Firefox 3+, Safari 4+, Opera current and Chrome current. You'll need a supported selector engine to operate on some of these older browsers.\n\n\n## Ender integration\n\nTraversty is designed to be inserted into an Ender build. It's in npm so simply include it in your build command, something like: `ender build sel bonzo traversty`\n\nTraversty will attempt to use whatever selector engine you've included in your Ender build.\n\n### What about Bonzo?\n\nTraversty is designed to add to the goodness you get in Bonzo, although Bonzo isn't a dependency. Bonzo has `next()` and `previous()` and a few other methods already and it is intended that Traversty replace these in your Ender build (because they are way-better!). Argument-less they should do exactly the same thing but Traversty adds the extra arguments for greater flexibility. If you are using Bonzo in Ender along with Traversty then you should make sure Traversty is included *after* Bonzo. Unfortunately, [Ender doesn't guarantee order](https://github.com/ender-js/Ender/issues/63) so you may have to fiddle a bit. The Ender 1.0 CLI does correct ordering but that's not formally released yet, you can use it by installing ender via npm with `npm install ender@dev`.\n\n\n## Contributing\n\nAwesome! Just do it, fork and submit your pull requests and they will be promptly considered.\n\nI'd also love it if you could contribute tests for bugs you find or features you add.\n\n### Tests\n\nTraversty uses [Buster](http://busterjs.org) for unit testing.\n\nSince Buster is still in Beta, the capture-server/client is a bit buggy and can be frustrating. So, instead, simply run *index.html* file in the *tests* directory in each of the browsers you need to test. It'll load and run all of the tests.\n\n\n## Credits\n\n * Firstly, much credit should go to the awesome Prototype guys and their excellent API that I initially ripped off for Traversty 0.x.\n * Obviously, kudos goes to John Resig and the jQuery team for their traversal and filtering API that I've so shamelessly ripped off.\n * Thanks to [@ded](http://github.com/ded) and [@fat](http://github.com/fat) for Ender, particularly @ded for Bonzo, upon which Traversty is designed to build.\n\n\n## Licence\n\nTraversty is Copyright (c) 2012 Rod Vagg [@rvagg](https://twitter.com/rvagg) and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.\n","readmeFilename":"README.md","bugs":{"url":"https://github.com/rvagg/traversty/issues"},"_id":"traversty@1.0.5","dist":{"shasum":"773b461024eb59cebcf7a1821aab591e43fbe76f","tarball":"https://registry.npmjs.org/traversty/-/traversty-1.0.5.tgz","integrity":"sha512-fw+IaACSEOOEkGJ/Af+cwQHIpjhRVvqk3bojd/PnvdW1Bo1yT8bFD38vFSaxwexL8o12cl/aVoOR1xbv28IwRg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCX7CN3atp05ZDLB7PJMU21+d5VAH8ZcQgyaJrPeTPObQIge0wOWH4lNs97ESsUiUZsPBC424YRZ2j983nGgbt5raY="}]},"_from":".","_npmVersion":"1.3.8","_npmUser":{"name":"rvagg","email":"rod@vagg.org"},"maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"directories":{},"deprecated":"no longer maintained"}},"readme":"Traversty &mdash; headache-free DOM traversal\n=============================================\n\nTraversty is a library-agnostic DOM traversal utility giving you 4 flexible methods for moving around the DOM.\n\nInspired by [Prototype](http://prototypejs.org)'s excelent \"DOM traversal toolkit\", you get `up()`, `down()`, `next()` and `previous()` with optional `selector` and `index` arguments, all in a multi-element environment (jQuery-like rather than Prototype's single-element implementation).\n\nTraversty is designed primarily to be integrated in an [Ender](http://ender.no.de/) build, to augment what's already available in [Bonzo](https://github.com/ded/bonzo) but can just as easily be used as a stand-alone utility. \n\nExample usage\n-------------\n\n*This code is used Traversty Ender integration tests and depends on Bonzo*\n\n```js\n$('#root > ul') // can match multiple elements\n  .down(0).css('color', 'red')\n  .next('li', 1).css('color', 'green')\n  .next().down('li', 2).css('color', 'blue')\n  .next().down().css('color', 'yellow')\n  .up(2).next().css('color', 'purple');\n```\n\n\nAPI\n---\n\n### Main: `traversty(elements || selector)` ###\n\nGives you a new Traversty instance containing the DOM elements you provide, allowing you to call any of the following methods. You can give a single DOM element or an array of DOM elements. If you provide a string argument it will be used as a selector to either query the DOM via the browser's native `querySelectorAll()` implementation or use a selector engine which you provide (see below).\n\nIndividual elements are available with array accessors, e.g. `traversty(document.body)[0] // → document.body` \n\nWhen included in an Ender build, `$(elements || selector)` does the same thing.\n\n### Next: `traversty(elements).next([selector = \"*\"[, index = 0]])` ###\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match all elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nReturns a new Traversty instance wrapped around the resulting DOM elements. You will get elements that match the given *selector* (or '*') starting from the *nextSibling* of the starting element(s), all the way across to the last *nextSibling*.\n\nIf no `index` or `selector` is given then you get just the *nextSibling*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *nextSibling*s of the element(s). i.e. `index` is 0-based, like arrays, 0 is *nextSibling* and 1 is *nextSibling.nextSibling*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching *nextSibling* elements.\n\n#### Examples ####\n\n```js\ntraversty('li:first-child').next(); // →  returns the second `<li>` of every list in the document\ntraversty('li.allstarts').next('li', 1); // →  returns the `nextSibling` of the `nextSibling` of the starting elements\ntraversty('li:first-child').next('li'); // →  returns all `<li>` elements, except for the first-children of every lits in the document\n```\n\n\n### Previous: `traversty(elements).previous([selector = \"*\"[, index = 0]])` ###\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match all elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nExactly the same as `.next()` except it works on *previousSibling*, so you move backwards amongst sibling elements.\n\n#### Examples ####\n\n```js\ntraversty('li:nth-child(20)').previous(); // →  returns 19th child of the every list in the document (where it exists)\ntraversty('li.allstarts').previous('li', 1); // →  returns the `previousSibling` of the `previousSibling` of the starting element\ntraversty('li:nth-child(20)').previous('.interesting'); // →  returns all `<li>` elements with class \"interesting\" up to the 19th child of every list in the document where there are at least 20 children.\n```\n\n### Up: `traversty(elements).up([selector = \"*\"[, index = 0]])` ###\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match all elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nSimilar to `next()` and `previous()` except that it works on *parentNode*s and will continue all the up to the document root depending on what you're asking for.\n\nIf no `index` or `selector` is given then you get just the `parentNode*s of the elements.\n\nIf just an `index` is provided then you'll get the `index+1` *parentNode*s of the element. i.e. `index` is 0-based, like arrays, 0 is *parentNode* and 1 is *parentNode.parentNode*, unless you provide a `selector` of course, in which case it'll skip over non-matching elements.\n\nIf just a `selector` is provided then no `index` will be assumed, you'll get **all** matching ancestor elements.\n\n\n#### Examples ####\n\n```js\ntraversty('li#start').up(); // →  returns the `<ul>` parent element\ntraversty('li.allstarts').up('ul', 1); // →  returns the grandparent `<ul>` elements if the start elements are nested at two levels\ntraversty('li.allstarts').up('ul'); // →  returns all ancestor `<ul>` elements, no matter how deep the nesting\n```\n\n### Down: `traversty(elements).down([selector = \"*\"[, index = 0]])` ###\n\n * `selector` *(String)* is an optional CSS selector (defaults to `'*'`, i.e. match all elements)\n * `index` *(Number)* is an optional array-ish index argument (defaults to `0`, i.e. first match)\n\nWhile `down()` is very similar to the other methods, it's perhaps best to think of it as what you might get with a `find()` method from a selector engine.\n\n`down()` works on elements **in document-order**, so it operates on child elements and children of children but it also moves through child-siblings on the way to children of children.\n\nThe following fragment should illustrate the `index`ing you get when you use `down()`:\n\n```html\n<ul id=\"root\">\n  <li>fisrt</li>   <!-- 0 -->\n  <li>second</li>  <!-- 1 -->\n  <li>third        <!-- 2 -->\n    <ul>           <!-- 3 -->\n      <li>i</li>   <!-- 4 -->\n      <li>ii</li>  <!-- 5 -->\n      <li>iii</li> <!-- 6 -->\n    </ul>\n  </ul>\n  <li>fourth</li>  <!-- 7 -->\n</ul>\n```\n\nSo\n\n```js\ntraversty('#root').down(5) // →  will give you `<li>ii</li>`\ntraversty('#root').down('li', 5) // →  will give you `<li>i</li>` because the `<ul>` is ignored:w\n```\n\nOf course `down()` works on multiple elements simultaneously just like the other methods.\n\n\nThings to note\n--------------\n\n * Traversty always does a **uniqueness** check on its collection of elements so you should never end up with duplicates. If you did a `traversty('body,ul').down('li')` you would still only get a unique list of all *<li>* elements in the document.\n\n * Traversty ignores text and comment nodes and should only ever operate on the DOM element nodes you would expect (i.e. with *nodeType==1*).\n\n * Traversty currently orders results (for each element in the starting list) in document-order, so `previous('*')` will give you results starting from the *firstChild* of the parent element up to the *previousSibling* of the starting element, rather than starting with the *previousSibling* and listing backwards (this doesn't impact on indexing, which still works backwards, only the order of result lists). This may change, I haven't decided yet!\n\n### Supported browsers ###\n\nTraversty is tested with IE6+, Firefox 3+, Safari 4+, Opera current and Chrome current. You'll need a supported selector engine to operate on some of these older browsers. See below.\n\n\nSelector engines\n----------------\n\nTraversty should work out-of-the-box on modern browsers as it leverages native `querySelectorAll()` and `matchesSelector()` where they exist. This means that you should be able to use Traversty without a selector engine on most smartphone browsers without any problems.\n\nUnfortunately, this doesn't work with older browsers, particularly IE8 and below. While IE8 has a CSS2-compliant `querySelectorAll()`, it doesn't have a `matchesSelector()` which Traversty makes heavy use of.\n\n### `traversty.setSelectorEngine(engine)` ###\n\nTraversty allows you to plug in your favourite selector engine so it can work on whatever browser your engine supports. Out of the box, Traversty is tested to support [Qwery](https://github.com/ded/qwery), [Sel](https://github.com/amccollum/sel), [Sizzle](https://github.com/jquery/sizzle) and [NWMatcher](https://github.com/dperini/nwmatcher).\n\nTraversty uses *feature detection* to figure out how to use your selector engine, it tries to find the method used to *find* elements given a element root and the method used to determine if an element *matches* a given selector. If it can't figure out how to use your selector engine then you just need to pretend that it works like one of the supported ones and it should be OK.\n\nFor example:\n\n```js\ntraversty.setSelectorEngine({\n    select: function(selector, root) {\n      return MyEngine(selector, root);\n    }\n  , is: function(selector, root) {\n      return MyEngine(root).isTheSameAs(selector);\n    }\n});\n```\n\nTraversty will also do some trickery to make up for deficiencies in some selector engines, such as out-of-order results when selecting on groups ('a,b').\n\nIf you have a new selector engine that you want Traversty to support then either let me know or fork, patch and submit.\n\n\nEnder integration\n-----------------\n\nTraversty is designed to be inserted into an Ender build. It's in NPM so simply include it in your build command, something like: `ender build sel bonzo traversty`\n\nTraversty will attempt to use whatever selector engine you've included in your Ender build.\n\n### What about Bonzo? ###\n\nTraversty is designed to add to the goodness you get in Bonzo, although Bonzo isn't a dependency. Bonzo has `next()` and `previous()` already and it is intended that Traversty replace these in your ender build. Argument-less they should do exactly the same thing but Traversty adds the extra arguments for greater flexibility. If you are using Bonzo in Ender along with Traversty then you should make sure Traversty is included *after* Bonzo. Unfortunately, [Ender doesn't guarantee order](https://github.com/ender-js/Ender/issues/63) so you may have to fiddle a bit. \n\n\nContributing\n------------\n\nAwesome! Just do it, fork and submit your pull requests and they will be promptly considered.\n\nI'd also love it if you could contribute tests for bugs you find or features you add.\n\nWhile I'm not a coding-style nazi but I do like consistency. I've chosen a particular style for this project (not my usual style, I have a Java background, I'm experimenting with style!) and I'd prefer to keep it consistent.\n\n### Tests ###\n\nTraversty uses [Buster](http://busterjs.org) for unit testing. It works by running a server for you to attach browsers to so you can submit all tests to be run in all of the attached browsers right from the command-line.\n\nSimply do this:\n\n```\n$ sudo npm install buster -g  # install Buster if you haven't already got it\n$ make server                 # will start the Buster server for you on port 1111.\n$                             # point a bunch of browsers to that server, including older versions of IE (start your VMs!)\n$ make test                   # will submit the tests to the Buster server to be run on those browsers\n```\n\nYou'll see a nice output with the results of the tests as they happen.\n\n### Where are your semi-colons? ###\n\nOh, you noticed that? Just think of this as my [The Cat in the Hat](http://en.wikipedia.org/wiki/The_Cat_in_the_Hat) project. It's an experiment in how difficult it is to write valid JavaScript devoid of semi-colons. There's only a couple of awkward constructions that could do with a `for` loop, but I don't think it's a big deal. \n\n\nCredits\n-------\n\n * Firstly, much credit should go to the awesome Prototype guys and their excellent API that I've ripped off.\n * Thanks to [@ded](http://github.com/ded) and [@fat](http://github.com/fat) for Ender, particularly @ded for Bonzo, upon which Traversty is designed to build.\n\nThe bulk of the work is done by me, Rod Vagg, [@rvagg](http://twitter.com/rvagg)\n\nLicence\n-------\n\nBlah, Blah, MIT\n","maintainers":[{"name":"rvagg","email":"rod@vagg.org"}],"time":{"modified":"2022-06-27T20:37:57.371Z","created":"2011-12-13T09:26:14.628Z","0.0.1":"2011-12-13T09:27:00.372Z","0.0.2":"2011-12-14T04:05:01.164Z","0.0.3":"2011-12-21T10:15:16.642Z","0.0.4":"2012-01-02T00:14:52.305Z","0.0.5":"2012-02-13T01:40:48.004Z","0.0.6":"2012-02-25T22:42:28.585Z","0.0.7":"2012-06-20T10:29:27.178Z","0.0.7-dev":"2012-05-12T10:14:18.205Z","0.0.8":"2012-05-12T10:16:04.805Z","1.0.0":"2012-11-01T05:19:44.878Z","1.0.1":"2012-11-01T06:41:27.049Z","1.0.2":"2012-11-02T00:53:44.614Z","1.0.3":"2013-01-29T00:14:41.804Z","1.0.4":"2013-02-05T06:01:02.105Z","1.0.5":"2013-09-23T01:48:20.247Z"},"author":{"name":"Rod Vagg","email":"rod@vagg.org"},"repository":{"type":"git","url":"https://github.com/rvagg/traversty.git"}}