links-notation 0.30.0 → 0.30.2

package/README.md

@@ -215,6 +215,40 @@ console.log(group.children[0].children[0].element.getValuesString()); // Detail
 `Parser.parse()` continues to return the existing list of links and expanded
 paths. `parseGroups()` preserves indentation even for the `name:` syntax.
 
+#### Indented ID Groups
+
+`parse` defines the canonical link values for `x:\n  a\n  b`: `(x: a b)`.
+`parseGroups` keeps the `x:` element as a self reference (`id: 'x'`,
+`values: []`), with children separate from that empty value list. Leaf lines
+containing a single reference inside an indented ID's value subtree become
+references, so folding that subtree agrees with `parse`:
+
+```javascript
+import { Link, Parser } from 'links-notation';
+
+const parser = new Parser();
+const unindent = ({ element, children }) =>
+  children.length
+    ? new Link(element.id, [...element.values, ...children.map(unindent)])
+    : element;
+const text = 'x:\n  a\n  b';
+console.log(parser.parse(text)[0].format()); // (x: a b)
+console.log(parser.parseGroups(text).map(unindent)[0].format()); // (x: a b)
+```
+
+Parentheses keep their meaning: `x:\n  (a)` gives `(x: (a))` in both readings.
+Named and multi-value children keep their structure too. Under an ordinary
+head such as `x: kind`, the child `a` remains a one-value link `(a)`;
+`parse` expands those lines into paths, so this folding function is only an
+equivalence with `parse` for indented ID subtrees. A standalone `id:` or
+`(id:)` has no values in either API. The Link model represents it with
+`id: 'id', values: []`; its existing default formatter writes `(id)`.
+
+Before 0.30.2, `parseGroups` kept the anonymous one-value wrapper around leaf
+references under `x:`. Callers that accessed `child.element.values[0]` there
+should now use `child.element`. C++ (`parse_groups`), Swift and Kotlin expose
+the same group contract; the other six bindings do not expose this parser API.
+
 `escapeReference` and `unescapeReference` are exported functions and static
 methods on `Link`. Use minimal mode only for whole text lines; default escaping
 still quotes spaces so references can be used inside tuples:

package/README.ru.md

@@ -213,6 +213,16 @@ stream.end('следующая связь');
 `listenerCount` и другие). До версии 0.27.1 `StreamParser` импортировал модуль
 `events`, и для браузерной сборки требовался пакет-полифил `events`.
 
+### Группы отступных ID
+
+В JavaScript, C++, Swift и Kotlin доступен `parseGroups`.
+Для отступного ID, например `x:\n  a\n  b`, элемент `x:` имеет пустой
+список значений, а его дети — ссылки `a` и `b`. Свёртка детей в значения
+элемента даёт `(x: a b)`, как канонический `parse`. Явное `(a)` сохраняет
+связь с одним значением; обычный заголовок `x: kind` сохраняет прежние
+дочерние связи и развёртку путей. Начиная с 0.30.2, ссылка в листе доступна
+как `child.element`, а не `child.element.values[0]`.
+
 ## Примеры синтаксиса
 
 ### Дуплеты (2-кортежи)

package/dist/index.js

