links-notation 0.24.0 → 0.25.0

package/README.md

@@ -147,6 +147,85 @@ const group = new LinksGroup(parsed);
 console.log(group.format());
 ```
 
+### Indented Text Documents
+
+Use `parseIndentedDocument` and `formatIndentedDocument` for text parents and
+their answers or options:
+
+```javascript
+import { parseIndentedDocument, formatIndentedDocument } from 'links-notation';
+
+const input = `What is your experience?
+  I have worked with JavaScript
+'Question with "quotes": and colon'
+  Answer
+Skills
+  JavaScript
+  Python
+`;
+const answers = parseIndentedDocument(input);
+console.log(answers.get('What is your experience?'));
+// I have worked with JavaScript
+console.log(answers.get('Skills')); // ['JavaScript', 'Python']
+console.log(formatIndentedDocument(answers));
+```
+
+A parent with no children maps to `[]`, one child maps to a string, and multiple
+children map to an array. Repeated parent lines accumulate children in order.
+To read multiple child lines as multiline text, pass
+`{ multipleValues: 'join' }`. These helpers accept the same parsing options as
+`Parser`, including `comments`, `maxInputSize`, and `maxDepth`.
+
+The formatter uses two spaces of indentation and adds a final newline to a
+nonempty document. Ordinary single-space prose stays unquoted. Quotes are
+escaped by doubling the enclosing delimiter. Structural characters, comment
+starts, reserved literal prefixes, and significant whitespace are quoted.
+Empty strings and control characters use the versioned reference literals
+introduced in 0.24.0. A multiline string is encoded as one reference with its
+exact line endings; an array is written as separate child references. Parsed
+IDs are already unescaped.
+
+The text format does not distinguish a one-element array from a single string;
+both read back as a string. Use a multiline string to distinguish one
+multiline answer from several options. The helpers reject grandchildren and
+named links with values instead of discarding their structure.
+
+For arbitrary indentation trees, `Parser.parseGroups(input)` returns existing
+`LinksGroup` instances. Each group's `element` is the `Link` on that line, and
+`children` contains its immediately indented groups. Parenthesized values retain
+their usual `Link` structure:
+
+```javascript
+import { Parser } from 'links-notation';
+
+const [group] = new Parser().parseGroups('Question\n  Answer\n    Detail');
+console.log(group.element.getValuesString()); // Question
+console.log(group.children[0].element.getValuesString()); // Answer
+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.
+
+`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:
+
+```javascript
+import { Link, escapeReference, unescapeReference } from 'links-notation';
+
+Link.escapeReference('plain text'); // "'plain text'"
+escapeReference('plain text', { minimal: true }); // 'plain text'
+unescapeReference("'it''s ready'"); // "it's ready"
+```
+
+`unescapeReference` decodes a complete serialized reference, including n-quote
+delimiters, doubled escapes, and versioned literals. It rejects incomplete
+quoted input and malformed literals, and preserves literal backslashes. Do not
+call it on already decoded `Link.id` values.
+
+See the [Q&A document example](../examples/js_indented_document.js).
+
 ### Streaming Parser (for Large Messages)
 
 The `StreamParser` allows you to parse Links Notation incrementally, processing data as it arrives without loading the entire message into memory. This is ideal for:
@@ -341,6 +420,7 @@ Main parser class for converting strings to links.
     recursed into until the stack runs out
 - `initialize()` - Initialize the parser (async)
 - `parse(input)` - Parse a Lino string and return links
+- `parseGroups(input)` - Read an indentation tree as `LinksGroup` instances
 
 #### `Link`
 
@@ -350,6 +430,9 @@ Represents a single link with ID and values.
 - `toString()` - Convert link to string format
 - `id` - Link identifier
 - `values` - Array of child values/links
+- `escapeReference(reference, options)` - Quote a reference; `minimal: true`
+  allows ordinary prose on a text document line
+- `unescapeReference(reference)` - Decode a complete serialized reference
 
 #### `LinksGroup`
 

package/README.ru.md

@@ -3,6 +3,54 @@
 Реализация парсера протокола Lino для JavaScript с использованием Bun и
 генератора парсеров Peggy.js.
 
+## Документы с отступами
+
+`parseIndentedDocument()` и `formatIndentedDocument()` преобразуют текстовые
+родительские строки и их дочерние строки в `Map<string, string | string[]>`:
+
+```javascript
+import { parseIndentedDocument, formatIndentedDocument } from 'links-notation';
+
+const answers = parseIndentedDocument(`Ваш опыт?
+  JavaScript
+Навыки
+  JavaScript
+  Python
+`);
+console.log(answers.get('Ваш опыт?')); // 'JavaScript'
+console.log(answers.get('Навыки')); // ['JavaScript', 'Python']
+console.log(formatIndentedDocument(answers));
+```
+
+Без дочерних строк значение равно `[]`, с одной строкой — строке, с несколькими
+— массиву. Повторяющиеся родительские строки объединяют дочерние значения в
+порядке документа. Опция `{ multipleValues: 'join' }` объединяет несколько
+значений через перевод строки. Поддерживаются опции `Parser`: `comments`,
+`maxInputSize` и `maxDepth`. Вложенность глубже одного дочернего уровня и
+именованные ссылки со значениями отклоняются.
+
+Форматирование использует два пробела для отступа и завершающий перевод строки.
+Обычный текст с одиночными пробелами остаётся без кавычек; специальные символы,
+значимые пробелы и зарезервированные префиксы литералов заключаются в кавычки.
+Кавычки экранируются удвоением. Пустые строки и управляющие символы используют
+версионированные литералы, введённые в 0.24.0. Массив из одного элемента при
+чтении становится строкой. Многострочная строка сохраняется одной ссылкой с
+точными переводами строк, а элементы массива записываются отдельными дочерними
+строками.
+
+`Parser.parseGroups()` возвращает дерево существующих объектов `LinksGroup`:
+`element` содержит ссылку текущей строки, а `children` — группы непосредственно
+вложенных строк. Поведение `Parser.parse()` сохраняется.
+
+Функции `escapeReference()` и `unescapeReference()` экспортируются из пакета и
+доступны как статические методы `Link`. Опция `{ minimal: true }` разрешает
+обычные пробелы при экранировании целой текстовой строки. По умолчанию пробелы
+по-прежнему заключаются в кавычки. `unescapeReference()` принимает целую
+сериализованную ссылку, включая версионированные литералы; значения `Link.id`
+уже декодированы.
+
+См. [пример базы вопросов и ответов](../examples/js_indented_document.js).
+
 ## Установка
 
 ### Использование Bun (рекомендуется)

package/dist/index.js

@@ -1,3 +1,159 @@
+// src/quotes.js
+var QUOTES = ['"', "'", "`"];
+
+class DelimitedReferences {
+  constructor(document) {
+    this.document = document;
+    this.runsByQuote = new Map;
+    this.readings = new Map;
+  }
+  readAt(start) {
+    if (!this.readings.has(start)) {
+      this.readings.set(start, this.#read(start));
+    }
+    return this.readings.get(start);
+  }
+  endAt(start) {
+    const reading = this.readAt(start);
+    return reading === null ? null : start + reading.length;
+  }
+  #read(start) {
+    const document = this.document;
+    const quote = document[start];
+    if (!QUOTES.includes(quote)) {
+      return null;
+    }
+    const runs = this.#runsOf(quote);
+    const opening = runs.indexOf(start);
+    const count = runs.end(opening) - start;
+    let closing = opening + 1;
+    while (closing < runs.count) {
+      const length = runs.lengths[closing];
+      if (length < count) {
+        closing = runs.nextLonger[closing];
+      } else if (Math.floor(length / count) % 2 === 1) {
+        break;
+      } else {
+        closing++;
+      }
+    }
+    const end = closing < runs.count ? runs.end(closing) : null;
+    return reading(document, start, quote, count, end);
+  }
+  #runsOf(quote) {
+    if (!this.runsByQuote.has(quote)) {
+      this.runsByQuote.set(quote, new DelimiterRuns(this.document, quote));
+    }
+    return this.runsByQuote.get(quote);
+  }
+}
+function readReference(document, start) {
+  const quote = document[start];
+  if (!QUOTES.includes(quote)) {
+    return null;
+  }
+  const count = runLength(document, start, quote);
+  let end = null;
+  let position = document.indexOf(quote, start + count);
+  while (position !== -1) {
+    const length = runLength(document, position, quote);
+    if (length >= count && Math.floor(length / count) % 2 === 1) {
+      end = position + length;
+      break;
+    }
+    position = document.indexOf(quote, position + length);
+  }
+  return reading(document, start, quote, count, end);
+}
+function reading(document, start, quote, count, end) {
+  const emptyReference = count % 2 === 0 ? { value: "", length: count } : null;
+  if (end === null) {
+    return emptyReference;
+  }
+  const parts = [];
+  let position = start + count;
+  let run = document.indexOf(quote, position);
+  while (run !== -1 && run < end) {
+    const length = runLength(document, run, quote);
+    const escaped = Math.floor(length / (2 * count)) * count;
+    const closes = run + length === end ? count : 0;
+    parts.push(document.slice(position, run));
+    parts.push(quote.repeat(length - escaped - closes));
+    position = run + length;
+    run = document.indexOf(quote, position);
+  }
+  const value = parts.join("");
+  if (emptyReference !== null && !isSubstantiveBody(value)) {
+    return emptyReference;
+  }
+  return { value, length: end - start };
+}
+function runLength(text, start, quote) {
+  let end = start;
+  while (end < text.length && text[end] === quote) {
+    end++;
+  }
+  return end - start;
+}
+
+class DelimiterRuns {
+  constructor(document, quote) {
+    this.starts = [];
+    this.lengths = [];
+    let position = document.indexOf(quote);
+    while (position !== -1) {
+      const length = runLength(document, position, quote);
+      this.starts.push(position);
+      this.lengths.push(length);
+      position = document.indexOf(quote, position + length);
+    }
+    this.count = this.starts.length;
+    this.nextLonger = new Array(this.count);
+    const longer = [];
+    for (let run = this.count - 1;run >= 0; run--) {
+      while (longer.length > 0 && this.lengths[longer[longer.length - 1]] <= this.lengths[run]) {
+        longer.pop();
+      }
+      this.nextLonger[run] = longer.length > 0 ? longer[longer.length - 1] : this.count;
+      longer.push(run);
+    }
+  }
+  end(run) {
+    return this.starts[run] + this.lengths[run];
+  }
+  indexOf(position) {
+    let low = 0;
+    let high = this.count - 1;
+    while (low < high) {
+      const middle = low + high + 1 >> 1;
+      if (this.starts[middle] <= position) {
+        low = middle;
+      } else {
+        high = middle - 1;
+      }
+    }
+    return low;
+  }
+}
+function isSubstantiveBody(content) {
+  let depth = 0;
+  let hasVisible = false;
+  for (const character of content) {
+    if (character === "(") {
+      depth++;
+    } else if (character === ")") {
+      depth--;
+      if (depth < 0) {
+        return false;
+      }
+    }
+    if (!/[ \t\n\r]/.test(character)) {
+      hasVisible = true;
+    }
+  }
+  return hasVisible && depth === 0;
+}
+
 // src/ReferenceLiteral.js
 function hasReferenceLiteralPrefix(text, start = 0) {
   return /^~[0-9]+\{/.test(text.slice(start));
@@ -44,6 +200,42 @@ function formatReference(text) {
   return delimiter + text + delimiter;
 }
 
+// src/references.js
+function escapeReference(reference, { minimal = false } = {}) {
+  if (reference === null || reference === undefined)
+    return "";
+  if (typeof reference !== "string" || !reference.isWellFormed()) {
+    throw new TypeError("Reference must be well-formed Unicode text");
+  }
+  if (!minimal || !reference || /[\u0000-\u001f\u007f]/u.test(reference)) {
+    return formatReference(reference);
+  }
+  const needsQuoting = /(^| )~[0-9]+\{/.test(reference) || /[:()'"`]|(?! )[\p{White_Space}\ufeff]/u.test(reference) || /(^ | $| {2,}|(^| )#)/.test(reference);
+  if (!needsQuoting)
+    return reference;
+  const singleQuotes = reference.split("'").length - 1;
+  const doubleQuotes = reference.split('"').length - 1;
+  let quote = singleQuotes <= doubleQuotes ? "'" : '"';
+  if (reference.startsWith(quote))
+    quote = quote === "'" ? '"' : "'";
+  return quote + reference.replaceAll(quote, quote + quote) + quote;
+}
+function unescapeReference(reference) {
+  if (typeof reference !== "string") {
+    throw new TypeError("Reference must be a string");
+  }
+  if (hasReferenceLiteralPrefix(reference)) {
+    return decodeReferenceLiteral(reference);
+  }
+  if (!QUOTES.includes(reference[0]))
+    return reference;
+  const reading = readReference(reference, 0);
+  if (reading === null || reading.length !== reference.length) {
+    throw new SyntaxError("Expected one complete quoted reference");
+  }
+  return reading.value;
+}
+
 // src/Link.js
 class Link {
   constructor(id = null, values = null) {
@@ -81,11 +273,11 @@ class Link {
   static getValueString(value) {
     return value && typeof value.toLinkOrIdString === "function" ? value.toLinkOrIdString() : String(value);
   }
-  static escapeReference(reference) {
-    if (reference === null || reference === undefined) {
-      return "";
-    }
-    return formatReference(reference);
+  static escapeReference(reference, options = {}) {
+    return escapeReference(reference, options);
+  }
+  static unescapeReference(reference) {
+    return unescapeReference(reference);
   }
   toLinkOrIdString() {
     if (!this.values || this.values.length === 0) {
@@ -296,6 +488,7 @@ class LinksGroup {
     return list.map((item) => `(${item.id || item})`).join(" ");
   }
 }
+
 // src/ParseError.js
 var QUOTED_LINE_WIDTH = 80;
 var ELLIPSIS = "...";
@@ -371,144 +564,6 @@ function windowAround(lineText, column) {
   return [quoted, target - start + shift + 1];
 }
 
-// src/quotes.js
-var QUOTES = ['"', "'", "`"];
-
-class DelimitedReferences {
-  constructor(document) {
-    this.document = document;
-    this.runsByQuote = new Map;
-    this.readings = new Map;
-  }
-  readAt(start) {
-    if (!this.readings.has(start)) {
-      this.readings.set(start, this.#read(start));
-    }
-    return this.readings.get(start);
-  }
-  endAt(start) {
-    const reading = this.readAt(start);
-    return reading === null ? null : start + reading.length;
-  }
-  #read(start) {
-    const document = this.document;
-    const quote = document[start];
-    if (!QUOTES.includes(quote)) {
-      return null;
-    }
-    const runs = this.#runsOf(quote);
-    const opening = runs.indexOf(start);
-    const count = runs.end(opening) - start;
-    let closing = opening + 1;
-    while (closing < runs.count) {
-      const length = runs.lengths[closing];
-      if (length < count) {
-        closing = runs.nextLonger[closing];
-      } else if (Math.floor(length / count) % 2 === 1) {
-        break;
-      } else {
-        closing++;
-      }
-    }
-    const end = closing < runs.count ? runs.end(closing) : null;
-    return reading(document, start, quote, count, end);
-  }
-  #runsOf(quote) {
-    if (!this.runsByQuote.has(quote)) {
-      this.runsByQuote.set(quote, new DelimiterRuns(this.document, quote));
-    }
-    return this.runsByQuote.get(quote);
-  }
-}
-function reading(document, start, quote, count, end) {
-  const emptyReference = count % 2 === 0 ? { value: "", length: count } : null;
-  if (end === null) {
-    return emptyReference;
-  }
-  const parts = [];
-  let position = start + count;
-  let run = document.indexOf(quote, position);
-  while (run !== -1 && run < end) {
-    const length = runLength(document, run, quote);
-    const escaped = Math.floor(length / (2 * count)) * count;
-    const closes = run + length === end ? count : 0;
-    parts.push(document.slice(position, run));
-    parts.push(quote.repeat(length - escaped - closes));
-    position = run + length;
-    run = document.indexOf(quote, position);
-  }
-  const value = parts.join("");
-  if (emptyReference !== null && !isSubstantiveBody(value)) {
-    return emptyReference;
-  }
-  return { value, length: end - start };
-}
-function runLength(text, start, quote) {
-  let end = start;
-  while (end < text.length && text[end] === quote) {
-    end++;
-  }
-  return end - start;
-}
-
-class DelimiterRuns {
-  constructor(document, quote) {
-    this.starts = [];
-    this.lengths = [];
-    let position = document.indexOf(quote);
-    while (position !== -1) {
-      const length = runLength(document, position, quote);
-      this.starts.push(position);
-      this.lengths.push(length);
-      position = document.indexOf(quote, position + length);
-    }
-    this.count = this.starts.length;
-    this.nextLonger = new Array(this.count);
-    const longer = [];
-    for (let run = this.count - 1;run >= 0; run--) {
-      while (longer.length > 0 && this.lengths[longer[longer.length - 1]] <= this.lengths[run]) {
-        longer.pop();
-      }
-      this.nextLonger[run] = longer.length > 0 ? longer[longer.length - 1] : this.count;
-      longer.push(run);
-    }
-  }
-  end(run) {
-    return this.starts[run] + this.lengths[run];
-  }
-  indexOf(position) {
-    let low = 0;
-    let high = this.count - 1;
-    while (low < high) {
-      const middle = low + high + 1 >> 1;
-      if (this.starts[middle] <= position) {
-        low = middle;
-      } else {
-        high = middle - 1;
-      }
-    }
-    return low;
-  }
-}
-function isSubstantiveBody(content) {
-  let depth = 0;
-  let hasVisible = false;
-  for (const character of content) {
-    if (character === "(") {
-      depth++;
-    } else if (character === ")") {
-      depth--;
-      if (depth < 0) {
-        return false;
-      }
-    }
-    if (!/[ \t\n\r]/.test(character)) {
-      hasVisible = true;
-    }
-  }
-  return hasVisible && depth === 0;
-}
-
 // src/comments.js
 var COMMENT = "#";
 var BEFORE_REFERENCE = [" ", "\t", `
@@ -2817,6 +2872,15 @@ class Parser {
     this.comments = options.comments ?? true;
   }
   parse(input) {
+    return this._parse(input, (raw) => this.transformResult(raw));
+  }
+  parseGroups(input) {
+    return this._parse(input, (raw) => raw.map((item) => this._transformGroup(item)));
+  }
+  _transformGroup(item) {
+    return new LinksGroup(this.transformLink(item), (item.children || []).map((child) => this._transformGroup(child)));
+  }
+  _parse(input, transform) {
     if (typeof input !== "string") {
       throw new TypeError("Input must be a string");
     }
@@ -2828,7 +2892,7 @@ class Parser {
       const rawResult = peg$parse(prepared, {
         maxDepth: this.maxDepth
       });
-      return this.transformResult(rawResult);
+      return transform(rawResult);
     } catch (error) {
       if (error && error.location) {
         throw new ParseError(input, error);
@@ -2950,6 +3014,64 @@ class Parser {
     return new Link(item.id ?? null, []);
   }
 }
+
+// src/IndentedDocument.js
+function lineText(link) {
+  if (link.id !== null && link.values.length === 0)
+    return link.id;
+  if (link.id === null && link.values.length > 0 && link.values.every((value) => value.id !== null && value.values.length === 0)) {
+    return link.values.map((value) => value.id).join(" ");
+  }
+  throw new TypeError("Indented document lines must contain only text references");
+}
+function parseIndentedDocument(input, options = {}) {
+  const { multipleValues = "array" } = options;
+  if (multipleValues !== "array" && multipleValues !== "join") {
+    throw new TypeError('multipleValues must be "array" or "join"');
+  }
+  const groups = new Parser(options).parseGroups(input);
+  const collected = new Map;
+  for (const group of groups) {
+    const parent = lineText(group.element);
+    const values = collected.get(parent) ?? [];
+    for (const child of group.children) {
+      if (child.children.length > 0) {
+        throw new TypeError("Indented documents support only immediate children");
+      }
+      values.push(lineText(child.element));
+    }
+    collected.set(parent, values);
+  }
+  return new Map([...collected].map(([parent, values]) => [
+    parent,
+    values.length === 1 ? values[0] : values.length > 1 && multipleValues === "join" ? values.join(`
+`) : values
+  ]));
+}
+function formatIndentedDocument(entries) {
+  if (!(entries instanceof Map)) {
+    throw new TypeError("Indented document entries must be a Map");
+  }
+  const lines = [];
+  for (const [parent, value] of entries) {
+    if (typeof parent !== "string") {
+      throw new TypeError("Indented document parents must be strings");
+    }
+    const values = Array.isArray(value) ? value : [value];
+    for (const child of values) {
+      if (typeof child !== "string") {
+        throw new TypeError("Indented document children must be strings");
+      }
+    }
+    lines.push(escapeReference(parent, { minimal: true }));
+    for (const child of values) {
+      lines.push("  " + escapeReference(child, { minimal: true }));
+    }
+  }
+  return lines.length > 0 ? lines.join(`
+`) + `
+` : "";
+}
 // src/StreamParser.js
 import { EventEmitter } from "events";
 var DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
@@ -3783,8 +3905,12 @@ export {
   StreamParser,
   decodeReferenceLiteral,
   encodeReferenceLiteral,
+  escapeReference,
   formatBinaryDocument,
   formatBinaryReference,
+  formatIndentedDocument,
   formatLinks,
-  stripComments
+  parseIndentedDocument,
+  stripComments,
+  unescapeReference
 };

package/index.d.ts

@@ -100,9 +100,29 @@ export class Link {
    * @param reference - The reference to escape
    * @returns Escaped reference
    */
-  static escapeReference(reference: string): string;
+  static escapeReference(
+    reference: string,
+    options?: EscapeReferenceOptions
+  ): string;
+
+  /** Decode one escaped reference. Link IDs returned by a parser are already decoded. */
+  static unescapeReference(reference: string): string;
 }
 
+export interface EscapeReferenceOptions {
+  /** Leave ordinary single-space prose unquoted for use on document lines. */
+  minimal?: boolean;
+}
+
+/** Escape a reference. Minimal mode doubles enclosing quotes; default formatting uses n-quotes. */
+export function escapeReference(
+  reference: string,
+  options?: EscapeReferenceOptions
+): string;
+
+/** Decode a complete escaped reference, including n-quotes and versioned literals. */
+export function unescapeReference(reference: string): string;
+
 /**
  * Parser options for configuring the parser behavior
  */
@@ -166,8 +186,40 @@ export class Parser {
    * @throws {ParseError} If the text does not parse
    */
   parse(input: string): Link[];
+
+  /** Read the indentation tree without expanding it into path combinations. */
+  parseGroups(input: string): IndentedGroup[];
+}
+
+/** A parsed line and the immediately indented lines below it. */
+export interface IndentedGroup extends LinksGroup {
+  element: Link;
+  children: IndentedGroup[];
 }
 
+export interface IndentedDocumentOptions extends ParserOptions {
+  /** Multiple children become an array (default) or text joined with newlines. */
+  multipleValues?: 'array' | 'join';
+}
+
+/**
+ * Read parent/children text. Repeated parents accumulate children in order.
+ * No children yields [], one yields a string, multiple yield an array by default.
+ * Named links with values and grandchildren are rejected.
+ */
+export function parseIndentedDocument(
+  input: string,
+  options?: IndentedDocumentOptions
+): Map<string, string | string[]>;
+
+/**
+ * Write minimally quoted text with two-space indentation and a final newline.
+ * Multiline strings remain one encoded reference; array entries become children.
+ */
+export function formatIndentedDocument(
+  entries: ReadonlyMap<string, string | string[]>
+): string;
+
 /** Options for incremental parsing. */
 export interface StreamParserOptions extends ParserOptions {
   /** Canonical parser instance to use for completed records. */

package/package.json

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

package/src/IndentedDocument.js

@@ -0,0 +1,88 @@
+import { Parser } from './Parser.js';
+import { escapeReference } from './references.js';
+
+// A text line can be a single quoted reference or a flat list of words. Named
+// links and nested values have more structure than this document format holds.
+function lineText(link) {
+  if (link.id !== null && link.values.length === 0) return link.id;
+  if (
+    link.id === null &&
+    link.values.length > 0 &&
+    link.values.every((value) => value.id !== null && value.values.length === 0)
+  ) {
+    return link.values.map((value) => value.id).join(' ');
+  }
+  throw new TypeError(
+    'Indented document lines must contain only text references'
+  );
+}
+
+/**
+ * Read text parents and their immediate text children into a Map. Repeated
+ * parents accumulate children in document order. Zero children yields [], one
+ * yields a string, and multiple yield an array (or joined text when requested).
+ * @param {string} input
+ * @param {Object} options - Parser options plus multipleValues: 'array' | 'join'
+ * @returns {Map<string, string|string[]>}
+ */
+export function parseIndentedDocument(input, options = {}) {
+  const { multipleValues = 'array' } = options;
+  if (multipleValues !== 'array' && multipleValues !== 'join') {
+    throw new TypeError('multipleValues must be "array" or "join"');
+  }
+  const groups = new Parser(options).parseGroups(input);
+  const collected = new Map();
+  for (const group of groups) {
+    const parent = lineText(group.element);
+    const values = collected.get(parent) ?? [];
+    for (const child of group.children) {
+      if (child.children.length > 0) {
+        throw new TypeError(
+          'Indented documents support only immediate children'
+        );
+      }
+      values.push(lineText(child.element));
+    }
+    collected.set(parent, values);
+  }
+  return new Map(
+    [...collected].map(([parent, values]) => [
+      parent,
+      values.length === 1
+        ? values[0]
+        : values.length > 1 && multipleValues === 'join'
+          ? values.join('\n')
+          : values,
+    ])
+  );
+}
+
+/**
+ * Write a text Map using minimal quoting and two-space child indentation.
+ * Multiline strings are encoded as one reference; array entries are separate
+ * children. Nonempty output ends with a newline.
+ * @param {Map<string, string|string[]>} entries
+ * @returns {string}
+ */
+export function formatIndentedDocument(entries) {
+  if (!(entries instanceof Map)) {
+    throw new TypeError('Indented document entries must be a Map');
+  }
+  const lines = [];
+  for (const [parent, value] of entries) {
+    if (typeof parent !== 'string') {
+      throw new TypeError('Indented document parents must be strings');
+    }
+    const values = Array.isArray(value) ? value : [value];
+    for (const child of values) {
+      if (typeof child !== 'string') {
+        throw new TypeError('Indented document children must be strings');
+      }
+    }
+    lines.push(escapeReference(parent, { minimal: true }));
+    for (const child of values) {
+      lines.push('  ' + escapeReference(child, { minimal: true }));
+    }
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}

package/src/Link.js

@@ -1,4 +1,4 @@
-import { formatReference } from './ReferenceLiteral.js';
+import { escapeReference, unescapeReference } from './references.js';
 
 export class Link {
   /**
@@ -81,14 +81,16 @@ export class Link {
   /**
    * Escape a reference string by adding quotes if necessary
    * @param {string} reference - The reference to escape
+   * @param {{minimal?: boolean}} options - Allow plain-text document lines
    * @returns {string} Escaped reference
    */
-  static escapeReference(reference) {
-    if (reference === null || reference === undefined) {
-      return '';
-    }
+  static escapeReference(reference, options = {}) {
+    return escapeReference(reference, options);
+  }
 
-    return formatReference(reference);
+  /** Decode an escaped reference, rather than an already parsed Link ID. */
+  static unescapeReference(reference) {
+    return unescapeReference(reference);
   }
 
   /**

package/src/Parser.js

@@ -1,4 +1,5 @@
 import { Link } from './Link.js';
+import { LinksGroup } from './LinksGroup.js';
 import { ParseError } from './ParseError.js';
 import { stripComments } from './comments.js';
 import * as parserModule from './parser-generated.js';
@@ -31,6 +32,30 @@ export class Parser {
    * @throws {Error} If parsing fails
    */
   parse(input) {
+    return this._parse(input, (raw) => this.transformResult(raw));
+  }
+
+  /**
+   * 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.
+   * @param {string} input - The Lino document
+   * @returns {LinksGroup[]}
+   */
+  parseGroups(input) {
+    return this._parse(input, (raw) =>
+      raw.map((item) => this._transformGroup(item))
+    );
+  }
+
+  _transformGroup(item) {
+    return new LinksGroup(
+      this.transformLink(item),
+      (item.children || []).map((child) => this._transformGroup(child))
+    );
+  }
+
+  _parse(input, transform) {
     // Validate input
     if (typeof input !== 'string') {
       throw new TypeError('Input must be a string');
@@ -50,7 +75,7 @@ export class Parser {
       const rawResult = parserModule.parse(prepared, {
         maxDepth: this.maxDepth,
       });
-      return this.transformResult(rawResult);
+      return transform(rawResult);
     } catch (error) {
       // A syntax error knows where it stopped; anything else is passed on with
       // the original error kept as the cause.

package/src/index.js

@@ -1,4 +1,9 @@
 export { Link, formatLinks } from './Link.js';
+export { escapeReference, unescapeReference } from './references.js';
+export {
+  parseIndentedDocument,
+  formatIndentedDocument,
+} from './IndentedDocument.js';
 export {
   encodeReferenceLiteral,
   decodeReferenceLiteral,

package/src/references.js

@@ -0,0 +1,63 @@
+import { QUOTES, readReference } from './quotes.js';
+import {
+  decodeReferenceLiteral,
+  formatReference,
+  hasReferenceLiteralPrefix,
+} from './ReferenceLiteral.js';
+
+/**
+ * Quote one reference. Minimal mode allows ordinary single-space prose on a
+ * document line; token formatting still quotes spaces by default.
+ * @param {string|null|undefined} reference
+ * @param {{minimal?: boolean}} options
+ * @returns {string}
+ */
+export function escapeReference(reference, { minimal = false } = {}) {
+  if (reference === null || reference === undefined) return '';
+  if (typeof reference !== 'string' || !reference.isWellFormed()) {
+    throw new TypeError('Reference must be well-formed Unicode text');
+  }
+  // Keep ordinary Link formatting identical to binary text formatting. The
+  // versioned literal also preserves empty strings and control characters in
+  // minimal document lines, including exact line endings.
+  if (!minimal || !reference || /[\u0000-\u001f\u007f]/u.test(reference)) {
+    return formatReference(reference);
+  }
+
+  const needsQuoting =
+    /(^| )~[0-9]+\{/.test(reference) ||
+    /[:()'"`]|(?! )[\p{White_Space}\ufeff]/u.test(reference) ||
+    /(^ | $| {2,}|(^| )#)/.test(reference);
+  if (!needsQuoting) return reference;
+
+  const singleQuotes = reference.split("'").length - 1;
+  const doubleQuotes = reference.split('"').length - 1;
+  let quote = singleQuotes <= doubleQuotes ? "'" : '"';
+
+  // The opening delimiter must be a run of exactly one quote. Choosing the
+  // other wrapper keeps a leading content quote from extending that run.
+  if (reference.startsWith(quote)) quote = quote === "'" ? '"' : "'";
+  return quote + reference.replaceAll(quote, quote + quote) + quote;
+}
+
+/**
+ * Decode a complete, escaped reference using the parser's delimiter rules.
+ * Plain text is returned unchanged. Parsed Link IDs are already decoded and
+ * should not be passed through this function a second time.
+ * @param {string} reference
+ * @returns {string}
+ */
+export function unescapeReference(reference) {
+  if (typeof reference !== 'string') {
+    throw new TypeError('Reference must be a string');
+  }
+  if (hasReferenceLiteralPrefix(reference)) {
+    return decodeReferenceLiteral(reference);
+  }
+  if (!QUOTES.includes(reference[0])) return reference;
+  const reading = readReference(reference, 0);
+  if (reading === null || reading.length !== reference.length) {
+    throw new SyntaxError('Expected one complete quoted reference');
+  }
+  return reading.value;
+}

package/tests/IndentedDocument.test.js

@@ -0,0 +1,256 @@
+import { readFileSync } from 'node:fs';
+import { test, expect } from 'bun:test';
+import * as lino from '../src/index.js';
+
+const { Link, LinksGroup, Parser, ParseError } = lino;
+
+test('mixed quotes round-trip through the existing Link formatter', () => {
+  const text = 'He said "it\'s ready"';
+  const formatted = new Link(text).toString();
+  expect(new Parser().parse(formatted)[0].values[0].id).toBe(text);
+  expect(formatted).not.toContain("\\'");
+  expect(lino.escapeReference(text, { minimal: true })).toBe(
+    "'He said \"it''s ready\"'"
+  );
+});
+
+test('minimal escaping leaves ordinary prose unquoted', () => {
+  expect(
+    Link.escapeReference('What is your experience?', { minimal: true })
+  ).toBe('What is your experience?');
+  expect(Link.escapeReference('What is your experience?')).toBe(
+    "'What is your experience?'"
+  );
+});
+
+test('public groups preserve immediate children and deeper indentation', () => {
+  const groups = new Parser().parseGroups(
+    'What is your experience?\n  JavaScript\n  Python\n    Django\nOther question\n  Answer'
+  );
+  expect(groups).toHaveLength(2);
+  expect(groups[0]).toBeInstanceOf(LinksGroup);
+  expect(groups[0].element.values.map((value) => value.id)).toEqual([
+    'What',
+    'is',
+    'your',
+    'experience?',
+  ]);
+  expect(groups[0].children).toHaveLength(2);
+  expect(groups[0].children[1].children[0].element.values[0].id).toBe('Django');
+  expect(groups[1].children[0].element.values[0].id).toBe('Answer');
+});
+
+test('groups retain named and nested links and share parser diagnostics', () => {
+  const parser = new Parser();
+  const [root] = parser.parseGroups(
+    'root:\n  child: (one two)\n  branch\n    leaf'
+  );
+  expect(root.element.id).toBe('root');
+  expect(root.element.values).toEqual([]);
+  expect(root.children[0].element.toString()).toBe('(child: (one two))');
+  expect(root.children[1].children).toHaveLength(1);
+  expect(() => parser.parseGroups('root: child: value')).toThrow(ParseError);
+  expect(() =>
+    new Parser({ maxDepth: 0 }).parseGroups('root\n  child')
+  ).toThrow(ParseError);
+  expect(() => new Parser({ maxInputSize: 2 }).parseGroups('root')).toThrow(
+    'Input size exceeds'
+  );
+  expect(() => parser.parseGroups(null)).toThrow(TypeError);
+});
+
+test('parse the issue document without inspecting private path flags', () => {
+  const input = `What is your experience?
+  I have worked with JavaScript
+'Question with "quotes": and colon'
+  Answer
+`;
+  expect(lino.parseIndentedDocument(input)).toEqual(
+    new Map([
+      ['What is your experience?', 'I have worked with JavaScript'],
+      ['Question with "quotes": and colon', 'Answer'],
+    ])
+  );
+});
+
+test('multiple child lines have explicit array or joined-text behavior', () => {
+  const input = 'Skills\n  JavaScript\n  Python\nUnanswered\nSkills\n  Go';
+  expect(lino.parseIndentedDocument(input)).toEqual(
+    new Map([
+      ['Skills', ['JavaScript', 'Python', 'Go']],
+      ['Unanswered', []],
+    ])
+  );
+  expect(lino.parseIndentedDocument(input, { multipleValues: 'join' })).toEqual(
+    new Map([
+      ['Skills', 'JavaScript\nPython\nGo'],
+      ['Unanswered', []],
+    ])
+  );
+  expect(() =>
+    lino.parseIndentedDocument(input, { multipleValues: 'guess' })
+  ).toThrow(TypeError);
+});
+
+test('format the issue document with two-space indentation and a final newline', () => {
+  const entries = new Map([
+    ['What is your experience?', 'I have worked with JavaScript'],
+    ['Skills', ['JavaScript', 'Python']],
+  ]);
+  expect(lino.formatIndentedDocument(entries)).toBe(
+    'What is your experience?\n  I have worked with JavaScript\nSkills\n  JavaScript\n  Python\n'
+  );
+  expect(
+    lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+  ).toEqual(entries);
+  expect(lino.formatIndentedDocument(new Map())).toBe('');
+  expect(lino.parseIndentedDocument('')).toEqual(new Map());
+});
+
+test('empty text, exact whitespace, comments, quotes, and multiline text survive', () => {
+  const references = [
+    '',
+    ' ',
+    '  leading',
+    'trailing  ',
+    'two  spaces',
+    'a\tb',
+    '# question',
+    'text # literal',
+    'issue#333',
+    'Question: (details)',
+    '`backticks`',
+    '"double" and \'single\'',
+    '\'starts with both "quotes"',
+    "\"starts with both 'quotes'",
+    'ends with both \'"',
+    'repeated \'\'\' and """',
+    "literal \\n and \\'",
+    'line one\n  line two',
+    'carriage\rreturn',
+    'Windows\r\nline',
+    'Привет 🌍',
+  ];
+  for (const text of references) {
+    const escaped = lino.escapeReference(text, { minimal: true });
+    expect(lino.unescapeReference(escaped)).toBe(text);
+    expect(Link.unescapeReference(escaped)).toBe(text);
+    const entries = new Map([[text, text]]);
+    expect(
+      lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+    ).toEqual(entries);
+  }
+});
+
+test('unescaping uses the grammar and never decodes already parsed IDs again', () => {
+  expect(lino.unescapeReference('"He said ""hello"""')).toBe('He said "hello"');
+  expect(lino.unescapeReference("'it''s ready'")).toBe("it's ready");
+  expect(lino.unescapeReference('``text with ` inside``')).toBe(
+    'text with ` inside'
+  );
+  expect(lino.unescapeReference('plain text')).toBe('plain text');
+  expect(lino.unescapeReference('literal \\n')).toBe('literal \\n');
+  expect(() => lino.unescapeReference('"unfinished')).toThrow(SyntaxError);
+  expect(() => lino.unescapeReference('"value" extra')).toThrow(SyntaxError);
+  expect(lino.parseIndentedDocument('Question\n  "two \'\' quotes"')).toEqual(
+    new Map([['Question', "two '' quotes"]])
+  );
+});
+
+test('document helpers reject deeper or named value structures instead of losing data', () => {
+  expect(() =>
+    lino.parseIndentedDocument('Question\n  Answer\n    Detail')
+  ).toThrow(TypeError);
+  expect(() => lino.parseIndentedDocument('Question\n  answer: value')).toThrow(
+    TypeError
+  );
+  expect(() =>
+    lino.formatIndentedDocument(new Map([['Question', 42]]))
+  ).toThrow(TypeError);
+  expect(() => lino.formatIndentedDocument(new Map([[42, 'Answer']]))).toThrow(
+    TypeError
+  );
+  expect(() =>
+    lino.formatIndentedDocument(new Map([['Question', ['ok', null]]]))
+  ).toThrow(TypeError);
+});
+
+test('document parsing respects comments and existing parser options', () => {
+  expect(
+    lino.parseIndentedDocument('# comment\nQuestion\n  Answer # comment')
+  ).toEqual(new Map([['Question', 'Answer']]));
+  expect(
+    lino.parseIndentedDocument('# question\n  Answer', { comments: false })
+  ).toEqual(new Map([['# question', 'Answer']]));
+});
+
+test('one-element arrays normalize to strings and unanswered parents remain distinct', () => {
+  const entries = new Map([
+    ['One option', ['only']],
+    ['No options', []],
+    ['Empty answer', ''],
+  ]);
+  expect(
+    lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+  ).toEqual(
+    new Map([
+      ['One option', 'only'],
+      ['No options', []],
+      ['Empty answer', ''],
+    ])
+  );
+  expect(() =>
+    lino.formatIndentedDocument(new Map([['Question', Array(1)]]))
+  ).toThrow(TypeError);
+});
+
+test('document helpers preserve the shared Unicode reference corpus and reserved prefixes', () => {
+  const references = readFileSync(
+    new globalThis.URL(
+      '../../docs/protocol/reference-literals.txt',
+      import.meta.url
+    ),
+    'utf8'
+  )
+    .trim()
+    .split('\n')
+    .filter((line) => !line.startsWith('#'))
+    .map((hex) =>
+      hex === '-' ? '' : Buffer.from(hex, 'hex').toString('utf8')
+    );
+  for (const text of [
+    ...references,
+    '~1{61}',
+    '~2{00}',
+    '~1{invalid}',
+    'text ~1{61} after',
+    'text ~2{00}',
+    'text ~1{invalid}',
+  ]) {
+    expect(lino.escapeReference(text)).toBe(lino.formatBinaryReference(text));
+    expect(lino.unescapeReference(lino.escapeReference(text))).toBe(text);
+    expect(
+      lino.unescapeReference(lino.escapeReference(text, { minimal: true }))
+    ).toBe(text);
+    const entries = new Map([[text, text]]);
+    expect(
+      lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+    ).toEqual(entries);
+  }
+});
+
+test('unescaping decodes versioned literals without decoding parsed document IDs twice', () => {
+  expect(lino.unescapeReference('~1{}')).toBe('');
+  expect(Link.unescapeReference('~1{00}')).toBe('\0');
+  expect(lino.unescapeReference('~1{C3A9}')).toBe('é');
+  for (const literal of ['~2{61}', '~1{0}', '~1{gg}', '~1{ff}']) {
+    expect(() => lino.unescapeReference(literal)).toThrow();
+  }
+  const entries = new Map([['~1{61}', '~1{62}']]);
+  expect(
+    lino.parseIndentedDocument(lino.formatIndentedDocument(entries))
+  ).toEqual(entries);
+  expect(() => lino.escapeReference('\ud800', { minimal: true })).toThrow(
+    TypeError
+  );
+});