Lutra/ui/src/components/editor/engineText.ts
danny 6c75c08d70 M2.2: PHP highlighting, syntax colour tokens and editor.reveal
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 12:17:17 +02:00

236 lines
7.7 KiB
TypeScript

/**
* Mapping between engine buffer text and CodeMirror documents.
*
* The engine keeps a file's text as it is on disk, line breaks included, and
* counts offsets in UTF-16 code units of that text. CodeMirror splits the
* text into lines and counts every line break as one position. Positions
* therefore differ by one for every `\r\n` before them. {@link EngineText}
* remembers which breaks are `\r\n` and converts positions and change sets
* into engine edits. Text without `\r\n` needs no bookkeeping.
*/
import { ChangeSet, Text } from "@codemirror/state";
/** Line ending of a buffer as the engine names it. */
export type LineEndingName = "lf" | "crlf" | "cr";
/** One change of a `buffer.edit` call, in engine UTF-16 offsets. */
export interface EngineEdit {
/** Start offset in the text at the base version. */
from: number;
/** End offset (exclusive) in the text at the base version. */
to: number;
/** Inserted text, with the buffer's line ending. */
insert: string;
}
/** Line breaks the engine and CodeMirror both recognise. */
const LINE_BREAK = /\r\n|\r|\n/g;
/**
* The line break string for a line ending name.
*
* @param name - the engine's name; anything unknown counts as `lf`.
*/
export function separatorOf(name: string): string {
return name === "crlf" ? "\r\n" : name === "cr" ? "\r" : "\n";
}
/**
* A CodeMirror document together with the kind of each of its line breaks
* in the engine text.
*/
export class EngineText {
/** The document as CodeMirror sees it. */
readonly doc: Text;
/**
* For each line break (index `i` follows line `i`, 0-based) whether it is
* `\r\n` in the engine text; null when there is none.
*/
private readonly crlf: readonly boolean[] | null;
/** Number of `\r\n` breaks before each line; built on first use. */
private prefix: Uint32Array | null = null;
/**
* @param doc - the CodeMirror document.
* @param crlf - break kinds, see {@link EngineText.crlf}.
*/
private constructor(doc: Text, crlf: readonly boolean[] | null) {
this.doc = doc;
this.crlf = crlf;
}
/**
* Builds the mapping for text received from the engine.
*
* @param text - the engine's buffer text.
*/
static fromEngine(text: string): EngineText {
const lines: string[] = [];
const crlf: boolean[] = [];
let any = false;
let start = 0;
LINE_BREAK.lastIndex = 0;
for (let m = LINE_BREAK.exec(text); m !== null; m = LINE_BREAK.exec(text)) {
lines.push(text.slice(start, m.index));
const isCrlf = m[0] === "\r\n";
crlf.push(isCrlf);
any ||= isCrlf;
start = m.index + m[0].length;
}
lines.push(text.slice(start));
return new EngineText(Text.of(lines), any ? crlf : null);
}
/**
* The engine text this mapping stands for, for checks and tests. Only
* `\r\n` breaks are remembered, so a lone `\r` comes back as `\n` (both
* are one UTF-16 unit, so offsets are unaffected).
*/
engineString(): string {
if (this.crlf === null) {
return this.doc.sliceString(0);
}
const parts: string[] = [];
let line = 0;
for (const text of this.doc.iterLines()) {
parts.push(text);
if (line < this.crlf.length) {
parts.push(this.crlf[line] === true ? "\r\n" : "\n");
}
line += 1;
}
return parts.join("");
}
/**
* Converts a CodeMirror position into an engine offset.
*
* @param pos - a position in {@link doc}, clamped to its length.
* @returns the UTF-16 offset in the engine text.
*/
toEngine(pos: number): number {
const clamped = Math.max(0, Math.min(pos, this.doc.length));
if (this.crlf === null) {
return clamped;
}
const line = this.doc.lineAt(clamped).number - 1;
return clamped + (this.prefixTable()[line] ?? 0);
}
/** The table of `\r\n` counts before each line. */
private prefixTable(): Uint32Array {
if (this.prefix === null) {
const crlf = this.crlf ?? [];
const table = new Uint32Array(crlf.length + 1);
for (let i = 0; i < crlf.length; i += 1) {
table[i + 1] = (table[i] ?? 0) + (crlf[i] === true ? 1 : 0);
}
this.prefix = table;
}
return this.prefix;
}
/**
* Translates a change set on {@link doc} into engine edits.
*
* @param changes - changes whose start document is {@link doc}.
* @param separator - line break for inserted text (the buffer's ending).
*/
edits(changes: ChangeSet, separator: string): EngineEdit[] {
const out: EngineEdit[] = [];
changes.iterChanges((fromA, toA, _fromB, _toB, inserted) => {
out.push({
from: this.toEngine(fromA),
to: this.toEngine(toA),
insert: inserted.sliceString(0, inserted.length, separator),
});
});
return out;
}
/**
* The mapping after a change set, assuming the engine applied the same
* changes with inserted line breaks written as `separator`.
*
* @param changes - changes whose start document is {@link doc}.
* @param separator - line break used for inserted text.
*/
apply(changes: ChangeSet, separator: string): EngineText {
const doc = changes.apply(this.doc);
const newCrlf = separator === "\r\n";
if (this.crlf === null && !newCrlf) {
return new EngineText(doc, null);
}
const old = this.crlf;
const out: boolean[] = [];
let cursor = 0;
changes.iterChanges((fromA, toA, _fromB, _toB, inserted) => {
const fromLine = this.doc.lineAt(fromA).number - 1;
const toLine = this.doc.lineAt(toA).number - 1;
for (let i = cursor; i < fromLine; i += 1) {
out.push(old?.[i] === true);
}
for (let i = 1; i < inserted.lines; i += 1) {
out.push(newCrlf);
}
cursor = Math.max(cursor, toLine);
});
for (let i = cursor; i < this.doc.lines - 1; i += 1) {
out.push(old?.[i] === true);
}
return new EngineText(doc, out.includes(true) ? out : null);
}
}
/**
* A minimal change set turning `from` into `to`: one replacement between
* their common prefix and suffix.
*
* @param from - the old document.
* @param to - the new document.
*/
export function diffDocs(from: Text, to: Text): ChangeSet {
const a = from.sliceString(0);
const b = to.sliceString(0);
if (a === b) {
return ChangeSet.empty(a.length);
}
const max = Math.min(a.length, b.length);
let prefix = 0;
while (prefix < max && a.charCodeAt(prefix) === b.charCodeAt(prefix)) {
prefix += 1;
}
let suffix = 0;
while (
suffix < max - prefix &&
a.charCodeAt(a.length - 1 - suffix) === b.charCodeAt(b.length - 1 - suffix)
) {
suffix += 1;
}
return ChangeSet.of(
[{ from: prefix, to: a.length - suffix, insert: b.slice(prefix, b.length - suffix) }],
a.length,
);
}
/**
* The CodeMirror position of an engine `{line, column}` position.
*
* Engine lines are split at the same breaks CodeMirror recognises, and a
* `\r\n` counts as one break on both sides, so line numbers carry over
* unchanged; the column counts UTF-16 code units inside the line, which is
* the same in both. A line past the end selects the last line, a column past
* the line's end (into a `\r\n`, say) its end, and negative or fractional
* values are clamped and truncated (non-finite ones count as 0). Converting the result back with
* {@link EngineText.toEngine} yields the engine offset.
*
* @param doc - the CodeMirror document.
* @param line - 0-based line.
* @param column - 0-based column in UTF-16 code units.
* @returns the position in `doc`.
*/
export function positionOf(doc: Text, line: number, column: number): number {
const whole = (n: number): number => (Number.isFinite(n) ? Math.max(Math.trunc(n), 0) : 0);
const target = doc.line(Math.min(whole(line) + 1, doc.lines));
return target.from + Math.min(whole(column), target.length);
}