1 | #CSSselect [![Build Status](https://secure.travis-ci.org/fb55/CSSselect.png?branch=master)](http://travis-ci.org/fb55/CSSselect)
|
2 |
|
3 | a CSS selector compiler/engine
|
4 |
|
5 | ##What?
|
6 |
|
7 | CSSselect 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 |
|
9 | In 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
|
20 | var 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 |
|
29 | Queries `elems`, returns an array containing all matches.
|
30 |
|
31 | Aliases: `CSSselect.selectAll(query, elems)`, `CSSselect.iterate(query, elems)`.
|
32 |
|
33 | ####`CSSselect.compile(query)`
|
34 |
|
35 | Compiles the query, returns the function.
|
36 |
|
37 | ####`CSSselect.is(elem, query, options)`
|
38 |
|
39 | Tests 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 |
|
43 | Arguments 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 |
|
53 | The 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 |
|
55 | While 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 |
|
57 | The 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 |
|
59 | And that's exactly what CSSselect does.
|
60 |
|
61 | ##How?
|
62 |
|
63 | By 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 |
|
104 | License: BSD-like
|