soml-lang 0.0.1 → 0.0.3

package/distribution/error.d.ts

@@ -0,0 +1,49 @@
+/**
+Thrown when the input is not a valid document, by `parse()`, `parseTree()`, `format()`, and `edit()`. Extends `SyntaxError`.
+
+The `message` includes the position and a code frame. Use `reason` for the message alone.
+
+@example
+```
+import {parse, ParseError} from 'soml-lang';
+
+try {
+    parse('name: api-gateway');
+} catch (error) {
+    if (error instanceof ParseError) {
+        console.log(error.message);
+    }
+}
+// Unexpected "api-gateway". A string value must be quoted, as in 'api-gateway' at line 1, column 7
+//
+// > 1 | name: api-gateway
+//     |       ^
+```
+*/
+export declare class ParseError extends SyntaxError {
+    readonly name = "ParseError";
+    /**
+    What is wrong, without the position.
+    */
+    readonly reason: string;
+    /**
+    The 1-based line of the error.
+    */
+    readonly line: number;
+    /**
+    The 1-based column of the error, counted in Unicode code points.
+    */
+    readonly column: number;
+    /**
+    The 0-based UTF-16 index of the error in the decoded text.
+    */
+    readonly offset: number;
+    /**
+    Up to three lines ending at the error, with a caret under the position. A long line is clipped around the position.
+    */
+    readonly codeFrame: string;
+    /**
+    Only the parser creates a `ParseError`.
+    */
+    private constructor();
+}

package/distribution/error.js

