links-notation 0.30.1 → 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

@@ -2943,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.1",
+  "version": "0.30.2",
   "description": "Links Notation parser for JavaScript",
   "main": "dist/index.js",
   "types": "index.d.ts",

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/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')");