soml-lang 0.0.2 → 0.0.4

package/distribution/shared.d.ts

@@ -1,3 +1,20 @@
+export declare const TAB = 9;
+export declare const LF = 10;
+export declare const SPACE = 32;
+export declare const DOUBLE_QUOTE = 34;
+export declare const HASH = 35;
+export declare const SINGLE_QUOTE = 39;
+export declare const ASTERISK = 42;
+export declare const COMMA = 44;
+export declare const DASH = 45;
+export declare const DOT = 46;
+export declare const SLASH = 47;
+export declare const COLON = 58;
+export declare const OPEN_BRACKET = 91;
+export declare const BACKSLASH = 92;
+export declare const CLOSE_BRACKET = 93;
+export declare const OPEN_BRACE = 123;
+export declare const CLOSE_BRACE = 125;
 export declare const MAX_DEPTH = 100;
 export declare const INT64_MIN: bigint;
 export declare const INT64_MAX: bigint;
@@ -13,17 +30,38 @@ export declare function trimTrailingZeros(digits: string): string;
 A duration as a `Temporal.Duration` in hours and smaller units, which hold any int64 count of nanoseconds exactly.
 */
 export declare function createDuration(nanoseconds: bigint): Temporal.Duration;
-export declare function validateIntegersOption(integers: unknown): asserts integers is 'bigint' | 'number';
+/**
+The `integers` option of `parse()`, `stringify()`, and `edit()`, checked, or its default when it is left out.
+*/
+export declare function getIntegersOption(options: unknown): 'bigint' | 'number';
 /**
 Whether a UTF-16 code unit can be part of a bare key. `NaN`, which `charCodeAt()` returns past the end of a string, cannot.
 */
 export declare function isBareKeyCharacter(code: number): boolean;
 /**
-Whether a key can be written without quotes: one or more ASCII letters, digits, `_`, or `-`.
+Whether a key can be written without quotes, as a bare key: one or more ASCII letters, digits, `_`, or `-`, in any order, so `404` and `-x` are bare keys too. `stringify()` writes such a key bare and quotes every other key.
+
+@param key - The decoded key.
+@returns Whether `key` can be a bare key.
+
+@example
+```
+import {isBareKey} from 'soml-lang';
+
+isBareKey('content-type');
+//=> true
+
+isBareKey('a.b');
+//=> false
+```
 */
 export declare function isBareKey(key: string): boolean;
 /**
-The end of the number, instant, or duration token that starts at `start`, which is a digit or `-`.
+A key as an error message shows it: bare when it can be, and otherwise quoted, and cut short when it is long.
+*/
+export declare function describeKey(key: string): string;
+/**
+The end of the number, instant, or duration token that starts at `start`, which is a digit, `-`, or the `i` of `infinity`.
 */
 export declare function findNumberEnd(source: string, start: number): number;
 /**
@@ -38,11 +76,27 @@ export declare function findBlockStringEnd(source: string, offset: number, quote
     delimiterStart: number;
 } | undefined;
 /**
+Whether a UTF-16 code unit is a space or a tab, the whitespace within a line.
+*/
+export declare function isSpace(code: number): boolean;
+/**
+The index after the spaces and tabs from `index` on.
+*/
+export declare function skipSpaces(text: string, index: number): number;
+/**
+The index after the last character before `index` that is not a space or a tab.
+*/
+export declare function skipSpacesBack(text: string, index: number): number;
+/**
+Whether a line in a block string is blank: empty, or only spaces and tabs. A blank line becomes an empty line in the value.
+*/
+export declare function isBlankLine(line: string): boolean;
+/**
 Shorten text quoted in an error message, so a huge token does not make a huge message. The cut never splits a surrogate pair.
 */
 export declare function abbreviate(text: string, maximumLength?: number): string;
 export declare function formatCodePoint(codePoint: number): string;
 /**
-Describe a character for an error message, such as `"$"` or `U+00A0 (NO-BREAK SPACE)`.
+Describe a character for an error message, such as `“$”` or `U+00A0 (NO-BREAK SPACE)`.
 */
 export declare function describeCharacter(codePoint: number): string;

package/distribution/shared.js

@@ -1,4 +1,24 @@
 /*
+UTF-16 code units of the characters that the lexers look for.
+*/
+export const TAB = 0x09;
+export const LF = 0x0A;
+export const SPACE = 0x20;
+export const DOUBLE_QUOTE = 0x22;
+export const HASH = 0x23;
+export const SINGLE_QUOTE = 0x27;
+export const ASTERISK = 0x2A;
+export const COMMA = 0x2C;
+export const DASH = 0x2D;
+export const DOT = 0x2E;
+export const SLASH = 0x2F;
+export const COLON = 0x3A;
+export const OPEN_BRACKET = 0x5B;
+export const BACKSLASH = 0x5C;
+export const CLOSE_BRACKET = 0x5D;
+export const OPEN_BRACE = 0x7B;
+export const CLOSE_BRACE = 0x7D;
+/*
 The deepest nesting either direction accepts. A recursive-descent parser would otherwise end in an engine stack overflow.
 */
 export const MAX_DEPTH = 100;