@@ -0,0 +1,156 @@
+import { findLineEnd } from "./shared.js";
+const CONTEXT_LINES = 2;
+const MAX_LINE_WIDTH = 100;
+// With the `v` flag, a surrogate in the class matches only when it is unpaired.
+const UNPRINTABLE = /[\p{Bidi_Control}\u{D800}-\u{DFFF}[\p{Control}--\t]]/gv;
+/**
+Thrown when the input is not a valid document, by `parse()`, `parseTree()`, `format()`, and `edit()`. Extends `SyntaxError`.
+
+The `message` includes the position and a code frame. Use `reason` for the message alone.
+
+@example
+```
+import {parse, ParseError} from 'soml-lang';
+
+try {
+    parse('name: api-gateway');
+} catch (error) {
+    if (error instanceof ParseError) {
+        console.log(error.message);
+    }
+}
+// Unexpected "api-gateway". A string value must be quoted, as in 'api-gateway' at line 1, column 7
+//
+// > 1 | name: api-gateway
+//     |       ^
+```
+*/
+export class ParseError extends SyntaxError {
+    /**
+    For the parser, which cannot call the private constructor.
+
+    @internal
+    */
+    static create(reason, source, offset) {
+        return new ParseError(reason, source, offset);
+    }
+    name = 'ParseError';
+    /**
+    What is wrong, without the position.
+    */
+    reason;
+    /**
+    The 1-based line of the error.
+    */
+    line;
+    /**
+    The 1-based column of the error, counted in Unicode code points.
+    */
+    column;
+    /**
+    The 0-based UTF-16 index of the error in the decoded text.
+    */
+    offset;
+    /**
+    Up to three lines ending at the error, with a caret under the position. A long line is clipped around the position.
+    */
+    codeFrame;
+    /**
+    Only the parser creates a `ParseError`.
+    */
+    constructor(reason, source, offset) {
+        const sanitizedReason = sanitize(reason);
+        const { line, column } = locate(source, offset);
+        const codeFrame = createCodeFrame(source, offset, line);
+        super(`${sanitizedReason} at line ${line}, column ${column}\n\n${codeFrame}`);
+        this.reason = sanitizedReason;
+        this.line = line;
+        this.column = column;
+        this.offset = offset;
+        this.codeFrame = codeFrame;
+    }
+}
+/*
+Line and column are 1-based, and the column counts code points, so an emoji is one column.
+*/
+function locate(source, offset) {
+    let line = 1;
+    let lineStart = 0;
+    for (let index = source.indexOf('\n'); index !== -1 && index < offset; index = source.indexOf('\n', index + 1)) {
+        line++;
+        lineStart = index + 1;
+    }
+    return { line, column: countCodePoints(source.slice(lineStart, offset)) + 1 };
+}
+function countCodePoints(string) {
+    let count = 0;
+    for (let index = 0; index < string.length; index++) {
+        const code = string.charCodeAt(index);
+        // A high surrogate followed by a low one is one code point.
+        if (code >= 0xD8_00 && code <= 0xDB_FF) {
+            const next = string.charCodeAt(index + 1);
+            if (next >= 0xDC_00 && next <= 0xDF_FF) {
+                index++;
+            }
+        }
+        count++;
+    }
+    return count;
+}
+function createCodeFrame(source, offset, line) {
+    // The error line and up to two lines before it, found by scanning back from the error, so that an error late in a long document does not split the whole document.
+    const lineStarts = [offset === 0 ? 0 : source.lastIndexOf('\n', offset - 1) + 1];
+    while (lineStarts.length <= CONTEXT_LINES && lineStarts[0] > 0) {
+        const searchFrom = lineStarts[0] - 2;
+        lineStarts.unshift(searchFrom < 0 ? 0 : source.lastIndexOf('\n', searchFrom) + 1);
+    }
+    const firstLine = line - lineStarts.length + 1;
+    const gutterWidth = String(line).length;
+    const output = [];
+    for (const [index, lineStart] of lineStarts.entries()) {
+        const number = firstLine + index;
+        const isErrorLine = number === line;
+        const lineText = sanitize(source.slice(lineStart, findLineEnd(source, lineStart)));
+        const { text, pointerOffset } = clip(lineText, isErrorLine ? offset - lineStart : 0);
+        const gutter = `${isErrorLine ? '>' : ' '} ${String(number).padStart(gutterWidth)} |`;
+        output.push(text === '' ? gutter : `${gutter} ${text}`);
+        if (!isErrorLine) {
+            continue;
+        }
+        // Keep the tabs from the line, so the caret lines up whatever the tab width is.
+        const padding = text.slice(0, pointerOffset).replaceAll(/[^\t]/gv, ' ');
+        output.push(`  ${' '.repeat(gutterWidth)} | ${padding}^`);
+    }
+    return output.join('\n');
+}
+/*
+The rejected text can hold characters that a terminal acts on rather than shows: control characters such as an escape or a carriage return, bidirectional controls, and lone surrogates. Each becomes U+FFFD, which is also one code unit, so the caret still lines up. Tabs are kept.
+*/
+function sanitize(text) {
+    return text.replaceAll(UNPRINTABLE, '\u{FFFD}');
+}
+/*
+A long line, such as a minified document, is cut to a window around the pointer. The cut never splits a surrogate pair.
+*/
+function clip(text, pointerOffset) {
+    if (text.length <= MAX_LINE_WIDTH) {
+        return { text, pointerOffset };
+    }
+    let start = Math.max(0, Math.min(pointerOffset - (MAX_LINE_WIDTH / 2), text.length - MAX_LINE_WIDTH));
+    let end = start + MAX_LINE_WIDTH;
+    if (isLowSurrogate(text.charCodeAt(start))) {
+        start++;
+    }
+    if (isLowSurrogate(text.charCodeAt(end))) {
+        end--;
+    }
+    const prefix = start > 0 ? '…' : '';
+    const suffix = end < text.length ? '…' : '';
+    return {
+        text: `${prefix}${text.slice(start, end)}${suffix}`,
+        pointerOffset: pointerOffset - start + prefix.length,
+    };
+}
+function isLowSurrogate(code) {
+    return code >= 0xDC_00 && code <= 0xDF_FF;
+}

package/distribution/format.d.ts

