text_diff.module
This package holds more than this page lists. See all of its files in its world.
README.md
text_diff
Pure-Luau line-diff helper used by world.diff / world.show and the
zm diff / zm show shell commands. LCS-based; produces structured
hunks (op-tagged lines, not unified-diff text) so AI consumers can
pattern-match on op instead of parsing +/-/ prefixes.
Exports
M.diff(oldText: string?, newText: string?, opts: DiffOpts?) -> FileDiff— diff two strings, return the structured per-file shape.M.added(newText: string?, opts: DiffOpts?) -> FileDiff— pure-add convenience (equivalent toM.diff("", newText, opts)).M.removed(oldText: string?, opts: DiffOpts?) -> FileDiff— pure-remove convenience.M.toUnifiedText(fileDiff: FileDiff) -> string— render structured diff back into unified-diff text.M.toStatLine(fileDiff: FileDiff) -> string—git diff --stat-style one-line summary.M.SIZE_CAP_BYTES: number— per-file size cap (256 KB). Files larger than this return a size-only summary withis_text=false.
Types:
DiffLine = { op: string, text: string }— one tagged line.opis"+","-", or" "(context).DiffHunk = { old_start, old_count, new_start, new_count, lines: { DiffLine } }— git-style hunk.DiffOpts = { context: number?, path: string?, action: string? }.FileDiff = { path?, action?, is_text, added?, removed?, hunks?, size_old?, size_new? }.
Usage
local TextDiff = require("@builtin::modules.text_diff")
local d = TextDiff.diff(oldBytes, newBytes, { path = "foo.luau" })
if d.is_text then
print(TextDiff.toStatLine(d)) -- "modified foo.luau +3 -1"
print(TextDiff.toUnifiedText(d))
else
print(string.format("oversize: %d -> %d bytes", d.size_old, d.size_new))
end
Notes
- The per-file size cap (
M.SIZE_CAP_BYTES = 256 * 1024) mirrors the spacetimetext_blobsinline threshold. Anything above that lives in the bucket as binary anyway, so the diff library never sees it as text in practice; the cap is belt-and-suspenders for callers that bypass the routing. - The alignment is a longest common subsequence computed on the diagonal
band of the table its edit distance reaches, one bit per cell, after the
common prefix and suffix are aligned line by line. Memory and time follow
the lengths of the two texts times their edit distance, so a few changed
lines in a long file cost a few bands of that file's length. A long diff
runs in slices that hand the frame back (
FrameBudget.yield) when the caller runs on a coroutine that can yield. - Where repeated lines leave several equally long alignments, the diff takes the one a walk back from the last lines takes: a common pair of lines is kept, and otherwise the new side's line is let go first, so each run of changed lines lists its removed lines before its added ones.
- Default context window is 3 lines (matches
git diff -U3). Override viaopts.context. - Hunk header line numbers follow git's
@@ -0,0 +1,N @@shape for pure additions (and the mirror for pure deletions). - Trailing newline handling: a final
\ndoesn't produce an empty trailing element. Matches POSIXwc -lsemantics and most diff tools.