README.chromium
README.md
1<p align="center">
2 <img src="https://raw.github.com/inikulin/parse5/master/logo.png" alt="parse5" />
3</p>
4
5[](https://travis-ci.org/inikulin/parse5)
6[](https://www.npmjs.com/package/parse5)
7
8*WHATWG HTML5 specification-compliant, fast and ready for production HTML parsing/serialization toolset for Node and io.js.*
9
10I needed fast and ready for production HTML parser, which will parse HTML as a modern browser's parser.
11Existing solutions were either too slow or their output was too inaccurate. So, this is how parse5 was born.
12
13**Included tools:**
14* [Parser](#class-parser) - HTML to DOM-tree parser.
15* [SimpleApiParser](#class-simpleapiparser) - [SAX](http://en.wikipedia.org/wiki/Simple_API_for_XML)-style parser for HTML.
16* [Serializer](#class-serializer) - DOM-tree to HTML code serializer.
17
18## Install
19```
20$ npm install parse5
21```
22
23
24## Usage
25```js
26var Parser = require('parse5').Parser;
27
28//Instantiate parser
29var parser = new Parser();
30
31//Then feed it with an HTML document
32var document = parser.parse('<!DOCTYPE html><html><head></head><body>Hi there!</body></html>')
33
34//Now let's parse HTML-snippet
35var fragment = parser.parseFragment('<title>Parse5 is fucking awesome!</title><h1>42</h1>');
36
37```
38
39## Is it fast?
40Check out [this benchmark](https://github.com/inikulin/node-html-parser-bench).
41
42```
43Starting benchmark. Fasten your seatbelts...
44html5 (https://github.com/aredridel/html5) x 0.18 ops/sec ±5.92% (5 runs sampled)
45htmlparser (https://github.com/tautologistics/node-htmlparser/) x 3.83 ops/sec ±42.43% (14 runs sampled)
46htmlparser2 (https://github.com/fb55/htmlparser2) x 4.05 ops/sec ±39.27% (15 runs sampled)
47parse5 (https://github.com/inikulin/parse5) x 3.04 ops/sec ±51.81% (13 runs sampled)
48Fastest is htmlparser2 (https://github.com/fb55/htmlparser2),parse5 (https://github.com/inikulin/parse5)
49```
50
51So, parse5 is as fast as simple specification incompatible parsers and ~15-times(!) faster than the current specification compatible parser available for the node.
52
53
54## API reference
55
56### Enum: TreeAdapters
57Provides built-in tree adapters which can be passed as an optional argument to the `Parser` and `Serializer` constructors.
58
59#### • TreeAdapters.default
60Default tree format for parse5.
61
62
63#### • TreeAdapters.htmlparser2
64Quite popular [htmlparser2](https://github.com/fb55/htmlparser2) tree format (e.g. used in [cheerio](https://github.com/MatthewMueller/cheerio) and [jsdom](https://github.com/tmpvar/jsdom)).
65
66---------------------------------------
67
68
69### Class: Parser
70Provides HTML parsing functionality.
71
72#### • Parser.ctor([treeAdapter, options])
73Creates new reusable instance of the `Parser`. Optional `treeAdapter` argument specifies resulting tree format. If `treeAdapter` argument is not specified, `default` tree adapter will be used.
74
75`options` object provides the parsing algorithm modifications:
76##### options.decodeHtmlEntities
77Decode HTML-entities like `&`, ` `, etc. Default: `true`. **Warning:** disabling this option may cause output which is not conform HTML5 specification.
78##### options.locationInfo
79Enables source code location information for the nodes. Default: `false`. When enabled, each node (except root node) has `__location` property, which contains `start` and `end` indices of the node in the source code. If element was implicitly created by the parser it's `__location` property will be `null`. In case the node is not an empty element, `__location` has two addition properties `startTag` and `endTag` which contain location information for individual tags in a fashion similar to `__location` property.
80
81*Example:*
82```js
83var parse5 = require('parse5');
84
85//Instantiate new parser with default tree adapter
86var parser1 = new parse5.Parser();
87
88//Instantiate new parser with htmlparser2 tree adapter
89var parser2 = new parse5.Parser(parse5.TreeAdapters.htmlparser2);
90```
91
92
93
94#### • Parser.parse(html)
95Parses specified `html` string. Returns `document` node.
96
97*Example:*
98```js
99var document = parser.parse('<!DOCTYPE html><html><head></head><body>Hi there!</body></html>');
100```
101
102
103#### • Parser.parseFragment(htmlFragment, [contextElement])
104Parses given `htmlFragment`. Returns `documentFragment` node. Optional `contextElement` argument specifies context in which given `htmlFragment` will be parsed (consider it as setting `contextElement.innerHTML` property). If `contextElement` argument is not specified then `<template>` element will be used as a context and fragment will be parsed in 'forgiving' manner.
105
106*Example:*
107```js
108var documentFragment = parser.parseFragment('<table></table>');
109
110//Parse html fragment in context of the parsed <table> element
111var trFragment = parser.parseFragment('<tr><td>Shake it, baby</td></tr>', documentFragment.childNodes[0]);
112```
113
114---------------------------------------
115
116
117### Class: SimpleApiParser
118Provides [SAX](https://en.wikipedia.org/wiki/Simple_API_for_XML)-style HTML parsing functionality.
119
120#### • SimpleApiParser.ctor(handlers, [options])
121Creates new reusable instance of the `SimpleApiParser`. `handlers` argument specifies object that contains parser's event handlers. Possible events and their signatures are shown in the example.
122
123`options` object provides the parsing algorithm modifications:
124##### options.decodeHtmlEntities
125Decode HTML-entities like `&`, ` `, etc. Default: `true`. **Warning:** disabling this option may cause output which is not conform HTML5 specification.
126##### options.locationInfo
127Enables source code location information for the tokens. Default: `false`. When enabled, each node handler receives `location` object as it's last argument. `location` object contains `start` and `end` indices of the token in the source code.
128
129
130*Example:*
131```js
132var parse5 = require('parse5');
133
134var parser = new parse5.SimpleApiParser({
135 doctype: function(name, publicId, systemId /*, [location] */) {
136 //Handle doctype here
137 },
138
139 startTag: function(tagName, attrs, selfClosing /*, [location] */) {
140 //Handle start tags here
141 },
142
143 endTag: function(tagName /*, [location] */) {
144 //Handle end tags here
145 },
146
147 text: function(text /*, [location] */) {
148 //Handle texts here
149 },
150
151 comment: function(text /*, [location] */) {
152 //Handle comments here
153 }
154});
155```
156
157#### • SimpleApiParser.parse(html)
158Raises parser events for the given `html`.
159
160*Example:*
161```js
162var parse5 = require('parse5');
163
164var parser = new parse5.SimpleApiParser({
165 text: function(text) {
166 console.log(text);
167 }
168});
169
170parser.parse('<body>Yo!</body>');
171```
172
173---------------------------------------
174
175### Class: Serializer
176Provides tree-to-HTML serialization functionality.
177**Note:** prior to v1.2.0 this class was called `TreeSerializer`. However, it's still accessible as `parse5.TreeSerializer` for backward compatibility.
178
179#### • Serializer.ctor([treeAdapter, options])
180Creates new reusable instance of the `Serializer`. Optional `treeAdapter` argument specifies input tree format. If `treeAdapter` argument is not specified, `default` tree adapter will be used.
181
182`options` object provides the serialization algorithm modifications:
183##### options.encodeHtmlEntities
184HTML-encode characters like `<`, `>`, `&`, etc. Default: `true`. **Warning:** disabling this option may cause output which is not conform HTML5 specification.
185
186
187*Example:*
188```js
189var parse5 = require('parse5');
190
191//Instantiate new serializer with default tree adapter
192var serializer1 = new parse5.Serializer();
193
194//Instantiate new serializer with htmlparser2 tree adapter
195var serializer2 = new parse5.Serializer(parse5.TreeAdapters.htmlparser2);
196```
197
198
199#### • Serializer.serialize(node)
200Serializes the given `node`. Returns HTML string.
201
202*Example:*
203```js
204var document = parser.parse('<!DOCTYPE html><html><head></head><body>Hi there!</body></html>');
205
206//Serialize document
207var html = serializer.serialize(document);
208
209//Serialize <body> element content
210var bodyInnerHtml = serializer.serialize(document.childNodes[0].childNodes[1]);
211```
212
213---------------------------------------
214
215
216## Testing
217Test data is adopted from [html5lib project](https://github.com/html5lib). Parser is covered by more than 8000 test cases.
218To run tests:
219```
220$ npm test
221```
222
223
224## Custom tree adapter
225You can create a custom tree adapter so parse5 can work with your own DOM-tree implementation.
226Just pass your adapter implementation to the parser's constructor as an argument:
227
228```js
229var Parser = require('parse5').Parser;
230
231var myTreeAdapter = {
232 //Adapter methods...
233};
234
235//Instantiate parser
236var parser = new Parser(myTreeAdapter);
237```
238
239Sample implementation can be found [here](https://github.com/inikulin/parse5/blob/master/lib/tree_adapters/default.js).
240The custom tree adapter should implement all methods exposed via `exports` in the sample implementation.
241
242## Questions or suggestions?
243If you have any questions, please feel free to create an issue [here on github](https://github.com/inikulin/parse5/issues).
244
245
246## Author
247[Ivan Nikulin](https://github.com/inikulin) (ifaaan@gmail.com)
248
