Summary#
An app that keeps versions of something — a document, a config, a pipeline's output, a code change — sooner or later
has to show what changed between two of them. Osysharp.Diff takes the unified diff text and draws it; you do not
parse anything yourself.
app Review {
use Osysharp.Diff@1;
use Osysharp.Ui;
model "model/**/*.osy";
}Signature#
using Osysharp.Diff;
DiffView(string patch, // `git diff`, `git show`, `diff -u` — one file or many
DiffLayout layout = DiffLayout.Unified, // or DiffLayout.Split: old left, new right
string oldText = "", string newText = "", // the WHOLE old/new file — either makes every fold openable
int maxLines = 1000, // the most lines of code drawn; the rest is counted
int wordLimit = 500, // the longest line whose changed words are marked
string label = "Diff") // what a screen reader and a test's `within:` call it
List<DiffFile> ParseDiff(string patch) // the files: paths, change, hunks, lines, notes
DiffWordPair DiffWords(string oldText, string newText, int maxChars) // the changed words of one pair of linesDescription#
What it reads#
The unified format, as git and diff -u print it: diff --git headers or bare ---/+++ pairs, @@ -a,b +c,d @@
hunks with their section text, \ No newline at end of file, new and deleted files, renames and copies (shown as
"renamed from …" and "copied from …"), mode changes, and binary files — a note, never their bytes. A commit message or an index line
around the files is passed over. A hunk ends when the line counts in its head are used up, so a removed line that
itself reads -- comment is a removed line, not the next file's header.
What it draws#
Each file under a bar with its path, what happened to it and +added −removed; each hunk under its @@ line; every
line with its old and new number. A removed line paired with the added line after it has the words that changed marked
inside both. The unchanged lines before the first hunk and between two hunks fold to one row: "⋯ 3 unchanged lines".
Opening a fold#
A diff carries only a few lines of context, so a fold can only be a count — unless you give the view the whole file.
Pass oldText or newText (either; both is fine) and every fold becomes a button, "Show 3 unchanged lines", that draws
the lines in place with both numbers; the run after the last hunk is folded too. This is for a diff of ONE file: for a
diff of several, draw one DiffView per file with its own texts.
Side by side#
layout: DiffLayout.Split sets the old file on the left and the new on the right. An unchanged line is on both sides;
a run of removed lines is set opposite the run of added lines after it, one for one, and the longer run's extra lines
face an empty cell.
Hostile input#
- Every line is plain text. A path, a hunk's section and a line are drawn as the characters they are —
<script>,**bold**,{name}and[Navigation](/reference/ui/navigation/)included. Nothing in a diff is read as markup. - The work is bounded. Parsing is one pass and never sizes anything from a hunk's head. Changed words are compared
only for lines of at most
wordLimitcharacters (default 500) and 200 words, and at most a million comparison cells per diff; a pair past either is drawn whole, and a note under the file says how many lines were not compared, and why: too long, or too many words. - The lines drawn are capped. At most
maxLines(default 1000); the rest is one row, "N more lines not shown, in M more files." RaisemaxLinesto draw more. - It declares no capability: no egress, no secret, no native code, no script — the renderer's own elements only.
Theming#
Every colour, the face and the sizes are Diff* tokens that default to the app's own: DiffSurface is the surface,
DiffInk the text, DiffGutterInk the muted text, DiffAddedMark/DiffRemovedMark the success and danger ink. The
four line and word tints (DiffAddedBg, DiffAddedWord, DiffRemovedBg, DiffRemovedWord) are the kit's own quiet
greens and reds in light and dark. Shadow any of them in your theme (theme tokens):
theme Review {
Colors { DiffAddedBg = Colors.SuccessTint; DiffRemovedBg = Colors.DangerTint; DiffFoldBg = Colors.Muted; }
Font { DiffFace = Font.Mono; }
}| Token | Group | Default |
|---|---|---|
DiffSurface · DiffBorder · DiffInk | Colors | Surface · CardLine · OnSurface |
DiffGutterInk · DiffNoteInk | Colors | TextMuted |
DiffFileBg · DiffFileInk | Colors | Muted · OnSurface |
DiffHunkBg · DiffHunkInk · DiffFoldBg · DiffFoldInk · DiffEmptyBg | Colors | Sunken · TextMuted |
DiffAddedBg · DiffAddedWord · DiffRemovedBg · DiffRemovedWord | Colors | the kit's light/dark tints |
DiffAddedMark · DiffRemovedMark | Colors | SuccessInk · DangerInk |
DiffFace | Font | Mono |
DiffText · DiffNote | FontSize | Label · Caption |
DiffStrong | FontWeight | Semibold |
DiffCard | Radius | Md |
Examples#
app Review {
use Osysharp.Diff@1;
use Osysharp.Ui;
model "model/**/*.osy";
}
using Osysharp.Diff;
[Composable]
component ChangeOf(string patch, string before, string after) {
render {
DiffView(patch, oldText: before, newText: after, label: "Change");
}
}using Osysharp.Diff;
[Test]
void a_rename_and_its_changed_word_are_read() {
var patch = "diff --git a/a.txt b/b.txt\nrename from a.txt\nrename to b.txt\n--- a/a.txt\n+++ b/b.txt\n@@ -1 +1 @@\n-price + tax\n+price + vat\n";
var file = ParseDiff(patch)[0];
Assert.Equal(DiffChange.Renamed, file.Change);
Assert.Equal("b.txt", file.NewPath);
Assert.Equal("vat", DiffWords("price + tax", "price + vat", 500).New.Single(s => s.Changed).Text);
}See also#
- theme tokens — a theme's tokens, and shadowing a kit's
- The chart kit — line, column, bar, scatter and candle, with no JavaScript — the other pure-Osy# drawing kit, themed the same way