Skip to main content

Crate linework

Crate linework 

Source
Expand description

LINEWORK — the drawn marks of an illustration, and here they are keyed by line. The engine-neutral protocol for binding language intelligence to an editor: line-keyed, two-wave code PAINT plus on-demand FACTS, with a trait (Limner) an editor widget can be generic over.

This crate has NO dependencies and knows nothing about any particular engine or editor. An intelligence engine (a parser toolchain, a language runtime) implements Limner; an editor consumes it. Neither needs the other’s types.

§The shape

  • Paint is LINE-KEYED: each line is a vector of Runs — 4-byte cells {len, style, mods} tiling the line’s bytes exactly. Runs are line-relative, so a line that merely SHIFTS re-emits nothing.
  • Paint is TWO-WAVE: style is the lexical class (wave 0 — available synchronously with a keystroke, from the damaged lines only), and mods carries semantic bits (wave 1 — definition, resolved/unresolved reference, public, foreign, typed) that ARRIVE WITHOUT EVER CHANGING A STYLE. Refinement is additive, so the first frame is already right and nothing flickers.
  • A PaintDelta names what one edit changed and nothing else: a spliced window of lines, plus semantic-only repaints by line number. The repaint set is the edit’s semantic blast radius, made visible.
  • FactCards answer “what IS this name” — definition site, problem, display type, namespace — and Hints carry inline decorations. Both are lookups against warm state, not requests.

Offsets and lengths are BYTES of UTF-8 text. Consumers that index by character (ropes) convert at the boundary.

The wire form is the memory form, little-endian; see encode_lines/decode_lines. Decoding is bounds checks, not parsing.

§Both sides of the seam

An engine implements Limner; an editor holds one and asks. This toy engine paints each line’s first word as style 0 and marks it a definition — enough to show the shape without being a real highlighter.

use linework::{FactCard, Hint, LineEdit, Limner, Paint, PaintDelta, Run,
               MOD_DEF, STYLE_NONE};

fn paint_line(line: &str) -> Vec<Run> {
    if line.is_empty() {
        return Vec::new();
    }
    // Byte indices throughout — never char indices.
    let head = line.find(' ').unwrap_or(line.len()) as u16;
    let tail = line.len() as u16 - head;
    let mut runs = vec![Run { len: head, style: 0, mods: MOD_DEF }];
    if tail > 0 {
        runs.push(Run { len: tail, style: STYLE_NONE, mods: 0 });
    }
    runs
}

#[derive(Default)]
struct FirstWord { rev: u64, text: String }

impl Limner for FirstWord {
    fn open(&mut self, text: &str) -> Paint {
        self.text = text.to_string();
        self.rev += 1;
        Paint { rev: self.rev, lines: text.lines().map(paint_line).collect() }
    }

    fn edit(&mut self, edit: &LineEdit) -> PaintDelta {
        self.rev += 1;
        let runs = edit.lines.iter().map(|l| paint_line(l)).collect();
        // Only the spliced window is re-emitted; untouched lines are
        // absent from the delta, not repeated.
        PaintDelta {
            rev: self.rev,
            splice: Some(((edit.start, edit.end), runs)),
            repaints: Vec::new(),
        }
    }

    fn facts(&mut self, _offset: u32) -> Option<FactCard> { None }
    fn hints(&mut self) -> Vec<Hint> { Vec::new() }
    fn legend(&self) -> Vec<String> { vec!["keyword".to_string()] }
    fn text(&mut self) -> String { self.text.clone() }
}

// --- the editor side: generic over the trait, blind to the engine ---
fn total_painted_bytes(limner: &mut dyn Limner, src: &str) -> u32 {
    let paint = limner.open(src);
    paint.lines.iter().flatten().map(|r| r.len as u32).sum()
}

let mut engine = FirstWord::default();
assert_eq!(total_painted_bytes(&mut engine, "let x\nlet y"), 10);

// An edit returns only what changed.
let delta = engine.edit(&LineEdit {
    start: 1,
    end: 2,
    lines: vec!["let zz".to_string()],
});
assert!(delta.repaints.is_empty());
let (range, lines) = delta.splice.unwrap();
assert_eq!(range, (1, 2));
assert_eq!(lines[0][0].mods, MOD_DEF);

Structs§

FactCard
Everything the engine knows about the name at an offset, in one record. No transport, no markdown — the editor renders it.
Hint
An inline decoration: text rendered at (line, col) — e.g. a : Num type hint after a definition’s name.
LineEdit
Replace lines [start, end) with lines (texts WITHOUT terminators). The limner preserves the replaced lines’ terminators positionally and uses its default for any extras — a pure-text protocol stays out of the newline-politics business.
Mark
One identified, categorized span of document STRUCTURE — the sparse counterpart to the dense paint runs. Marks arrive flat, in document order, with well-nested spans, so containment IS the hierarchy: an ancestor precedes and encloses its descendants, and an editor can rebuild the tree — or just walk a chain — without parent pointers on the wire. One channel feeds breadcrumbs, structure views, sticky context, and folding.
Paint
A full paint: per-line runs tiling each line exactly (text plus terminator bytes), tagged with the revision they describe.
PaintDelta
What one edit changed, and nothing else.
Run
One horizontal span of identically-painted bytes. Four bytes, by design: a dense 200-column line is a handful of cache lines, and a 10k-line buffer’s whole paint fits in ~KBs.

Constants§

MOD_DEF
This run’s bytes are a definition’s name.
MOD_FOREIGN
The reference resolves into ANOTHER file.
MOD_PUBLIC
The definition is visible outside its own module or file — whatever the language calls that (pub, export, public).
MOD_REF
A reference that RESOLVES (navigation will land somewhere).
MOD_TYPED
A type is known for this name. What counts as a type is the engine’s business; this bit only says one is available.
MOD_UNRESOLVED
A reference that does not resolve — including “exists but is not exported” and broken qualified paths (the squiggle substrate).
STYLE_NONE
style value for bytes with no declared class (trivia, plain).

Traits§

Limner
One who limns: the thing that draws a document’s linework. An intelligence engine implements this; an editor widget holds one and stays ignorant of everything behind it.

Functions§

decode_lines
encode_lines
[rev u64][n u32] then per line [line u32][nruns u32][runs…], each run [len u16][style u8][mods u8], all little-endian.