soml-lang 0.0.2 → 0.0.4

package/distribution/tree.js

@@ -1,7 +1,7 @@
-import { parse } from "./parse.js";
-import { isBareKeyCharacter, findNumberEnd, findLineEnd, findBlockStringEnd, } from "./shared.js";
+import { parseWithTimes, } from "./parse.js";
+import { isBareKeyCharacter, isSpace, findNumberEnd, findLineEnd, findBlockStringEnd, LF, DOUBLE_QUOTE, HASH, SINGLE_QUOTE, ASTERISK, COMMA, SLASH, BACKSLASH, OPEN_BRACKET, CLOSE_BRACKET, OPEN_BRACE, CLOSE_BRACE, } from "./shared.js";
 /**
-The properties of each node type that hold its child nodes, in source order. For tools that walk the tree, such as an ESLint language plugin.
+The properties of each node type that hold its child nodes, in source order, for tools that walk the tree, such as an ESLint language plugin.
 
 @example
 ```
@@ -20,8 +20,7 @@ export const visitorKeys = Object.freeze({
     Object: Object.freeze(['members']),
     Member: Object.freeze(['key', 'value']),
     Array: Object.freeze(['elements']),
-    Key: Object.freeze(['segments']),
-    KeySegment: Object.freeze([]),
+    Key: Object.freeze([]),
     String: Object.freeze([]),
     Integer: Object.freeze([]),
     Float: Object.freeze([]),
@@ -31,31 +30,16 @@ export const visitorKeys = Object.freeze({
     Duration: Object.freeze([]),
 });
 /* eslint-enable @typescript-eslint/naming-convention */
-const TAB = 0x09;
-const LF = 0x0A;
-const SPACE = 0x20;
-const DOUBLE_QUOTE = 0x22;
-const HASH = 0x23;
-const SINGLE_QUOTE = 0x27;
-const ASTERISK = 0x2A;
-const COMMA = 0x2C;
-const DOT = 0x2E;
-const SLASH = 0x2F;
-const BACKSLASH = 0x5C;
-const OPEN_BRACKET = 0x5B;
-const CLOSE_BRACKET = 0x5D;
-const OPEN_BRACE = 0x7B;
-const CLOSE_BRACE = 0x7D;
-const WHITESPACE = new Set([SPACE, TAB, LF]);
 /*
 `infinity` and `-infinity` are read as numbers, because they are floats.
 */
 const KEYWORDS = ['true', 'false', 'null'];
-const RADIX = { x: 16, o: 8, b: 2 };
+// A map rather than an object, so that a property added to `Object.prototype` is never read as an entry.
+const RADIX = new Map([['x', 16], ['o', 8], ['b', 2]]);
 /**
-Parse a document into a syntax tree, for tools such as linters and formatters.
+Parse a document into a syntax tree, for tools such as linters and formatters. Returns a `Document` node, which also holds every token and comment.
 
-Every node, token, and comment has a `range` and a `loc`.
+Every node, token, and comment has a `range`, which is `[start, end]` as UTF-16 offsets into `text`, and a `loc`, which is `{start: {line, column}, end: {line, column}}`, with a 1-based line and a 0-based column in UTF-16 code units, as in ESTree. A `ParseError` counts its column differently, for people to read, so use its `offset` to find the position in the tree. A scalar node or a key shares its `range` and `loc` with its token, and other nodes, except `Document`, share the positions in `loc` with their first and last token, so treat them as read-only.
 
 @param text - The document.
 @returns The root node, which also holds every token and comment.
@@ -80,21 +64,26 @@ export function parseTree(text) {
         throw new TypeError(`Expected a string, got ${text === null ? 'null' : typeof text}`);
     }
     // Validates the whole document, so the builder below can assume valid input.
-    parse(text);
+    parseWithTimes(text);
     return new TreeBuilder(text).build();
 }
 /*
-The value of one scalar, read by the parser itself so that the tree and `parse()` cannot disagree. A scalar's validity does not depend on its context, so it parses on its own inside an array.
+The value of one scalar, read by the parser itself so that the tree and `parse()` cannot disagree. A scalar's validity does not depend on its context, so it parses on its own inside an array. An instant or a duration is a `Time`.
 */
 function readScalar(raw) {
-    return parse(`[${raw}]`)[0];
+    return parseWithTimes(`[${raw}]`)[0];
 }
