links-notation 0.17.0 → 0.19.0

package/README.md

@@ -252,6 +252,39 @@ const links = new Parser().parse(`value (
 console.log(formatLinks(links)); // (value ((id 1) (label one)))
 ```
 
+### Comments
+
+A `#` hides the rest of the line it stands on, so a document can carry prose
+about itself:
+
+```lino
+# the machines this deploys to
+deploy: staging # only staging, for now
+```
+
+Both comments are gone by the time the document is read, leaving the single
+link `(deploy: staging)`. A `#` only opens a comment where a reference could
+begin, so a `#` inside a token (`issue#1047`) and a `#` inside a delimited
+reference (`"#"`) stay ordinary characters.
+
+A formatter keeps the same rule from the other side: a reference that begins
+with a `#` is written quoted (`'#tag'`), so a document it writes reads back as
+itself.
+
+Comments are on by default, and a parser can be told to read `#` as an ordinary
+character again, for documents written before comments existed:
+
+```javascript
+import { Parser, formatLinks } from 'links-notation';
+
+const document =
+  '# the machines this deploys to\ndeploy: staging # only staging, for now\n';
+console.log(formatLinks(new Parser().parse(document))); // (deploy: staging)
+
+const plain = new Parser({ comments: false });
+console.log(formatLinks(plain.parse('# a b\n'))); // (# a b)
+```
+
 ## API Reference
 
 ### Classes
@@ -260,6 +293,8 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 
 Main parser class for converting strings to links.
 
+- `constructor(options)` - Create a parser; `options.comments` set to `false`
+  reads `#` as an ordinary character instead of the start of a comment
 - `initialize()` - Initialize the parser (async)
 - `parse(input)` - Parse a Lino string and return links
 
@@ -279,11 +314,44 @@ Container for grouping related links.
 - `constructor(links)` - Create a new group
 - `format()` - Format the group as a string
 
+#### `ParseError`
+
+Thrown by `parse(input)` when the document does not parse. The message says
+where the document stopped making sense and quotes the offending line:
+
+```js
+import { Parser, ParseError } from 'links-notation';
+
+try {
+  new Parser().parse('ci_gate x\nstage: rust: nextest\n');
+} catch (error) {
+  console.error(error.message);
+  if (error instanceof ParseError) {
+    console.error(`${error.line}:${error.column} (offset ${error.offset})`);
+  }
+}
+```
+
+```text
+Syntax error at line 2, column 12: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
+2 | stage: rust: nextest
+  |            ^
+```
+
+- `offset` - Offset of the offending position from the start of the document
+- `line`, `column` - Where the document stopped parsing, counted from 1
+- `found` - The character found instead, or `null` at the end of the document
+- `lineText` - The offending line, as written
+- `snippet` - The offending line with a caret under the offending column
+- `location` - The position as the generated parser reports it
+- `cause` - The error the generated parser threw
+
 ## Project Structure
 
 - `src/grammar.pegjs` - Peggy.js grammar definition
 - `src/Link.js` - Link data structure
 - `src/LinksGroup.js` - Links group container
+- `src/ParseError.js` - Parse error with the position of the defect
 - `src/Parser.js` - Parser wrapper
 - `src/index.js` - Main entry point
 - `tests/` - Test files

package/README.ru.md

@@ -171,6 +171,39 @@ const links = new Parser().parse(`value (
 console.log(formatLinks(links)); // (value ((id 1) (label one)))
 ```
 
+### Комментарии
+
+`#` скрывает остаток строки, на которой стоит, поэтому документ может нести
+пояснения о самом себе:
+
+```lino
+# машины, на которые идёт выкладка
+deploy: staging # пока только staging
+```
+
+К моменту чтения документа обоих комментариев уже нет, остаётся одна связь
+`(deploy: staging)`. `#` открывает комментарий только там, где могла бы
+начаться ссылка, поэтому `#` внутри токена (`issue#1047`) и `#` внутри ссылки
+в кавычках (`"#"`) остаются обычными символами.
+
+Форматтер соблюдает то же правило с другой стороны: ссылка, начинающаяся с `#`,
+записывается в кавычках (`'#tag'`), поэтому написанный им документ читается
+обратно как он сам.
+
+Комментарии включены по умолчанию, а парсеру можно велеть снова читать `#` как
+обычный символ - для документов, написанных до появления комментариев:
+
+```javascript
+import { Parser, formatLinks } from 'links-notation';
+
+const document =
+  '# машины, на которые идёт выкладка\ndeploy: staging # пока только staging\n';
+console.log(formatLinks(new Parser().parse(document))); // (deploy: staging)
+
+const plain = new Parser({ comments: false });
+console.log(formatLinks(plain.parse('# a b\n'))); // (# a b)
+```
+
 ## Справочник API
 
 ### Классы
@@ -179,6 +212,8 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 
 Основной класс парсера для преобразования строк в связи.
 
+- `constructor(options)` - Создать парсер; `options.comments` со значением
+  `false` читает `#` как обычный символ, а не как начало комментария
 - `initialize()` - Инициализация парсера (асинхронно)
 - `parse(input)` - Парсинг строки Lino и возвращение связей
 
@@ -198,11 +233,44 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 - `constructor(links)` - Создание новой группы
 - `format()` - Форматирование группы в строку
 
+#### `ParseError`
+
+Выбрасывается методом `parse(input)`, когда документ не разбирается. Сообщение
+говорит, где документ перестал быть понятным, и цитирует сломанную строку:
+
+```js
+import { Parser, ParseError } from 'links-notation';
+
+try {
+  new Parser().parse('ci_gate x\nstage: rust: nextest\n');
+} catch (error) {
+  console.error(error.message);
+  if (error instanceof ParseError) {
+    console.error(`${error.line}:${error.column} (смещение ${error.offset})`);
+  }
+}
+```
+
+```text
+Syntax error at line 2, column 12: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
+2 | stage: rust: nextest
+  |            ^
+```
+
+- `offset` - Смещение сломанной позиции от начала документа
+- `line`, `column` - Где документ перестал разбираться, счет с 1
+- `found` - Найденный символ или `null` в конце документа
+- `lineText` - Сломанная строка, как она написана
+- `snippet` - Сломанная строка с указателем под нужным столбцом
+- `location` - Позиция в том виде, в каком ее сообщает сгенерированный парсер
+- `cause` - Ошибка, которую выбросил сгенерированный парсер
+
 ## Структура проекта
 
 - `src/grammar.pegjs` - Определение грамматики Peggy.js
 - `src/Link.js` - Структура данных связи
 - `src/LinksGroup.js` - Контейнер групп связей
+- `src/ParseError.js` - Ошибка разбора с позицией дефекта
 - `src/Parser.js` - Обертка парсера
 - `src/index.js` - Главная точка входа
 - `tests/` - Файлы тестов

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, "\\'")}'`;
@@ -269,6 +269,144 @@ class LinksGroup {
     return list.map((item) => `(${item.id || item})`).join(" ");
   }
 }
