Skip to content

Commit 2cfc0fd

Browse files
eGavreGavr
committed
Merge pull request #68 from bem/update-readme
Update README
2 parents c5811b4 + bc829b1 commit 2cfc0fd

2 files changed

Lines changed: 142 additions & 42 deletions

File tree

‎README.md‎

Lines changed: 138 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
# html-differ [![Build Status](https://travis-ci.org/bem/html-differ.svg)](https://travis-ci.org/bem/html-differ) [![Coverage Status](https://img.shields.io/coveralls/bem/html-differ.svg)](https://coveralls.io/r/bem/html-differ?branch=master) [![Dependency Status](https://david-dm.org/bem/html-differ.svg)](https://david-dm.org/bem/html-differ)
22

3-
Сompares two ```html-files```.
3+
Сompares two `HTML` codes.
44

55
## The comparison algorithm
66

7-
```html-differ``` compares files on the following criteria:
7+
`html-differ` compares `HTML` codes using the following criteria:
88

9-
1. Two respective attributes ```class``` are considered to be equal if they refer on same groups of ```CSS-styles```
10-
2. Two respective lists of attributes are considered to be equal even if they go in different order
9+
1. Two respective lists of attributes are considered to be equivalent even if they are specified in different order.
10+
2. Two respective attributes `class` are considered to be equivalent if they refer to the same groups of `CSS` styles.
1111

12-
This code
12+
For example, the following two code samples will be considered to be equivalent:
1313

1414
```html
1515
<html>
@@ -18,21 +18,19 @@ This code
1818
</head>
1919
<body>
2020
<label>label for input</label>
21-
<input id="random" class="ab bc cd" for="blah">
21+
<input id="random" class="ab bc cd" tabIndex="1">
2222
</body>
2323
</html>
2424
```
2525

26-
equals to
27-
2826
```html
2927
<html>
3028
<head>
3129
<title>Test</title>
3230
</head>
3331
<body>
3432
<label>label for input</label>
35-
<input class=" cd ab bc" for="blah" id="random">
33+
<input class=" cd ab bc" tabIndex="1" id="random">
3634
</body>
3735
</html>
3836
```
@@ -50,28 +48,37 @@ $ npm install html-differ -g
5048
####html-differ####
5149

