@adecore/editor-react 0.43.0 → 0.44.1

package/src/postfix.ts

@@ -0,0 +1,224 @@
+import type { EditorPosition, EditorPostfixOperand, EditorRange } from '@adecore/editor';
+import type { CompletionItem } from '@adecore/lsp';
+import type { LocalCompletionItem } from './completion.ts';
+import { isIdentifierCharacter } from './completion-model.ts';
+import { comparePositions } from './diagnostics-model.ts';
+import type { EditorLanguage } from './editor-language.ts';
+import { lineTextOf, textBeforeOf } from './line-text.ts';
+import type { PickRow } from './popups.ts';
+import { bodyWithIndentUnit, dedentLines, indentUnitOf, insertSnippet } from './snippet-insert.ts';
+import { compileSnippet } from './snippet.ts';
+import { SNIPPET_KIND, sortAfterServer, templateContextAt } from './template-context.ts';
+import type { PostfixTemplate } from './templates.ts';
+
+const MAX_ROW_LENGTH = 80;
+
+/* The postfix templates that apply to the expressions before one dot. */
+interface Candidates {
+    readonly dot: EditorPosition;
+    readonly operands: readonly EditorPostfixOperand[];
+    readonly templates: readonly PostfixTemplate[];
+}
+
+/* A key Tab can expand, starting at the dot that leads it. */
+interface PostfixKey {
+    readonly start: EditorPosition;
+    expand(): boolean;
+}
+
+/* The identifier characters after the last dot of `before`, and where that dot is; null when no dot leads them. */
+function typedKey(before: string): { readonly key: string; readonly dot: number } | null {
+    let index = before.length;
+
+    while (index > 0 && isIdentifierCharacter(before[index - 1]!)) {
+        index--;
+    }
+
+    return index > 0 && before[index - 1] === '.' ? { key: before.slice(index), dot: index - 1 } : null;
+}
+
+/* One line of a chooser row: whitespace collapsed and cut short. */
+function rowLabel(text: string): string {
+    const line = text.replace(/\s+/g, ' ').trim();
+
+    return line.length > MAX_ROW_LENGTH ? `${line.slice(0, MAX_ROW_LENGTH - 1)}…` : line;
+}
+
+/*
+ * Postfix completion: a dot and a key after an expression, and Tab or an accepted row wraps the expression in a
+ * template. The registry holds the templates and `TemplatesFeature` decides whether Tab is ours or a live template's.
+ */
+export class PostfixFeature {
+    private readonly language: EditorLanguage;
+
+    constructor(language: EditorLanguage) {
+        this.language = language;
+    }
+
+    /* The key before the caret that a template of the registry applies to; null where Tab has no postfix template to expand. */
+    key(): PostfixKey | null {
+        const { editor, project } = this.language;
+
+        if (!project.templates.settings.postfix) {
+            return null;
+        }
+
+        const caret = editor.getCaret();
+        const typed = typedKey(textBeforeOf(editor, caret));
+
+        if (typed === null || typed.key === '') {
+            return null;
+        }
+
+        const candidates = this.candidates({ line: caret.line, character: typed.dot }, (template) => template.key === typed.key);
+
+        if (candidates === null) {
+            return null;
+        }
+
+        return { start: candidates.dot, expand: () => this.expandKey(candidates, caret) };
+    }
+
+    /* The rows of the suggestion list after a dot, for the templates whose key the typed characters can lead to. */
+    rows(position: EditorPosition): readonly LocalCompletionItem[] {
+        const { editor, project } = this.language;
+        const { settings } = project.templates;
+        const selections = editor.getSelections();
+
+        if (!settings.postfix || !settings.postfixInCompletion || selections.length !== 1 || comparePositions(selections[0]!.start, selections[0]!.end) !== 0) {
+            return [];
+        }
+
+        const typed = typedKey(textBeforeOf(editor, position));
+
+        if (typed === null) {
+            return [];
+        }
+
+        const candidates = this.candidates({ line: position.line, character: typed.dot }, (template) => template.key.startsWith(typed.key));
+
+        if (candidates === null) {
+            return [];
+        }
+
+        const range = { start: { line: position.line, character: typed.dot + 1 }, end: position };
+
+        return candidates.templates.map((template) => this.row(template, candidates, range, sortAfterServer(template.key)));
+    }
+
+    private row(template: PostfixTemplate, candidates: Candidates, range: EditorRange, sortText: string): LocalCompletionItem {
+        const item: CompletionItem = {
+            label: template.key,
+            kind: SNIPPET_KIND,
+            detail: template.example,
+            documentation: template.description,
+            filterText: template.key,
+            sortText,
+            textEdit: { range, newText: template.key }
+        };
+
+        return { item, accept: () => this.expand(template, candidates, this.language.editor.getCaret()) };
+    }
+
+    /* The templates `matches` lets through that apply to the expressions before `dot`; null when none does. */
+    private candidates(dot: EditorPosition, matches: (template: PostfixTemplate) => boolean): Candidates | null {
+        const { editor, project } = this.language;
+        const operands = editor.postfixOperands?.(dot) ?? [];
+
+        if (operands.length === 0) {
+            return null;
+        }
+
+        const context = templateContextAt(this.language, dot);
+
+        if (context.place !== 'code') {
+            return null;
+        }
+
+        const widest = operands.at(-1)!;
+
+        const templates = project.templates.postfix.filter(
+            (template) =>
+                matches(template) &&
+                template.languages.some((family) => context.families.includes(family)) &&
+                (template.expression !== 'statement' || widest.statement)
+        );
+
+        return templates.length === 0 ? null : { dot, operands, templates };
+    }
+
+    /* Expands the one template of a key, or lists them when several share it. */
+    private expandKey(candidates: Candidates, caret: EditorPosition): boolean {
+        if (candidates.templates.length === 1) {
+            this.expand(candidates.templates[0]!, candidates, caret);
+
+            return true;
+        }
+
+        const start = { line: candidates.dot.line, character: candidates.dot.character + 1 };
+
+        this.language.completion.showItems(
+            candidates.templates.map((template) => this.row(template, candidates, { start, end: caret }, template.id)),
+            start
+        );
+
+        return true;
+    }
+
+    /* Wraps the widest expression for a statement, the only one there is, or the one a person picks from the expressions. */
+    private expand(template: PostfixTemplate, candidates: Candidates, caret: EditorPosition): void {
+        const { operands } = candidates;
+
+        if (template.expression === 'statement' || operands.length === 1) {
+            void this.run(template, template.expression === 'statement' ? operands.at(-1)! : operands[0]!, caret);
+
+            return;
+        }
+
+        const { editor, completion, pick, project } = this.language;
+        const rows = operands.map((operand, index): PickRow => ({ id: String(index), label: rowLabel(editor.textInRange(operand.range)), detail: '' }));
+
+        completion.close();
+
+        pick.open({
+            anchor: caret,
+            title: project.i18n.t('editor:language.postfix.expressions'),
+            groups: [{ title: null, rows }],
+            accept: (id) => void this.run(template, operands[Number(id)]!, caret),
+            preview: (id) => Promise.resolve({ removed: [], added: this.rendered(template, operands[Number(id)]!).split('\n'), note: null, kind: 'text' })
+        });
+    }
+
+    private run(template: PostfixTemplate, operand: EditorPostfixOperand, caret: EditorPosition): Promise<boolean> {
+        const { editor } = this.language;
+        const expression = this.expressionOf(operand);
+
+        return insertSnippet(
+            this.language,
+            bodyWithIndentUnit(template.body, indentUnitOf(editor)),
+            [{ range: { start: operand.range.start, end: caret } }],
+            (name) => (name === 'EXPR' ? expression : undefined)
+        );
+    }
+
+    /* What the template would put in place of the expression, tab stops at their placeholders. */
+    private rendered(template: PostfixTemplate, operand: EditorPostfixOperand): string {
+        const expression = this.expressionOf(operand);
+
+        return compileSnippet(bodyWithIndentUnit(template.body, indentUnitOf(this.language.editor))).render(
+            (name) => (name === 'EXPR' ? expression : undefined),
+            undefined,
+            {
+                indentVariables: true
+            }
+        ).text;
+    }
+
+    /* The text of an expression, with the indentation of its first line taken off the lines after it. */
+    private expressionOf(operand: EditorPostfixOperand): string {
+        const { editor } = this.language;
+        const indent = /^[\t ]*/.exec(lineTextOf(editor, operand.range.start.line))![0];
+
+        return dedentLines(editor.textInRange(operand.range).trimEnd(), indent);
+    }
+}