@@ -10,7 +30,7 @@ The instant range is checked in UTC, so that every instant has a canonical form
 export const MIN_INSTANT = -62135596800000000000n; // 0001-01-01T00:00:00Z
 export const MAX_INSTANT = 253402300799999999999n; // 9999-12-31T23:59:59.999999999Z
 /*
-`Temporal` is built into Node.js 26 and later. Before that, only instants and durations need it, so that everything else works without a polyfill. It is read at import, so a polyfill must be loaded before this package.
+`Temporal` is built into Node.js 26 and later. Before that, only the values of instants and durations need it, so that everything else works without a polyfill, including `format()` and `parseTree()`. It is read at import, so a polyfill must be loaded before this package.
 */
 const temporal = typeof Temporal === 'undefined' ? undefined : Temporal;
 export function requireTemporal() {
@@ -54,10 +74,21 @@ export function createDuration(nanoseconds) {
     const [hours, minutes, seconds, milliseconds, microseconds, nanosecondsPart] = parts;
     return new (requireTemporal().Duration)(0, 0, 0, 0, hours, minutes, seconds, milliseconds, microseconds, nanosecondsPart);
 }
-export function validateIntegersOption(integers) {
+/**
+The `integers` option of `parse()`, `stringify()`, and `edit()`, checked, or its default when it is left out.
+*/
+export function getIntegersOption(options) {
+    if (options === undefined) {
+        return 'bigint';
+    }
+    if (typeof options !== 'object' || options === null) {
+        throw new TypeError(`The options must be an object, got ${options === null ? 'null' : typeof options}`);
+    }
+    const { integers = 'bigint' } = options;
     if (integers !== 'bigint' && integers !== 'number') {
         throw new TypeError(`The \`integers\` option must be 'bigint' or 'number', got ${typeof integers === 'string' ? `'${abbreviate(integers)}'` : typeof integers}`);
     }
+    return integers;
 }
 /*
 Names for the characters that are invisible or easy to mistake, so an error can say what it found.
@@ -122,7 +153,21 @@ export function isBareKeyCharacter(code) {
     return code < 128 && bareKeyCharacters[code] === 1;
 }
 /**
-Whether a key can be written without quotes: one or more ASCII letters, digits, `_`, or `-`.
+Whether a key can be written without quotes, as a bare key: one or more ASCII letters, digits, `_`, or `-`, in any order, so `404` and `-x` are bare keys too. `stringify()` writes such a key bare and quotes every other key.
+
+@param key - The decoded key.
+@returns Whether `key` can be a bare key.
+
+@example
+```
+import {isBareKey} from 'soml-lang';
+
+isBareKey('content-type');
+//=> true
+
+isBareKey('a.b');
+//=> false
+```
 */
 export function isBareKey(key) {
     if (key === '') {
@@ -136,7 +181,13 @@ export function isBareKey(key) {
     return true;
 }
 /**
-The end of the number, instant, or duration token that starts at `start`, which is a digit or `-`.
+A key as an error message shows it: bare when it can be, and otherwise quoted, and cut short when it is long.
+*/
+export function describeKey(key) {
+    return isBareKey(key) ? abbreviate(key) : JSON.stringify(abbreviate(key));
+}
+/**
+The end of the number, instant, or duration token that starts at `start`, which is a digit, `-`, or the `i` of `infinity`.
 */
 export function findNumberEnd(source, start) {
     let end = start + 1;
@@ -160,10 +211,7 @@ Find the closing delimiter of a block string: the first line from `offset` on th
 */
 export function findBlockStringEnd(source, offset, quote, length) {
     for (let lineStart = offset; lineStart < source.length; lineStart = findLineEnd(source, lineStart) + 1) {
-        let delimiterStart = lineStart;
-        while (source.charCodeAt(delimiterStart) === 0x20 || source.charCodeAt(delimiterStart) === 0x09) {
-            delimiterStart++;
-        }
+        const delimiterStart = skipSpaces(source, lineStart);
         let runLength = 0;
         while (source.charCodeAt(delimiterStart + runLength) === quote) {
             runLength++;
@@ -172,9 +220,43 @@ export function findBlockStringEnd(source, offset, quote, length) {
             return { lineStart, delimiterStart };
         }
     }
+    // Past the last line, either because the source ended with a line break or because the last line was content.
     return undefined;
 }
 /**
+Whether a UTF-16 code unit is a space or a tab, the whitespace within a line.
+*/
+export function isSpace(code) {
+    return code === SPACE || code === TAB;
+}
+/*
+Whitespace within a line is scanned with loops rather than regular expressions such as `/[\t ]*:/`, because a regular expression that backtracks over a run of a few million spaces runs out of stack.
+*/
+/**
+The index after the spaces and tabs from `index` on.
+*/
+export function skipSpaces(text, index) {
+    while (isSpace(text.charCodeAt(index))) {
+        index++;
+    }
+    return index;
+}
+/**
+The index after the last character before `index` that is not a space or a tab.
+*/
+export function skipSpacesBack(text, index) {
+    while (index > 0 && isSpace(text.charCodeAt(index - 1))) {
+        index--;
+    }
+    return index;
+}
+/**
+Whether a line in a block string is blank: empty, or only spaces and tabs. A blank line becomes an empty line in the value.
+*/
+export function isBlankLine(line) {
+    return skipSpaces(line, 0) === line.length;
+}
+/**
 Shorten text quoted in an error message, so a huge token does not make a huge message. The cut never splits a surrogate pair.
 */
 export function abbreviate(text, maximumLength = 40) {
@@ -189,7 +271,7 @@ export function formatCodePoint(codePoint) {
     return `U+${codePoint.toString(16).toUpperCase().padStart(4, '0')}`;
 }
 /**
-Describe a character for an error message, such as `"$"` or `U+00A0 (NO-BREAK SPACE)`.
+Describe a character for an error message, such as `“$”` or `U+00A0 (NO-BREAK SPACE)`.
 */
 export function describeCharacter(codePoint) {
     const name = CHARACTER_NAMES.get(codePoint);
@@ -198,6 +280,6 @@ export function describeCharacter(codePoint) {
         return `${formatCodePoint(codePoint)} (${name}${isWhitespace ? '; only space, tab, and line feed are whitespace' : ''})`;
     }
     const character = String.fromCodePoint(codePoint);
-    // Control, format, private-use, unassigned, surrogate, and separator characters are invisible or ambiguous, so they are shown by code point.
-    return codePoint !== 0x20 && /^[\p{Other}\p{Separator}]$/v.test(character) ? formatCodePoint(codePoint) : `"${character}"`;
+    // Control, format, private-use, unassigned, surrogate, separator, and default-ignorable characters are invisible or ambiguous, so they are shown by code point.
+    return codePoint !== 0x20 && /^[\p{Default_Ignorable_Code_Point}\p{Other}\p{Separator}]$/v.test(character) ? formatCodePoint(codePoint) : `“${character}”`;
 }

package/distribution/stringify.d.ts

@@ -1,6 +1,9 @@
+/**
+Options for `stringify()`.
+*/
 export type StringifyOptions = {
     /**
-    How an int is represented in the value.
+    How an int is represented in `value`.
 
     - `'bigint'`: A `bigint` is written as an int, and a `number` is always written as a float, so `8080` becomes `8080.0`.
     - `'number'`: A `number` that is a safe integer is written as an int, and any other `number` as a float. A `bigint` is still written as an int.
@@ -8,21 +11,42 @@ export type StringifyOptions = {
     @default 'bigint'
     */
     readonly integers?: 'bigint' | 'number';
+    /**
+    Write exact canonical form, with the members of every object sorted by key, for hashing, signing, or comparing.
+
+    By default, members keep the order of `value`, which reads better in a file for people, and every other rule of canonical form is followed. JavaScript puts integer-like keys, such as `404` or `10`, before every other key, in numeric order, so their order in `value` cannot be kept.
+
+    @default false
+
+    @example
+    ```
+    import {stringify} from 'soml-lang';
+
+    stringify({name: 'api', description: 'The edge service'});
+    //=> "name: 'api'\ndescription: 'The edge service'\n"
+
+    stringify({name: 'api', description: 'The edge service'}, {canonical: true});
+    //=> "description: 'The edge service'\nname: 'api'\n"
+    ```
+    */
+    readonly canonical?: boolean;
 };
 /**
-Serialize an object or an array to canonical form.
+Serialize an object or an array to SOML. Nesting is written with braces and tabs, and the output ends with one line feed. Comments and block strings are never written.
 
-Canonical form is unique for a value: two equal values produce the same bytes, so the output can be hashed, signed, or compared. Members are sorted by key, and comments, dotted keys, and block strings are never written.
+Members keep the order of `value`, which reads better in a file for people, and every other rule of canonical form is followed. With the `canonical: true` option, members are sorted by key, and the output is canonical form: two equal values produce the same bytes, so it can be hashed, signed, or compared.
+
+JavaScript puts integer-like keys, such as `404` or `10`, before every other key, in numeric order, so their order in `value` cannot be kept.
 
 A `bigint` is written as an int and a `number` as a float, so `{port: 8080}` becomes `port: 8080.0`. Use `8080n`, or the `integers: 'number'` option.
 
-A `Date` is accepted and written as an instant. A member whose value is `undefined` is left out.
+Besides the types that `parse()` returns, a `Date` is accepted and written as an instant, a `Temporal.Duration` is accepted when it has no years, months, weeks, or days, because those are not a fixed length, and a member whose value is `undefined` is left out, as `JSON.stringify` does.
 
 @param value - A plain object or an array.
-@param options - How to write ints.
-@returns The canonical form, ending with one line feed.
-@throws {TypeError} When the value contains something that cannot be represented, such as `NaN`, a function, a class instance, an invalid `Date`, a `Temporal.Duration` with years, months, weeks, or days, a circular reference, or a string or key with a lone surrogate or a carriage return. Also when `options.integers` is not `'bigint'` or `'number'`.
-@throws {RangeError} When an int is outside the 64-bit range, an instant is outside the years 0001 to 9999, a duration is outside the 64-bit range of nanoseconds, or the value is nested more than 100 levels deep.
+@param options - How an int is represented in `value`, and whether to sort members.
+@returns The document, ending with one line feed.
+@throws {TypeError} For a value that cannot be represented: `NaN`, a function, a symbol value, an object that is neither a plain object nor an array (such as a class instance or a `Map`), `undefined` in an array, a circular reference, a non-collection at the top level, an invalid `Date`, a `Temporal.Duration` with years, months, weeks, or days, an object that only claims to be a `Date`, a `Temporal.Instant`, or a `Temporal.Duration`, and a string or key with a lone surrogate or a carriage return. Also when `options` is not an object, its `integers` is not `'bigint'` or `'number'`, or its `canonical` is not a boolean.
+@throws {RangeError} For an int outside the 64-bit range, an instant outside the years 0001 to 9999, a duration outside the 64-bit range of nanoseconds, and nesting deeper than 100 levels.
 
 @example
 ```
@@ -30,6 +54,62 @@ import {stringify} from 'soml-lang';
 
 stringify({name: 'api-gateway', replicas: 3n, timeout: 30});
 //=> "name: 'api-gateway'\nreplicas: 3\ntimeout: 30.0\n"
+
+stringify({port: 8080}, {integers: 'number'});
+//=> 'port: 8080\n'
+
+stringify({name: 'api', description: 'The edge service'}, {canonical: true});
+//=> "description: 'The edge service'\nname: 'api'\n"
 ```
 */
 export declare function stringify(value: object, options?: StringifyOptions): string;
+/**
+Serialize one value as it is written in a document: a scalar on one line, and an object or an array in braces or brackets over several lines, with each level indented by one more tab. There is no line feed at the end.
+
+For showing a value, as in a message, or for writing it into a template. Use `stringify()` to write a whole document, and `edit()` to change a value in one.
+
+It takes the same values and options as `stringify()`, and any of them at the top level, so `1.5` gives `'1.5'` and `'it\'s'` gives `"it's"`. Members keep their order, as in `stringify()`, unless the `canonical: true` option sorts them.
+
+@param value - A value of any type that `stringify()` accepts in a document.
+@param options - How an int is represented in `value`, and whether to sort members.
+@returns The value as it is written in a document.
+@throws {TypeError} For a value that cannot be represented, as for `stringify()`, and for `undefined`.
+@throws {RangeError} For a value out of range, as for `stringify()`.
+
+@example
+```
+import {stringifyValue} from 'soml-lang';
+
+stringifyValue(0.1 + 0.2);
+//=> '0.30000000000000004'
+
+stringifyValue(8080n);
+//=> '8080'
+
+stringifyValue({b: 1n, a: [true]});
+//=> '{\n\tb: 1\n\ta: [\n\t\ttrue\n\t]\n}'
+
+stringifyValue({b: 1n, a: [true]}, {canonical: true});
+//=> '{\n\ta: [\n\t\ttrue\n\t]\n\tb: 1\n}'
+```
+*/
+export declare function stringifyValue(value: unknown, options?: StringifyOptions): string;
+/**
+Compare two keys in canonical order, which is by their Unicode scalar values, as `stringify()` sorts members with the `canonical: true` option. For a sort, such as in a lint rule that keeps the members of an object in canonical order.
+
+The default `Array#sort()` compares UTF-16 code units, which puts U+E000 to U+FFFF after every character above U+FFFF, so it differs from canonical order for keys that hold such characters.
+
+@param left - A key.
+@param right - Another key.
+@returns A negative number when `left` comes first, a positive number when `right` comes first, and `0` when they are equal.
+
+@example
+```
+import {compareKeys} from 'soml-lang';
+
+['b', 'a', '😀', 'ff'].toSorted(compareKeys);
+//=> ['a', 'b', 'ff', '😀']
+```
+*/
+export declare function compareKeys(left: string, right: string): number;
+export declare function formatKey(key: string): string;