@@ -0,0 +1,62 @@
+/**
+Format a document. Returns the document with its layout normalized, ending with one line feed.
+
+The layout follows the formatter in the specification: one tab per level, every member and item on its own line with no commas, and no trailing whitespace or runs of blank lines. An object or an array whose brackets are on one line stays on one line, as in `ports: [80, 443]`, with a comma and a space between its members or items. To give a one-line container one member or item per line, put a line break anywhere inside it. Comments, member order, dotted keys, block strings, and the spelling of every value stay as they are, so the value never changes. The one change inside a block comment is the same layout rule: trailing whitespace is removed, and runs of blank lines collapse to one.
+
+In detail, as the specification states:
+
+- A block comment that a value follows on the same line, as in `1, /* note *\/ 2`, stays in front of that value when each item goes on its own line.
+- One space follows each `:`, as in canonical form.
+- A value on the line after its `key:` moves up to that line, unless a comment comes between them. Then it stays on its own line, one level deeper than the key, and the blank lines between them are removed.
+- A block string begins on the line after its key, and its delimiters and content have the indentation of that line. Its lines are not otherwise changed.
+- There are no blank lines at the start of the file or directly inside brackets.
+
+@param text - The document.
+@returns The formatted document, ending with one line feed.
+@throws {ParseError} When the document is not valid, the same as `parse()`.
+@throws {TypeError} When `text` is not a string.
+
+@example
+```
+import {format} from 'soml-lang';
+
+format('pool: {min: 2,   max: 16,} # Connections');
+//=> 'pool: {min: 2, max: 16} # Connections\n'
+
+format('pool: {\nmin: 2, max: 16}');
+//=> 'pool: {\n\tmin: 2\n\tmax: 16\n}\n'
+```
+*/
+export declare function format(text: string): string;
+/**
+A change to a document: a range of its text, and the text that replaces it.
+*/
+export type FormatEdit = {
+    /**
+    The start and end of the replaced text, as UTF-16 offsets into the document. They are equal when the edit only inserts.
+    */
+    readonly range: readonly [start: number, end: number];
+    /**
+    The text that replaces the range. It is empty when the edit only removes.
+    */
+    readonly text: string;
+};
+/**
+The changes that `format()` makes to a document, as edits of its text. For an editor or a linter, which shows or applies each change where it is, rather than replacing the whole document.
+
+The edits are sorted, do not overlap, and change only spaces, tabs, line feeds, and commas, as `format()` does. Each one is as small as possible, so it leaves out the characters at its ends that stay the same. Applying all of them gives the same text as `format()`, and a document that is already formatted gives no edits.
+
+@param text - The document.
+@returns The edits, in the order of their ranges.
+@throws {ParseError} When the document is not valid, the same as `parse()`.
+@throws {TypeError} When `text` is not a string.
+
+@example
+```
+import {formatEdits} from 'soml-lang';
+
+formatEdits('a: [1,\n2]\n');
+//=> [{range: [4, 4], text: '\n\t'}, {range: [5, 7], text: '\n\t'}, {range: [8, 8], text: '\n'}]
+```
+*/
+export declare function formatEdits(text: string): FormatEdit[];

package/distribution/format.js

