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:
styleis the lexical class (wave 0 — available synchronously with a keystroke, from the damaged lines only), andmodscarries 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
PaintDeltanames 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 — andHints 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§
- Fact
Card - 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:
textrendered at(line, col)— e.g. a: Numtype hint after a definition’s name. - Line
Edit - Replace lines
[start, end)withlines(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.
- Paint
Delta - 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 stylevalue 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.