blob: e604ed47b8fc8a42c7b33b391abd246e9c419c2a (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
# cheerio-advanced-selectors
Add support for the following selectors to
[cheerio](https://github.com/cheeriojs/cheerio):
- `:first`
- `:last`
- `:eq(index)`
More selectors can easily be added: Just [open an issue](https://github.com/watson/cheerio-advanced-selectors/issues) and I'll look into it :)
[](https://travis-ci.org/watson/cheerio-advanced-selectors)
[](https://github.com/feross/standard)
This module is inspired by
[cheerio-eq](https://github.com/watson/cheerio-eq) with the added
support for many different selectors.
Supports cheerio version 0.18.0 and above.
## Installation
```
npm install cheerio-advanced-selectors
```
## Usage
Use the `.wrap()` function to make cheerio-advanced-selectors take care
of everything for you:
```js
var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')
cheerio = cheerioAdv.wrap(cheerio)
var $ = cheerio.load('<div>foo</div><div>bar</div>')
$('div:first').text() // => 'foo'
```
## Advanced usage
Alternatively use the `.find()` function to only use
cheerio-advanced-selectors for a specific selector:
```js
var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')
var $ = cheerio.load('<div><span>foo</span></div><div><span>bar</span></div>')
cheerioAdv.find($, 'div:eq(1)').text() // => 'bar'
```
If you need to run the same selector on a lot of different HTML
documents, you can speed things up by pre-compiling the selector using
the `.compile()` function:
```js
var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')
var myH1 = cheerioAdv.compile('div:first span:eq(1) h1')
var html1 = cheerio.load('<div><span><h1>foo1</h1></span><span><h1>bar1</h1></span></div>')
var html2 = cheerio.load('<div><span><h1>foo2</h1></span><span><h1>bar2</h1></span></div>')
myH1(html1).text() // => 'bar1'
myH1(html2).text() // => 'bar2'
```
## What's the problem?
Cheerio sacrifices advanced CSS selector support for speed. This means
for instance that the `:eq()` selector isn't supported. The work-around
is normally to use the `.eq()` function instead:
```js
// this will not work:
$('div:eq(1)');
// use this instead:
$('div').eq(1);
```
This is a good alternative if you write the CSS selectors from scrach,
but what if you are working with selectors that already contain `:eq()`?
**Don't fear, cheerio-advanced-selectors is here :)**
### Solution
The solution to the problem is to automatically parse the selector
string at run-time. So if you give cheerio-advanced-selectors a selector
like `div:eq(1)` it will return the following cheerio cursor:
`$('div').eq(1)`.
It also works for complex selectors, so that `div:eq(1) h2:first span`
will be converted and interpreted as
`$('div').eq(1).find('h2').first().find('span')`.
## Supported advanced selectors
This module currently only support a minimal subset of the possible
advanced selectors:
- `:first`
- `:last`
- `:eq(index)`
But don't fear :) It's easy to add support for other selectors. Just
[open an
issue](https://github.com/watson/cheerio-advanced-selectors/issues) or
make a pull request.
## API
#### `.wrap(cheerio)`
Wraps the main cheerio module to overload the standard `load` function
so it knows how to handle the advanced selectors.
Returns the `cheerio` module.
#### `.find(cheerio, selector [, context [, root]])`
Run the `selector` on the given cheerio object optionally within the
given `context` and optionally on the given `root`.
The `cheerio` object is usually called `$`.
#### `.compile(selector)`
Compiles the `selector` and returns a function which take 3 arguments:
`fn(cheerio [, context [, root]])`:
- `cheerio` - a reference to the cheerio object (usually called `$`)
- `context` - the context in which to run the selector (optional)
- `root` - the HTML root on which to run the selector (optional)
## License
MIT
|
