From 0e9140f1dcf8beb2c2933d421ac364adbaf7e92e Mon Sep 17 00:00:00 2001 From: Evgeniy Gavryushin Date: Thu, 4 Dec 2014 16:21:07 +0300 Subject: [PATCH] try --- README.md | 362 ++---------------------------------------------------- 1 file changed, 10 insertions(+), 352 deletions(-) diff --git a/README.md b/README.md index 2842931..90c389d 100644 --- a/README.md +++ b/README.md @@ -1,357 +1,15 @@ -# 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) [![devDependency Status](https://david-dm.org/bem/html-differ/dev-status.svg)](https://david-dm.org/bem/html-differ#info=devDependencies) -Сompares two HTML. + +* bla + * bla + * bla -## The comparison algorithm -**html-differ** compares HTML using the following criteria: + +# bla -* `` declarations are case-insensitive, so the following two code samples will be considered to be equivalent: + +###### bla -```html - -``` - -```html - -``` - -* Whitespaces (spaces, tabs, new lines etc.) inside start and end tags are ignored during the comparison. - -For example, the following two code samples will be considered to be equivalent: - -```html - -``` - -```html - -``` - -* Two respective lists of attributes are considered to be equivalent even if they are specified in different order. - -For example, the following two code samples will be considered to be equivalent: - -```html -Text -``` - -```html -Text -``` - -* Two respective attributes `class` are considered to be equivalent if they refer to the same groups of CSS styles. - -For example, the following two code samples will be considered to be equivalent: - -```html -Text -``` - -```html -Text -``` - -**CAUTION!**
-**html-differ** does not check the validity of HTML, but compares them using the above shown criteria and specified options (see the list of possible options in the [API](https://github.com/bem/html-differ#api)). - -## Install - -```bash -$ npm install html-differ -g -``` - -## API - -###HtmlDiffer### - -```js -var HtmlDiffer = require('html-differ').HtmlDiffer, - htmlDiffer = new HtmlDiffer(options); -``` - -where `options` is an object: - -* **ignoreAttributes: [ Array ]** - -Sets what kind of respective attributes' content will be ignored during the comparison (default: `[]`). - -**Example**: `['id', 'for']`
-The following two code samples will be considered to be equivalent: - -```html - - -``` - -```html - - -``` - -* **compareAttributesAsJSON: [ Array ]** - -Sets what kind of respective attributes' content will be compared as JSON objects, but not as strings (default: `[]`).
-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`. - -**Example**: `[{ name: 'data', isFunction: false }, { name: 'onclick', isFunction: true }]`
-The following two code samples will be considered to be equivalent: - -```html -
- - - - -``` - -```html -
- - - - -``` - -**REMARK!**
-The first element of the array could be written in a short form as string:
-`['data', { name: 'onclick', isFunction: true }]`. - -* **ignoreWhitespaces: Boolean** - -Makes **html-differ** ignore whitespaces (spaces, tabs, new lines etc.) during the comparison (default: `true`). - -**Example**: `true`
-The following two code samples will be considered to be equivalent: - -```html -Text TextText -``` - -```html - - Text Text - - - - - - - - Text - - - - - - - - -``` - -* **ignoreComments: Boolean** - -Makes **html-differ** ignore HTML comments during the comparison (default: `true`). - -**Example**: `true`
-The following two code samples will be considered to be equivalent: - -```html - - - - - - <!-- comments2 --> - - -Text - - -``` - -```html - - - - - - - - -Text - - -``` - -* **ignoreEndTags: Boolean** - -Makes **html-differ** ignore end tags during the comparison (default: `false`). - -**Example**: `true`
-The following two code samples will be considered to be equivalent: - -```html -Text -``` - -```html -Text -``` - -* **ignoreDuplicateAttributes: Boolean** - -Makes **html-differ** ignore tags' duplicate attributes during the comparison.
-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`). - -**Example**: `true`
-For example, the following two code samples will be considered to be equivalent: - -```html -Text -``` - -```html -Text -``` - -**BEM preset** - -You can set predefined options for [BEM](http://bem.info/) using the _preset_: - -```js -var HtmlDiffer = require('html-differ').HtmlDiffer, - htmlDiffer = new HtmlDiffer('bem'); -``` - -The options wiil be predefined: - -```js -{ - ignoreAttributes: ['id', 'for', 'aria-labelledby', 'aria-describedby'], - compareAttributesAsJSON: [ - 'data-bem', - { name: 'onclick', isFunction: true }, - { name: 'ondblclick', isFunction: true } - ], - ignoreWhitespaces: true, - ignoreComments: true, - ignoreEndTags: false, - ignoreDuplicateAttributes: false -} -``` - -####Methods#### - -**htmlDiffer.diffHtml**
-**@param** *{String}* - the 1-st HTML code
-**@param** *{String}* - the 2-nd HTML code
-**@returns** *{Array of objects}* - [array with diffs](https://github.com/kpdecker/jsdiff#change-objects) between HTML - -**htmlDiffer.isEqual**
-**@param** *{String}* - the 1-st HTML code
-**@param** *{String}* - the 2-nd HTML code
-**@returns** *{Boolean}* - - -###Logger### - -```js -var logger = require('html-differ/lib/logger'); -``` - -####Methods#### - -**logger.getDiffText**
-**@param** *{Array of objects}* - the result of the work of the method **htmlDiffer.diffHtml**
-**@param** *{Object}* - options:
- -* **charsAroundDiff: Number** - the number of characters around the diff result between two HTML (default: `40`). - -**@returns** *{String}* - -**logger.logDiffText**
-**@param** *{Array of objects}* - the result of the work of the method **htmlDiffer.diffHtml**
-**@param** *{Object}* - options:
- -* **charsAroundDiff: Number** - the number of characters around the diff result between two HTML (default: `40`). - -**@returns** - pretty logging of diffs: - - - - -###Example### - -```js -var fs = require('fs'), - HtmlDiffer = require('html-differ').HtmlDiffer, - logger = require('html-differ/lib/logger'); - -var html1 = fs.readFileSync('1.html', 'utf-8'), - html2 = fs.readFileSync('2.html', 'utf-8'); - -var options = { - ignoreAttributes: [], - compareAttributesAsJSON: [], - ignoreWhitespaces: true, - ignoreComments: true, - ignoreEndTags: false, - ignoreDuplicateAttributes: false - }; - -var htmlDiffer = new HtmlDiffer(options); - -var diff = htmlDiffer.diffHtml(html1, html2), - isEqual = htmlDiffer.isEqual(html1, html2), - res = logger.getDiffText(diff, { charsAroundDiff: 40 }); - -logger.logDiffText(diff, { charsAroundDiff: 40 }); -``` - -##Usage as a program## - -```bash -$ html-differ --help -Compares two HTML - -Usage: - html-differ [OPTIONS] [ARGS] - -Options: - -h, --help : Help - -v, --version : Shows the version number - --config=CONFIG : Path to configuration JSON file - --bem : Uses predefined options for BEM - --chars-around-diff=CHARSAROUNDDIFF : The number of characters around the diff (default: 40) - -Arguments: - PATH1 : Path to the 1-st HTML file (required) - PATH2 : Path to the 2-nd HTML file (required) -``` - -###Example### - -```bash -$ html-differ path/to/html1 path/to/html2 - -$ html-differ --config=path/to/config --chars-around-diff=40 path/to/html1 path/to/html2 - -$ html-differ --bem path/to/html1 path/to/html2 -``` - -###Configuration file## - -Study the following `config.json` file: - -```js -{ - "ignoreAttributes": [], - "compareAttributesAsJSON": [], - "ignoreWhitespaces": true, - "ignoreComments": true, - "ignoreEndTags": false, - "ignoreDuplicateAttributes": false -} -``` + +## bla