|
| 1 | +# DiffLib |
| 2 | + |
| 3 | +DiffLib is a Hack library for creating and parsing diffs. Diffs can be created |
| 4 | +between any two sequences of items. Additional helpers (such as support for |
| 5 | +unified diffs, and colored diffs) are provided for string diffs. |
| 6 | + |
| 7 | +Diffs are represented as a sequence of `DiffOp` operations; these can 'keep' an |
| 8 | +element (i.e. it's unchanged in both sequences), insert an element, or delete an |
| 9 | +element. For example, in a unified diff, these would be: |
| 10 | + |
| 11 | +```diff |
| 12 | + DiffKeepOp |
| 13 | +- DiffDeleteOp |
| 14 | ++ DiffInsertOp |
| 15 | +``` |
| 16 | + |
| 17 | +String diffs are typically represented as a sequence of lines, but can also be |
| 18 | +represented as a sequence of characters, allowing intra-line diffs. |
| 19 | + |
| 20 | +## Examples |
| 21 | + |
| 22 | +```Hack |
| 23 | +use namespace Facebook\DiffLib; |
| 24 | +
|
| 25 | +function create_unified_diff(string $from, string $to): string { |
| 26 | + return DiffLib\StringDiff::lines($from, $to)->getUnifiedDiff(); |
| 27 | +} |
| 28 | +
|
| 29 | +function create_colored_diff(string $from, string $to): string { |
| 30 | + return DiffLib\CLIColoredUnifiedDiff::create($from, $to); |
| 31 | +} |
| 32 | +
|
| 33 | +final class IntDiff extends DiffLib\Diff { |
| 34 | + const type TContent = int; |
| 35 | +} |
| 36 | +
|
| 37 | +function dump_int_diff(vec<int> $from, vec<int> $to): void { |
| 38 | + $diff = (new IntDiff($from, $to))->getDiff(); |
| 39 | + foreach ($diff as $op) { |
| 40 | + if ($op is DiffLib\DiffKeepOp<_>) { |
| 41 | + \printf(" %d\n", $op->getContent()); |
| 42 | + } else if ($op is DiffLib\DiffDeleteOp<_>) { |
| 43 | + \printf("- %d\n", $op->getContent()); |
| 44 | + } else { |
| 45 | + $op = $op as DiffLib\DiffInsertOp<_>; |
| 46 | + printf("+ %d\n", $op->getContent()); |
| 47 | + } |
| 48 | + } |
| 49 | +} |
| 50 | +
|
| 51 | +``` |
| 52 | + |
| 53 | +`dump_int_diff(vec[1, 3, 9], vec[1, 4, 9])` will produce this output: |
| 54 | + |
| 55 | +``` |
| 56 | + 1 |
| 57 | +- 3 |
| 58 | ++ 4 |
| 59 | + 9 |
| 60 | +``` |
| 61 | + |
| 62 | +## Requirements |
| 63 | + |
| 64 | +* The current release version of HHVM |
| 65 | + |
| 66 | +## Installing DiffLib |
| 67 | + |
| 68 | +``` |
| 69 | +composer require facebook/difflib |
| 70 | +``` |
| 71 | + |
| 72 | +## How DiffLib works |
| 73 | + |
| 74 | +Diffs are created using Myers' diff algorithm: |
| 75 | +Myers, E.W. Algorithmica (1986) 1: 251. https://doi.org/10.1007/BF01840446 |
| 76 | + |
| 77 | +For more details, see [the commented implementation](src/Diff.php). |
| 78 | + |
| 79 | +## Full documentation |
| 80 | + |
| 81 | +- `DiffLib\Diff`: abstract base class. Needs to be subclassed to operate on |
| 82 | + any particular type. |
| 83 | +- `DiffLib\StringDiff`: final class for diffing strings, and adds support |
| 84 | + for creating unified diffs |
| 85 | +- `DiffLib\ColoredUnifiedDiff`: abstract class for rendering unified diffs. |
| 86 | + Output may be any type - for example, strings or XHP. |
| 87 | +- `DiffLib\CLIColoredUnifiedDiff`: abstract final class for rendering unified |
| 88 | + diffs to a terminal that supports color escape sequences. Provides intra-line |
| 89 | + highlighting. |
| 90 | +- `DiffLib\DiffOp`: abstract class for a diff operation. Sealed to |
| 91 | + `DiffInsertOp`, `DiffKeepOp`, and `DiffDeleteOp`. |
| 92 | +- `DiffLib\cluster()`: utility function to group together sequential operations |
| 93 | + of the same kind. Converts `vec<DiffOp<T>>` to a generally shorter number of |
| 94 | + `vec<DiffOp<vec<T>>>` |
| 95 | + |
| 96 | +## License |
| 97 | +DiffLib is MIT licensed, as found in the LICENSE file. |
0 commit comments