@@ -348,7 +348,7 @@ class Link {
       return this._formatWithOptions(lessParentheses, isCompoundValue);
     }
     if (this.id === null && (!this.values || this.values.length === 0)) {
-      return lessParentheses ? "" : "()";
+      return "()";
     }
     if (!this.values || this.values.length === 0) {
       const escapedId = Link.escapeReference(this.id);
@@ -359,7 +359,7 @@ class Link {
     }
     const valuesStr = this.values.map((v) => this.formatValue(v)).join(" ");
     if (this.id === null) {
-      if (lessParentheses) {
+      if (lessParentheses && !this._hasLoneNestedValue()) {
         const allSimple = this.values.every((v) => !v.values || v.values.length === 0);
         if (allSimple) {
           const simpleValuesStr = this.values.map((v) => Link.escapeReference(v.id)).join(" ");
@@ -389,9 +389,12 @@ class Link {
   needsParentheses(str) {
     return str && (str.includes(" ") || str.includes(":") || str.includes("(") || str.includes(")"));
   }
+  _hasLoneNestedValue() {
+    return this.values.length === 1 && this.values[0].values?.length > 0;
+  }
   _formatWithOptions(options, isCompoundValue = false) {
     if (this.id === null && (!this.values || this.values.length === 0)) {
-      return options.lessParentheses ? "" : "()";
+      return "()";
     }
     if (!this.values || this.values.length === 0) {
       const escapedId = Link.escapeReference(this.id);
@@ -410,7 +413,7 @@ class Link {
         const idStr = Link.escapeReference(this.id);
         testLine = options.lessParentheses ? `${idStr}: ${valuesStr}` : `(${idStr}: ${valuesStr})`;
       } else {
-        testLine = options.lessParentheses ? valuesStr : `(${valuesStr})`;
+        testLine = options.lessParentheses && !this._hasLoneNestedValue() ? valuesStr : `(${valuesStr})`;
       }
       if (options.shouldIndentByLength(testLine)) {
         shouldIndent = true;
@@ -421,7 +424,7 @@ class Link {
     }
     const valuesStr = this.values.map((v) => this.formatValue(v)).join(" ");
     if (this.id === null) {
-      if (options.lessParentheses) {
+      if (options.lessParentheses && !this._hasLoneNestedValue()) {
         const allSimple = this.values.every((v) => !v.values || v.values.length === 0);
         if (allSimple) {
           return this.values.map((v) => Link.escapeReference(v.id)).join(" ");
@@ -2940,8 +2943,10 @@ class Parser {
     this.parse(input);
     return buildCst(input, { comments: this.comments });
   }
-  _transformGroup(item) {
-    return new LinksGroup(this.transformLink(item), (item.children || []).map((child) => this._transformGroup(child)));
+  _transformGroup(item, indentedValue = false) {
+    const children = item.children || [];
+    const childValues = indentedValue || item.id != null && !item.values?.length;
+    return new LinksGroup(indentedValue && children.length === 0 ? this.transformIndentedValue(item) : this.transformLink(item), children.map((child) => this._transformGroup(child, childValues)));
   }
   _parse(input, transform) {
     if (typeof input !== "string") {

package/index.d.ts

@@ -264,7 +264,11 @@ export class Parser {
    */
   parse(input: string): Link[];
 
-  /** Read the indentation tree without expanding it into path combinations. */
+  /**
+   * Read the indentation tree without expanding it into path combinations.
+   * Indented ID elements have no values; their single-reference leaf children
+   * are references, so folding an indented ID subtree agrees with parse().
+   */
   parseGroups(input: string): IndentedGroup[];
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "links-notation",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "description": "Links Notation parser for JavaScript",
   "main": "dist/index.js",
   "types": "index.d.ts",

package/src/Link.js

@@ -196,7 +196,7 @@ export class Link {
     // Original implementation for backward compatibility
     // Empty link
     if (this.id === null && (!this.values || this.values.length === 0)) {
-      return lessParentheses ? '' : '()';
+      return '()';
     }
 
     // Link with only ID, no values
@@ -217,7 +217,7 @@ export class Link {
     // Link with values only (null id)
     if (this.id === null) {
       // For lessParentheses mode with simple values, don't wrap the whole thing
-      if (lessParentheses) {
+      if (lessParentheses && !this._hasLoneNestedValue()) {
         // Check if all values are simple (no nested values)
         const allSimple = this.values.every(
           (v) => !v.values || v.values.length === 0
@@ -288,6 +288,16 @@ export class Link {
     );
   }
 
+  /**
+   * Whether this link holds exactly one link that has values. The parentheses
+   * of an anonymous link are what nest such a value: `((b c))` without them is
+   * `(b c)`, a different link, so lessParentheses has to keep them.
+   * @returns {boolean} True if the only value has values of its own
+   */
+  _hasLoneNestedValue() {
+    return this.values.length === 1 && this.values[0].values?.length > 0;
+  }
+
   /**
    * Format the link using a FormatOptions object
    * @param {FormatOptions} options - FormatOptions object with formatting options
@@ -297,7 +307,7 @@ export class Link {
   _formatWithOptions(options, isCompoundValue = false) {
     // Empty link
     if (this.id === null && (!this.values || this.values.length === 0)) {
-      return options.lessParentheses ? '' : '()';
+      return '()';
     }
 
     // Link with only ID, no values
@@ -325,7 +335,10 @@ export class Link {
           ? `${idStr}: ${valuesStr}`
           : `(${idStr}: ${valuesStr})`;
       } else {
-        testLine = options.lessParentheses ? valuesStr : `(${valuesStr})`;
+        testLine =
+          options.lessParentheses && !this._hasLoneNestedValue()
+            ? valuesStr
+            : `(${valuesStr})`;
       }
 
       if (options.shouldIndentByLength(testLine)) {
@@ -343,7 +356,7 @@ export class Link {
 
     // Link with values only (null id)
     if (this.id === null) {
-      if (options.lessParentheses) {
+      if (options.lessParentheses && !this._hasLoneNestedValue()) {
         const allSimple = this.values.every(
           (v) => !v.values || v.values.length === 0
         );

package/src/Parser.js

@@ -42,6 +42,8 @@ export class Parser {
    * Read the indentation tree before it is expanded into path combinations.
    * Each group's element is the Link on that line; its children are groups
    * for the immediately indented lines. Parenthesized values remain Links.
+   * In an indented ID value subtree, single-reference leaves are references,
+   * as in parse(); the ID element itself keeps an empty value list.
    * @param {string} input - The Lino document
    * @returns {LinksGroup[]}
    */
@@ -65,10 +67,18 @@ export class Parser {
     return buildCst(input, { comments: this.comments });
   }
 
-  _transformGroup(item) {
+  _transformGroup(item, indentedValue = false) {
+    const children = item.children || [];
+    // Carry the value context through an indented ID subtree, just as
+    // transformIndentedValue does. Keep non-leaf containers: folding their
+    // children later must retain the reference written on the parent line.
+    const childValues =
+      indentedValue || (item.id != null && !item.values?.length);
     return new LinksGroup(
-      this.transformLink(item),
-      (item.children || []).map((child) => this._transformGroup(child))
+      indentedValue && children.length === 0
+        ? this.transformIndentedValue(item)
+        : this.transformLink(item),
+      children.map((child) => this._transformGroup(child, childValues))
     );
   }
 

package/tests/IndentedIdGroups.test.js

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs';
+import { URL } from 'node:url';
+import { expect, test } from 'bun:test';
+import { Link, Parser } from '../src/index.js';
+
+const unindent = ({ element, children }) =>
+  children.length
+    ? new Link(element.id, [...element.values, ...children.map(unindent)])
+    : element;
+
+const fixtures = JSON.parse(
+  readFileSync(
+    new URL('../../parity/text-fixtures.json', import.meta.url),
+    'utf8'
+  )
+);
+
+test('indented ID groups fold to the same links as parse (#381)', () => {
+  for (const input of [
+    'x:\n  a\n  b',
+    "'x':\n  'a'\n  ~1{62}",
+    'x:\n  (a)\n  b c\n  child: value',
+    'x:\n  inner:\n    a\n  branch\n    b',
+    'x:\n  child: kind\n    a\n  (branch)\n    b',
+    'x:\r\n  a # comment\r\n\r\n  b',
+    ...fixtures
+      .filter((fixture) => fixture.id.startsWith('indented-id-'))
+      .map((fixture) => fixture.input),
+  ]) {
+    const parser = new Parser();
+    expect(parser.parseGroups(input).map(unindent), input).toEqual(
+      parser.parse(input)
+    );
+  }
+});
+
+test('a bare ID group is a self reference with an empty value list', () => {
+  const parser = new Parser();
+  for (const input of ['id:', '(id:)', 'id:\n  a']) {
+    const [group] = parser.parseGroups(input);
+    expect(group.element.id).toBe('id');
+    expect(group.element.values).toEqual([]);
+    expect(group.children).toHaveLength(input.includes('\n') ? 1 : 0);
+  }
+  expect(parser.parse('id:')).toEqual([new Link('id', [])]);
+});
+
+test('reference children keep syntax metadata and explicit parentheses', () => {
+  const [group] = new Parser().parseGroups("'x':\n  'a'\n  (b)");
+  expect(group.element.rawId).toBe("'x'");
+  expect(group.children[0].element.id).toBe('a');
+  expect(group.children[0].element.rawId).toBe("'a'");
+  expect(group.children[0].element.quote).toBe("'");
+  expect(group.children[1].element).toEqual(new Link(null, [new Link('b')]));
+  const [ast] = new Parser({ syntax: false }).parseGroups("x:\n  'a'");
+  expect(ast.children[0].element.rawId).toBeNull();
+});
+
+test('ordinary heads retain one-value child links and path expansion', () => {
+  const parser = new Parser();
+  for (const input of ['x\n  a\n  b', 'x: kind\n  a\n  b']) {
+    const [group] = parser.parseGroups(input);
+    expect(group.children.map((child) => child.element)).toEqual([
+      new Link(null, [new Link('a')]),
+      new Link(null, [new Link('b')]),
+    ]);
+    expect(parser.parse(input)).toHaveLength(3);
+  }
+});

package/tests/SharedTextParity.test.js

@@ -1,7 +1,13 @@
 import { readFileSync } from 'node:fs';
 import { URL } from 'node:url';
 import { expect, test } from 'bun:test';
-import { Parser, StreamParser, formatLinks } from '../src/index.js';
+import {
+  FormatOptions,
+  Link,
+  Parser,
+  StreamParser,
+  formatLinks,
+} from '../src/index.js';
 
 const fixtures = JSON.parse(
   readFileSync(
@@ -25,3 +31,49 @@ test('shared text parity', () => {
     expect(tree(stream.end()), fixture.id).toEqual(fixture.expected);
   }
 });
+
+test('shared less parentheses round trip', () => {
+  const options = new FormatOptions({ lessParentheses: true });
+  for (const fixture of fixtures) {
+    const parsed = new Parser().parse(fixture.input);
+    expect(formatLinks(parsed, true), fixture.id).toBe(fixture.lessParentheses);
+    expect(formatLinks(parsed, options), fixture.id).toBe(
+      fixture.lessParentheses
+    );
+    expect(
+      tree(new Parser().parse(fixture.lessParentheses)),
+      fixture.id
+    ).toEqual(fixture.expected);
+    for (const link of parsed) {
+      const [readBack] = new Parser().parse(link.format(true));
+      expect(link.equals(readBack), fixture.id).toBe(true);
+    }
+  }
+});
+
+test('less parentheses keeps the parentheses of a lone nested value', () => {
+  const nested = new Link(null, [new Link('b'), new Link('c')]);
+  expect(new Link(null, [nested]).format(true)).toBe('((b c))');
+  expect(new Link(null, [new Link('b')]).format(true)).toBe('b');
+  expect(new Link(null, [new Link('a'), nested]).format(true)).toBe('a (b c)');
+});
+
+test('less parentheses keeps the parentheses of an empty link', () => {
+  const options = new FormatOptions({ lessParentheses: true });
+  expect(new Link(null, []).format(true)).toBe('()');
+  expect(new Link(null, []).format(options)).toBe('()');
+  expect(formatLinks([], true)).toBe('');
+});
+
+test('line length is measured on the parentheses a lone nested value keeps', () => {
+  const link = new Link(null, [new Link(null, [new Link('b'), new Link('c')])]);
+  const options = (maxLineLength) =>
+    new FormatOptions({
+      lessParentheses: true,
+      indentLongLines: true,
+      maxLineLength,
+      preferInline: false,
+    });
+  expect(link.format(options(7))).toBe('((b c))');
+  expect(link.format(options(6))).toBe('  (b c)');
+});

package/tests/SyntaxMetadata.test.js

@@ -69,7 +69,7 @@ describe('syntax metadata on parsed links (issue #364)', () => {
   test('parseGroups and StreamParser keep the metadata', () => {
     const groups = new Parser().parseGroups('\'root\':\n  "child"');
     expect(groups[0].element.rawId).toBe("'root'");
-    expect(groups[0].children[0].element.values[0].rawId).toBe('"child"');
+    expect(groups[0].children[0].element.rawId).toBe('"child"');
     const stream = new StreamParser();
     stream.write("(a '");
     stream.write("b')");