/** * 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); }