text.diff

The diff package finds what changed between two texts. It compares them line by line, finds the shortest list of lines to remove and add, and can print the result as a unified diff, the format of diff -u and git diff: a --- and a +++ header, then hunks that start with @@ -1,3 +1,4 @@ and mark lines with , - and +. The output follows Python's difflib.unified_diff exactly, so tools that read one read the other. Use it for a test that compares generated output with an expected file, for a build step that shows what a generator changed, and for an update check that asks whether anything is different.

There are two levels. Unified and UnifiedText give the finished lines; Opcodes gives the edit script itself, a list of Opcode records that say "lines a[i1:i2] were replaced by b[j1:j2]", for a program that wants to draw the difference its own way. Ratio and RatioText give a number between 0 and 1 for how alike two inputs are.

What people get wrong:

• Expecting nothing back to mean an error. When both inputs are equal, Unified returns an empty list and UnifiedText an empty string, not even a header. That is how you test for "no difference".
• Passing text where lines are expected. Unified takes Vector<str>; split a text with Lines first, or call UnifiedText. Lines drops the last empty piece after a final newline and a trailing \r on each line, so files with Windows line ends compare equal to files with Unix ones.
• Reading the ratio as an edit distance. Ratio is 2*M/T, where M is the number of lines the two share in order and T the total of both lengths. It is built from a longest common subsequence, so it can be a little higher than difflib.SequenceMatcher.ratio(), which stops early on some inputs.
• Diffing huge, completely different inputs. The search stops after 3000 edits and then treats what is left as one block replaced by another. The result is still a correct diff, only not the shortest.
• Forgetting to free. Lines, Unified, Opcodes and GroupedOpcodes return vectors the caller frees (and each inner vector of GroupedOpcodes).

Showing what changed between two files

Read both files, hand them to UnifiedText with their names for the header, and print the answer when it is not empty. The third argument after the names is the number of unchanged lines to show around each change (3 is the usual choice, 0 shows only the changes).

import text.diff
import fs.file
import fs.path
import os.temp

func main:
    work := temp.Directory()
    defer temp.RemoveDir(work)
    left := path.Join(work, "config.old")
    right := path.Join(work, "config.new")
    file.WriteText(left, "port=80\nhost=a\nmode=safe\n")
    file.WriteText(right, "port=8080\nhost=a\nmode=safe\ndebug=1\n")
    patch := diff.UnifiedText(file.ReadText(left), file.ReadText(right), "config.old", "config.new", 1)
    if patch.len() == 0:
        println "the files are the same"
    else:
        print patch
    end
    println "same file:", diff.UnifiedText("x\n", "x\n", "a", "b", 3).len() == 0
end

Suggesting the closest name

RatioText turns "how alike are these two words" into a number, so a program can answer a typo with "did you mean". The example below tries each option, keeps the one with the highest score and only suggests it when the score is at least 0.6. Ratio does the same for lists of lines: three of the four lines are shared, so the score is 0.75.

import text.diff

func closest(word: str, options: str[]): str:
    mut best := ""
    mut best_score := 0.0
    each option in options:
        score := diff.RatioText(word, option)
        if score > best_score:
            best_score = score
            best = option
        end
    end
    ret best
end

func main:
    commands := ["start", "stop", "status", "restart", "version"]
    each typed in ["starts", "stops", "restarts", "xyz"]:
        guess := closest(typed, commands)
        score := guess.len() > 0 ? diff.RatioText(typed, guess) : 0.0
        if score >= 0.6:
            println typed, "->", guess
        else:
            println typed, "-> no suggestion"
        end
    end

    old := diff.Lines("a\nb\nc\nd\n")
    fresh := diff.Lines("a\nb\nx\nd\n")
    defer old.free()
    defer fresh.free()
    println "lines in common:", diff.Ratio(old, fresh)
end

Types

struct Opcode

import text.diff
import str

func name(tag: int): str:
    switch tag:
        diff.Equal:
            ret "equal"
        end
        diff.Replace:
            ret "replace"
        end
        diff.Delete:
            ret "delete"
        end
        else:
            ret "insert"
        end
    end
end

func main:
    a := diff.Lines("one\ntwo\nthree\nfour\n")
    b := diff.Lines("one\n2\nthree\nfour\nfive\n")
    defer a.free()
    defer b.free()
    ops := diff.Opcodes(a, b)
    defer ops.free()
    each op in ops:
        println name(op.tag), "a[" + str.FromInt(op.a_start as i64) + ":" + str.FromInt(op.a_stop as i64) + "]", "b[" + str.FromInt(op.b_start as i64) + ":" + str.FromInt(op.b_stop as i64) + "]"
    end
    groups := diff.GroupedOpcodes(a, b, 0)
    println "hunks:", groups.len()
    each g in groups:
        g.free()
    end
    groups.free()
end

Constants and variables

const Equal: i32 = 0

const Replace: i32 = 1

const Delete: i32 = 2

const Insert: i32 = 3

Functions

func Opcodes(a: Vector<str>, b: Vector<str>): Vector<Opcode>

func GroupedOpcodes(a: Vector<str>, b: Vector<str>, context: int): Vector<Vector<Opcode>>

func Unified(a: Vector<str>, b: Vector<str>, from_name: str, to_name: str, context: int): Vector<str>

import text.diff

func main:
    old := diff.Lines("red\ngreen\nblue\n")
    fresh := diff.Lines("red\nyellow\nblue\nblack\n")
    defer old.free()
    defer fresh.free()
    lines := diff.Unified(old, fresh, "old.txt", "new.txt", 1)
    defer lines.free()
    each line in lines:
        println line
    end
    print diff.UnifiedText("a\nb\n", "a\nc\n", "x", "y", 0)
end

func Lines(text: str): Vector<str>

func UnifiedText(a: str, b: str, from_name: str, to_name: str, context: int): str

func Ratio(a: Vector<str>, b: Vector<str>): f64

import text.diff

func main:
    println diff.RatioText("kitten", "sitting")
    println diff.RatioText("same", "same"), diff.RatioText("abc", "xyz")
    a := diff.Lines("a\nb\nc\nd\n")
    b := diff.Lines("a\nb\nx\nd\n")
    defer a.free()
    defer b.free()
    println diff.Ratio(a, b)
end

func RatioText(a: str, b: str): f64