links-notation 0.30.1 → 0.31.0

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:
@@ -626,3 +660,48 @@ fail the format check.
 
 Exact Unicode identifiers and values round-trip with the [reference literal contract](../docs/protocol/reference-literals.md)
 introduced in 0.24.0, including mixed quotes, empty strings, controls and multiline text.
+
+### Recursive nested output
+
+`formatNested` writes a link's leading atoms on its line and its trailing link
+values on indented lines, recursively:
+
+```javascript
+import { Link, Parser, formatNested } from 'links-notation';
+const parser = new Parser();
+const links = parser.parse(
+  '(form: stack (direction vertical) (save: button Save (on press (emit save))))'
+);
+const text = formatNested(links);
+// form: stack
+//   direction vertical
+//   save: button Save
+//     on press
+//       emit save
+
+const unindent = ({ element, children }) =>
+  children.length
+    ? new Link(element.id, [...element.values, ...children.map(unindent)])
+    : element;
+const readBack = parser.parseGroups(text).map(unindent);
+console.log(readBack[0].equals(links[0])); // true
+```
+
+Run the complete [form example](../examples/js_nested_format.mjs) with Node.
+
+Use `parseGroups` plus this fold to read nested output. Canonical `parse` keeps
+its path expansion for ordinary indented heads. `formatIndentedDocument` remains
+the separate two-level plain-text document helper.
+
+The default indentation is two spaces; `formatNested(links, '    ')` uses four.
+The result has no final newline. References use normal escaping. Parentheses
+stay where needed for `()`, `((a b))`, or a lone reference under a bare `name:`
+ancestor. An atom after a link stays in place, so `(root: (a b) tail (c d))`
+becomes `root: (a b) tail\n  c d` without changing value order. The existing
+inline formatter's exclusions for empty links and named empty-value links used
+as values also apply to this writer.
+
+Threshold options (`maxInlineRefs`, `indentLongLines`, `preferInline`) retain
+anonymous links inline when indentation would lose their container. Use
+`formatNested` for recursive output. The same writer is available in all ten
+bindings; see the [cross-language API table](../parity/README.md#recursive-nested-formatting).

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

@@ -439,9 +439,7 @@ class Link {
   }
   _formatIndented(options) {
     if (this.id === null) {
-      const lines = this.values.map((v) => options.indentString + this.formatValue(v));
-      return lines.join(`
-`);
+      return this.format(options.lessParentheses);
     }
     const idStr = Link.escapeReference(this.id);
     const lines = [`${idStr}:`];
@@ -2943,8 +2941,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") {
@@ -4069,6 +4069,34 @@ class BinaryLinoCodec {
     return this.formatDocument(this.decode(bytes));
   }
 }
+// src/NestedFormat.js
+var isAtom = (link) => link.id !== null && link.values.length === 0;
+var canNest = (link) => !isAtom(link) && !(link.id === null && link.values.length === 1 && !isAtom(link.values[0]));
+var lineHolds = (link, count) => link.id !== null || count >= 2 || count === 1 && isAtom(link.values[0]);
+function nestedLines(link, pad, indent, underName = false) {
+  if (!lineHolds(link, link.values.length) || underName && link.id === null && link.values.length === 1) {
+    return [pad + link.format()];
+  }
+  let count = link.values.length;
+  while (count > 0 && canNest(link.values[count - 1]))
+    count--;
+  while (count < link.values.length && !lineHolds(link, count))
+    count++;
+  const values = link.values.slice(0, count).map((value) => isAtom(value) ? Link.escapeReference(value.id) : value.format());
+  if (link.id !== null)
+    values.unshift(`${Link.escapeReference(link.id)}:`);
+  return [
+    pad + values.join(" "),
+    ...link.values.slice(count).flatMap((value) => nestedLines(value, pad + indent, indent, underName || link.id !== null && count === 0))
+  ];
+}
+function formatNested(links, indent = "  ") {
+  if (typeof indent !== "string" || !/^ +$/.test(indent)) {
+    throw new TypeError("indent must contain only spaces and be nonempty");
+  }
+  return links.flatMap((link) => nestedLines(link, "", indent)).join(`
+`);
+}
 export {
   ArityRange,
   BinaryLinoCodec,
@@ -4096,6 +4124,7 @@ export {
   formatBinaryReference,
   formatIndentedDocument,
   formatLinks,
+  formatNested,
   parseIndentedDocument,
   referenceQuote,
   stripComments,

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[];
 
   /**
@@ -720,3 +724,6 @@ export function formatBinaryReference(reference: string): string;
 export function encodeReferenceLiteral(text: string): string;
 /** Decode a complete literal. Throws on malformed hex, UTF-8, or unsupported versions. */
 export function decodeReferenceLiteral(literal: string): string;
+
+/** Write recursive nested lines, read by folding Parser.parseGroups(). No final newline. */
+export function formatNested(links: Link[], indent?: string): string;

package/package.json

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

package/src/Link.js

@@ -383,11 +383,8 @@ export class Link {
    */
   _formatIndented(options) {
     if (this.id === null) {
-      // Values only - format each on separate line
-      const lines = this.values.map(
-        (v) => options.indentString + this.formatValue(v)
-      );
-      return lines.join('\n');
+      // A headless list reads as separate links. Keep the inline container.
+      return this.format(options.lessParentheses);
     }
 
     // Link with ID - format as id:\n  value1\n  value2

package/src/NestedFormat.js

@@ -0,0 +1,55 @@
+import { Link } from './Link.js';
+
+const isAtom = (link) => link.id !== null && link.values.length === 0;
+const canNest = (link) =>
+  !isAtom(link) &&
+  !(link.id === null && link.values.length === 1 && !isAtom(link.values[0]));
+const lineHolds = (link, count) =>
+  link.id !== null || count >= 2 || (count === 1 && isAtom(link.values[0]));
+
+function nestedLines(link, pad, indent, underName = false) {
+  if (
+    !lineHolds(link, link.values.length) ||
+    (underName && link.id === null && link.values.length === 1)
+  ) {
+    return [pad + link.format()];
+  }
+  // Only move a trailing run: moving a link past a later atom changes order.
+  let count = link.values.length;
+  while (count > 0 && canNest(link.values[count - 1])) count--;
+  while (count < link.values.length && !lineHolds(link, count)) count++;
+  const values = link.values
+    .slice(0, count)
+    .map((value) =>
+      isAtom(value) ? Link.escapeReference(value.id) : value.format()
+    );
+  if (link.id !== null) values.unshift(`${Link.escapeReference(link.id)}:`);
+  return [
+    pad + values.join(' '),
+    ...link.values
+      .slice(count)
+      .flatMap((value) =>
+        nestedLines(
+          value,
+          pad + indent,
+          indent,
+          underName || (link.id !== null && count === 0)
+        )
+      ),
+  ];
+}
+
+/**
+ * Write recursively nested lines. Read with Parser.parseGroups(), appending
+ * each group's children to its element's values. Ordinary parse() retains
+ * its path-expansion semantics. No final newline is added.
+ * @param {Link[]} links - Links in document order
+ * @param {string} [indent='  '] - Nonempty spaces for one indentation level
+ * @returns {string} Nested Links Notation
+ */
+export function formatNested(links, indent = '  ') {
+  if (typeof indent !== 'string' || !/^ +$/.test(indent)) {
+    throw new TypeError('indent must contain only spaces and be nonempty');
+  }
+  return links.flatMap((link) => nestedLines(link, '', indent)).join('\n');
+}

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/src/index.js

@@ -32,3 +32,5 @@ export {
   formatBinaryDocument,
   formatBinaryReference,
 } from './Binary.js';
+
+export { formatNested } from './NestedFormat.js';

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/NestedFormat.test.js

@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs';
+import { URL } from 'node:url';
+import { expect, test } from 'bun:test';
+import * as lino from '../src/index.js';
+
+const { Parser, Link, FormatOptions, formatLinks } = lino;
+const parser = new Parser();
+const fold = ({ element, children }) =>
+  children.length
+    ? new Link(element.id, [...element.values, ...children.map(fold)])
+    : element;
+const tree = (links) =>
+  links.map(({ id, values }) => ({ id, values: tree(values) }));
+const form =
+  "(form: stack (direction vertical) (gap 8px) (save: button 'Save' (on press (emit save) (navigate home))))";
+
+test('recursive nested writer formats the issue form and reads back through groups', () => {
+  const links = parser.parse(form);
+  const text = lino.formatNested(links);
+  expect(text).toBe(
+    'form: stack\n  direction vertical\n  gap 8px\n  save: button Save\n    on press\n      emit save\n      navigate home'
+  );
+  expect(tree(parser.parseGroups(text).map(fold))).toEqual(tree(links));
+});
+
+test('anonymous threshold output retains the anonymous container', () => {
+  for (const input of ['a b c', '((b c))', '(a (b c))']) {
+    const links = parser.parse(input);
+    for (const threshold of [
+      { maxInlineRefs: 1 },
+      { indentLongLines: true, maxLineLength: 1 },
+    ]) {
+      const text = formatLinks(
+        links,
+        new FormatOptions({
+          lessParentheses: true,
+          preferInline: false,
+          ...threshold,
+        })
+      );
+      expect(tree(parser.parse(text)), input).toEqual(tree(links));
+    }
+  }
+});
+
+test('nested writer folds every existing shared text fixture without changing values', () => {
+  const fixtures = JSON.parse(
+    readFileSync(
+      new URL('../../parity/text-fixtures.json', import.meta.url),
+      'utf8'
+    )
+  );
+  for (const fixture of fixtures) {
+    const links = parser.parse(fixture.input);
+    const text = lino.formatNested(links);
+    expect(tree(parser.parseGroups(text).map(fold)), fixture.id).toEqual(
+      tree(links)
+    );
+  }
+});
+
+test('shared nested golden corpus and custom indentation read back exactly', () => {
+  const cases = JSON.parse(
+    readFileSync(
+      new URL('../../parity/nested-fixtures.json', import.meta.url),
+      'utf8'
+    )
+  );
+  for (const fixture of cases) {
+    const links = parser.parse(fixture.input);
+    expect(lino.formatNested(links), fixture.id).toBe(fixture.nested);
+    for (const indent of ['  ', '    ']) {
+      const text = lino.formatNested(links, indent);
+      expect(tree(parser.parseGroups(text).map(fold)), fixture.id).toEqual(
+        tree(links)
+      );
+    }
+  }
+  expect(() => lino.formatNested([], '')).toThrow();
+  expect(() => lino.formatNested([], 'x')).toThrow();
+  expect(() => lino.formatNested([], '\t')).toThrow();
+});

package/tests/SharedTextParity.test.js

@@ -75,5 +75,5 @@ test('line length is measured on the parentheses a lone nested value keeps', ()
       preferInline: false,
     });
   expect(link.format(options(7))).toBe('((b c))');
-  expect(link.format(options(6))).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')");