UNPKG

3.73 kBMarkdownView Raw
1#CSSselect [![Build Status](https://secure.travis-ci.org/fb55/CSSselect.png?branch=master)](http://travis-ci.org/fb55/CSSselect)
2
3a CSS selector compiler/engine
4
5##What?
6
7CSSselect turns CSS selectors into functions that tests if elements match them. When searching for elements, testing is executed "from the top", similar to how browsers execute CSS selectors.
8
9In its default configuration, CSSselect queries the DOM structure of the [`domhandler`](https://github.com/fb55/domhandler) module.
10
11__Features:__
12
13- Full implementation of CSS3 selectors
14- Partial implementation of jQuery/Sizzle extensions
15- 100% test coverage
16
17##API
18
19```js
20var CSSselect = require("CSSselect");
21```
22
23####`CSSselect(query, elems, options)`
24
25- `query` can be either a function or a string. If it's a string, the string is compiled as a CSS selector.
26- `elems` can be either an array of elements, or a single element. If it is an element, its children will be used (so we're working with an array again).
27- `options` is described below.
28
29Queries `elems`, returns an array containing all matches.
30
31Aliases: `CSSselect.selectAll(query, elems)`, `CSSselect.iterate(query, elems)`.
32
33####`CSSselect.compile(query)`
34
35Compiles the query, returns the function.
36
37####`CSSselect.is(elem, query, options)`
38
39Tests whether or not an element is matched by `query`. `query` can be either a CSS selector or a function.
40
41####`CSSselect.selectOne(query, elems, options)`
42
43Arguments are the same as for `CSSselect(query, elems)`. Only returns the first match, or `null` if there was no match.
44
45###Options
46
47- `xmlMode`: When enabled, tag names will be case-sensitive. Default: `false`.
48- `strict`: Limits the module to only use CSS3 selectors. Default: `false`.
49- `rootFunc`: The last function in the stack. Will be called with the last element that's looked at. Should return `true` if it shouldn't be called again for every matching subselector.
50
51##Why?
52
53The common approach of executing CSS selectors (used eg. by [`Sizzle`](https://github.com/jquery/sizzle), [`nwmatcher`](https://github.com/dperini/nwmatcher/) and [`qwery`](https://github.com/ded/qwery)) is to execute every component of the selector in order, from left to right. The selector `a b` for example will first look for `a` elements, then search these for `b` elements.
54
55While this works, it has some downsides: Children of `a`s will be checked multiple times, first, to check if they are also `a`s, then, for every superior `a` once, if they are `b`s. Using [Big O notation](http://en.wikipedia.org/wiki/Big_O_notation), that would be `O(n^2)`.
56
57The far more efficient approach is to first look for `b` elements, then check if they have superior `a` elements: Using big O notation again, that would be `O(n)`.
58
59And that's exactly what CSSselect does.
60
61##How?
62
63By stacking functions!
64
65_//TODO: Better explanation. For now, if you're interested, have a look at the source code._
66
67##Supported selectors:
68
69* Universal (`*`)
70* Tag (`<tagname>`)
71* Descendant (` `)
72* Child (`>`)
73* Parent (`<`) *
74* Sibling (`+`)
75* Adjacent (`~`)
76* Attribute (`[attr=foo]`), with supported comparisons:
77 * `[attr]` (existential)
78 * `=`
79 * `~=`
80 * `|=`
81 * `*=`
82 * `^=`
83 * `$=`
84 * `!=` *
85 * Also, `i` can be added after the comparison to make the comparison case-insensitive (eg. `[attr=foo i]`) *
86* Pseudos:
87 * `:not`
88 * `:contains` *
89 * `:has` *
90 * `:root`
91 * `:empty`
92 * `:parent` *
93 * `:[first|last]-child[-of-type]`
94 * `:only-of-type`, `:only-child`
95 * `:nth-[last-]child[-of-type]`
96 * `:selected` *, `:checked`
97 * `:enabled`, `:disabled`
98 * `:header`, `:button`, `:input`, `:text`, `:checkbox`, `:file`, `:password`, `:reset`, `:radio` etc. *
99
100__*__: Non-standard extensions
101
102---
103
104License: BSD-like