Skip to content

Commit 2aa5b83

Browse files
eGavreGavr
committed
Fix docs
1 parent 8e609d7 commit 2aa5b83

2 files changed

Lines changed: 102 additions & 41 deletions

File tree

‎README.md‎

Lines changed: 51 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Compares two HTML.
2929
* [Configuration file](#configuration-file)
3030
* [Masks](#masks)
3131
* [Syntax](#syntax)
32+
* [Screening](#screening)
3233

3334
<!-- TOC END -->
3435

@@ -94,7 +95,7 @@ $ npm install html-differ
9495

9596
## API
9697

97-
###HtmlDiffer###
98+
### HtmlDiffer
9899

99100
```js
100101
var HtmlDiffer = require('html-differ').HtmlDiffer,
@@ -103,9 +104,9 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
103104

104105
where `options` is an object.
105106

106-
####Options####
107+
#### Options
107108

108-
#####ignoreAttributes: [Array]#####
109+
##### ignoreAttributes: [Array]
109110

110111
Sets what kind of respective attributes' content will be ignored during the comparison (default: `[]`).
111112

@@ -122,7 +123,7 @@ The following two code samples will be considered to be equivalent:
122123
<input id="sfsdfksdf">
123124
```
124125

125-
#####compareAttributesAsJSON: [Array]#####
126+
##### compareAttributesAsJSON: [Array]
126127

127128
Sets what kind of respective attributes' content will be compared as JSON objects, but not as strings (default: `[]`).<br>
128129
In cases when the value of the attribute is an invalid JSON or can not be wrapped into a function, it will be compared as `undefined`.
@@ -150,7 +151,7 @@ The following two code samples will be considered to be equivalent:
150151
The first element of the array could be written in a short form as string:<br>
151152
`['data', { name: 'onclick', isFunction: true }]`.
152153

153-
#####ignoreWhitespaces: Boolean#####
154+
##### ignoreWhitespaces: Boolean
154155

155156
Makes **html-differ** ignore whitespaces (spaces, tabs, new lines etc.) during the comparison (default: `true`).
156157

@@ -182,7 +183,7 @@ The following two code samples will be considered to be equivalent:
182183

183184
```
184185

185-
#####ignoreComments: Boolean#####
186+
##### ignoreComments: Boolean
186187

187188
Makes **html-differ** ignore HTML comments during the comparison (default: `true`).
188189

@@ -231,7 +232,7 @@ Text
231232
</html>
232233
```
233234

234-
#####ignoreEndTags: Boolean#####
235+
##### ignoreEndTags: Boolean
235236

236237
Makes **html-differ** ignore end tags during the comparison (default: `false`).
237238

@@ -246,7 +247,7 @@ The following two code samples will be considered to be equivalent:
246247
<span>Text</spane>
247248
```
248249

249-
#####ignoreDuplicateAttributes: Boolean#####
250+
##### ignoreDuplicateAttributes: Boolean
250251

251252
Makes **html-differ** ignore tags' duplicate attributes during the comparison.<br>
252253
From the list of the same tag's attributes, the attribute which goes the first will be taken for comparison, others will be ignored (default: `false`).
@@ -262,12 +263,12 @@ For example, the following two code samples will be considered to be equivalent:
262263
<span id="blah">Text</span>
263264
```
264265

265-
####Presets####
266+
#### Presets
266267

267268
* [bem](https://github.com/bem/html-differ/blob/master/presets/bem.json) - sets predefined options for [BEM](http://bem.info/).
268269

269270

270-
#####Usage#####
271+
##### Usage
271272

272273
Passing of a preset via the constructor:
273274

@@ -283,36 +284,39 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
283284
htmlDiffer = new HtmlDiffer({ preset: 'bem', ignoreAttributes: [] });
284285
```
285286

286-
####Methods####
287+
#### Methods
288+
289+
##### htmlDiffer.diffHtml
287290

288-
#####htmlDiffer.diffHtml#####
289291
**@param** *{String}* - the 1-st HTML code<br>
290292
**@param** *{String}* - the 2-nd HTML code<br>
291293
**@returns** *{Array of objects}* - [array with diffs](https://github.com/kpdecker/jsdiff#change-objects) between HTML
292294

293-
#####htmlDiffer.isEqual#####
295+
##### htmlDiffer.isEqual
296+
294297
**@param** *{String}* - the 1-st HTML code<br>
295298
**@param** *{String}* - the 2-nd HTML code<br>
296299
**@returns** *{Boolean}*
297300

298301

299-
###Logger###
302+
### Logger
300303

301304
```js
302305
var logger = require('html-differ/lib/logger');
303306
```
304307

305-
####Methods####
308+
#### Methods
309+
310+
##### logger.getDiffText
306311

307-
#####logger.getDiffText#####
308312
**@param** *{Array of objects}* - the result of the work of the method [htmlDiffer.diffHtml](https://github.com/bem/html-differ/tree/master#htmldifferdiffhtml)<br>
309313
**@param** *{Object}* - options:<br>
310314

311315
* **charsAroundDiff: Number** - the number of characters around the diff result between two HTML (default: `40`).
312316

313317
**@returns** *{String}*
314318

315-
#####logger.logDiffText#####
319+
##### logger.logDiffText
316320
**@param** *{Array of objects}* - the result of the work of the method [htmlDiffer.diffHtml](https://github.com/bem/html-differ/tree/master#htmldifferdiffhtml)<br>
317321
**@param** *{Object}* - options:<br>
318322

@@ -323,7 +327,7 @@ var logger = require('html-differ/lib/logger');
323327
<img src='https://cloud.githubusercontent.com/assets/6376693/3648928/a6b9d48a-110d-11e4-8a07-d9b156145017.png'/>
324328

325329

326-
###Example###
330+
### Example
327331

328332
```js
329333
var fs = require('fs'),
@@ -351,7 +355,7 @@ var diff = htmlDiffer.diffHtml(html1, html2),
351355
logger.logDiffText(diff, { charsAroundDiff: 40 });
352356
```
353357

354-
##Usage as a program##
358+
## Usage as a program
355359

356360
```bash
357361
$ html-differ --help
@@ -373,7 +377,7 @@ Arguments:
373377
PATH2 : Path to the 2-nd HTML file (required)
374378
```
375379

376-
###Example###
380+
### Example
377381

378382
```bash
379383
$ html-differ path/to/html1 path/to/html2
@@ -383,7 +387,7 @@ $ html-differ --config=path/to/config --chars-around-diff=40 path/to/html1 path/
383387
$ html-differ --preset=bem path/to/html1 path/to/html2
384388
```
385389

386-
###Configuration file##
390+
### Configuration file
387391

388392
Study the following file `config.json`:
389393

@@ -427,3 +431,29 @@ where:
427431
* `RegExp` – regular expression for matching with the corresponding value in another HTML. The syntax is similar to regular expressions in JavaScript written in a literal notation.
428432

429433
* `}}` – closing identifier of the _mask_.
434+
435+
### Screening
436+
437+
The rules of screening of symbols are similar to the rules which are used in regular expressions in JavaScript written in a literal notation.
438+
439+
For example, the following two code samples will be considered to be equivalent:
440+
441+
```html
442+
<div id="{{\d\.\d}}">
443+
```
444+
445+
```html
446+
<div id="1.1">
447+
```
448+
449+
If you want to use `{{` or `}}` inside a mask, you should screen both curly braces, i.e. `\{\}` or `\}\}`.
450+
451+
For example, the following two code samples will be considered to be equivalent:
452+
453+
```html
454+
<div class="{{a\{\{b\}\}c}}">
455+
```
456+
457+
```html
458+
<div class="a{{b}}c">
459+
```

‎README.ru.md‎

Lines changed: 51 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
* [Конфигурационный файл](#Конфигурационный-файл)
3030
* [Маски](#Маски)
3131
* [Синтаксис](#Синтаксис)
32+
* [Экранирование](#Экранирование)
3233

3334
<!-- TOC END -->
3435

@@ -103,9 +104,9 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
103104

104105
где `options` – это объект.
105106

106-
####Опции####
107+
#### Опции
107108

108-
#####ignoreAttributes: [Array]#####
109+
##### ignoreAttributes: [Array]
109110

110111
Устанавливает, значения каких атрибутов следует игнорировать при сравнении (по умолчанию: `[]`).
111112

@@ -122,7 +123,7 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
122123
<input id="sfsdfksdf">
123124
```
124125

125-
#####compareAttributesAsJSON: [Array]#####
126+
##### compareAttributesAsJSON: [Array]
126127

127128
Устанавливает, значения каких атрибутов следует сравнивать как JSON-объекты, а не как строки (по умолчанию: `[]`).<br>
128129
В тех случаях, когда в качестве значения атрибута выступает некорректный JSON или это значение нельзя обернуть в функцию, то оно будет сравниваться как `undefined`.
@@ -150,7 +151,7 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
150151
Первый элемент массива мог быть записан в короткой форме в качестве строки:<br>
151152
`['data', { name: 'onclick', isFunction: true }]`.
152153

153-
#####ignoreWhitespaces: Boolean#####
154+
##### ignoreWhitespaces: Boolean
154155

155156
**html-differ** будет игнорировать пробельные символы (пробелы, табуляция, переводы строк и т. д.) при сравнении (по умолчанию: `true`).
156157

@@ -182,7 +183,7 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
182183

183184
```
184185

185-
#####ignoreComments: Boolean#####
186+
##### ignoreComments: Boolean
186187

187188
**html-differ** будет игнорировать HTML-комментарии при сравнении (по умолчанию: `true`).
188189

@@ -230,7 +231,7 @@ Text
230231
</html>
231232
```
232233

233-
#####ignoreEndTags: Boolean#####
234+
##### ignoreEndTags: Boolean
234235

235236
**html-differ** будет игнорировать закрывающие тэги при сравнении (по умолчанию: `false`).
236237

@@ -245,7 +246,7 @@ Text
245246
<span>Text</spane>
246247
```
247248

248-
#####ignoreDuplicateAttributes: Boolean#####
249+
##### ignoreDuplicateAttributes: Boolean
249250

250251
**html-differ** будет игнорировать повторяющиеся атрибуты.<br>
251252
Из списка одинаковых атрибутов тэга, для сравнения будет взят тот, который идет первым, остальные будут проигнорированы (по умолчанию: `false`).
@@ -261,12 +262,12 @@ Text
261262
<span id="blah">Text</span>
262263
```
263264

264-
####Пресеты####
265+
#### Пресеты
265266

266267
* [bem](https://github.com/bem/html-differ/blob/master/presets/bem.json) - уставливает предопределенные опции для [БЭМ](http://ru.bem.info/).
267268

268269

269-
#####Использование#####
270+
##### Использование
270271

271272
Передача пресета конструктору:
272273

@@ -282,35 +283,39 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
282283
htmlDiffer = new HtmlDiffer({ preset: 'bem', ignoreAttributes: [] });
283284
```
284285

285-
####Методы####
286+
#### Методы
287+
288+
##### htmlDiffer.diffHtml
286289

287-
#####htmlDiffer.diffHtml#####
288290
**@param** *{String}* - 1-й HTML<br>
289291
**@param** *{String}* - 2-й HTML<br>
290292
**@returns** *{Array of objects}* - [массив с отличиями](https://github.com/kpdecker/jsdiff#change-objects) между HTML
291293

292-
#####htmlDiffer.isEqual#####
294+
##### htmlDiffer.isEqual
295+
293296
**@param** *{String}* - 1-й HTML<br>
294297
**@param** *{String}* - 2-й HTML<br>
295298
**@returns** *{Boolean}*
296299

297-
###Logger###
300+
### Logger
298301

299302
```js
300303
var logger = require('html-differ/lib/logger');
301304
```
302305

303-
####Методы####
306+
#### Методы
307+
308+
##### logger.getDiffText
304309

305-
#####logger.getDiffText#####
306310
**@param** *{Array of objects}* - результат работы метода [htmlDiffer.diffHtml](https://github.com/bem/html-differ/blob/master/README.ru.md#htmldifferdiffhtml)<br>
307311
**@param** *{Object}* - опции:<br>
308312

309313
* **charsAroundDiff: Number** - количество символов перед отличием между HTML и после него (по умолчанию: `40`)
310314

311315
**@returns** *{String}*
312316

313-
#####logger.logDiffText#####
317+
##### logger.logDiffText
318+
314319
**@param** *{Array of objects}* - результат работы метода [htmlDiffer.diffHtml](https://github.com/bem/html-differ/blob/master/README.ru.md#htmldifferdiffhtml)<br>
315320
**@param** *{Object}* - опции:<br>
316321

@@ -320,7 +325,7 @@ var logger = require('html-differ/lib/logger');
320325

321326
<img src='https://cloud.githubusercontent.com/assets/6376693/3648928/a6b9d48a-110d-11e4-8a07-d9b156145017.png'/>
322327

323-
###Пример###
328+
### Пример
324329

325330
```js
326331
var fs = require('fs'),
@@ -348,7 +353,7 @@ var diff = htmlDiffer.diffHtml(html1, html2),
348353
logger.logDiffText(diff, { charsAroundDiff: 40 });
349354
```
350355

351-
##Использование в качестве программы##
356+
## Использование в качестве программы
352357

353358
```bash
354359
$ html-differ --help
@@ -370,7 +375,7 @@ $ html-differ --help
370375
PATH2 : Путь ко 2-ому HTML-файлу (обязательный аргумент)
371376
```
372377

373-
###Пример###
378+
### Пример
374379

375380
```bash
376381
$ html-differ путь/к/html1 путь/к/html2
@@ -380,7 +385,7 @@ $ html-differ --config=путь/к/конфигу --chars-around-diff=40 пут
380385
$ html-differ --preset=bem путь/к/html1 путь/к/html2
381386
```
382387

383-
###Конфигурационный файл###
388+
### Конфигурационный файл
384389

385390
Рассмотрите следующий файл `config.json`:
386391

@@ -424,3 +429,29 @@ $ html-differ --preset=bem путь/к/html1 путь/к/html2
424429
* `RegExp` – регулярное выражение для сопоставления с соответствующим значением в сравниваемом HTML. Имеет такой же синтаксис как и регулярные выражения в JavaScript, записанные в _literal notation_.
425430

426431
* `}}` – закрывающий идентификатор _маски_.
432+
433+
### Экранирование
434+
435+
Правила экранирования символов такие же как и при использовании регулярных выражений в JavaScript, записанных в _literal notation_.
436+
437+
Например, следующие два HTML будут считаться эквивалентными:
438+
439+
```html
440+
<div id="{{\d\.\d}}">
441+
```
442+
443+
```html
444+
<div id="1.1">
445+
```
446+
447+
Если вы хотите хотите использовать `{{` или `}}` внутри маски, вам необходимо экранировать обе фигурные скобки, то есть `\{\}` или `\}\}`
448+
449+
Например, следующие два HTML будут считаться эквивалентными:
450+
451+
```html
452+
<div class="{{a\{\{b\}\}c}}">
453+
```
454+
455+
```html
456+
<div class="a{{b}}c">
457+
```

0 commit comments

Comments
 (0)