.config/coc/extensions/node_modules/coc-prettier/node_modules/diff/README.md

   1 # jsdiff
   2
   3 [![Build Status](https://secure.travis-ci.org/kpdecker/jsdiff.svg)](http://travis-ci.org/kpdecker/jsdiff)
   4 [![Sauce Test Status](https://saucelabs.com/buildstatus/jsdiff)](https://saucelabs.com/u/jsdiff)
   5
   6 A javascript text differencing implementation.
   7
   8 Based on the algorithm proposed in
   9 ["An O(ND) Difference Algorithm and its Variations" (Myers, 1986)](http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.4.6927).
  10
  11 ## Installation
  12 ```bash
  13 npm install diff --save
  14 ```
  15
  16 ## API
  17
  18 * `JsDiff.diffChars(oldStr, newStr[, options])` - diffs two blocks of text, comparing character by character.
  19
  20     Returns a list of change objects (See below).
  21
  22     Options
  23     * `ignoreCase`: `true` to ignore casing difference. Defaults to `false`.
  24
  25 * `JsDiff.diffWords(oldStr, newStr[, options])` - diffs two blocks of text, comparing word by word, ignoring whitespace.
  26
  27     Returns a list of change objects (See below).
  28
  29     Options
  30     * `ignoreCase`: Same as in `diffChars`.
  31
  32 * `JsDiff.diffWordsWithSpace(oldStr, newStr[, options])` - diffs two blocks of text, comparing word by word, treating whitespace as significant.
  33
  34     Returns a list of change objects (See below).
  35
  36 * `JsDiff.diffLines(oldStr, newStr[, options])` - diffs two blocks of text, comparing line by line.
  37
  38     Options
  39     * `ignoreWhitespace`: `true` to ignore leading and trailing whitespace. This is the same as `diffTrimmedLines`
  40     * `newlineIsToken`: `true` to treat newline characters as separate tokens.  This allows for changes to the newline structure to occur independently of the line content and to be treated as such. In general this is the more human friendly form of `diffLines` and `diffLines` is better suited for patches and other computer friendly output.
  41
  42     Returns a list of change objects (See below).
  43
  44 * `JsDiff.diffTrimmedLines(oldStr, newStr[, options])` - diffs two blocks of text, comparing line by line, ignoring leading and trailing whitespace.
  45
  46     Returns a list of change objects (See below).
  47
  48 * `JsDiff.diffSentences(oldStr, newStr[, options])` - diffs two blocks of text, comparing sentence by sentence.
  49
  50     Returns a list of change objects (See below).
  51
  52 * `JsDiff.diffCss(oldStr, newStr[, options])` - diffs two blocks of text, comparing CSS tokens.
  53
  54     Returns a list of change objects (See below).
  55
  56 * `JsDiff.diffJson(oldObj, newObj[, options])` - diffs two JSON objects, comparing the fields defined on each. The order of fields, etc does not matter in this comparison.
  57
  58     Returns a list of change objects (See below).
  59
  60 * `JsDiff.diffArrays(oldArr, newArr[, options])` - diffs two arrays, comparing each item for strict equality (===).
  61
  62     Options
  63     * `comparator`: `function(left, right)` for custom equality checks
  64
  65     Returns a list of change objects (See below).
  66
  67 * `JsDiff.createTwoFilesPatch(oldFileName, newFileName, oldStr, newStr, oldHeader, newHeader)` - creates a unified diff patch.
  68
  69     Parameters:
  70     * `oldFileName` : String to be output in the filename section of the patch for the removals
  71     * `newFileName` : String to be output in the filename section of the patch for the additions
  72     * `oldStr` : Original string value
  73     * `newStr` : New string value
  74     * `oldHeader` : Additional information to include in the old file header
  75     * `newHeader` : Additional information to include in the new file header
  76     * `options` : An object with options. Currently, only `context` is supported and describes how many lines of context should be included.
  77
  78 * `JsDiff.createPatch(fileName, oldStr, newStr, oldHeader, newHeader)` - creates a unified diff patch.
  79
  80     Just like JsDiff.createTwoFilesPatch, but with oldFileName being equal to newFileName.
  81
  82
  83 * `JsDiff.structuredPatch(oldFileName, newFileName, oldStr, newStr, oldHeader, newHeader, options)` - returns an object with an array of hunk objects.
  84
  85     This method is similar to createTwoFilesPatch, but returns a data structure
  86     suitable for further processing. Parameters are the same as createTwoFilesPatch. The data structure returned may look like this:
  87
  88     ```js
  89     {
  90       oldFileName: 'oldfile', newFileName: 'newfile',
  91       oldHeader: 'header1', newHeader: 'header2',
  92       hunks: [{
  93         oldStart: 1, oldLines: 3, newStart: 1, newLines: 3,
  94         lines: [' line2', ' line3', '-line4', '+line5', '\\ No newline at end of file'],
  95       }]
  96     }
  97     ```
  98
  99 * `JsDiff.applyPatch(source, patch[, options])` - applies a unified diff patch.
 100
 101     Return a string containing new version of provided data. `patch` may be a string diff or the output from the `parsePatch` or `structuredPatch` methods.
 102
 103     The optional `options` object may have the following keys:
 104
 105     - `fuzzFactor`: Number of lines that are allowed to differ before rejecting a patch. Defaults to 0.
 106     - `compareLine(lineNumber, line, operation, patchContent)`: Callback used to compare to given lines to determine if they should be considered equal when patching. Defaults to strict equality but may be overridden to provide fuzzier comparison. Should return false if the lines should be rejected.
 107
 108 * `JsDiff.applyPatches(patch, options)` - applies one or more patches.
 109
 110     This method will iterate over the contents of the patch and apply to data provided through callbacks. The general flow for each patch index is:
 111
 112     - `options.loadFile(index, callback)` is called. The caller should then load the contents of the file and then pass that to the `callback(err, data)` callback. Passing an `err` will terminate further patch execution.
 113     - `options.patched(index, content, callback)` is called once the patch has been applied. `content` will be the return value from `applyPatch`. When it's ready, the caller should call `callback(err)` callback. Passing an `err` will terminate further patch execution.
 114
 115     Once all patches have been applied or an error occurs, the `options.complete(err)` callback is made.
 116
 117 * `JsDiff.parsePatch(diffStr)` - Parses a patch into structured data
 118
 119     Return a JSON object representation of the a patch, suitable for use with the `applyPatch` method. This parses to the same structure returned by `JsDiff.structuredPatch`.
 120
 121 * `convertChangesToXML(changes)` - converts a list of changes to a serialized XML format
 122
 123
 124 All methods above which accept the optional `callback` method will run in sync mode when that parameter is omitted and in async mode when supplied. This allows for larger diffs without blocking the event loop. This may be passed either directly as the final parameter or as the `callback` field in the `options` object.
 125
 126 ### Change Objects
 127 Many of the methods above return change objects. These objects consist of the following fields:
 128
 129 * `value`: Text content
 130 * `added`: True if the value was inserted into the new string
 131 * `removed`: True if the value was removed from the old string
 132
 133 Note that some cases may omit a particular flag field. Comparison on the flag fields should always be done in a truthy or falsy manner.
 134
 135 ## Examples
 136
 137 Basic example in Node
 138
 139 ```js
 140 require('colors');
 141 var jsdiff = require('diff');
 142
 143 var one = 'beep boop';
 144 var other = 'beep boob blah';
 145
 146 var diff = jsdiff.diffChars(one, other);
 147
 148 diff.forEach(function(part){
 149   // green for additions, red for deletions
 150   // grey for common parts
 151   var color = part.added ? 'green' :
 152     part.removed ? 'red' : 'grey';
 153   process.stderr.write(part.value[color]);
 154 });
 155
 156 console.log();
 157 ```
 158 Running the above program should yield
 159
 160 <img src="images/node_example.png" alt="Node Example">
 161
 162 Basic example in a web page
 163
 164 ```html
 165 <pre id="display"></pre>
 166 <script src="diff.js"></script>
 167 <script>
 168 var one = 'beep boop',
 169     other = 'beep boob blah',
 170     color = '',
 171     span = null;
 172
 173 var diff = JsDiff.diffChars(one, other),
 174     display = document.getElementById('display'),
 175     fragment = document.createDocumentFragment();
 176
 177 diff.forEach(function(part){
 178   // green for additions, red for deletions
 179   // grey for common parts
 180   color = part.added ? 'green' :
 181     part.removed ? 'red' : 'grey';
 182   span = document.createElement('span');
 183   span.style.color = color;
 184   span.appendChild(document
 185     .createTextNode(part.value));
 186   fragment.appendChild(span);
 187 });
 188
 189 display.appendChild(fragment);
 190 </script>
 191 ```
 192
 193 Open the above .html file in a browser and you should see
 194
 195 <img src="images/web_example.png" alt="Node Example">
 196
 197 **[Full online demo](http://kpdecker.github.com/jsdiff)**
 198
 199 ## Compatibility
 200
 201 [![Sauce Test Status](https://saucelabs.com/browser-matrix/jsdiff.svg)](https://saucelabs.com/u/jsdiff)
 202
 203 jsdiff supports all ES3 environments with some known issues on IE8 and below. Under these browsers some diff algorithms such as word diff and others may fail due to lack of support for capturing groups in the `split` operation.
 204
 205 ## License
 206
 207 See [LICENSE](https://github.com/kpdecker/jsdiff/blob/master/LICENSE).