soml-lang 0.0.1 → 0.0.2

package/distribution/error.d.ts

@@ -0,0 +1,32 @@
+/**
+Thrown by `parse()` when the input is not a valid document.
+
+The `message` includes the position and a code frame. Use `reason` for the message alone.
+*/
+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 `parse()` creates a `ParseError`.
+    */
+    private constructor();
+}

package/distribution/error.js

@@ -0,0 +1,139 @@
+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 by `parse()` when the input is not a valid document.
+
+The `message` includes the position and a code frame. Use `reason` for the message alone.
+*/
+export class ParseError extends SyntaxError {
+    /**
+    For `parse()`, 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 `parse()` 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,18 @@
+/**
+Format a document: normalize its layout, and keep everything the author chose about its content.
+
+The layout follows the spec's formatter: one tab per level, every member and item on its own line, a trailing comma after every member and item inside braces and brackets, and no trailing whitespace or runs of blank lines. Comments, member order, dotted keys, and the spelling of every value stay as they are.
+
+@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()`.
+
+@example
+```
+import {format} from 'soml-lang';
+
+format('pool: {min: 2, max: 16} # Connections');
+//=> 'pool: {\n\tmin: 2,\n\tmax: 16,\n} # Connections\n'
+```
+*/
+export declare function format(text: string): string;

package/distribution/format.js

@@ -0,0 +1,243 @@
+import { parseTree, } from "./tree.js";
+const INDENT = '\t';
+const BLANK = /^[\t ]*$/v;
+/**
+Format a document: normalize its layout, and keep everything the author chose about its content.
+
+The layout follows the spec's formatter: one tab per level, every member and item on its own line, a trailing comma after every member and item inside braces and brackets, and no trailing whitespace or runs of blank lines. Comments, member order, dotted keys, and the spelling of every value stay as they are.
+
+@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()`.
+
+@example
+```
+import {format} from 'soml-lang';
+
+format('pool: {min: 2, max: 16} # Connections');
+//=> 'pool: {\n\tmin: 2,\n\tmax: 16,\n} # Connections\n'
+```
+*/
+export function format(text) {
+    return new Printer(text, parseTree(text)).print();
+}
+class Printer {
+    #text;
+    #tree;
+    #output = '';
+    #commentIndex = 0;
+    constructor(text, tree) {
+        this.#text = text;
+        this.#tree = tree;
+    }
+    #write(text) {
+        this.#output += text;
+    }
+    /*
+    Starts a new line at `level`, with one blank line before it when the source had one.
+    */
+    #newLine(level, isBlank) {
+        if (this.#output === '') {
+            return;
+        }
+        this.#write(`${isBlank ? '\n\n' : '\n'}${INDENT.repeat(level)}`);
+    }
+    #isSameLine(start, end) {
+        return !this.#text.slice(start, end).includes('\n');
+    }
+    #hasBlankLine(start, end) {
+        return /\n[\t ]*\n/v.test(this.#text.slice(start, end));
+    }
+    /*
+    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, apart from trailing whitespace.
+        this.#write(`/*${comment.value}*/`.split('\n').map(line => trimTrailingWhitespace(line)).join('\n'));
+    }
+    /*
+    The offset of the `,` after an item in the source, or `undefined` when there is none.
+    */
+    #findComma(start, end) {
+        const index = this.#text.slice(start, end).replaceAll(/\/\*.*?\*\/|#[^\n]*/gsv, comment => ' '.repeat(comment.length)).indexOf(',');
+        return index === -1 ? undefined : start + index;
+    }
+    /*
+    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 gets its own line.
+    */
+    #list(items, { start, end, level, hasCommas }) {
+        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 = hasCommas;
+        let hasWritten = false;
+        let isOnSameLine = false;
+        for (const item of [...items, undefined]) {
+            const itemStart = item?.range[0] ?? end;
+            const comma = hasCommas ? this.#findComma(previousEnd, itemStart) : undefined;
+            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,
+                    itemStart: item?.range[0],
+                    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 && (item !== undefined || nextStart < itemStart) && 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, hasCommas);
+            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, itemStart, 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.
+        if (itemStart !== undefined && comment.type === 'Block' && (comma === undefined || isAfterComma) && this.#isSameLine(commentEnd, itemStart)) {
+            return false;
+        }
+        // A comment after the comma ends the comma's line, which may be later than the item's. The comma goes after the item, so that only holds when nothing came between them.
+        const lineEnd = isAfterComma && previousEnd === itemEnd ? comma + 1 : previousEnd;
+        return this.#isSameLine(lineEnd, commentStart);
+    }
+    #item(item, level, hasComma) {
+        if (item.type === 'Member') {
+            this.#member(item, level);
+        }
+        else {
+            this.#value(item, level);
+        }
+        if (hasComma) {
+            this.#write(',');
+        }
+    }
+    #member(member, level) {
+        const { key, value } = member;
+        this.#write(`${this.#text.slice(...key.range)}:`);
+        if (this.#peekComment(value.range[0]) === undefined) {
+            this.#write(' ');
+            this.#value(value, level);
+            return;
+        }
+        // With comments between the `:` and the value, the line breaks between them are kept, 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.#isSameLine(previousEnd, comment.range[0])) {
+                valueLevel = level + 1;
+            }
+            this.#writeSeparator(previousEnd, comment.range[0], level + 1);
+            this.#writeComment(comment);
+            previousEnd = comment.range[1];
+        }
+        if (!this.#isSameLine(previousEnd, value.range[0])) {
+            valueLevel = level + 1;
+        }
+        this.#writeSeparator(previousEnd, value.range[0], 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`.
+    */
+    #writeSeparator(start, end, level) {
+        if (this.#isSameLine(start, end)) {
+            this.#write(' ');
+        }
+        else {
+            this.#newLine(level, false);
+        }
+    }
+    #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;
+            }
+            this.#write(opening);
+            this.#list(items, {
+                start: start + 1,
+                end: end - 1,
+                level: level + 1,
+                hasCommas: 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 + 1)) : text);
+    }
+    print() {
+        const { body } = this.#tree;
+        const items = body.type === 'Object' && !body.braced ? body.members : [body];
+        // The document is a list without commas: the members of a brace-less object, or one braced collection.
+        this.#list(items, {
+            start: 0,
+            end: this.#text.length,
+            level: 0,
+            hasCommas: false,
+        });
+        return `${this.#output}\n`;
+    }
+}
+/*
+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.
+    let end = text.length;
+    while (end > 0 && (text[end - 1] === ' ' || text[end - 1] === '\t')) {
+        end--;
+    }
+    return text.slice(0, end);
+}
+/*
+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, closing.length - closing.trimStart().length);
+    return lines.map((line, index) => index === 0 || (index < lines.length - 1 && BLANK.test(line)) ? line : indentation + line.slice(oldIndentation.length)).join('\n');
+}

package/distribution/index.d.ts

@@ -0,0 +1,5 @@
+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 ValueNode, type Node, } from './tree.ts';
+export { format } from './format.ts';
+export { stringify, type StringifyOptions } from './stringify.ts';
+export { ParseError } from './error.ts';

package/distribution/index.js

@@ -0,0 +1,5 @@
+export { parse, } from "./parse.js";
+export { parseTree, visitorKeys, } from "./tree.js";
+export { format } from "./format.js";
+export { stringify } from "./stringify.js";
+export { ParseError } from "./error.js";

package/distribution/parse.d.ts

@@ -0,0 +1,68 @@
+/**
+A value in a document.
+
+| Format | JavaScript |
+|---|---|
+| string | `string` |
+| int | `bigint`, or `number` with `integers: 'number'` |
+| float | `number` |
+| bool | `boolean` |
+| null | `null` |
+| instant | `Temporal.Instant` |
+| duration | `Temporal.Duration`, in hours and smaller units |
+| array | `Array` |
+| object | plain `Object` |
+*/
+export type Value<Integer extends bigint | number = bigint> = string | Integer | number | boolean | null | Temporal.Instant | Temporal.Duration | Value<Integer>[] | ObjectValue<Integer>;
+/**
+An object in a document.
+*/
+export type ObjectValue<Integer extends bigint | number = bigint> = {
+    [key: string]: Value<Integer>;
+};
+/**
+A whole document, which is always an object or an array.
+*/
+export type Document<Integer extends bigint | number = bigint> = ObjectValue<Integer> | Array<Value<Integer>>;
+export type ParseOptions = {
+    /**
+    How an int is represented.
+
+    - `'bigint'`: Every int is a `bigint`, and every float is a `number`, so `3` and `3.0` stay different, and every 64-bit int is exact. This is the only conforming mode.
+    - `'number'`: Every int is a `number`. An int outside `Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER` throws a `ParseError` rather than being rounded. `3` and `3.0` both become `3`, so `stringify()` cannot tell them apart afterwards.
+
+    @default 'bigint'
+    */
+    readonly integers?: 'bigint' | 'number';
+};
+/**
+Parse a document.
+
+@param text - The document, as a string or as UTF-8 bytes.
+@returns The object or array the document contains.
+@throws {ParseError} When the document is not valid.
+@throws {TypeError} When `text` is not a string or a `Uint8Array`, or `options.integers` is not `'bigint'` or `'number'`.
+
+@example
+```
+import {parse} from 'soml-lang';
+
+parse(`
+name: 'api-gateway'
+replicas: 3
+timeout: 30.0
+postgres.host: 'db.internal'
+`);
+//=> {name: 'api-gateway', replicas: 3n, timeout: 30, postgres: {host: 'db.internal'}}
+
+parse('replicas: 3', {integers: 'number'});
+//=> {replicas: 3}
+```
+*/
+export declare function parse(text: string | Uint8Array, options?: ParseOptions & {
+    readonly integers?: 'bigint';
+}): Document;
+export declare function parse(text: string | Uint8Array, options: ParseOptions & {
+    readonly integers: 'number';
+}): Document<number>;
+export declare function parse(text: string | Uint8Array, options?: ParseOptions): Document | Document<number>;