links-notation 0.30.2 → 0.31.0

package/README.md

@@ -660,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/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}:`];
@@ -4071,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,
@@ -4098,6 +4124,7 @@ export {
   formatBinaryReference,
   formatIndentedDocument,
   formatLinks,
+  formatNested,
   parseIndentedDocument,
   referenceQuote,
   stripComments,

package/index.d.ts

@@ -724,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.2",
+  "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/index.js

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

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))');
 });