links-notation 0.27.1 → 0.30.0

package/src/comments.js

@@ -13,23 +13,35 @@
  */
 
 import { DelimitedReferences, QUOTES, readReference } from './quotes.js';
+import { referenceLiteralEnd } from './ReferenceLiteral.js';
 
 /** The character that starts a comment. */
 export const COMMENT = '#';
 
-/** What a delimited reference may start after. */
-const BEFORE_REFERENCE = [' ', '\t', '\n', '\r', '(', ':'];
+/**
+ * What ends a bare reference. A token starts after one of these, at the start
+ * of the document, and right after a delimited reference or a versioned
+ * literal: the places the grammar reads a reference from.
+ */
+const SEPARATORS = [' ', '\t', '\n', '\r', '(', ':', ')'];
 
 /** What a comment may start after. */
 const BEFORE_COMMENT = [' ', '\t', '\n', '\r'];
 
 /**
  * The document with every comment blanked out.
+ *
+ * The document is read token by token, the way the grammar reads it, so a `#`
+ * inside a delimited reference that starts right after a group, another
+ * reference or a literal is content, as it is in one that starts after a
+ * space. References are read in the document as written, as the grammar
+ * reads them.
  * @param {string} document - The document to read
  * @returns {string} The document, of the same length, without its comments
  * @example
  * stripComments('a: b # why\n'); // 'a: b      \n'
  * stripComments('"# kept"\n'); // '"# kept"\n'
+ * stripComments('(a)" #kept"\n'); // '(a)" #kept"\n'
  * stripComments('issue#1047\n'); // 'issue#1047\n'
  */
 export function stripComments(document) {
@@ -37,20 +49,13 @@ export function stripComments(document) {
   // parse error reports are both counted in.
   let blanked = null;
   let position = 0;
+  // Whether a token may start at `position`.
+  let tokenStart = true;
   const references = new DelimitedReferences(document);
 
   while (position < document.length) {
     const character = document[position];
 
-    if (
-      QUOTES.includes(character) &&
-      follows(document, position, BEFORE_REFERENCE)
-    ) {
-      const end = references.endAt(position);
-      position = end === null ? position + 1 : end;
-      continue;
-    }
-
     if (character === COMMENT && follows(document, position, BEFORE_COMMENT)) {
       blanked = blanked ?? document.split('');
       while (
@@ -64,12 +69,46 @@ export function stripComments(document) {
       continue;
     }
 
+    if (SEPARATORS.includes(character)) {
+      tokenStart = true;
+      position++;
+      continue;
+    }
+
+    if (tokenStart) {
+      const end = delimitedTokenEnd(document, position, references);
+      if (end !== null) {
+        position = end;
+        continue;
+      }
+    }
+
+    // Anything else is part of a bare reference, which runs to a separator.
+    tokenStart = false;
     position++;
   }
 
   return blanked === null ? document : blanked.join('');
 }
 
+/**
+ * The position just past the delimited reference or versioned literal that
+ * starts the token at `start`, or `null` when the token there is a bare
+ * reference: a delimiter run that never closes is read as one, as the grammar
+ * reads it.
+ * @param {string} document - The document being read
+ * @param {number} start - Position where a token starts
+ * @param {DelimitedReferences} references - The references of the document
+ * @returns {number|null} The position just past the token
+ */
+export function delimitedTokenEnd(document, start, references) {
+  const literal = referenceLiteralEnd(document, start);
+  if (literal !== -1) {
+    return literal;
+  }
+  return QUOTES.includes(document[start]) ? references.endAt(start) : null;
+}
+
 /**
  * Whether the character before the given position is one the caller allows,
  * the start of the document counting as allowed.

package/src/grammar.pegjs

@@ -16,6 +16,8 @@
   // until the stack overflows.
   let contextDepth = 0;
   const maxDepth = options.maxDepth ?? Infinity;
+  // The document as the caller wrote it, comments included.
+  const source = options.source ?? input;
   // Lines already found unreadable, keyed by where they start and whether they
   // are inside a parenthesised group. Reading a line depends on nothing else: a
   // group starts a fresh indentation context, and indentation only decides
@@ -115,8 +117,10 @@
   }
 
   // Delimited references of this document, each read once however many
-  // alternatives ask for it (see quotes.js for how a reference is read)
-  const delimitedReferences = new DelimitedReferences(input);
+  // alternatives ask for it (see quotes.js for how a reference is read). They
+  // are read in the document as written, as the comment reader reads them, so
+  // blanking a comment never changes how far a reference reaches (issue #377).
+  const delimitedReferences = new DelimitedReferences(source);
 
   // Universal procedural parser for N-quote strings (any N >= 1)
   // Parses from the given position in the input string
@@ -164,7 +168,7 @@ element = &{ return !unreadableLines.has(lineKey(offset())); }
   // succeed without consuming input.
   / &{ unreadableLines.add(lineKey(offset())); return false; } .
 
-referenceOrLink = l:multiLineAnyLink { return l; } / i:reference { return { id: i }; }
+referenceOrLink = l:multiLineAnyLink { return l; } / r:reference { return { id: r.value, rawId: r.raw }; }
 
 // A line that starts with a parenthesised group reads that group once and then
 // branches on what follows it: the end of the line makes the group the whole
@@ -210,15 +214,24 @@ singleLineValueAndWhitespace = __ value:referenceOrLink { return value; }
 
 singleLineValues = list:singleLineValueAndWhitespace+ { return list; }
 
-singleLineLink = __ id:reference __ ":" v:singleLineValues { return { id: id, values: v }; }
+singleLineLink = __ id:reference __ ":" v:singleLineValues { return { id: id.value, rawId: id.raw, values: v }; }
 
 singleLineValueLink = v:singleLineValues { return { values: v }; }
 
-indentedIdLink = id:reference __ ":" eol { return { id: id, values: [] }; }
+indentedIdLink = id:reference __ ":" eol { return { id: id.value, rawId: id.raw, values: [] }; }
+
+// A reference is read as its value together with the text it was written as,
+// so a parsed link can say whether its ID was bare, quoted or a literal. The
+// text is taken from the document as the caller wrote it, which keeps the same
+// offsets as the document with its comments blanked out.
+reference = value:referenceValue {
+    const { start, end } = range();
+    return { value: value, raw: source.slice(start, end) };
+  }
 
 // 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 = referenceLiteral / quotedReference / simpleReference
+referenceValue = 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.

package/src/index.js

@@ -1,5 +1,10 @@
 export { Link, formatLinks } from './Link.js';
-export { escapeReference, unescapeReference } from './references.js';
+export {
+  escapeReference,
+  unescapeReference,
+  referenceQuote,
+} from './references.js';
+export { CstKind, CstNode } from './Cst.js';
 export {
   parseIndentedDocument,
   formatIndentedDocument,