+/*
+Every node is an object literal with the same property order, `type`, its own fields, `range`, and `loc`, rather than one generic function that spreads the fields, which is several times slower. A node that is one token, such as a scalar or a key, shares the token's `range` and `loc`.
+*/
 class TreeBuilder {
     #source;
     #index = 0;
     #tokens = [];
     #comments = [];
     #lineStarts = [0];
+    // The line of the last offset looked up. Offsets mostly arrive in order, so it is the best first guess for the next one.
+    #line = 0;
     constructor(source) {
         this.#source = source;
         for (let index = source.indexOf('\n'); index !== -1; index = source.indexOf('\n', index + 1)) {
@@ -109,29 +98,40 @@ class TreeBuilder {
     */
     #position(offset) {
         const lineStarts = this.#lineStarts;
-        let low = 0;
-        let high = lineStarts.length - 1;
-        while (low < high) {
-            const middle = Math.ceil((low + high) / 2);
-            if (lineStarts[middle] <= offset) {
-                low = middle;
-            }
-            else {
-                high = middle - 1;
+        // The binary search runs only when the offset is not on the line of the last one or the line after it, which makes building the tree about twice as fast.
+        if (this.#isOnLine(offset, this.#line + 1)) {
+            this.#line++;
+        }
+        else if (!this.#isOnLine(offset, this.#line)) {
+            let low = 0;
+            let high = lineStarts.length - 1;
+            while (low < high) {
+                const middle = Math.ceil((low + high) / 2);
+                if (lineStarts[middle] <= offset) {
+                    low = middle;
+                }
+                else {
+                    high = middle - 1;
+                }
             }
+            this.#line = low;
         }
-        return { line: low + 1, column: offset - lineStarts[low] };
+        return { line: this.#line + 1, column: offset - lineStarts[this.#line] };
     }
-    #node(type, start, end, fields) {
-        return {
+    #isOnLine(offset, line) {
+        const lineStarts = this.#lineStarts;
+        return line < lineStarts.length && lineStarts[line] <= offset && (line + 1 === lineStarts.length || lineStarts[line + 1] > offset);
+    }
+    #location(start, end) {
+        return { start: this.#position(start), end: this.#position(end) };
+    }
+    #token(type, start, end) {
+        const token = {
             type,
-            ...fields,
+            value: this.#source.slice(start, end),
             range: [start, end],
-            loc: { start: this.#position(start), end: this.#position(end) },
+            loc: this.#location(start, end),
         };
-    }
-    #token(type, start, end) {
-        const token = this.#node(type, start, end, { value: this.#source.slice(start, end) });
         this.#tokens.push(token);
         return token;
     }
@@ -144,48 +144,73 @@ class TreeBuilder {
         for (;;) {
             const code = this.#code();
             const start = this.#index;
-            if (WHITESPACE.has(code)) {
+            if (code === LF || isSpace(code)) {
                 this.#index++;
             }
             else if (code === HASH) {
                 this.#index = findLineEnd(source, start);
-                this.#comments.push(this.#node('Line', start, this.#index, { value: source.slice(start + 1, this.#index) }));
+                this.#comment('Line', start, this.#index, source.slice(start + 1, this.#index));
             }
             else if (code === SLASH && this.#code(start + 1) === ASTERISK) {
                 this.#index = source.indexOf('*/', start + 2) + 2;
-                this.#comments.push(this.#node('Block', start, this.#index, { value: source.slice(start + 2, this.#index - 2) }));
+                this.#comment('Block', start, this.#index, source.slice(start + 2, this.#index - 2));
             }
             else {
                 return;
             }
         }
     }
+    #comment(type, start, end, value) {
+        this.#comments.push({
+            type,
+            value,
+            range: [start, end],
+            loc: this.#location(start, end),
+        });
+    }
     #bareObject() {
         const members = [];
         do {
             members.push(this.#member());
             this.#skipTrivia();
         } while (this.#index < this.#source.length);
-        return this.#node('Object', members[0].range[0], members.at(-1).range[1], { members, braced: false });
+        const first = members[0];
+        const last = members.at(-1);
+        return {
+            type: 'Object',
+            members,
+            braced: false,
+            range: [first.range[0], last.range[1]],
+            loc: spanLocation(first, last),
+        };
     }
     #object() {
-        const start = this.#index;
-        const members = this.#items(CLOSE_BRACE, () => this.#member());
-        return this.#node('Object', start, this.#index, { members, braced: true });
+        const { items: members, opening, closing } = this.#items(CLOSE_BRACE, () => this.#member());
+        return {
+            type: 'Object',
+            members,
+            braced: true,
+            range: [opening.range[0], closing.range[1]],
+            loc: spanLocation(opening, closing),
+        };
     }
     #array() {
-        const start = this.#index;
-        const elements = this.#items(CLOSE_BRACKET, () => this.#value());
-        return this.#node('Array', start, this.#index, { elements });
+        const { items: elements, opening, closing } = this.#items(CLOSE_BRACKET, () => this.#value());
+        return {
+            type: 'Array',
+            elements,
+            range: [opening.range[0], closing.range[1]],
+            loc: spanLocation(opening, closing),
+        };
     }
     /*
-    The items between an opening bracket and its `closing` bracket, which is consumed too. The parser has already checked the commas.
+    The items between an opening bracket and its `closingCode` bracket, which is consumed too. Items are separated by a comma, a line break, or both, so a comma token may be absent. The parser has already checked the separators, including that a comma is on the line of the item before it.
     */
-    #items(closing, parseItem) {
+    #items(closingCode, parseItem) {
         const items = [];
-        this.#punctuator();
+        const opening = this.#punctuator();
         this.#skipTrivia();
-        while (this.#code() !== closing) {
+        while (this.#code() !== closingCode) {
             items.push(parseItem());
             this.#skipTrivia();
             if (this.#code() !== COMMA) {
@@ -194,36 +219,45 @@ class TreeBuilder {
             this.#punctuator();
             this.#skipTrivia();
         }
-        this.#punctuator();
-        return items;
+        return { items, opening, closing: this.#punctuator() };
     }
     #member() {
         const key = this.#key();
         this.#punctuator(); // `:`
         this.#skipTrivia();
         const value = this.#value();
-        return this.#node('Member', key.range[0], value.range[1], { key, value });
+        return {
+            type: 'Member',
+            key,
+            value,
+            range: [key.range[0], value.range[1]],
+            loc: spanLocation(key, value),
+        };
     }
     #key() {
-        const segments = [this.#keySegment()];
-        while (this.#code() === DOT) {
-            this.#punctuator();
-            segments.push(this.#keySegment());
-        }
-        return this.#node('Key', segments[0].range[0], segments.at(-1).range[1], { segments });
-    }
-    #keySegment() {
         const start = this.#index;
         const code = this.#code();
         if (code === SINGLE_QUOTE || code === DOUBLE_QUOTE) {
-            const { value, style } = this.#singleLineString();
-            return this.#node('KeySegment', start, this.#index, { value, style });
+            const { value, style, token: { range, loc } } = this.#singleLineString();
+            return {
+                type: 'Key',
+                value,
+                style,
+                range,
+                loc,
+            };
         }
         while (isBareKeyCharacter(this.#code())) {
             this.#index++;
         }
-        const token = this.#token('BareKey', start, this.#index);
-        return this.#node('KeySegment', start, this.#index, { value: token.value, style: 'bare' });
+        const { value, range, loc } = this.#token('BareKey', start, this.#index);
+        return {
+            type: 'Key',
+            value,
+            style: 'bare',
+            range,
+            loc,
+        };
     }
     #value() {
         const code = this.#code();
@@ -238,16 +272,30 @@ class TreeBuilder {
             if (this.#code(start + 1) === code && this.#code(start + 2) === code) {
                 return this.#blockString(code);
             }
-            const { value, style } = this.#singleLineString();
-            return this.#node('String', start, this.#index, { value, style, block: false });
+            const { value, style, token: { range, loc } } = this.#singleLineString();
+            return {
+                type: 'String',
+                value,
+                style,
+                block: false,
+                range,
+                loc,
+            };
         }
-        const keyword = KEYWORDS.find(word => this.#source.startsWith(word, start) && !isBareKeyCharacter(this.#code(start + word.length)));
+        // The document is valid, so a value that starts with a keyword is that keyword, as a number cannot start with a letter other than the `i` of `infinity`.
+        const keyword = KEYWORDS.find(word => this.#source.startsWith(word, start));
         if (keyword !== undefined) {
             this.#index += keyword.length;
-            this.#token('Keyword', start, this.#index);
-            return keyword === 'null'
-                ? this.#node('Null', start, this.#index, {})
-                : this.#node('Boolean', start, this.#index, { value: keyword === 'true' });
+            const { range, loc } = this.#token('Keyword', start, this.#index);
+            if (keyword === 'null') {
+                return { type: 'Null', range, loc };
+            }
+            return {
+                type: 'Boolean',
+                value: keyword === 'true',
+                range,
+                loc,
+            };
         }
         return this.#numberOrTime();
     }
@@ -270,8 +318,8 @@ class TreeBuilder {
         this.#index = end + 1;
         const token = this.#token('String', start, this.#index);
         return quote === SINGLE_QUOTE
-            ? { value: source.slice(start + 1, end), style: 'literal' }
-            : { value: readScalar(token.value), style: 'escaped' };
+            ? { value: source.slice(start + 1, end), style: 'literal', token }
+            : { value: readScalar(token.value), style: 'escaped', token };
     }
     /*
     The block ends at the first line whose first non-whitespace content is a run of exactly as many quotes as the opening delimiter.
@@ -285,12 +333,15 @@ class TreeBuilder {
         }
         const closing = findBlockStringEnd(source, source.indexOf('\n', start) + 1, quote, delimiterLength);
         this.#index = closing.delimiterStart + delimiterLength;
-        const token = this.#token('String', start, this.#index);
-        return this.#node('String', start, this.#index, {
-            value: readScalar(token.value),
+        const { value, range, loc } = this.#token('String', start, this.#index);
+        return {
+            type: 'String',
+            value: readScalar(value),
             style: quote === SINGLE_QUOTE ? 'literal' : 'escaped',
             block: true,
-        });
+            range,
+            loc,
+        };
     }
     #numberOrTime() {
         const start = this.#index;
@@ -299,16 +350,53 @@ class TreeBuilder {
         const raw = this.#source.slice(start, end);
         const value = readScalar(raw);
         if (typeof value === 'bigint') {
-            this.#token('Integer', start, end);
-            return this.#node('Integer', start, end, { value, radix: RADIX[raw.charAt(1)] ?? 10 });
+            const { range, loc } = this.#token('Integer', start, end);
+            return {
+                type: 'Integer',
+                value,
+                radix: RADIX.get(raw.charAt(1)) ?? 10,
+                range,
+                loc,
+            };
         }
         if (typeof value === 'number') {
-            this.#token('Float', start, end);
-            return this.#node('Float', start, end, { value });
+            const { range, loc } = this.#token('Float', start, end);
+            return {
+                type: 'Float',
+                value,
+                range,
+                loc,
+            };
+        }
+        const time = value;
+        const { range, loc } = this.#token(time.type, start, end);
+        let temporal;
+        if (time.type === 'Duration') {
+            // A getter, so that the `Temporal` object is made when `value` is first read.
+            const node = {
+                type: 'Duration',
+                get value() {
+                    temporal ??= time.toTemporal();
+                    return temporal;
+                },
+                negative: raw.startsWith('-'),
+                parts: readDurationParts(raw),
+                range,
+                loc,
+            };
+            return node;
         }
-        const type = value instanceof Temporal.Instant ? 'Instant' : 'Duration';
-        this.#token(type, start, end);
-        return this.#node(type, start, end, { value });
+        // A getter, so that the `Temporal` object is made when `value` is first read.
+        const node = {
+            type: 'Instant',
+            get value() {
+                temporal ??= time.toTemporal();
+                return temporal;
+            },
+            range,
+            loc,
+        };
+        return node;
     }
     build() {
         this.#skipTrivia();
@@ -324,10 +412,41 @@ class TreeBuilder {
             body = this.#bareObject();
         }
         this.#skipTrivia();
-        return this.#node('Document', 0, this.#source.length, {
+        return {
+            type: 'Document',
             body,
             tokens: this.#tokens,
             comments: this.#comments,
-        });
+            range: [0, this.#source.length],
+            loc: this.#location(0, this.#source.length),
+        };
+    }
+}
+/*
+The location from the start of `first` to the end of `last`, which shares their positions rather than looking them up again. A node that ends far from where it starts, such as a large object, would otherwise move the line cache in `#position` back and forth.
+*/
+function spanLocation(first, last) {
+    return { start: first.loc.start, end: last.loc.end };
+}
+/*
+The parts of a duration that is already valid. A part is a number, which has no letters, and then a unit, which has only lowercase letters.
+*/
+function readDurationParts(raw) {
+    // From `a` to `z`.
+    const isUnitCharacter = (index) => raw.charCodeAt(index) >= 0x61 && raw.charCodeAt(index) <= 0x7A;
+    const parts = [];
+    let index = raw.startsWith('-') ? 1 : 0;
+    while (index < raw.length) {
+        let unitStart = index;
+        while (!isUnitCharacter(unitStart)) {
+            unitStart++;
+        }
+        let unitEnd = unitStart;
+        while (unitEnd < raw.length && isUnitCharacter(unitEnd)) {
+            unitEnd++;
+        }
+        parts.push({ number: raw.slice(index, unitStart), unit: raw.slice(unitStart, unitEnd) });
+        index = unitEnd;
     }
+    return parts;
 }

package/package.json

@@ -1,8 +1,9 @@
 {
 	"name": "soml-lang",
-	"version": "0.0.2",
-	"description": "Reference parser, canonical serializer, and formatter for SOML, a config format for humans",
+	"version": "0.0.4",
+	"description": "Reference parser, serializer, and formatter for SOML, a config format for humans",
 	"license": "MIT",
+	"repository": "som-lang/soml-javascript",
 	"author": "Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)",
 	"type": "module",
 	"exports": {
@@ -16,7 +17,7 @@
 	"scripts": {
 		"build": "tsc --project tsconfig.build.json",
 		"prepack": "npm run build",
-		"test": "xo && tsc && node --test",
+		"test": "xo && tsc && node --test 'test/*.ts'",
 		"bench": "node bench/index.ts"
 	},
 	"files": [