links-notation 0.12.0 → 0.15.0

package/src/Link.js

@@ -32,8 +32,9 @@ export class Link {
    * @returns {string} Space-separated string of values
    */
   getValuesString() {
-    return (!this.values || this.values.length === 0) ?
-      '' : this.values.map(v => Link.getValueString(v)).join(' ');
+    return !this.values || this.values.length === 0
+      ? ''
+      : this.values.map((v) => Link.getValueString(v)).join(' ');
   }
 
   /**
@@ -46,7 +47,7 @@ export class Link {
     } else if (this.values.length === 1) {
       return this.values[0];
     } else {
-      const newValues = this.values.map(v => {
+      const newValues = this.values.map((v) => {
         // Check if value has simplify method (defensive programming)
         return v && typeof v.simplify === 'function' ? v.simplify() : v;
       });
@@ -70,7 +71,9 @@ export class Link {
    */
   static getValueString(value) {
     // Defensive check for method existence
-    return value && typeof value.toLinkOrIdString === 'function' ? value.toLinkOrIdString() : String(value);
+    return value && typeof value.toLinkOrIdString === 'function'
+      ? value.toLinkOrIdString()
+      : String(value);
   }
 
   /**
@@ -79,10 +82,16 @@ export class Link {
    * @returns {string} Escaped reference
    */
   static escapeReference(reference) {
-    if (!reference || reference.trim() === '') {
+    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('"');
 
@@ -164,7 +173,6 @@ export class Link {
     return true;
   }
 
-
   /**
    * Format the link as a string
    * @param {boolean|FormatOptions} lessParentheses - If true, omit parentheses where safe; or a FormatOptions object
@@ -174,8 +182,12 @@ export class Link {
   format(lessParentheses = false, isCompoundValue = false) {
     // Support FormatOptions/FormatConfig as first parameter
     // Check if it's an object with formatting properties (FormatOptions or FormatConfig)
-    if (lessParentheses && typeof lessParentheses === 'object' &&
-        (lessParentheses.constructor.name === 'FormatOptions' || lessParentheses.constructor.name === 'FormatConfig')) {
+    if (
+      lessParentheses &&
+      typeof lessParentheses === 'object' &&
+      (lessParentheses.constructor.name === 'FormatOptions' ||
+        lessParentheses.constructor.name === 'FormatConfig')
+    ) {
       return this._formatWithOptions(lessParentheses, isCompoundValue);
     }
 
@@ -184,7 +196,7 @@ export class Link {
     if (this.id === null && (!this.values || this.values.length === 0)) {
       return lessParentheses ? '' : '()';
     }
-    
+
     // Link with only ID, no values
     if (!this.values || this.values.length === 0) {
       const escapedId = Link.escapeReference(this.id);
@@ -192,21 +204,27 @@ export class Link {
       if (isCompoundValue) {
         return `(${escapedId})`;
       }
-      return lessParentheses && !this.needsParentheses(this.id) ? escapedId : `(${escapedId})`;
+      return lessParentheses && !this.needsParentheses(this.id)
+        ? escapedId
+        : `(${escapedId})`;
     }
-    
-    // Format values recursively  
-    const valuesStr = this.values.map(v => this.formatValue(v)).join(' ');
-    
+
+    // Format values recursively
+    const valuesStr = this.values.map((v) => this.formatValue(v)).join(' ');
+
     // Link with values only (null id)
     if (this.id === null) {
       // For lessParentheses mode with simple values, don't wrap the whole thing
       if (lessParentheses) {
         // Check if all values are simple (no nested values)
-        const allSimple = this.values.every(v => !v.values || v.values.length === 0);
+        const allSimple = this.values.every(
+          (v) => !v.values || v.values.length === 0
+        );
         if (allSimple) {
           // Format each value without extra wrapping
-          const simpleValuesStr = this.values.map(v => Link.escapeReference(v.id)).join(' ');
+          const simpleValuesStr = this.values
+            .map((v) => Link.escapeReference(v.id))
+            .join(' ');
           return simpleValuesStr;
         }
         // For mixed or complex values in lessParentheses mode, still avoid outer wrapper
@@ -216,13 +234,15 @@ export class Link {
       // For normal mode, wrap in parentheses
       return `(${valuesStr})`;
     }
-    
+
     // Link with ID and values
     const idStr = Link.escapeReference(this.id);
     const withColon = `${idStr}: ${valuesStr}`;
-    return lessParentheses && !this.needsParentheses(this.id) ? withColon : `(${withColon})`;
+    return lessParentheses && !this.needsParentheses(this.id)
+      ? withColon
+      : `(${withColon})`;
   }
-  
+
   /**
    * Format a value within this link
    * @param {Link} value - The value to format
@@ -257,7 +277,13 @@ export class Link {
    * @returns {boolean} True if parentheses are needed
    */
   needsParentheses(str) {
-    return str && (str.includes(' ') || str.includes(':') || str.includes('(') || str.includes(')'));
+    return (
+      str &&
+      (str.includes(' ') ||
+        str.includes(':') ||
+        str.includes('(') ||
+        str.includes(')'))
+    );
   }
 
   /**
@@ -278,7 +304,9 @@ export class Link {
       if (isCompoundValue) {
         return `(${escapedId})`;
       }
-      return options.lessParentheses && !this.needsParentheses(this.id) ? escapedId : `(${escapedId})`;
+      return options.lessParentheses && !this.needsParentheses(this.id)
+        ? escapedId
+        : `(${escapedId})`;
     }
 
     // Check if we should use indented format
@@ -287,11 +315,13 @@ export class Link {
       shouldIndent = true;
     } else {
       // Try inline format first
-      const valuesStr = this.values.map(v => this.formatValue(v)).join(' ');
+      const valuesStr = this.values.map((v) => this.formatValue(v)).join(' ');
       let testLine;
       if (this.id !== null) {
         const idStr = Link.escapeReference(this.id);
-        testLine = options.lessParentheses ? `${idStr}: ${valuesStr}` : `(${idStr}: ${valuesStr})`;
+        testLine = options.lessParentheses
+          ? `${idStr}: ${valuesStr}`
+          : `(${idStr}: ${valuesStr})`;
       } else {
         testLine = options.lessParentheses ? valuesStr : `(${valuesStr})`;
       }
@@ -307,14 +337,16 @@ export class Link {
     }
 
     // Standard inline formatting
-    const valuesStr = this.values.map(v => this.formatValue(v)).join(' ');
+    const valuesStr = this.values.map((v) => this.formatValue(v)).join(' ');
 
     // Link with values only (null id)
     if (this.id === null) {
       if (options.lessParentheses) {
-        const allSimple = this.values.every(v => !v.values || v.values.length === 0);
+        const allSimple = this.values.every(
+          (v) => !v.values || v.values.length === 0
+        );
         if (allSimple) {
-          return this.values.map(v => Link.escapeReference(v.id)).join(' ');
+          return this.values.map((v) => Link.escapeReference(v.id)).join(' ');
         }
         return valuesStr;
       }
@@ -324,7 +356,9 @@ export class Link {
     // Link with ID and values
     const idStr = Link.escapeReference(this.id);
     const withColon = `${idStr}: ${valuesStr}`;
-    return options.lessParentheses && !this.needsParentheses(this.id) ? withColon : `(${withColon})`;
+    return options.lessParentheses && !this.needsParentheses(this.id)
+      ? withColon
+      : `(${withColon})`;
   }
 
   /**
@@ -335,7 +369,9 @@ 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));
+      const lines = this.values.map(
+        (v) => options.indentString + this.formatValue(v)
+      );
       return lines.join('\n');
     }
 
@@ -373,7 +409,11 @@ function _groupConsecutiveLinks(links) {
 
       while (j < links.length) {
         const nextLink = links[j];
-        if (nextLink.id === current.id && nextLink.values && nextLink.values.length > 0) {
+        if (
+          nextLink.id === current.id &&
+          nextLink.values &&
+          nextLink.values.length > 0
+        ) {
           sameIdValues.push(...nextLink.values);
           j++;
         } else {
@@ -401,17 +441,21 @@ export function formatLinks(links, lessParentheses = false) {
   if (!links || links.length === 0) return '';
 
   // Support FormatOptions/FormatConfig as parameter
-  if (lessParentheses && typeof lessParentheses === 'object' &&
-      (lessParentheses.constructor.name === 'FormatOptions' || lessParentheses.constructor.name === 'FormatConfig')) {
+  if (
+    lessParentheses &&
+    typeof lessParentheses === 'object' &&
+    (lessParentheses.constructor.name === 'FormatOptions' ||
+      lessParentheses.constructor.name === 'FormatConfig')
+  ) {
     const options = lessParentheses;
     // Apply consecutive link grouping if enabled
     let linksToFormat = links;
     if (options.groupConsecutive) {
       linksToFormat = _groupConsecutiveLinks(links);
     }
-    return linksToFormat.map(link => link.format(options)).join('\n');
+    return linksToFormat.map((link) => link.format(options)).join('\n');
   }
 
   // Backward compatibility with boolean parameter
-  return links.map(link => link.format(lessParentheses)).join('\n');
-}
+  return links.map((link) => link.format(lessParentheses)).join('\n');
+}

package/src/LinksGroup.js

@@ -25,6 +25,6 @@ export class LinksGroup {
 
   toString() {
     const list = this.toList();
-    return list.map(item => `(${item.id || item})`).join(' ');
+    return list.map((item) => `(${item.id || item})`).join(' ');
   }
-}
+}

package/src/Parser.js

@@ -26,7 +26,9 @@ export class Parser {
     }
 
     if (input.length > this.maxInputSize) {
-      throw new Error(`Input size exceeds maximum allowed size of ${this.maxInputSize} bytes`);
+      throw new Error(
+        `Input size exceeds maximum allowed size of ${this.maxInputSize} bytes`
+      );
     }
 
     try {
@@ -62,7 +64,11 @@ export class Parser {
     if (item.children && item.children.length > 0) {
       // Special case: If this is an ID with empty values but has children,
       // the children should become the values of the link (indented ID syntax)
-      if (item.id && (!item.values || item.values.length === 0)) {
+      if (
+        item.id !== undefined &&
+        item.id !== null &&
+        (!item.values || item.values.length === 0)
+      ) {
         const childValues = item.children.map((child) => {
           // For indented children, extract the actual reference from the child's values
           if (child.values && child.values.length === 1) {
@@ -72,10 +78,10 @@ export class Parser {
         });
         const linkWithChildren = {
           id: item.id,
-          values: childValues
+          values: childValues,
         };
         const currentLink = this.transformLink(linkWithChildren);
-        
+
         if (parentPath.length === 0) {
           result.push(currentLink);
         } else {
@@ -84,17 +90,17 @@ export class Parser {
       } else {
         // Regular indented structure - process as before
         const currentLink = this.transformLink(item);
-        
+
         // Add the link combined with parent path
         if (parentPath.length === 0) {
           result.push(currentLink);
         } else {
           result.push(this.combinePathElements(parentPath, currentLink));
         }
-        
+
         // Process each child with this item in the path
         const newPath = [...parentPath, currentLink];
-        
+
         for (const child of item.children) {
           this.collectLinks(child, newPath, result);
         }
@@ -102,7 +108,7 @@ export class Parser {
     } else {
       // Leaf item or item with inline values
       const currentLink = this.transformLink(item);
-      
+
       if (parentPath.length === 0) {
         result.push(currentLink);
       } else {
@@ -110,7 +116,7 @@ export class Parser {
       }
     }
   }
-  
+
   combinePathElements(pathElements, current) {
     if (pathElements.length === 0) return current;
     if (pathElements.length === 1) {
@@ -118,21 +124,44 @@ export class Parser {
       combined._isFromPathCombination = true;
       return combined;
     }
-    
+
     // For multiple path elements, we need to build proper nesting
     // The last element in the path should be combined with its parent
     const parentPath = pathElements.slice(0, -1);
     const lastElement = pathElements[pathElements.length - 1];
-    
+
     // Build the parent structure
     let parent = this.combinePathElements(parentPath, lastElement);
-    
+
     // Add current element to the built structure
     const combined = new Link(null, [parent, current]);
     combined._isFromPathCombination = true;
     return combined;
   }
-  
+
+  /**
+   * Transform the links of a nested (parenthesised) context into a single Link.
+   * The nested context is parsed with the same rules as the root, so it yields
+   * a list of links; a single link is used as is, several links become the
+   * values of one anonymous link. An already parenthesised single link keeps
+   * its own group so that `((a b))` stays distinct from `(a b)`.
+   * @param {Array} nested - Raw items parsed inside the parentheses
+   * @returns {Link} The link representing the parenthesised group
+   */
+  transformNested(nested) {
+    const nestedLinks = [];
+    for (const item of nested) {
+      if (item !== null && item !== undefined) {
+        this.collectLinks(item, [], nestedLinks);
+      }
+    }
+    const wrapsSingleGroup =
+      nested.length === 1 && nested[0] && nested[0].nested !== undefined;
+    if (nestedLinks.length === 1 && !wrapsSingleGroup) {
+      return nestedLinks[0];
+    }
+    return new Link(null, nestedLinks);
+  }
 
   /**
    * Transform a parsed item into a Link object
@@ -147,6 +176,11 @@ export class Parser {
       return item;
     }
 
+    // Parenthesised group parsed as a nested context
+    if (item.nested !== undefined) {
+      return this.transformNested(item.nested);
+    }
+
     // Handle simple reference objects like {id: 'a'}
     if (item.id !== undefined && !item.values && !item.children) {
       return new Link(item.id);
@@ -155,13 +189,12 @@ export class Parser {
     // For items with values, create a link with those values
     if (item.values && Array.isArray(item.values)) {
       // Create a link with id (if present) and transformed values
-      const link = new Link(item.id || null, []);
-      link.values = item.values.map(v => this.transformLink(v));
+      const link = new Link(item.id ?? null, []);
+      link.values = item.values.map((v) => this.transformLink(v));
       return link;
     }
 
     // Default case
-    return new Link(item.id || null, []);
+    return new Link(item.id ?? null, []);
   }
-
-}
+}

package/src/grammar.pegjs

@@ -1,6 +1,37 @@
 {
   let indentationStack = [0];
   let baseIndentation = null;
+  // Saved indentation contexts of the enclosing scopes. Every parenthesised
+  // group opens a nested context that starts fresh at indentation level zero,
+  // so line breaks and indentation mean the same thing at every depth.
+  let contextStack = [];
+
+  function resetState() {
+    indentationStack = [0];
+    baseIndentation = null;
+    contextStack = [];
+    return true;
+  }
+
+  function enterNestedContext() {
+    contextStack.push({ indentationStack, baseIndentation });
+    indentationStack = [0];
+    baseIndentation = null;
+    return true;
+  }
+
+  function exitNestedContext() {
+    const saved = contextStack.pop();
+    if (saved) {
+      indentationStack = saved.indentationStack;
+      baseIndentation = saved.baseIndentation;
+    }
+    return true;
+  }
+
+  function isInsideNestedContext() {
+    return contextStack.length > 0;
+  }
 
   function setBaseIndentation(spaces) {
     if (baseIndentation === null) {
@@ -34,10 +65,97 @@
   function getCurrentIndentation() {
     return indentationStack[indentationStack.length - 1];
   }
+
+  // A body written between an even run of delimiters is substantive when it
+  // holds at least one visible character and does not straddle a parenthesis.
+  // An even run can always be read as delimiter pairs enclosing nothing, so the
+  // n-quote reading is only taken when it carries something the pairs cannot.
+  function isSubstantiveBody(content) {
+    let depth = 0;
+    let hasVisible = false;
+
+    for (const c of content) {
+      if (c === '(') {
+        depth++;
+      } else if (c === ')') {
+        depth--;
+        if (depth < 0) {
+          return false;
+        }
+      }
+      if (!/\s/.test(c)) {
+        hasVisible = true;
+      }
+    }
+
+    return hasVisible && depth === 0;
+  }
+
+  // Universal procedural parser for N-quote strings (any N >= 1)
+  // Parses from the given position in the input string
+  // A run of an even number of delimiters that does not open a reference with a
+  // substantive body is the empty reference: the shortest reading, a bare
+  // delimiter pair enclosing nothing, wins over a longer n-quote delimiter.
+  // Returns { value, length } or null
+  function parseQuotedStringAt(inputStr, startPos, quoteChar) {
+    if (startPos >= inputStr.length || inputStr[startPos] !== quoteChar) {
+      return null;
+    }
+
+    // Count opening quotes
+    let quoteCount = 0;
+    let pos = startPos;
+    while (pos < inputStr.length && inputStr[pos] === quoteChar) {
+      quoteCount++;
+      pos++;
+    }
+
+    const isEvenRun = quoteCount % 2 === 0;
+    const emptyReference = isEvenRun ? { value: '', length: quoteCount } : null;
+
+    const closeSeq = quoteChar.repeat(quoteCount);
+    const escapeSeq = quoteChar.repeat(quoteCount * 2);
+
+    let content = '';
+    while (pos < inputStr.length) {
+      // Check for escape sequence (2*N quotes)
+      if (inputStr.substr(pos, escapeSeq.length) === escapeSeq) {
+        content += closeSeq; // 2*N quotes become N quotes
+        pos += escapeSeq.length;
+        continue;
+      }
+
+      // Check for closing sequence (exactly N quotes)
+      if (inputStr.substr(pos, quoteCount) === closeSeq) {
+        // Verify it's exactly N quotes (not followed by more of same char)
+        const afterClose = pos + quoteCount;
+        if (afterClose >= inputStr.length || inputStr[afterClose] !== quoteChar) {
+          // Found valid closing
+          if (isEvenRun && !isSubstantiveBody(content)) {
+            return emptyReference;
+          }
+          return {
+            value: content,
+            length: afterClose - startPos
+          };
+        }
+      }
+
+      // Add character to content
+      content += inputStr[pos];
+      pos++;
+    }
+
+    return emptyReference; // No valid closing found
+  }
+
+  // Global state for passing parsed values between predicate and action
+  let parsedValue = null;
+  let parsedLength = 0;
 }
 
-document = &{ indentationStack = [0]; baseIndentation = null; return true; } skipEmptyLines links:links _ eof { return links; }
-  / &{ indentationStack = [0]; baseIndentation = null; return true; } _ eof { return []; }
+document = &{ return resetState(); } skipEmptyLines links:links _ eof { return links; }
+  / &{ return resetState(); } _ eof { return []; }
 
 skipEmptyLines = ([ \t]* [\r\n])*
 
@@ -48,7 +166,7 @@ firstLine = SET_BASE_INDENTATION l:element { return l; }
 line = CHECK_INDENTATION l:element { return l; }
 
 element = e:anyLink PUSH_INDENTATION l:links {
-    return { id: e.id, values: e.values, children: l };
+    return Object.assign({}, e, { children: l });
   }
   / e:anyLink { return e; }
 
@@ -56,14 +174,23 @@ referenceOrLink = l:multiLineAnyLink { return l; } / i:reference { return { id:
 
 anyLink = ml:multiLineAnyLink eol { return ml; } / il:indentedIdLink { return il; } / sl:singleLineAnyLink { return sl; }
 
-multiLineAnyLink = multiLineValueLink / multiLineLink
+multiLineAnyLink = nestedGroup
 
 singleLineAnyLink = fl:singleLineLink eol { return fl; }
   / vl:singleLineValueLink eol { return vl; }
 
-multiLineValueAndWhitespace = value:referenceOrLink _ { return value; }
+// A parenthesised group opens a nested context that follows exactly the same
+// rules as the root of the document: line breaks separate links and
+// indentation nests them, starting fresh at indentation level zero.
+nestedGroup = "(" ENTER_NESTED_CONTEXT body:nestedGroupBody {
+    exitNestedContext();
+    return body;
+  }
+
+nestedGroupBody = skipEmptyLines l:links _ ")" { return { nested: l }; }
+  / _ ")" { return { nested: [] }; }
 
-multiLineValues = _ list:multiLineValueAndWhitespace* { return list; }
+ENTER_NESTED_CONTEXT = &{ return enterNestedContext(); }
 
 singleLineValueAndWhitespace = __ value:referenceOrLink { return value; }
 
@@ -71,21 +198,65 @@ singleLineValues = list:singleLineValueAndWhitespace+ { return list; }
 
 singleLineLink = __ id:reference __ ":" v:singleLineValues { return { id: id, values: v }; }
 
-multiLineLink = "(" _ id:reference _ ":" v:multiLineValues _ ")" { return { id: id, values: v }; }
-
 singleLineValueLink = v:singleLineValues { return { values: v }; }
 
-multiLineValueLink = "(" v:multiLineValues _ ")" { return { values: v }; }
-
 indentedIdLink = id:reference __ ":" eol { return { id: id, values: [] }; }
 
-reference = doubleQuotedReference / singleQuotedReference / simpleReference 
+// 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
 
 simpleReference = chars:referenceSymbol+ { return chars.join(''); }
 
-doubleQuotedReference = '"' r:[^"]+ '"' { return r.join(''); }
+// Universal quoted reference - handles any N quotes for all quote types
+// Uses procedural parsing with input/offset() for clean, simple logic
+quotedReference = doubleQuotedUniversal / singleQuotedUniversal / backtickQuotedUniversal
+
+// Double quotes: peek at input, parse procedurally, consume exact chars
+doubleQuotedUniversal = &'"' &{
+  const pos = offset();
+  const result = parseQuotedStringAt(input, pos, '"');
+  if (result) {
+    parsedValue = result.value;
+    parsedLength = result.length;
+    return true;
+  }
+  return false;
+} chars:consumeDouble { return parsedValue; }
+
+// Consume exactly parsedLength characters for double quotes
+consumeDouble = c:. cs:consumeDoubleMore* { return [c].concat(cs).join(''); }
+consumeDoubleMore = &{ return parsedLength > 1 && (parsedLength--, true); } c:. { return c; }
+
+// Single quotes
+singleQuotedUniversal = &"'" &{
+  const pos = offset();
+  const result = parseQuotedStringAt(input, pos, "'");
+  if (result) {
+    parsedValue = result.value;
+    parsedLength = result.length;
+    return true;
+  }
+  return false;
+} chars:consumeSingle { return parsedValue; }
+
+consumeSingle = c:. cs:consumeSingleMore* { return [c].concat(cs).join(''); }
+consumeSingleMore = &{ return parsedLength > 1 && (parsedLength--, true); } c:. { return c; }
+
+// Backticks
+backtickQuotedUniversal = &'`' &{
+  const pos = offset();
+  const result = parseQuotedStringAt(input, pos, '`');
+  if (result) {
+    parsedValue = result.value;
+    parsedLength = result.length;
+    return true;
+  }
+  return false;
+} chars:consumeBacktick { return parsedValue; }
 
-singleQuotedReference = "'" r:[^']+ "'" { return r.join(''); }
+consumeBacktick = c:. cs:consumeBacktickMore* { return [c].concat(cs).join(''); }
+consumeBacktickMore = &{ return parsedLength > 1 && (parsedLength--, true); } c:. { return c; }
 
 SET_BASE_INDENTATION = spaces:" "* { setBaseIndentation(spaces); }
 
@@ -93,7 +264,11 @@ PUSH_INDENTATION = spaces:" "* &{ return normalizeIndentation(spaces) > getCurre
 
 CHECK_INDENTATION = spaces:" "* &{ return checkIndentation(spaces); }
 
-eol = __ ([\r\n]+ / eof)
+eol = __ ([\r\n]+ / eof / nestedGroupEnd)
+
+// Inside a parenthesised group the closing parenthesis terminates a line the
+// same way the end of the input does at the root.
+nestedGroupEnd = &{ return isInsideNestedContext(); } &")"
 
 eof = !.
 
@@ -103,4 +278,4 @@ _ = whiteSpaceSymbol*
 
 whiteSpaceSymbol = [ \t\n\r]
 
-referenceSymbol = [^ \t\n\r(:)]
+referenceSymbol = [^ \t\n\r(:)]

package/src/index.js

@@ -2,4 +2,4 @@ export { Link, formatLinks } from './Link.js';
 export { LinksGroup } from './LinksGroup.js';
 export { Parser } from './Parser.js';
 export { FormatConfig } from './FormatConfig.js';
-export { FormatOptions } from './FormatOptions.js';
+export { FormatOptions } from './FormatOptions.js';