@@ -0,0 +1,403 @@
+import { parseTree, } from "./tree.js";
+import { ASTERISK, isBlankLine, COMMA, HASH, SLASH, findLineEnd, isSpace, skipSpaces, skipSpacesBack, LF, } from "./shared.js";
+const INDENT = '\t';
+/**
+Format a document. Returns the document with its layout normalized, ending with one line feed.
+
+The layout follows the formatter in the specification: one tab per level, every member and item on its own line with no commas, and no trailing whitespace or runs of blank lines. An object or an array whose brackets are on one line stays on one line, as in `ports: [80, 443]`, with a comma and a space between its members or items. To give a one-line container one member or item per line, put a line break anywhere inside it. Comments, member order, dotted keys, block strings, and the spelling of every value stay as they are, so the value never changes. The one change inside a block comment is the same layout rule: trailing whitespace is removed, and runs of blank lines collapse to one.
+
+In detail, as the specification states:
+
+- A block comment that a value follows on the same line, as in `1, /* note *\/ 2`, stays in front of that value when each item goes on its own line.
+- One space follows each `:`, as in canonical form.
+- A value on the line after its `key:` moves up to that line, unless a comment comes between them. Then it stays on its own line, one level deeper than the key, and the blank lines between them are removed.
+- A block string begins on the line after its key, and its delimiters and content have the indentation of that line. Its lines are not otherwise changed.
+- There are no blank lines at the start of the file or directly inside brackets.
+
+@param text - The document.
+@returns The formatted document, ending with one line feed.
+@throws {ParseError} When the document is not valid, the same as `parse()`.
+@throws {TypeError} When `text` is not a string.
+
+@example
+```
+import {format} from 'soml-lang';
+
+format('pool: {min: 2,   max: 16,} # Connections');
+//=> 'pool: {min: 2, max: 16} # Connections\n'
+
+format('pool: {\nmin: 2, max: 16}');
+//=> 'pool: {\n\tmin: 2\n\tmax: 16\n}\n'
+```
+*/
+export function format(text) {
+    return new Printer(text, parseTree(text)).print();
+}
+/**
+The changes that `format()` makes to a document, as edits of its text. For an editor or a linter, which shows or applies each change where it is, rather than replacing the whole document.
+
+The edits are sorted, do not overlap, and change only spaces, tabs, line feeds, and commas, as `format()` does. Each one is as small as possible, so it leaves out the characters at its ends that stay the same. Applying all of them gives the same text as `format()`, and a document that is already formatted gives no edits.
+
+@param text - The document.
+@returns The edits, in the order of their ranges.
+@throws {ParseError} When the document is not valid, the same as `parse()`.
+@throws {TypeError} When `text` is not a string.
+
+@example
+```
+import {formatEdits} from 'soml-lang';
+
+formatEdits('a: [1,\n2]\n');
+//=> [{range: [4, 4], text: '\n\t'}, {range: [5, 7], text: '\n\t'}, {range: [8, 8], text: '\n'}]
+```
+*/
+export function formatEdits(text) {
+    const formatted = format(text);
+    const edits = [];
+    let textIndex = 0;
+    let formattedIndex = 0;
+    // Without the characters that the formatter changes, the two texts are the same. So walking both at once, every run of those characters that differs is one edit, which takes linear time, where a general diff takes quadratic time on a document with many changes.
+    while (textIndex < text.length || formattedIndex < formatted.length) {
+        const textStart = textIndex;
+        const formattedStart = formattedIndex;
+        const textGapEnd = skipLayout(text, textIndex);
+        const formattedGapEnd = skipLayout(formatted, formattedIndex);
+        if (text.slice(textIndex, textGapEnd) !== formatted.slice(formattedIndex, formattedGapEnd)) {
+            edits.push(createEdit(text, textIndex, textGapEnd, formatted.slice(formattedIndex, formattedGapEnd)));
+        }
+        textIndex = textGapEnd;
+        formattedIndex = formattedGapEnd;
+        while (textIndex < text.length && !isLayout(text.charCodeAt(textIndex)) && text.charCodeAt(textIndex) === formatted.charCodeAt(formattedIndex)) {
+            textIndex++;
+            formattedIndex++;
+        }
+        // Both stop at a different character, or one at its end, only when the formatter changed something else, and then the walk would never end.
+        if (textIndex === textStart && formattedIndex === formattedStart) {
+            throw new Error(`The formatter changed more than the layout at offset ${textIndex}. This is a bug in soml-lang.`);
+        }
+    }
+    return edits;
+}
+/*
+The characters that the formatter changes.
+*/
+function isLayout(code) {
+    return isSpace(code) || code === LF || code === COMMA;
+}
+/*
+The end of the run of layout characters at `index`.
+*/
+function skipLayout(text, index) {
+    while (index < text.length && isLayout(text.charCodeAt(index))) {
+        index++;
+    }
+    return index;
+}
+/*
+The edit that replaces `text.slice(start, end)` with `replacement`, without the characters at its ends that stay the same, as in `, ` to `\n\t`.
+*/
+function createEdit(text, start, end, replacement) {
+    let prefixLength = 0;
+    while (start + prefixLength < end && prefixLength < replacement.length && text[start + prefixLength] === replacement[prefixLength]) {
+        prefixLength++;
+    }
+    let suffixLength = 0;
+    while (end - suffixLength > start + prefixLength && replacement.length - suffixLength > prefixLength && text[end - suffixLength - 1] === replacement[replacement.length - suffixLength - 1]) {
+        suffixLength++;
+    }
+    return {
+        range: [start + prefixLength, end - suffixLength],
+        text: replacement.slice(prefixLength, replacement.length - suffixLength),
+    };
+}
+class Printer {
+    #text;
+    #tree;
+    // Joined once at the end. Appending with `+=` builds a deep rope, and reading it one character at a time, as `formatEdits()` does, can take quadratic time once V8 deoptimizes the reader.
+    #output = [];
+    #commentIndex = 0;
+    constructor(text, tree) {
+        this.#text = text;
+        this.#tree = tree;
+    }
+    #write(text) {
+        this.#output.push(text);
+    }
+    /*
+    Starts a new line at `level`, with one blank line before it when the source had one.
+    */
+    #newLine(level, isBlank) {
+        if (this.#output.length === 0) {
+            return;
+        }
+        this.#write(`${isBlank ? '\n\n' : '\n'}${INDENT.repeat(level)}`);
+    }
+    #isSameLine(start, end) {
+        return !this.#text.slice(start, end).includes('\n');
+    }
+    /*
+    Whether a line between `start` and `end` holds only spaces and tabs, if anything.
+    */
+    #hasBlankLine(start, end) {
+        // A slice, so that the search for a line break stops at `end`.
+        const gap = this.#text.slice(start, end);
+        for (let index = gap.indexOf('\n'); index !== -1; index = gap.indexOf('\n', index + 1)) {
+            index = skipSpaces(gap, index + 1);
+            if (gap.charCodeAt(index) === LF) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /*
+    The next comment that ends at or before `end`, without consuming it.
+    */
+    #peekComment(end) {
+        const comment = this.#tree.comments[this.#commentIndex];
+        return comment !== undefined && comment.range[1] <= end ? comment : undefined;
+    }
+    #writeComment(comment) {
+        this.#commentIndex++;
+        if (comment.type === 'Line') {
+            this.#write(trimTrailingWhitespace(`#${comment.value}`));
+            return;
+        }
+        // The lines of a block comment keep their own indentation. Trailing whitespace is removed, and runs of blank lines collapse to one, as everywhere outside a block string.
+        const lines = `/*${comment.value}*/`.split('\n').map(line => trimTrailingWhitespace(line));
+        this.#write(lines.filter((line, index) => line !== '' || lines[index - 1] !== '').join('\n'));
+    }
+    /*
+    The offset of the `,` after an item in the source, or `undefined` when there is none.
+    */
+    #findComma(start, end) {
+        const text = this.#text;
+        // Between two items there is only whitespace, comments, and at most one comma.
+        for (let index = start; index < end; index++) {
+            const code = text.charCodeAt(index);
+            if (code === COMMA) {
+                return index;
+            }
+            if (code === HASH) {
+                index = findLineEnd(text, index);
+            }
+            else if (code === SLASH && text.charCodeAt(index + 1) === ASTERISK) {
+                index = text.indexOf('*/', index + 2) + 1;
+            }
+        }
+        return undefined;
+    }
+    /*
+    Writes `items` one per line at `level`, with the comments between them, from `start` to `end` in the source.
+
+    A comment on the line of the item before it, or of the opening bracket, stays at the end of that line. The exception is a block comment after the comma that the next item follows on the same line, as in `[1, /* note *\/ 2]`: it stays in front of that item. Every other comment starts a new line, and a comment or an item that follows a block comment on its line stays on that line.
+    */
+    #list(items, { start, end, level, isBracketed }) {
+        let previousEnd = start;
+        let itemEnd;
+        // Whether a comment may stay at the end of the line before it, which needs an item or an opening bracket there.
+        let canTrail = isBracketed;
+        let hasWritten = false;
+        let isOnSameLine = false;
+        for (const item of [...items, undefined]) {
+            const itemStart = item?.range[0] ?? end;
+            const comma = isBracketed ? this.#findComma(previousEnd, itemStart) : undefined;
+            // Found once per item rather than once per comment, which would be quadratic in the number of comments on one line.
+            const itemLineStart = item === undefined ? undefined : previousEnd + this.#text.slice(previousEnd, itemStart).lastIndexOf('\n') + 1;
+            for (let comment = this.#peekComment(itemStart); comment !== undefined; comment = this.#peekComment(itemStart)) {
+                const [commentStart, commentEnd] = comment.range;
+                const isTrailing = canTrail && !isOnSameLine && this.#isTrailing(comment, {
+                    previousEnd,
+                    itemEnd,
+                    itemLineStart,
+                    comma,
+                });
+                if (isTrailing || isOnSameLine) {
+                    this.#write(' ');
+                }
+                else {
+                    this.#newLine(level, hasWritten && this.#hasBlankLine(previousEnd, commentStart));
+                }
+                this.#writeComment(comment);
+                hasWritten ||= !isTrailing;
+                // A block comment that the next comment or item follows on the same line keeps it on that line.
+                const nextStart = this.#peekComment(itemStart)?.range[0] ?? itemStart;
+                isOnSameLine = comment.type === 'Block' && !isTrailing && this.#isSameLine(commentEnd, nextStart);
+                previousEnd = commentEnd;
+            }
+            if (item === undefined) {
+                return;
+            }
+            if (isOnSameLine) {
+                this.#write(' ');
+            }
+            else {
+                this.#newLine(level, hasWritten && this.#hasBlankLine(previousEnd, itemStart));
+            }
+            this.#item(item, level);
+            previousEnd = item.range[1];
+            itemEnd = previousEnd;
+            canTrail = true;
+            hasWritten = true;
+            isOnSameLine = false;
+        }
+    }
+    /*
+    Whether a comment stays at the end of the line before it. That line ends at the item before it, or at the comma after that item.
+    */
+    #isTrailing(comment, { previousEnd, itemEnd, itemLineStart, comma }) {
+        const [commentStart, commentEnd] = comment.range;
+        const isAfterComma = comma !== undefined && commentStart > comma;
+        // A block comment after the comma that the next item follows on the same line stays in front of that item. The comment ends on the item's line when it ends after the start of that line.
+        if (itemLineStart !== undefined && comment.type === 'Block' && (comma === undefined || isAfterComma) && commentEnd >= itemLineStart) {
+            return false;
+        }
+        // A comment after the comma ends the comma's line, which is later than the item's when a block comment that spans lines comes between them. The comma is removed, so the comment moves to the end of the item's line, which only holds when nothing came between them.
+        const lineEnd = isAfterComma && previousEnd === itemEnd ? comma + 1 : previousEnd;
+        return this.#isSameLine(lineEnd, commentStart);
+    }
+    /*
+    Writes a container that is on one line in the source on one line, with a comma and a space between its members or items and no trailing comma. Only a block comment can be inside it, and each one stays where it is among the items and commas.
+    */
+    #oneLine(items, { start, end, level }, opening, closing) {
+        this.#write(opening);
+        let previousEnd = start + 1;
+        let hasWrittenToken = false;
+        for (const item of [...items, undefined]) {
+            const itemStart = item?.range[0] ?? (end - 1);
+            // The comma after the last item is left out.
+            const comma = item === undefined ? undefined : this.#findComma(previousEnd, itemStart);
+            let hasWrittenComma = false;
+            for (let comment = this.#peekComment(itemStart); comment !== undefined; comment = this.#peekComment(itemStart)) {
+                if (!hasWrittenComma && comma !== undefined && comma < comment.range[0]) {
+                    this.#write(',');
+                    hasWrittenComma = true;
+                }
+                this.#write(hasWrittenToken ? ' ' : '');
+                this.#writeComment(comment);
+                hasWrittenToken = true;
+            }
+            if (item === undefined) {
+                break;
+            }
+            if (comma !== undefined && !hasWrittenComma) {
+                this.#write(', ');
+            }
+            else if (hasWrittenToken) {
+                this.#write(' ');
+            }
+            this.#item(item, level);
+            previousEnd = item.range[1];
+            hasWrittenToken = true;
+        }
+        this.#write(closing);
+    }
+    #item(item, level) {
+        if (item.type === 'Member') {
+            this.#member(item, level);
+        }
+        else {
+            this.#value(item, level);
+        }
+    }
+    #member(member, level) {
+        const { key, value } = member;
+        this.#write(`${this.#text.slice(...key.range)}:`);
+        const isBlockString = value.type === 'String' && value.block;
+        if (this.#peekComment(value.range[0]) === undefined) {
+            // A block string begins on the next line, one level deeper, so its delimiters and content line up.
+            if (isBlockString) {
+                this.#newLine(level + 1, false);
+                this.#value(value, level + 1);
+                return;
+            }
+            this.#write(' ');
+            this.#value(value, level);
+            return;
+        }
+        // With comments between the `:` and the value, the line breaks between them are kept, but not the blank lines, and a value on a new line is one level deeper.
+        let previousEnd = key.range[1] + 1;
+        let valueLevel = level;
+        for (let comment = this.#peekComment(value.range[0]); comment !== undefined; comment = this.#peekComment(value.range[0])) {
+            if (this.#writeSeparator(previousEnd, comment.range[0], level + 1)) {
+                valueLevel = level + 1;
+            }
+            this.#writeComment(comment);
+            previousEnd = comment.range[1];
+        }
+        if (isBlockString) {
+            this.#newLine(level + 1, false);
+            valueLevel = level + 1;
+        }
+        else if (this.#writeSeparator(previousEnd, value.range[0], level + 1)) {
+            valueLevel = level + 1;
+        }
+        this.#value(value, valueLevel);
+    }
+    /*
+    A space when `end` is on the line of `start` in the source, and otherwise a new line at `level`. Returns whether it started a new line.
+    */
+    #writeSeparator(start, end, level) {
+        if (this.#isSameLine(start, end)) {
+            this.#write(' ');
+            return false;
+        }
+        this.#newLine(level, false);
+        return true;
+    }
+    #value(node, level) {
+        const [start, end] = node.range;
+        if (node.type === 'Object' || node.type === 'Array') {
+            const [opening, closing] = node.type === 'Object' ? ['{', '}'] : ['[', ']'];
+            const items = node.type === 'Object' ? node.members : node.elements;
+            if (items.length === 0 && this.#peekComment(end) === undefined) {
+                this.#write(opening + closing);
+                return;
+            }
+            if (this.#isSameLine(start, end)) {
+                this.#oneLine(items, { start, end, level }, opening, closing);
+                return;
+            }
+            this.#write(opening);
+            this.#list(items, {
+                start: start + 1,
+                end: end - 1,
+                level: level + 1,
+                isBracketed: true,
+            });
+            this.#newLine(level, false);
+            this.#write(closing);
+            return;
+        }
+        const text = this.#text.slice(start, end);
+        this.#write(node.type === 'String' && node.block ? reindentBlockString(text, INDENT.repeat(level)) : text);
+    }
+    print() {
+        const { body } = this.#tree;
+        const items = body.type === 'Object' && !body.braced ? body.members : [body];
+        // The document is a list without brackets: the members of a brace-less object, or one braced collection.
+        this.#list(items, {
+            start: 0,
+            end: this.#text.length,
+            level: 0,
+            isBracketed: false,
+        });
+        this.#output.push('\n');
+        return this.#output.join('');
+    }
+}
+/*
+Only spaces and tabs are whitespace in SOML. Any other character, such as a no-break space, is content.
+*/
+function trimTrailingWhitespace(text) {
+    // A loop rather than a regular expression, which would take quadratic time on a long run of spaces inside a line.
+    return text.slice(0, skipSpacesBack(text, text.length));
+}
+/*
+Moves a block string to a new indentation. Its content is relative to the closing delimiter's indentation, so replacing that indentation on every line keeps the value. A blank line is left as it is, because it becomes an empty line either way.
+*/
+function reindentBlockString(text, indentation) {
+    const lines = text.split('\n');
+    const closing = lines.at(-1);
+    const oldIndentation = closing.slice(0, skipSpaces(closing, 0));
+    return lines.map((line, index) => index === 0 || isBlankLine(line) ? line : indentation + line.slice(oldIndentation.length)).join('\n');
+}

package/distribution/index.d.ts

@@ -0,0 +1,8 @@
+/// <reference lib="esnext.temporal" preserve="true" />
+export { parse, type Value, type ObjectValue, type Document, type ParseOptions, } from './parse.ts';
+export { parseTree, visitorKeys, type Position, type SourceLocation, type Token, type Comment, type DocumentNode, type ObjectNode, type MemberNode, type ArrayNode, type KeyNode, type KeySegmentNode, type StringNode, type IntegerNode, type FloatNode, type BooleanNode, type NullNode, type InstantNode, type DurationNode, type DurationPart, type ValueNode, type Node, } from './tree.ts';
+export { format, formatEdits, type FormatEdit } from './format.ts';
+export { edit, type EditOptions, type PathSegment } from './edit.ts';
+export { stringify, stringifyValue, compareKeys, type StringifyOptions, } from './stringify.ts';
+export { isBareKey } from './shared.ts';
+export { ParseError } from './error.ts';