links-notation 0.18.0 → 0.20.0

package/dist/index.js

@@ -44,7 +44,7 @@ class Link {
     }
     const hasSingleQuote = reference.includes("'");
     const hasDoubleQuote = reference.includes('"');
-    const needsQuoting = reference.includes(":") || reference.includes("(") || reference.includes(")") || reference.includes(" ") || reference.includes("\t") || reference.includes(`
+    const needsQuoting = reference.startsWith("#") || reference.includes(":") || reference.includes("(") || reference.includes(")") || reference.includes(" ") || reference.includes("\t") || reference.includes(`
 `) || reference.includes("\r") || hasDoubleQuote || hasSingleQuote;
     if (hasSingleQuote && hasDoubleQuote) {
       return `'${reference.replace(/'/g, "\\'")}'`;
@@ -320,6 +320,93 @@ function windowAround(lineText, column) {
   return [quoted, target - start + shift + 1];
 }
 
+// src/comments.js
+var COMMENT = "#";
+var QUOTES = ['"', "'", "`"];
+var BEFORE_REFERENCE = [" ", "\t", `
+`, "\r", "(", ":"];
+var BEFORE_COMMENT = [" ", "\t", `
+`, "\r"];
+function stripComments(document) {
+  let blanked = null;
+  let position = 0;
+  while (position < document.length) {
+    const character = document[position];
+    if (QUOTES.includes(character) && follows(document, position, BEFORE_REFERENCE)) {
+      const end = quotedReferenceEnd(document, position);
+      position = end === null ? position + 1 : end;
+      continue;
+    }
+    if (character === COMMENT && follows(document, position, BEFORE_COMMENT)) {
+      blanked = blanked ?? document.split("");
+      while (position < document.length && document[position] !== `
+` && document[position] !== "\r") {
+        blanked[position] = " ";
+        position++;
+      }
+      continue;
+    }
+    position++;
+  }
+  return blanked === null ? document : blanked.join("");
+}
+function follows(document, position, allowed) {
+  return position === 0 || allowed.includes(document[position - 1]);
+}
+function quotedReferenceEnd(document, start) {
+  const quote = document[start];
+  if (!QUOTES.includes(quote)) {
+    return null;
+  }
+  let position = start;
+  while (position < document.length && document[position] === quote) {
+    position++;
+  }
+  const count = position - start;
+  const isEvenRun = count % 2 === 0;
+  const emptyReference = isEvenRun ? start + count : null;
+  const closing = quote.repeat(count);
+  const escape = quote.repeat(count * 2);
+  let content = "";
+  while (position < document.length) {
+    if (document.startsWith(escape, position)) {
+      content += closing;
+      position += escape.length;
+      continue;
+    }
+    if (document.startsWith(closing, position)) {
+      const afterClosing = position + count;
+      if (afterClosing >= document.length || document[afterClosing] !== quote) {
+        if (isEvenRun && !isSubstantiveBody(content)) {
+          return emptyReference;
+        }
+        return afterClosing;
+      }
+    }
+    content += document[position];
+    position++;
+  }
+  return emptyReference;
+}
+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 (!/\s/.test(character)) {
+      hasVisible = true;
+    }
+  }
+  return hasVisible && depth === 0;
+}
+
 // src/parser-generated.js
 class peg$SyntaxError extends SyntaxError {
   constructor(message, expected, found, location) {
@@ -1751,42 +1838,189 @@ function peg$parse(input, options) {
     return s0;
   }
   function peg$parseeol() {
-    let s0, s1, s2, s3;
+    let s0, s1, s2;
     s0 = peg$currPos;
     s1 = peg$parse__();
-    s2 = [];
-    s3 = input.charAt(peg$currPos);
-    if (peg$r1.test(s3)) {
+    s2 = peg$parselineBreaks();
+    if (s2 === peg$FAILED) {
+      s2 = peg$parseeof();
+      if (s2 === peg$FAILED) {
+        s2 = peg$parsenestedGroupEnd();
+      }
+    }
+    if (s2 !== peg$FAILED) {
+      s1 = [s1, s2];
+      s0 = s1;
+    } else {
+      peg$currPos = s0;
+      s0 = peg$FAILED;
+    }
+    return s0;
+  }
+  function peg$parselineBreaks() {
+    let s0, s1, s2, s3, s4, s5, s6;
+    s0 = peg$currPos;
+    s1 = [];
+    s2 = input.charAt(peg$currPos);
+    if (peg$r1.test(s2)) {
       peg$currPos++;
     } else {
-      s3 = peg$FAILED;
+      s2 = peg$FAILED;
       if (peg$silentFails === 0) {
         peg$fail(peg$e1);
       }
     }
-    if (s3 !== peg$FAILED) {
-      while (s3 !== peg$FAILED) {
-        s2.push(s3);
-        s3 = input.charAt(peg$currPos);
-        if (peg$r1.test(s3)) {
+    if (s2 !== peg$FAILED) {
+      while (s2 !== peg$FAILED) {
+        s1.push(s2);
+        s2 = input.charAt(peg$currPos);
+        if (peg$r1.test(s2)) {
           peg$currPos++;
         } else {
-          s3 = peg$FAILED;
+          s2 = peg$FAILED;
           if (peg$silentFails === 0) {
             peg$fail(peg$e1);
           }
         }
       }
     } else {
-      s2 = peg$FAILED;
+      s1 = peg$FAILED;
     }
-    if (s2 === peg$FAILED) {
-      s2 = peg$parseeof();
-      if (s2 === peg$FAILED) {
-        s2 = peg$parsenestedGroupEnd();
+    if (s1 !== peg$FAILED) {
+      s2 = [];
+      s3 = peg$currPos;
+      s4 = [];
+      s5 = input.charAt(peg$currPos);
+      if (peg$r0.test(s5)) {
+        peg$currPos++;
+      } else {
+        s5 = peg$FAILED;
+        if (peg$silentFails === 0) {
+          peg$fail(peg$e0);
+        }
+      }
+      if (s5 !== peg$FAILED) {
+        while (s5 !== peg$FAILED) {
+          s4.push(s5);
+          s5 = input.charAt(peg$currPos);
+          if (peg$r0.test(s5)) {
+            peg$currPos++;
+          } else {
+            s5 = peg$FAILED;
+            if (peg$silentFails === 0) {
+              peg$fail(peg$e0);
+            }
+          }
+        }
+      } else {
+        s4 = peg$FAILED;
+      }
+      if (s4 !== peg$FAILED) {
+        s5 = [];
+        s6 = input.charAt(peg$currPos);
+        if (peg$r1.test(s6)) {
+          peg$currPos++;
+        } else {
+          s6 = peg$FAILED;
+          if (peg$silentFails === 0) {
+            peg$fail(peg$e1);
+          }
+        }
+        if (s6 !== peg$FAILED) {
+          while (s6 !== peg$FAILED) {
+            s5.push(s6);
+            s6 = input.charAt(peg$currPos);
+            if (peg$r1.test(s6)) {
+              peg$currPos++;
+            } else {
+              s6 = peg$FAILED;
+              if (peg$silentFails === 0) {
+                peg$fail(peg$e1);
+              }
+            }
+          }
+        } else {
+          s5 = peg$FAILED;
+        }
+        if (s5 !== peg$FAILED) {
+          s4 = [s4, s5];
+          s3 = s4;
+        } else {
+          peg$currPos = s3;
+          s3 = peg$FAILED;
+        }
+      } else {
+        peg$currPos = s3;
+        s3 = peg$FAILED;
+      }
+      while (s3 !== peg$FAILED) {
+        s2.push(s3);
+        s3 = peg$currPos;
+        s4 = [];
+        s5 = input.charAt(peg$currPos);
+        if (peg$r0.test(s5)) {
+          peg$currPos++;
+        } else {
+          s5 = peg$FAILED;
+          if (peg$silentFails === 0) {
+            peg$fail(peg$e0);
+          }
+        }
+        if (s5 !== peg$FAILED) {
+          while (s5 !== peg$FAILED) {
+            s4.push(s5);
+            s5 = input.charAt(peg$currPos);
+            if (peg$r0.test(s5)) {
+              peg$currPos++;
+            } else {
+              s5 = peg$FAILED;
+              if (peg$silentFails === 0) {
+                peg$fail(peg$e0);
+              }
+            }
+          }
+        } else {
+          s4 = peg$FAILED;
+        }
+        if (s4 !== peg$FAILED) {
+          s5 = [];
+          s6 = input.charAt(peg$currPos);
+          if (peg$r1.test(s6)) {
+            peg$currPos++;
+          } else {
+            s6 = peg$FAILED;
+            if (peg$silentFails === 0) {
+              peg$fail(peg$e1);
+            }
+          }
+          if (s6 !== peg$FAILED) {
+            while (s6 !== peg$FAILED) {
+              s5.push(s6);
+              s6 = input.charAt(peg$currPos);
+              if (peg$r1.test(s6)) {
+                peg$currPos++;
+              } else {
+                s6 = peg$FAILED;
+                if (peg$silentFails === 0) {
+                  peg$fail(peg$e1);
+                }
+              }
+            }
+          } else {
+            s5 = peg$FAILED;
+          }
+          if (s5 !== peg$FAILED) {
+            s4 = [s4, s5];
+            s3 = s4;
+          } else {
+            peg$currPos = s3;
+            s3 = peg$FAILED;
+          }
+        } else {
+          peg$currPos = s3;
+          s3 = peg$FAILED;
+        }
       }
-    }
-    if (s2 !== peg$FAILED) {
       s1 = [s1, s2];
       s0 = s1;
     } else {
@@ -2063,6 +2297,7 @@ class Parser {
   constructor(options = {}) {
     this.maxInputSize = options.maxInputSize || 10 * 1024 * 1024;
     this.maxDepth = options.maxDepth || 1000;
+    this.comments = options.comments ?? true;
   }
   parse(input) {
     if (typeof input !== "string") {
@@ -2071,8 +2306,9 @@ class Parser {
     if (input.length > this.maxInputSize) {
       throw new Error(`Input size exceeds maximum allowed size of ${this.maxInputSize} bytes`);
     }
+    const prepared = this.comments ? stripComments(input) : input;
     try {
-      const rawResult = peg$parse(input);
+      const rawResult = peg$parse(prepared);
       return this.transformResult(rawResult);
     } catch (error) {
       if (error && error.location) {
@@ -2183,6 +2419,222 @@ class Parser {
     return new Link(item.id ?? null, []);
   }
 }
+// src/StreamParser.js
+import { EventEmitter } from "events";
+var DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
+
+class StreamParseError extends Error {
+  constructor(error, startOffset, startLine) {
+    const localOffset = error?.offset ?? 0;
+    const localLine = error?.line ?? 1;
+    const column = error?.column ?? 1;
+    const line = startLine + localLine - 1;
+    super(`Stream parse error at line ${line}, column ${column}: ${error.message}`);
+    this.name = "StreamParseError";
+    this.cause = error;
+    this.offset = startOffset + localOffset;
+    this.line = line;
+    this.column = column;
+    this.found = error?.found ?? null;
+    this.lineText = error?.lineText ?? "";
+    this.snippet = error?.snippet ?? "";
+  }
+}
+
+class StreamParser extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.parser = options.parser ?? new Parser(options);
+    this.comments = options.comments ?? this.parser.comments ?? true;
+    this.maxBufferSize = options.maxBufferSize ?? options.maxInputSize ?? DEFAULT_MAX_BUFFER_SIZE;
+    this.collect = options.collect ?? true;
+    this.reset();
+  }
+  write(chunk) {
+    if (typeof chunk !== "string") {
+      return this._fail(new TypeError("Input must be a string"));
+    }
+    if (this.ended) {
+      return this._fail(new Error("Cannot write after end()"));
+    }
+    const emitted = [];
+    for (let index = 0;index < chunk.length; index++) {
+      const character = chunk[index];
+      this.currentLine += character;
+      this.offset += 1;
+      if (character === `
+`) {
+        this.buffer += this.currentLine;
+        this.currentLine = "";
+        this.lineClassified = false;
+        this.line += 1;
+        this.column = 1;
+      } else {
+        if (!this.lineClassified && character !== " " && character !== "\t" && character !== "\r") {
+          this.lineClassified = true;
+          const isComment = this.comments && character === "#";
+          if (!isComment) {
+            const indentation = leadingSpaces(this.currentLine);
+            this._startContentLine(indentation, emitted);
+          }
+        }
+        this.column += 1;
+      }
+      if (this.buffer.length + this.currentLine.length > this.maxBufferSize) {
+        return this._fail(new RangeError(`Buffered record exceeds maximum size of ${this.maxBufferSize} characters`));
+      }
+    }
+    return emitted;
+  }
+  end(chunk = "") {
+    const emitted = chunk === "" ? [] : this.write(chunk);
+    if (this.ended) {
+      return this.collect ? [...this.links] : emitted;
+    }
+    const document = this.buffer + this.currentLine;
+    if (document.length > 0) {
+      let links;
+      try {
+        links = this.parser.parse(document);
+      } catch (error) {
+        const streamError = new StreamParseError(error, this.segmentOffset, this.segmentLine);
+        return this._fail(streamError);
+      }
+      this._publish(links, emitted);
+      this._advanceSegment(document);
+    }
+    this.buffer = "";
+    this.currentLine = "";
+    this.baseIndentation = null;
+    this.ended = true;
+    const result = this.collect ? [...this.links] : emitted;
+    this.emit("end", result);
+    return result;
+  }
+  drain() {
+    const links = this.links;
+    this.links = [];
+    return links;
+  }
+  reset() {
+    this.buffer = "";
+    this.currentLine = "";
+    this.baseIndentation = null;
+    this.lineClassified = false;
+    this.links = [];
+    this.offset = 0;
+    this.line = 1;
+    this.column = 1;
+    this.segmentOffset = 0;
+    this.segmentLine = 1;
+    this.ended = false;
+    return this;
+  }
+  position() {
+    return {
+      offset: this.offset,
+      line: this.line,
+      column: this.column,
+      buffered: this.buffer.length + this.currentLine.length
+    };
+  }
+  static *parse(chunks, options = {}) {
+    const parser = new StreamParser({ ...options, collect: false });
+    for (const chunk of chunks) {
+      yield* parser.write(chunk);
+    }
+    yield* parser.end();
+  }
+  static async* parseAsync(chunks, options = {}) {
+    const parser = new StreamParser({ ...options, collect: false });
+    for await (const chunk of chunks) {
+      yield* parser.write(chunk);
+    }
+    yield* parser.end();
+  }
+  _startContentLine(indentation, emitted) {
+    if (this.buffer.length > 0 && this.baseIndentation !== null && indentation <= this.baseIndentation && structurallyComplete(this.buffer, this.comments)) {
+      let links;
+      try {
+        links = this.parser.parse(this.buffer);
+      } catch {
+        links = null;
+      }
+      if (links !== null) {
+        this._publish(links, emitted);
+        this._advanceSegment(this.buffer);
+        this.buffer = "";
+        this.baseIndentation = null;
+      }
+    }
+    if (this.baseIndentation === null) {
+      this.baseIndentation = indentation;
+    }
+  }
+  _publish(links, emitted) {
+    for (const link of links) {
+      emitted.push(link);
+      if (this.collect)
+        this.links.push(link);
+      this.emit("link", link);
+    }
+  }
+  _advanceSegment(document) {
+    this.segmentOffset += document.length;
+    this.segmentLine += countNewlines(document);
+  }
+  _fail(error) {
+    this.emit("error", error);
+    throw error;
+  }
+}
+function leadingSpaces(line) {
+  let indentation = 0;
+  while (line[indentation] === " ")
+    indentation += 1;
+  return indentation;
+}
+function countNewlines(value) {
+  let count = 0;
+  for (const character of value) {
+    if (character === `
+`)
+      count += 1;
+  }
+  return count;
+}
+function structurallyComplete(document, comments) {
+  const quotes = ['"', "'", "`"];
+  const beforeReference = [" ", "\t", `
+`, "\r", "(", ":"];
+  const beforeComment = [" ", "\t", `
+`, "\r"];
+  let depth = 0;
+  for (let position = 0;position < document.length; position++) {
+    const character = document[position];
+    const previous = position === 0 ? null : document[position - 1];
+    if (quotes.includes(character) && (previous === null || beforeReference.includes(previous))) {
+      const end = quotedReferenceEnd(document, position);
+      if (end === null)
+        return false;
+      position = end - 1;
+      continue;
+    }
+    if (comments && character === "#" && (previous === null || beforeComment.includes(previous))) {
+      const newline = document.indexOf(`
+`, position);
+      if (newline === -1)
+        return true;
+      position = newline;
+      continue;
+    }
+    if (character === "(")
+      depth += 1;
+    if (character === ")")
+      depth -= 1;
+  }
+  return depth === 0;
+}
 // src/FormatOptions.js
 class FormatOptions {
   constructor(options = {}) {
@@ -2218,5 +2670,8 @@ export {
   LinksGroup,
   ParseError,
   Parser,
-  formatLinks
+  StreamParseError,
+  StreamParser,
+  formatLinks,
+  stripComments
 };

package/index.d.ts

@@ -116,6 +116,12 @@ export interface ParserOptions {
    * Maximum nesting depth (default: 1000)
    */
   maxDepth?: number;
+
+  /**
+   * If false, read `#` as an ordinary character instead of the start of a
+   * comment (default: true)
+   */
+  comments?: boolean;
 }
 
 /**
@@ -134,6 +140,11 @@ export class Parser {
    */
   maxDepth: number;
 
+  /**
+   * Whether `#` starts a comment that runs to the end of its line
+   */
+  comments: boolean;
+
   /**
    * Create a new Parser instance
    * @param options - Parser options
@@ -149,6 +160,90 @@ export class Parser {
   parse(input: string): Link[];
 }
 
+/** Options for incremental parsing. */
+export interface StreamParserOptions extends ParserOptions {
+  /** Canonical parser instance to use for completed records. */
+  parser?: Parser;
+
+  /** Largest unresolved record retained in memory (default: 10MB). */
+  maxBufferSize?: number;
+
+  /** Retain emitted links for end() and drain() (default: true). */
+  collect?: boolean;
+}
+
+/** Position immediately after the last character written. */
+export interface StreamPosition {
+  offset: number;
+  line: number;
+  column: number;
+  buffered: number;
+}
+
+/** Canonical parse error translated to coordinates in the complete stream. */
+export class StreamParseError extends Error {
+  cause: Error;
+  offset: number;
+  line: number;
+  column: number;
+  found: string | null;
+  lineText: string;
+  snippet: string;
+}
+
+/** Incrementally emits complete top-level Links Notation records. */
+export class StreamParser {
+  parser: Parser;
+  comments: boolean;
+  maxBufferSize: number;
+  collect: boolean;
+
+  constructor(options?: StreamParserOptions);
+
+  /** Feed a chunk and return links made complete by it. */
+  write(chunk: string): Link[];
+
+  /** Finish the stream, optionally after consuming one final chunk. */
+  end(chunk?: string): Link[];
+
+  /** Return and forget retained links. */
+  drain(): Link[];
+
+  /** Reuse this parser while preserving its options and listeners. */
+  reset(): this;
+
+  /** Return the absolute stream position and unresolved buffer size. */
+  position(): StreamPosition;
+
+  on(event: 'link', listener: (link: Link) => void): this;
+  on(event: 'end', listener: (links: Link[]) => void): this;
+  on(event: 'error', listener: (error: Error) => void): this;
+  once(event: 'link', listener: (link: Link) => void): this;
+  once(event: 'end', listener: (links: Link[]) => void): this;
+  once(event: 'error', listener: (error: Error) => void): this;
+  off(event: string, listener: (...arguments_: any[]) => void): this;
+
+  /** Lazily parse a synchronous iterable of chunks. */
+  static parse(
+    chunks: Iterable<string>,
+    options?: StreamParserOptions
+  ): IterableIterator<Link>;
+
+  /** Lazily parse an asynchronous iterable of chunks. */
+  static parseAsync(
+    chunks: AsyncIterable<string> | Iterable<string>,
+    options?: StreamParserOptions
+  ): AsyncIterableIterator<Link>;
+}
+
+/**
+ * Blank out every comment in a document, keeping its length so that every
+ * character stays at the offset it was written at.
+ * @param document - The document to read
+ * @returns The document, of the same length, without its comments
+ */
+export function stripComments(document: string): string;
+
 /**
  * The position a parse stopped at, as the generated parser reports it
  */

package/package.json

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

package/src/Link.js

@@ -95,7 +95,11 @@ export class Link {
     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(')') ||