5250
**html-differ.diffHtml**<br>
53-
**@param** *String* - the 1-st ```html-code```<br>
54-
**@param** *String* - the 2-nd ```html-code```<br>
55-
**@returns** *{Array of objects}* - see [here](https://github.com/kpdecker/jsdiff#change-objects)
51+
**@param** *{String}* - the 1-st `HTML` code<br>
52+
**@param** *{String}* - the 2-nd `HTML` code<br>
53+
**@returns** *{Array of objects}* - [array with diffs](https://github.com/kpdecker/jsdiff#change-objects) between `HTML` codes
5654

5755
**html-differ.isEqual**<br>
58-
This method has the same parameters as the previous one, but returns ```Boolean```.
56+
**@param** *{String}* - the 1-st `HTML` code<br>
57+
**@param** *{String}* - the 2-nd `HTML` code<br>
58+
**@returns** *{Boolean}*
5959

6060
####diff-logger####
6161

6262
**diff-logger.getDiffText**<br>
63-
**@param** *{Object}* - the result of the work of the method ```html-differ.diffHtml```<br>
63+
**@param** *{Array of objects}* - the result of the work of the method `html-differ.diffHtml`<br>
6464
**@param** *{Object}* - options:<br>
65-
* the number of characters before the diff and after it<br>
66-
(for example, ```charsAroundDiff: 40```, default: ```40```)<br>
65+
66+
* `charsAroundDiff: Number` - the number of characters before and after the diff result of two `HTML` codes (default: `40`).
6767

6868
**@returns** *{String}* - diffs
6969

7070
**diff-logger.log**<br>
71-
Pretty logging of diffs.<br>
72-
This method has the same parameters as the previous one.
71+
**@param** *{Array of objects}* - the result of the work of the method `html-differ.diffHtml`<br>
72+
**@param** *{Object}* - options:<br>
73+
74+
* `charsAroundDiff: Number` - the number of characters before and after the diff result of two `HTML` codes (default: `40`).
7375

74-
####Example####
76+
**@returns** - pretty logging of diffs:
77+
78+
<img src='https://cloud.githubusercontent.com/assets/6376693/3648928/a6b9d48a-110d-11e4-8a07-d9b156145017.png'/>
79+
80+
81+
**Example**
7582

7683
```js
7784
var fs = require('fs'),
@@ -84,7 +91,8 @@ var html1 = fs.readFileSync('1.html', 'utf-8'),
8491
var options = {
8592
ignoreHtmlAttrs: [],
8693
compareHtmlAttrsAsJSON: [],
87-
ignoreWhitespace: true,
94+
ignoreWhitespaces: true,
95+
ignoreHtmlComments: true,
8896
bem: false
8997
}
9098

@@ -99,63 +107,155 @@ var res = diffLogger.getDiffText(diff, { charsAroundDiff: 40 });
99107
diffLogger.log(diff, { charsAroundDiff: 40 });
100108
```
101109

102-
where ```options``` is the ```Object```:
110+
Where `options` is the `Object`:
111+
112+
* **ignoreHtmlAttrs: [ Array ]**
113+
114+
Sets what kind of respective attributes' content will be ignored during the comparison (default: `[]`).
115+
116+
**Example**: `['id', 'for']`<br>
117+
The following two code samples will be considered to be equivalent:
118+
119+
```html
120+
<label for="random">label for input</label>
121+
<input id="random">
122+
```
123+
124+
```html
125+
<label for="sfsdfksdf">label for input</label>
126+
<input id="sfsdfksdf">
127+
```
103128

104-
* ```ignoreHtmlAttrs: [ Array ]``` - sets what respective attributes are always considered to be equal
129+
* **compareHtmlAttrsAsJSON: [ Array ]**
105130

106-
* ```compareHtmlAttrsAsJSON: [ Array ]``` - sets what respective attributes' content will be compared as ```JSONs```, not as ```Strings```
131+
Sets what kind of respective attributes' content will be compared as `JSON` objects, but not as strings (default: `[]`).
132+
133+
**Example**: `['onclick']`<br>
134+
The following two code samples will be considered to be equivalent:
135+
136+
```html
137+
<div onclick='return {"bla":{"first":"ololo","second":"trololo"}}'></div>
138+
```
139+
140+
```html
141+
<div onclick='return {"bla":{"second":"trololo","first":"ololo"}}'></div>
142+
```
143+
144+
* **ignoreWhitespaces: Boolean**
145+
146+
Makes `html-differ` ignore whitespaces (spaces, tabs, new lines etc.) during the comparison (default: `true`).
147+
148+
**Example**: `true`<br>
149+
The following two code samples will be considered to be equivalent:
150+
151+
```html
152+
<html>Text Text<head lang="en"><title></title></head><body>Text</body></html>
153+
```
154+
155+
```html
156+
<html>
157+
Text Text
158+
<head lang ="en">
159+
<title > </title>
107160

108-
* ```ignoreWhitespace: Boolean``` - if is set ```true```, ```html-differ``` will consider all groups of ```spaces```, ```new lines```, ```tabs``` as one ```space```
109161

110-
* ```bem: Boolean``` - predefined options for BEM
162+
</head>
163+
164+
<body>
165+
Text
166+
167+
</body>
168+
169+
170+
171+
172+
</html>
173+
174+
```
175+
176+
* **ignoreHtmlComments: Boolean**
177+
178+
Makes `html-differ` ignore `HTML` comments during the comparison (default: `true`).
179+
180+
**Example**: `true`<br>
181+
The following two code samples will be considered to be equivalent:
182+
183+
```html
184+
<!DOCTYPE html>
185+
<!-- comments1 -->
186+
<html>
187+
<head lang="en">
188+
<meta charset="UTF-8">
189+
<title><!-- comments2 --></title>
190+
</head>
191+
<body>
192+
Text<!-- comments3 -->
193+
</body>
194+
</html>
195+
```
196+
197+
```html
198+
<!DOCTYPE html>
199+
200+
<html>
201+
<head lang="en">
202+
<meta charset="UTF-8">
203+
<title></title>
204+
</head>
205+
<body>
206+
Text
207+
</body>
208+
</html>
209+
```
111210

211+
* **bem: Boolean**
112212

113-
####For BEM####
114-
Options for BEM are predefined:
115-
* ```ignoreHtmlAttrs: ['id', 'for']```
213+
Sets predefined options for `BEM` (default: `false`).
116214

117-
* ```compareHtmlAttrsAsJSON: ['data-bem', 'onclick', 'ondblclick']```
215+
**Example**: `true`
118216

119-
* ```charsAroundDiff: 40```
217+
* `ignoreHtmlAttrs: ['id', 'for']`
218+
* `compareHtmlAttrsAsJSON: ['data-bem', 'onclick', 'ondblclick']`
120219

121220

122221
###As a program###
123222

124223
```bash
125224
$ html-differ --help
126-
Compares two html-files
225+
Compares two HTML files
127226

128227
Usage:
129228
html-differ [OPTIONS] [ARGS]
130229

131230
Options:
132231
-h, --help : Help
133232
-v, --version : Shows the version number
134-
--config=CONFIG : Path to configuration JSON-file
233+
--config=CONFIG : Path to configuration JSON file
135234
--chars-around-diff=CHARSAROUNDDIFF : The number of characters around the diff (default: 40)
136235

137236
Arguments:
138-
PATH1 : Path to the 1-st html-file (required)
139-
PATH2 : Path to the 2-nd html-file (required)
237+
PATH1 : Path to the 1-st HTML file (required)
238+
PATH2 : Path to the 2-nd HTML file (required)
140239
```
141240

142-
####Example####
241+
**Example**
143242

144243
```bash
145244
$ bin/html-differ path/to/html1 path/to/html2
146245

147-
$ bin/html-differ --config=path/to/config path/to/html1 path/to/html2 --chars-around-diff=40
246+
$ bin/html-differ --config=path/to/config --chars-around-diff=40 path/to/html1 path/to/html2
148247
```
149248

150249
####Configuration file###
151250

152-
Study the following ```config.json```:
251+
Look at the following `config.json` file:
153252

154253
```js
155254
{
156255
"ignoreHtmlAttrs": [],
157256
"compareHtmlAttrsAsJSON": [],
158-
"ignoreWhitespace": true,
257+
"ignoreWhitespaces": true,
258+
"ignoreHtmlComments": true,
159259
"bem": false
160260
}
161261
```

‎lib/cli.js‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ var path = require('path'),
88
module.exports = require('coa').Cmd()
99
.name(process.argv[1])
1010
.helpful()
11-
.title('Compares two html-files')
11+
.title('Compares two HTML codes')
1212
.opt()
1313
.name('version')
1414
.title('Shows the version number')
@@ -22,7 +22,7 @@ module.exports = require('coa').Cmd()
2222
.end()
2323
.opt()
2424
.name('config')
25-
.title('Path to configuration JSON-file')
25+
.title('Path to configuration JSON file')
2626
.long('config')
2727
.end()
2828
.opt()
@@ -36,12 +36,12 @@ module.exports = require('coa').Cmd()
3636
.end()
3737
.arg()
3838
.name('path1')
39-
.title('Path to the 1-st html-file')
39+
.title('Path to the 1-st HTML file')
4040
.req()
4141
.end()
4242
.arg()
4343
.name('path2')
44-
.title('Path to the 2-nd html-file')
44+
.title('Path to the 2-nd HTML file')
4545
.req()
4646
.end()
4747
.act(function(opts, args) {

0 commit comments

Comments
 (0)