+// src/ParseError.js
+var QUOTED_LINE_WIDTH = 80;
+var ELLIPSIS = "...";
+
+class ParseError extends Error {
+  constructor(input, error) {
+    const start = error?.location?.start ?? { offset: 0, line: 1, column: 1 };
+    const lineText = lineAt(input, start.offset);
+    const summary = `line ${start.line}, column ${start.column}: ${error.message}`;
+    const snippet = quote(start.line, lineText, start.column);
+    super(`Syntax error at ${summary}
+${snippet}`);
+    this.name = "ParseError";
+    this.cause = error;
+    this.location = error.location;
+    this.offset = start.offset;
+    this.line = start.line;
+    this.column = start.column;
+    this.found = error.found ?? null;
+    this.lineText = lineText;
+    this.snippet = snippet;
+  }
+}
+function lineAt(input, offset) {
+  const at = Math.max(0, Math.min(offset, input.length));
+  const start = input.lastIndexOf(`
+`, at - 1) + 1;
+  const end = input.indexOf(`
+`, start);
+  const line = input.slice(start, end === -1 ? input.length : end);
+  return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+function quote(number, lineText, column) {
+  const [quoted, at] = windowAround(lineText, column);
+  const gutter = " ".repeat(String(number).length);
+  return `${number} | ${quoted}
+${gutter} | ${" ".repeat(at - 1)}^`;
+}
+function windowAround(lineText, column) {
+  if (lineText.length <= QUOTED_LINE_WIDTH) {
+    return [lineText, column];
+  }
+  const target = column - 1;
+  const lastStart = lineText.length - QUOTED_LINE_WIDTH;
+  const start = Math.min(Math.max(target - Math.floor(QUOTED_LINE_WIDTH / 2), 0), lastStart);
+  const end = start + QUOTED_LINE_WIDTH;
+  const quoted = (start > 0 ? ELLIPSIS : "") + lineText.slice(start, end) + (end < lineText.length ? ELLIPSIS : "");
+  const shift = start > 0 ? ELLIPSIS.length : 0;
+  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) {
@@ -1700,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 {
@@ -2012,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") {
@@ -2020,13 +2306,16 @@ 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) {
+        throw new ParseError(input, error);
+      }
       const parseError = new Error(`Parse error: ${error.message}`);
       parseError.cause = error;
-      parseError.location = error.location;
       throw parseError;
     }
   }
@@ -2163,6 +2452,8 @@ export {
   FormatOptions,
   Link,
   LinksGroup,
+  ParseError,
   Parser,
-  formatLinks
+  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
@@ -144,11 +155,70 @@ export class Parser {
    * Parse Lino notation text into Link objects
    * @param input - The Lino notation text to parse
    * @returns Array of parsed Link objects
-   * @throws {Error} If parsing fails
+   * @throws {ParseError} If the text does not parse
    */
   parse(input: string): 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
+ */
+export interface ParseErrorLocation {
+  start: { offset: number; line: number; column: number };
+  end: { offset: number; line: number; column: number };
+}
+
+/**
+ * The error thrown when a document does not parse
+ *
+ * The message says where the document stopped making sense and quotes the
+ * offending line with a caret under it.
+ */
+export class ParseError extends Error {
+  /**
+   * Offset of the offending position from the start of the document
+   */
+  offset: number;
+
+  /**
+   * Line the offending position is on, counted from 1
+   */
+  line: number;
+
+  /**
+   * Column the offending position is at, counted from 1
+   */
+  column: number;
+
+  /**
+   * The character found instead, or null at the end of the document
+   */
+  found: string | null;
+
+  /**
+   * The offending line, as written, without its line ending
+   */
+  lineText: string;
+
+  /**
+   * The offending line with a caret under the offending column
+   */
+  snippet: string;
+
+  /**
+   * The position the generated parser reported
+   */
+  location: ParseErrorLocation;
+}
+
 /**
  * Options for formatting links
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "links-notation",
-  "version": "0.17.0",
+  "version": "0.19.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(')') ||