links-notation 0.22.0 → 0.24.0

package/src/Link.js

@@ -1,3 +1,5 @@
+import { formatReference } from './ReferenceLiteral.js';
+
 export class Link {
   /**
    * Create a new Link
@@ -86,53 +88,7 @@ export class Link {
       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}'`;
-    }
-
-    // No quoting needed
-    return reference;
+    return formatReference(reference);
   }
 
   /**

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,8 @@
 export { Link, formatLinks } from './Link.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';
@@ -6,3 +10,15 @@ export { ParseError } from './ParseError.js';
 export { FormatConfig } from './FormatConfig.js';
 export { FormatOptions } from './FormatOptions.js';
 export { stripComments } from './comments.js';
+export {
+  ArityRange,
+  BinaryLinoCodec,
+  BinaryLinoOptions,
+  DecodeLimits,
+  External,
+  LinksPacket,
+  PacketReader,
+  Section,
+  formatBinaryDocument,
+  formatBinaryReference,
+} from './Binary.js';