Unified-diff engine — hunks, writer, and patch scanner
A unified-diff engine the whole ecosystem can share: LCS line diffing, numbered context hunks, a GNU diff -u writer, and a scanner that numbers the rows of any patch. Extracted from candy-code's BuildsUnifiedDiff trait (now a delegating consumer) and the DiffGutter region model (which still keeps its own copy today). First-party — there is no 1:1 Go counterpart.
composer require sugarcraft/sugar-diff:@dev
use SugarCraft\Diff\Diff;
use SugarCraft\Diff\DiffOptions;
use SugarCraft\Diff\Reader\UnifiedScan;
$before = "Hello World\n";
$after = "Hello PHP\n";
$diff = Diff::compute($before, $after);
$patchText = $diff->unified('file.txt');
echo $patchText;
// --- a/file.txt
// +++ b/file.txt
// @@ -1 +1 @@
// -Hello World
// +Hello PHP
// Immutable, fluent options — the defaults reproduce candy-code's hunk
// bodies and grouping (headers are GNU-faithful).
$wide = Diff::compute($before, $after, DiffOptions::new()
->withContextLines(10)
->withIgnoreWhitespace()
->withNoNewlineMarker()
->withDevNullOnEmptySide());
// Number the rows of an existing patch (gutter/viewer support):
foreach (UnifiedScan::lines($patchText) as $row) {
// $row->old, $row->new, $row->fileHeader, $row->kind (ScanRowKind enum)
}
| Class | Method | Description |
|---|---|---|
| Diff | compute(string|list<string> $before, string|list<string> $after, ?DiffOptions $options = null): self | Line-mode LCS diff; `degraded` reports the cell-budget fallback (candy-code defaults reproduced for hunk bodies and grouping) |
| Diff | unified(string $oldPath, ?string $newPath = null): string | Full diff -u text with --- / +++ headers; the second argument names the new side only |
| Diff | hunkText(): string | Hunks only, no file headers |
| Diff | isEmpty() / addedLines() / removedLines(): int|bool | Summary counts |
| Hunk | header() / lines() / removedCount() / addedCount() | The @@ block (GNU-elided single-line ranges), its rows, and -/+ row tallies |
| Line / LineKind | kind / text / oldNumber / newNumber; marker() / toUnifiedRow() | One numbered verbatim row; eq/del/ins vocabulary |
| DiffOptions | withContextLines(int) / withMaxLcsCells(int) | Context window (DEFAULT_CONTEXT_LINES = 3) and LCS cell budget (DEFAULT_MAX_LCS_CELLS = 250 000, counted as the table's real (n+1)×(m+1) footprint) |
| DiffOptions | withIgnoreWhitespace() / withIgnoreCase() | Fold comparisons; emitted rows keep original bytes |
| DiffOptions | withNoNewlineMarker() / withDevNullOnEmptySide() | GNU annotations, opt-in (the marker only annotates STRING sides) |
| UnifiedFormat | write(Diff, string $oldPath, ?string $newPath) / hunksOnly(Diff): string | The writer behind Diff::unified()/hunkText(); NO_NEWLINE_ROW; path labels are control-byte-safe |
| SideBySideFormat | rows(Diff) / fromUnified(string|list<string>): list<SideBySideRow> | Split-view pairing; SideBySideRow->left/->right, isPaired() |
| UnifiedScan | lines(string|list<string>): list<ScannedLine> | Per-row old/new line numbers, fileHeader flag, and ScanRowKind; declared-count budgets, fail-closed boundaries (MAX_LINE_NUMBER_DIGITS caps start fields) |
| UnifiedScan | fileHeaders(string|list<string>): list<bool> / rowsOf(string): list<string> | Which rows start a new file; the writer-compatible row split |