package/src/project-language.ts

@@ -14,6 +14,7 @@ import {
 } from '@adecore/lsp';
 import type { Editor, EditorPosition } from '@adecore/editor';
 import { ClipboardHistory } from './clipboard-history.ts';
+import { TemplateRegistry } from './templates.ts';
 import { EditLocations } from './edit-locations.ts';
 import { NavigationHistory, type Place } from './navigation-history.ts';
 import { ProjectProblems, serviceProblems } from './project-problems.ts';
@@ -128,6 +129,7 @@ export class ProjectLanguage {
     readonly history = new NavigationHistory();
     readonly edits: EditLocations;
     readonly clipboard: ClipboardHistory;
+    readonly templates: TemplateRegistry;
     private readonly holders = new Map<string, Holder>();
     private readonly files: ProjectFiles | null;
 
@@ -150,6 +152,7 @@ export class ProjectLanguage {
         this.files = host.files ?? null;
         this.edits = new EditLocations(host.editHistoryLimit);
         this.clipboard = host.clipboard ?? new ClipboardHistory();
+        this.templates = host.templates ?? new TemplateRegistry();
         this.panelBodyHeight = host.panelBodyHeight ?? PANEL_BODY_HEIGHT;
         this.problems = new ProjectProblems(host.problemSource ?? serviceProblems(service, (uri) => this.pathOfLocation(uri) ?? uri));
         const shows = service.onShowDocument?.((params) => this.showDocument(params));

package/src/snippet-insert.ts

@@ -0,0 +1,258 @@
+import { SnippetTransformQueueError } from './snippet-transform-queue.ts';
+import type { Editor, EditorContentChange, EditorPosition, EditorRange } from '@adecore/editor';
+import { comparePositions, shiftPosition } from './diagnostics-model.ts';
+import type { EditorLanguage } from './editor-language.ts';
+import { lineTextOf, textBeforeOf } from './line-text.ts';
+import { wordRangeAt } from './rename-model.ts';
+import { jobTable } from './snippet-field-transforms.ts';
+import { indentSnippet } from './snippet-indent.ts';
+import { positionInInsertion } from './snippet-session.ts';
+import { SnippetTransformError } from './snippet-transform-client.ts';
+import { MAX_TRANSFORM_JOBS, MAX_TRANSFORM_WORK } from './snippet-transform-protocol.ts';
+import { compileSnippet, tabOrder, type ParsedSnippet, type SnippetTemplate } from './snippet.ts';
+import { createSnippetResolver } from './snippet-variables.ts';
+import { fileUriToPath } from '@adecore/lsp';
+
+/* The same limits as an inserted completion item. */
+const MAX_CHARACTERS = 2_000_000;
+const MAX_RANGES = 1_000;
+const TOAST_ID = 'language-completion';
+
+export interface SnippetPlacement {
+    readonly range: EditorRange;
+
+    /* The value of `TM_SELECTED_TEXT` at this placement; empty without it. */
+    readonly selectedText?: string;
+}
+
+class LimitError extends Error {}
+
+interface Draft {
+    readonly placement: SnippetPlacement;
+    readonly resolve: (name: string) => string | undefined;
+
+    /* As rendered, which is the text the variable transforms read. */
+    raw: ParsedSnippet;
+
+    /* Indented to the text before the placement. */
+    parsed: ParsedSnippet;
+}
+
+/* Each line's leading tabs become the editor's own indentation unit. */
+export function bodyWithIndentUnit(body: string, unit: string): string {
+    return unit === '\t' ? body : body.replace(/^\t+/gm, (tabs) => unit.repeat(tabs.length));
+}
+
+/* One level of the editor's indentation: spaces for a tab size, or a tab. */
+export function indentUnitOf(editor: Editor): string {
+    const { tabSize, insertSpaces } = editor.getIndentation();
+
+    return insertSpaces ? ' '.repeat(tabSize) : '\t';
+}
+
+/* The lines after the first without `base` in front of them, or without the shortest indentation among them. */
+export function dedentLines(text: string, base?: string): string {
+    const lines = text.split(/\r\n|\r|\n/).slice(1);
+    const indents = lines.filter((line) => line.trim() !== '').map((line) => /^[\t ]*/.exec(line)![0].length);
+    const removed = base?.length ?? (indents.length === 0 ? 0 : Math.min(...indents));
+
+    return removed === 0
+        ? text
+        : text.replace(
+              /(\r\n|\r|\n)([^\r\n]*)/g,
+              (_match, lineBreak: string, line: string) => lineBreak + line.slice(Math.min(removed, /^[\t ]*/.exec(line)![0].length))
+          );
+}
+
+function sizeOf(parsed: ParsedSnippet): number {
+    return (
+        (parsed.transforms?.length ?? 0) +
+        (parsed.fields?.reduce((count, field) => count + field.ranges.length + (field.linked?.length ?? 0), 1) ?? parsed.stops.length)
+    );
+}
+
+/*
+ * Inserts a snippet at every placement, the last of them the primary one, and starts a session on its tab stops. The
+ * variables are resolved for each placement (`extra` first, then the host's and the built-in ones), the lines are indented
+ * to the text before the placement, and a running session takes the insertion as a nested one. False when nothing was inserted.
+ */
+export async function insertSnippet(
+    language: EditorLanguage,
+    source: string,
+    placements: readonly SnippetPlacement[],
+    extra?: (name: string) => string | undefined
+): Promise<boolean> {
+    const { editor, project, uri, snippets } = language;
+
+    if (placements.length === 0 || editor.isReadOnly?.() === true) {
+        return false;
+    }
+
+    const template: SnippetTemplate = compileSnippet(source);
+    const now = new Date();
+    const token = snippets.token;
+    const continuing = snippets.isActive;
+    let stale = false;
+    const off = editor.onTextChange(() => {
+        stale = true;
+    });
+    const current = (): boolean => !stale && snippets.token === token;
+
+    try {
+        let characters = 0;
+        let ranges = 0;
+
+        const drafts = placements.map((placement, index): Draft => {
+            const line = lineTextOf(editor, placement.range.start.line);
+            const word = wordRangeAt(line, placement.range.start);
+
+            const resolver = createSnippetResolver(
+                {
+                    uri,
+                    languageId: language.languageId,
+                    position: placement.range.start,
+                    selection: placement.range,
+                    selectedText: placement.selectedText ?? '',
+                    currentLine: line,
+                    currentWord: word === null ? '' : editor.textInRange(word),
+                    cursorIndex: index,
+                    cursorCount: placements.length,
+                    folder: project.host.folder,
+                    path: fileUriToPath(uri) ?? project.host.pathOfUri?.(uri) ?? undefined
+                },
+                project.host.resolveSnippetVariable?.bind(project.host),
+                { now }
+            );
+
+            const resolve = (name: string): string | undefined => extra?.(name) ?? resolver(name);
+
+            const raw = template.render(resolve, undefined, { indentVariables: true });
+
+            return { placement, resolve, raw, parsed: indentSnippet(raw, textBeforeOf(editor, placement.range.start)) };
+        });
+
+        for (const { parsed } of drafts) {
+            characters += parsed.text.length;
+            ranges += sizeOf(parsed);
+
+            if (parsed.limited === true || characters > MAX_CHARACTERS || ranges > MAX_RANGES) {
+                throw new LimitError();
+            }
+        }
+
+        await transformVariables(language, template, drafts, current);
+
+        if (!current()) {
+            return false;
+        }
+
+        const changes = drafts.map((draft): EditorContentChange => ({ range: draft.placement.range, text: draft.parsed.text }));
+
+        if (changes.reduce((total, change) => total + change.text.length, 0) > MAX_CHARACTERS) {
+            throw new LimitError();
+        }
+
+        // Insertions before one another move it, so each start is mapped through the changes in front of it.
+        const starts = changes.map((change) =>
+            changes
+                .filter((other) => other !== change && comparePositions(other.range.end, change.range.start) <= 0)
+                .sort((left, right) => comparePositions(right.range.start, left.range.start))
+                .reduce((place, other) => shiftPosition(place, other), change.range.start)
+        );
+
+        if (!(continuing ? snippets.applyEdits(changes, token) : editor.applyEdits(changes))) {
+            return false;
+        }
+
+        off();
+        place(language, drafts, starts, continuing && snippets.isActive && snippets.token === token);
+        editor.focus();
+
+        return true;
+    } catch (error) {
+        if (error instanceof LimitError || (error instanceof SnippetTransformError && error.kind === 'range')) {
+            project.host.notify?.({ id: TOAST_ID, kind: 'error', title: project.i18n.t('editor:language.completion.tooLarge') });
+
+            return false;
+        }
+
+        if (error instanceof SnippetTransformQueueError) {
+            project.host.notify?.({ id: TOAST_ID, kind: 'error', title: project.i18n.t('editor:language.completion.transformBusy') });
+
+            return false;
+        }
+
+        if (error instanceof SnippetTransformError) {
+            project.host.notify?.({ id: TOAST_ID, kind: 'error', title: project.i18n.t('editor:language.completion.transformFailed') });
+
+            return false;
+        }
+
+        throw error;
+    } finally {
+        off();
+    }
+}
+
+/* Runs the transforms of variables through the worker, once for all placements, and renders them again with the answers. */
+async function transformVariables(language: EditorLanguage, template: SnippetTemplate, drafts: Draft[], current: () => boolean): Promise<void> {
+    const { editor, project, snippets } = language;
+    const { jobs, slotOf } = jobTable();
+    const slots = drafts.map((draft) =>
+        (draft.raw.transforms ?? []).map((range) => slotOf({ ...range.transform, value: draft.raw.text.slice(range.start, range.end) }))
+    );
+
+    if (jobs.length === 0 || project.host.snippetTransformWorker === undefined) {
+        return;
+    }
+
+    if (jobs.length > MAX_TRANSFORM_JOBS || jobs.reduce((sum, job) => sum + job.value.length, 0) > MAX_TRANSFORM_WORK) {
+        throw new LimitError();
+    }
+
+    const values = await snippets.transformVariables(jobs, current);
+
+    if (values === null || !current()) {
+        return;
+    }
+
+    drafts.forEach((draft, index) => {
+        const raw = template.render(
+            draft.resolve,
+            slots[index]!.map((slot) => values[slot]!),
+            { indentVariables: true }
+        );
+
+        const parsed = indentSnippet(raw, textBeforeOf(editor, draft.placement.range.start));
+
+        if (parsed.limited === true) {
+            throw new LimitError();
+        }
+
+        draft.raw = raw;
+        draft.parsed = parsed;
+    });
+}
+
+/* Starts the session on the tab stops, or puts the caret after the primary insertion when there are none. */
+function place(language: EditorLanguage, drafts: readonly Draft[], starts: readonly EditorPosition[], nested: boolean): void {
+    const { editor, snippets } = language;
+    const primary = drafts.at(-1)!.parsed;
+
+    if (primary.stops.length > 0) {
+        snippets.beginInstances(
+            drafts.map((draft, index) => ({ start: starts[index]!, text: draft.parsed.text, stops: tabOrder(draft.parsed), fields: draft.parsed.fields })),
+            { nested }
+        );
+
+        return;
+    }
+
+    editor.setSelections(
+        drafts.map((draft, index) => {
+            const end = positionInInsertion(starts[index]!, draft.parsed.text, draft.parsed.text.length);
+
+            return { start: end, end };
+        })
+    );
+}

package/src/snippet.ts

@@ -40,15 +40,21 @@ export interface ParsedSnippet {
 }
 
 type Node =
-    | { kind: 'text'; text: string; transform?: SnippetTransform }
+    // `indent` marks the value of a variable whose lines after the first take the indentation of the line it starts on.
+    | { kind: 'text'; text: string; transform?: SnippetTransform; indent?: true }
     | { kind: 'field'; index: number; body?: Node[]; choices?: string[]; transform?: SnippetTransform }
     | { kind: 'variable'; name: string; body?: Node[]; transform?: SnippetTransform };
 
 export type SnippetVariableResolver = (name: string) => string | undefined;
 
+export interface SnippetRenderOptions {
+    /* The way VS Code treats `TM_SELECTED_TEXT`: the lines of a value after its first take the leading whitespace of the output line the variable starts on. */
+    readonly indentVariables?: boolean;
+}
+
 export interface SnippetTemplate {
     readonly source: string;
-    render(resolve?: SnippetVariableResolver, variableTransforms?: readonly string[]): ParsedSnippet;
+    render(resolve?: SnippetVariableResolver, variableTransforms?: readonly string[], options?: SnippetRenderOptions): ParsedSnippet;
 }
 
 type FieldNode = Extract<Node, { kind: 'field' }>;
@@ -235,6 +241,13 @@ class SnippetParser {
     }
 }
 
+/* The lines of a value after its first, behind the whitespace the last line of `before` starts with; blank lines stay blank. */
+function indentLines(value: string, before: string): string {
+    const prefix = /^[\t ]*/.exec(before.slice(before.lastIndexOf('\n') + 1))![0];
+
+    return prefix === '' ? value : value.replace(/(\r\n|\r|\n)(?=[^\r\n])/g, `$1${prefix}`);
+}
+
 function renderSnippet(nodes: readonly Node[], variableTransforms?: readonly string[]): ParsedSnippet {
     const definitions = new Map<number, FieldNode>();
 
@@ -304,7 +317,8 @@ function renderSnippet(nodes: readonly Node[], variableTransforms?: readonly str
 
             if (node.kind === 'text') {
                 const start = text.length;
-                const value = node.transform === undefined || variableTransforms === undefined ? node.text : variableTransforms[transforms.length];
+                const given = node.transform === undefined || variableTransforms === undefined ? node.text : variableTransforms[transforms.length];
+                const value = node.indent === true && typeof given === 'string' ? indentLines(given, text) : given;
 
                 if (typeof value !== 'string') {
                     throw new RangeError('The variable transform count does not match the snippet.');
@@ -453,7 +467,7 @@ function variableIndices(nodes: readonly Node[]): ReadonlyMap<string, number> {
     );
 }
 
-function resolveVariables(nodes: readonly Node[], indices: ReadonlyMap<string, number>, resolve?: SnippetVariableResolver): Node[] {
+function resolveVariables(nodes: readonly Node[], indices: ReadonlyMap<string, number>, resolve?: SnippetVariableResolver, indentVariables = false): Node[] {
     const unknown = new Map<string, { index: number; body: Node[]; defaulted: boolean; definition: Node }>();
     const values = new Map<string, string | undefined>();
 
@@ -513,7 +527,11 @@ function resolveVariables(nodes: readonly Node[], indices: ReadonlyMap<string, n
                     return [{ kind: 'text', text: value ?? '', transform: node.transform }];
                 }
 
-                return value !== undefined && value !== '' ? [{ kind: 'text', text: value }] : normalize(node.body ?? [], visiting, depth + 1);
+                if (value !== undefined && value !== '') {
+                    return [{ kind: 'text', text: value, ...(indentVariables ? { indent: true as const } : {}) }];
+                }
+
+                return normalize(node.body ?? [], visiting, depth + 1);
             }
 
             if (node.kind === 'field') {
@@ -565,13 +583,13 @@ export function compileSnippet(source: string): SnippetTemplate {
 
     return {
         source,
-        render: (resolve, variableTransforms) => {
+        render: (resolve, variableTransforms, options) => {
             if (nodes === null) {
                 return { text: source, stops: [], limited: true };
             }
 
             try {
-                return renderSnippet(resolveVariables(nodes, indices, resolve), variableTransforms);
+                return renderSnippet(resolveVariables(nodes, indices, resolve, options?.indentVariables === true), variableTransforms);
             } catch (error) {
                 if (!(error instanceof SnippetLimitError)) {
                     throw error;
@@ -615,3 +633,60 @@ export function tabOrder(parsed: ParsedSnippet): SnippetStop[] {
 
     return [...visited, first.get(0) ?? { index: 0, start: parsed.text.length, end: parsed.text.length }];
 }
+
+/* The names of the variables a snippet uses, the editable ones that are no built-in too. A source that does not parse names none. */
+export function snippetVariables(source: string): ReadonlySet<string> {
+    const names = new Set<string>();
+
+    const scan = (nodes: readonly Node[]): void => {
+        for (const node of nodes) {
+            if (node.kind === 'variable') {
+                names.add(node.name);
+            }
+
+            if (node.kind !== 'text' && node.body !== undefined) {
+                scan(node.body);
+            }
+        }
+    };
+
+    if (source.length > MAX_SNIPPET_TEXT) {
+        return names;
+    }
+
+    try {
+        scan(new SnippetParser(source).parse());
+    } catch {
+        return new Set();
+    }
+
+    return names;
+}
+
+/* Why a snippet cannot be used, in English for a host to show, or null: it does not parse, or it is over the limits an insertion keeps. */
+export function checkSnippet(source: string): string | null {
+    if (source.length > MAX_SNIPPET_TEXT) {
+        return `The text is longer than ${MAX_SNIPPET_TEXT} characters.`;
+    }
+
+    try {
+        new SnippetParser(source).parse();
+    } catch (error) {
+        if (error instanceof MalformedSnippetError) {
+            return 'A transform in the text is not valid.';
+        }
+
+        if (error instanceof SnippetLimitError) {
+            return 'The text has too many parts or is nested too deeply.';
+        }
+
+        throw error;
+    }
+
+    return compileSnippet(source).render().limited === true ? 'The text expands to more than a snippet can hold.' : null;
+}
+
+/* Escapes `\`, `$` and `}`, so the text reads back as itself in a snippet. */
+export function escapeSnippetText(text: string): string {
+    return text.replace(/[\\$}]/g, '\\$&');
+}