# jq-html-parser
> A jQuery powered parser for extracting text (strings) from HTML documents
Latest version **0.3.0** (published 2015-03-30) · ISC license · 0 weekly downloads
## Install
```sh
npm install jq-html-parser
pnpm add jq-html-parser
yarn add jq-html-parser
bun add jq-html-parser
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.3.0 |
| Published | 2015-03-30 |
| First published | 2014-06-02 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Jack Stevens |
| Maintainers | jpstevens |
| Keywords | jquery, html, parser, parse |
## Links
- npm: https://www.npmjs.com/package/jq-html-parser
- Repository: https://github.com/jpstevens/jq-html-parser
- Issues: https://github.com/jpstevens/jq-html-parser/issues
- npm.io page: https://npm.io/package/jq-html-parser
## Dependencies (2)
- [chalk](https://npm.io/package/chalk.md) ^1.0.0
- [jqdom](https://npm.io/package/jqdom.md) 0.0.5
## Alternatives
- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads
## Recent versions
- 0.3.0 (latest) — 2015-03-30
- 0.2.1 — 2014-07-18
- 0.2.0 — 2014-07-18
- 0.1.0 — 2014-06-30
- 0.0.7 — 2014-06-02
- 0.0.6 — 2014-06-02
- 0.0.5 — 2014-06-02
- 0.0.4 — 2014-06-02
- 0.0.3 — 2014-06-02
- 0.0.2 — 2014-06-02
- 0.0.1 — 2014-06-02
## README
# jq-html-parser
[](https://travis-ci.org/jpstevens/jq-html-parser)
A jQuery powered parser for extracting text (strings) from HTML documents
## Example Usage:
```javascript
var Parser, request, config, url;
// npm dependencies
Parser = require("jq-html-parser");
request = require("request");
// config, etc.
config = {
title: "title",
logo: {
selector: "#hplogo",
attribute: "style",
regexp: "url\\(([\/A-z0-9]+.png)\\)"
}
};
url = "http://google.co.uk";
// request a page
request.get(url, function(err, res, body){
// handle error and non-200 response here
if(err || (res.statusCode != 200)){
return console.log("An error occured.");
}
var parser, result;
// parse body
parser = new Parser(config);
result = parser.parse(body);
console.log(result.title); // "Google"
console.log(result.logo); // "/images/srpr/logo11w.png"
});
```
## Options:
### selector (required)
The jQuery selector, used to locate the desired element.
For example, if `html` equals:
```html
Hello, world!
Another Hello!
```
And our JavaScript is:
```javascript
var parser = new Parser(html);
var result = parser.parse({
myElement: { selector: "h1" }
});
```
The parser would match the first h1 element from the DOM, and assign its value to the `myElement` attribute:
```js
// value of 'result':
{ myElement: "Hello, world!"}
```
The parser would match all h1 elements from the DOM, and assign the array to the `myElement` attribute:
**NOTE:** To return *all* h1's from the DOM, see the `multiple` option below.
### multiple (optional, defaults to `false`)
Returns an array of values when set to `true`. By default, or when set to `false`, will return a string containing the first value found for the specified jQuery selector.
For example, if `html` equals:
```html
Hello, world!
Another Hello!
```
And our JavaScript is:
```javascript
var parser = new Parser(html);
var result = parser.parse({
myElement: { selector: "h1", multiple: true }
});
```
The parser would match all h1 elements from the DOM, and assign the array to the `myElement` attribute:
```js
// value of 'result':
{
myElement: ["Hello, world!", "Another Hello!"]
}
```
```javascript
var parser = new Parser(config);
parser.parse(html); // returns { myElement: ["Hello, world!", "Another Hello!"]}
```
### attribute (optional)
Returns the text value of the specified attribute, for the given selector.
For example, if `html` equals:
```html
Hello, world!
```
And our JavaScript is:
```javascript
var parser = new Parser(html);
var result = parser.parse({
myElement: { selector: "h1", attribute: "data-secret-title" }
});
```
Then our result would contains "Shh, don't tell...", as that is the
`data-secret-title` attribute of the `h1` tag:
```js
// value of 'result':
{
myElement: "Shh, don't tell..."
}
```
**NOTE** Setting the `attribute` option will ignore `remove` and `html` options, as those options relate to the inner contents of an element, and not the attribute.
### remove (optional)
Specifies any descendant elements to remove before parsing the value of the selected elements.
For example, if `html` equals:
```html
Keep me.
Annoying advert
Keep me too.
```
And our JavaScript is:
```javascript
var parser = new Parser(html);
var result = parser.parse({
myElement: { selector: "article", remove: ".advert" }
});
```
Then our result will contain everything inside of `article`, except the content from `.advert`:
```js
// value of 'result':
{
myElement: "Keep me. Keep me too."
}
```
### html (optional, defaults to `false`)
When set to `true`, sets return the selected element as HTML. By default, or when set to true, returns the contents of the selected element as text.
For example, if `html` equals:
```html
I am the text
```
And our JavaScript is:
```javascript
var parser = new Parser(html);
var result = parser.parse({
myElement: { selector: "article", html: true }
});
```
Then our result will be a string of HTML, instead of the text value:
```js
// value of 'result':
{
myElement: "I am the text
" // this would simply be "I am the text" if html=false
}
```
### regexp (optional)
Use regular expressions to extract data from the parsed value(s) from your selected elements. `regexp` is the second-to-last option applied to the text, before `transform`.
For example, if `html` equals:
```html
The title is 'jQuery Rocks'
```
And our JavaScript is:
```javascript
var parser = new Parser(html);
var result = parser.parse({
myElement: { selector: "h1", regexp: "The title is '(.*)'" }
});
```
Then our result will be "jQuery Rocks".
```js
// value of 'result':
{
myElement: "jQuery Rocks"
}
```
**NOTE** Only the first match will be returned. For more advanced transformations, like combining multiple regular expression matches together, use the `transform` option.
### transform
Used to transform parsed values of selected element(s).
For example, if `html` equals:
```html
Total points: 21
```
And our JavaScript is:
```javascript
var parser = new Parser(html);
var result = parser.parse({
pointsScored: {
selector: "h1",
regexp: "Total points: (.*)",
transform: function (val) {
return val ? parseInt(val) : 0;
}
}
});
```
Then our result will be the numerical value for "points scored":
```js
// value of 'result':
{
pointsScored: 21
}
```
## Combining Options:
All options can be combined, and when being parsed they will be processed in a particular order, depending on their specificity.
If you find your returned object doesn't match what you were expecting, it may be due to conflicting configuration options.
Configuration options will be evaluated in the following order:
1. `selector`
2. `multiple`
3. `attribute`
4. `remove` (skipped if `attribute` is defined)
5. `html` (skipped if `attribute` is defined)
6. `regexp`
7. `transform`
## Support
If you need any help, please let me know via the "issues" tab on Github.
Contributions are also welcome, so please feel free to fork the code, play around, then put in a PR.
---
_Source: https://npm.io/package/jq-html-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._