diff options
Diffstat (limited to 'node_modules/css-select/README.md')
| -rw-r--r-- | node_modules/css-select/README.md | 133 |
1 files changed, 0 insertions, 133 deletions
diff --git a/node_modules/css-select/README.md b/node_modules/css-select/README.md deleted file mode 100644 index e36282fe2..000000000 --- a/node_modules/css-select/README.md +++ /dev/null @@ -1,133 +0,0 @@ -# css-select [](https://npmjs.org/package/css-select) [](http://travis-ci.org/fb55/css-select) [](https://npmjs.org/package/css-select) [](https://coveralls.io/r/fb55/css-select) - -a CSS selector compiler/engine - -## What? - -css-select 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. - -In its default configuration, css-select queries the DOM structure of the [`domhandler`](https://github.com/fb55/domhandler) module (also known as htmlparser2 DOM). - -__Features:__ - -- Full implementation of CSS3 selectors -- Partial implementation of jQuery/Sizzle extensions -- Very high test coverage -- Pretty good performance - -## Why? - -The traditional approach of executing CSS selectors, named left-to-right execution, is to execute every component of the selector in order, from left to right _(duh)_. The execution of the selector `a b` for example will first query for `a` elements, then search these for `b` elements. (That's the approach of eg. [`Sizzle`](https://github.com/jquery/sizzle), [`nwmatcher`](https://github.com/dperini/nwmatcher/) and [`qwery`](https://github.com/ded/qwery).) - -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^(k+1))`, where `k` is the number of descendant selectors (that's the space in the example above). - -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)`. That's called right-to-left execution. - -And that's what css-select does – and why it's quite performant. - -## How does it work? - -By building a stack of functions. - -_Wait, what?_ - -Okay, so let's suppose we want to compile the selector `a b` again, for right-to-left execution. We start by _parsing_ the selector, which means we turn the selector into an array of the building-blocks of the selector, so we can distinguish them easily. That's what the [`css-what`](https://github.com/fb55/css-what) module is for, if you want to have a look. - -Anyway, after parsing, we end up with an array like this one: - -```js -[ - { type: 'tag', name: 'a' }, - { type: 'descendant' }, - { type: 'tag', name: 'b' } -] -``` - -Actually, this array is wrapped in another array, but that's another story (involving commas in selectors). - -Now that we know the meaning of every part of the selector, we can compile it. That's where it becomes interesting. - -The basic idea is to turn every part of the selector into a function, which takes an element as its only argument. The function checks whether a passed element matches its part of the selector: If it does, the element is passed to the next turned-into-a-function part of the selector, which does the same. If an element is accepted by all parts of the selector, it _matches_ the selector and double rainbow ALL THE WAY. - -As said before, we want to do right-to-left execution with all the big O improvements nonsense, so elements are passed from the rightmost part of the selector (`b` in our example) to the leftmost (~~which would be `c`~~ of course `a`). - -_//TODO: More in-depth description. Implementation details. Build a spaceship._ - -## API - -```js -var CSSselect = require("css-select"); -``` - -#### `CSSselect(query, elems, options)` - -Queries `elems`, returns an array containing all matches. - -- `query` can be either a CSS selector or a function. -- `elems` can be either an array of elements, or a single element. If it is an element, its children will be queried. -- `options` is described below. - -Aliases: `CSSselect.selectAll(query, elems)`, `CSSselect.iterate(query, elems)`. - -#### `CSSselect.compile(query)` - -Compiles the query, returns a function. - -#### `CSSselect.is(elem, query, options)` - -Tests whether or not an element is matched by `query`. `query` can be either a CSS selector or a function. - -#### `CSSselect.selectOne(query, elems, options)` - -Arguments are the same as for `CSSselect(query, elems)`. Only returns the first match, or `null` if there was no match. - -### Options - -- `xmlMode`: When enabled, tag names will be case-sensitive. Default: `false`. -- `strict`: Limits the module to only use CSS3 selectors. Default: `false`. -- `rootFunc`: The last function in the stack, will be called with the last element that's looked at. Should return `true`. - -## Supported selectors - -_As defined by CSS 4 and / or jQuery._ - -* Universal (`*`) -* Tag (`<tagname>`) -* Descendant (` `) -* Child (`>`) -* Parent (`<`) * -* Sibling (`+`) -* Adjacent (`~`) -* Attribute (`[attr=foo]`), with supported comparisons: - * `[attr]` (existential) - * `=` - * `~=` - * `|=` - * `*=` - * `^=` - * `$=` - * `!=` * - * Also, `i` can be added after the comparison to make the comparison case-insensitive (eg. `[attr=foo i]`) * -* Pseudos: - * `:not` - * `:contains` * - * `:icontains` * (case-insensitive version of `:contains`) - * `:has` * - * `:root` - * `:empty` - * `:parent` * - * `:[first|last]-child[-of-type]` - * `:only-of-type`, `:only-child` - * `:nth-[last-]child[-of-type]` - * `:link`, `:visited` (the latter doesn't match any elements) - * `:selected` *, `:checked` - * `:enabled`, `:disabled` - * `:required`, `:optional` - * `:header`, `:button`, `:input`, `:text`, `:checkbox`, `:file`, `:password`, `:reset`, `:radio` etc. * - * `:matches` * - -__*__: Not part of CSS3 - ---- - -License: BSD-like |