links-notation 0.23.0 → 0.25.0

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. */
@@ -561,3 +613,8 @@ export class BinaryLinoCodec {
 }
 export function formatBinaryDocument(document: Link[]): string;
 export function formatBinaryReference(reference: string): string;
+
+/** Encode exact Unicode as a version 1 UTF-8 hex literal (~1{...}). Throws on unpaired surrogates. */
+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;

package/package.json

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

package/src/Binary.js

@@ -1,5 +1,6 @@
 /** Binary links notation v1. Packet and document layers share no transport. */
 import { Link } from './Link.js';
+import { formatReference } from './ReferenceLiteral.js';
 import { Parser } from './Parser.js';
 
 const U64 = (1n << 64n) - 1n;
@@ -695,26 +696,7 @@ function canonical(node) {
   return new Link(node.id, node.values.map(canonical));
 }
 export function formatBinaryReference(text) {
-  if (
-    text &&
-    !text.startsWith('#') &&
-    !/[\p{White_Space}\u001c-\u001f\ufeff():"'`]/u.test(text)
-  )
-    return text;
-  let choice = null;
-  for (const quote of ["'", '"', '`'])
-    if (!text.startsWith(quote)) {
-      let longest = 0,
-        run = 0;
-      for (const c of text) {
-        run = c === quote ? run + 1 : 0;
-        longest = Math.max(longest, run);
-      }
-      const count = (longest + 1) | 1;
-      if (choice === null || count < choice.count) choice = { quote, count };
-    }
-  const delimiter = choice.quote.repeat(choice.count);
-  return delimiter + text + delimiter;
+  return formatReference(text);
 }
 export function formatBinaryDocument(document) {
   function nested(node, top = false) {

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,3 +1,5 @@
+import { escapeReference, unescapeReference } from './references.js';
+
 export class Link {
   /**
    * Create a new Link
@@ -79,60 +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 '';
-    }
-
-    // The empty reference is written as a bare delimiter pair, so that it reads
-    // back as itself instead of disappearing from the document.
-    if (reference === '') {
-      return '""';
-    }
-
-    const hasSingleQuote = reference.includes("'");
-    const hasDoubleQuote = reference.includes('"');
-
-    // A reference that begins with a `#` has to be quoted, or it would read
-    // back as a comment. A `#` anywhere else in a reference is content
-    // (`issue#1047`), so only the first character matters.
-    const needsQuoting =
-      reference.startsWith('#') ||
-      reference.includes(':') ||
-      reference.includes('(') ||
-      reference.includes(')') ||
-      reference.includes(' ') ||
-      reference.includes('\t') ||
-      reference.includes('\n') ||
-      reference.includes('\r') ||
-      hasDoubleQuote ||
-      hasSingleQuote;
-
-    // Handle edge case: reference contains both single and double quotes
-    if (hasSingleQuote && hasDoubleQuote) {
-      // Escape single quotes and wrap in single quotes
-      return `'${reference.replace(/'/g, "\\'")}'`;
-    }
-
-    // Prefer single quotes if double quotes are present
-    if (hasDoubleQuote) {
-      return `'${reference}'`;
-    }
-
-    // Use double quotes if single quotes are present
-    if (hasSingleQuote) {
-      return `"${reference}"`;
-    }
-
-    // Use single quotes for special characters
-    if (needsQuoting) {
-      return `'${reference}'`;
-    }
+  static escapeReference(reference, options = {}) {
+    return escapeReference(reference, options);
+  }
 
-    // No quoting needed
-    return 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/ReferenceLiteral.js

@@ -0,0 +1,66 @@
+/* global TextEncoder, TextDecoder */
+
+/** Detect the reserved versioned-literal prefix at a reference boundary. */
+export function hasReferenceLiteralPrefix(text, start = 0) {
+  return /^~[0-9]+\{/.test(text.slice(start));
+}
+
+/** Encode exact Unicode text as a version 1 UTF-8 hexadecimal reference. */
+export function encodeReferenceLiteral(text) {
+  if (typeof text !== 'string' || !text.isWellFormed()) {
+    throw new TypeError('Reference must be well-formed Unicode text');
+  }
+  const hex = Array.from(new TextEncoder().encode(text), (byte) =>
+    byte.toString(16).padStart(2, '0')
+  ).join('');
+  return `~1{${hex}}`;
+}
+
+/** Decode a complete versioned literal, rejecting malformed bytes and versions. */
+export function decodeReferenceLiteral(literal) {
+  const match = /^~([0-9]+)\{([0-9a-fA-F]*)\}$/.exec(literal);
+  if (
+    !match ||
+    match[0] !== literal ||
+    match[1] !== '1' ||
+    match[2].length % 2 !== 0
+  ) {
+    throw new TypeError(
+      'Invalid or unsupported reference literal (expected ~1{UTF-8 hex})'
+    );
+  }
+  return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(
+    Uint8Array.from(match[2].match(/../g) ?? [], (hex) => parseInt(hex, 16))
+  );
+}
+
+/** Use readable legacy quoting where possible and a literal for empty/control text. */
+export function formatReference(text) {
+  if (typeof text !== 'string' || !text.isWellFormed()) {
+    throw new TypeError('Reference must be well-formed Unicode text');
+  }
+  if (!text || /[\u0000-\u001f\u007f]/u.test(text)) {
+    return encodeReferenceLiteral(text);
+  }
+  if (
+    !text.startsWith('#') &&
+    !/^~[0-9]+\{/.test(text) &&
+    !/[\p{White_Space}\ufeff():"'`]/u.test(text)
+  ) {
+    return text;
+  }
+  let choice = null;
+  for (const quote of ["'", '"', '`']) {
+    if (text.startsWith(quote)) continue;
+    let longest = 0;
+    let run = 0;
+    for (const character of text) {
+      run = character === quote ? run + 1 : 0;
+      longest = Math.max(longest, run);
+    }
+    const count = (longest + 1) | 1;
+    if (choice === null || count < choice.count) choice = { quote, count };
+  }
+  const delimiter = choice.quote.repeat(choice.count);
+  return delimiter + text + delimiter;
+}

package/src/grammar.pegjs

@@ -1,5 +1,6 @@
 {{
   import { DelimitedReferences } from './quotes.js';
+  import { decodeReferenceLiteral, hasReferenceLiteralPrefix } from './ReferenceLiteral.js';
 }}
 
 {
@@ -217,9 +218,18 @@ indentedIdLink = id:reference __ ":" eol { return { id: id, values: [] }; }
 
 // Reference can be quoted (with any number of quotes N >= 1) or simple unquoted
 // Universal approach: use procedural parsing for all quote types and counts
-reference = quotedReference / simpleReference
+reference = referenceLiteral / quotedReference / simpleReference
+
+// Versioned literals reserve ~<version>{<UTF-8 hex>} at a reference boundary.
+// A malformed reserved token must fail rather than fall back to a bare name.
+referenceLiteral = &'~' &{
+  return hasReferenceLiteralPrefix(input, offset());
+} literal:$('~' [0-9]+ '{' [^} \t\r\n()]* '}') {
+  return decodeReferenceLiteral(literal);
+}
 
-simpleReference = chars:referenceSymbol+ { return chars.join(''); }
+simpleReference = &{ return !hasReferenceLiteralPrefix(input, offset()); }
+ chars:referenceSymbol+ { return chars.join(''); }
 
 // Universal quoted reference - handles any N quotes for all quote types
 // Uses procedural parsing with input/offset() for clean, simple logic

package/src/index.js

@@ -1,4 +1,13 @@
 export { Link, formatLinks } from './Link.js';
+export { escapeReference, unescapeReference } from './references.js';
+export {
+  parseIndentedDocument,
+  formatIndentedDocument,
+} from './IndentedDocument.js';
+export {
+  encodeReferenceLiteral,
+  decodeReferenceLiteral,
+} from './ReferenceLiteral.js';
 export { LinksGroup } from './LinksGroup.js';
 export { Parser, DEFAULT_MAX_DEPTH } from './Parser.js';
 export { StreamParseError, StreamParser } from './StreamParser.js';