links-notation 0.27.0 → 0.28.0

package/README.md

@@ -27,6 +27,14 @@ bun add links-notation
 import { Parser, Link } from 'npm:links-notation@^0.6.0';
 ```
 
+#### In browsers
+
+The package has no runtime dependencies and imports no Node.js built-in
+modules, so bundlers need no polyfills. For example, esbuild bundles it with
+`esbuild entry.js --bundle --platform=browser`. Before 0.27.1, `StreamParser`
+imported Node's `events` module, and browser bundles needed the `events`
+package installed as a polyfill.
+
 ### Local Development Setup
 
 For contributors working on the source code:
@@ -226,6 +234,47 @@ call it on already decoded `Link.id` values.
 
 See the [Q&A document example](../examples/js_indented_document.js).
 
+### How a Document Was Written (CST)
+
+Parsing keeps how every ID was written. Quoting never changes a reference:
+`1` and `'1'` are the same reference, so equality, formatting and JSON stay as
+they were. Each parsed link also carries `rawId`, the ID exactly as written,
+and `quote`, the delimiter it was written between:
+
+```javascript
+import { Parser } from 'links-notation';
+
+const [link] = new Parser().parse("(t 1 '1')");
+const [, bare, quoted] = link.values;
+bare.equals(quoted); // true: the same reference
+[bare.rawId, bare.quote]; // ['1', null]
+[quoted.rawId, quoted.quote]; // ["'1'", "'"]
+link.format(); // '(t 1 1)'
+```
+
+`rawId` is `null` for links without an ID, links built in code, and links
+made by indentation path combination. Use `new Parser({ syntax: false })` (AST
+mode) to leave it out.
+
+`parseCst(input)` returns the lossless concrete syntax tree. Every character,
+including comments, blank lines, indentation, quotes and line endings, belongs
+to exactly one token, so the original text is always recovered:
+
+```javascript
+const cst = new Parser().parseCst("(t 1 '1') # note\n");
+cst.toString(); // "(t 1 '1') # note\n"
+cst.tokens().map((token) => [token.kind, token.text]);
+// [['open_paren', '('], ['reference', 't'], ['whitespace', ' '], ...]
+cst.toSExpression();
+// (document (line (group open_paren:"(" (line reference:"t" ...) close_paren:")") whitespace:" " comment:"# note" newline:"\n"))
+```
+
+A `document` node holds `line` nodes. A line holds its tokens up to and
+including its line ending. A `group` node holds `(`, the lines inside it, and
+`)`. Reference tokens carry `value` (what the reference means) and `quote`.
+`parseCst` refuses exactly what `parse` refuses. See
+[the issue 364 case study](../docs/case-studies/issue-364/README.md).
+
 ### Streaming Parser (for Large Messages)
 
 The `StreamParser` allows you to parse Links Notation incrementally, processing data as it arrives without loading the entire message into memory. This is ideal for:
@@ -421,6 +470,9 @@ Main parser class for converting strings to links.
 - `initialize()` - Initialize the parser (async)
 - `parse(input)` - Parse a Lino string and return links
 - `parseGroups(input)` - Read an indentation tree as `LinksGroup` instances
+- `parseCst(input)` - Read the lossless concrete syntax tree (`CstNode`)
+  - `options.syntax` - If `false` (AST mode), parsed links leave `rawId` null
+    (default: `true`)
 
 #### `Link`
 
@@ -430,6 +482,9 @@ Represents a single link with ID and values.
 - `toString()` - Convert link to string format
 - `id` - Link identifier
 - `values` - Array of child values/links
+- `rawId` - The ID exactly as the parsed document wrote it, or `null`; ignored
+  by `equals`, `format` and JSON
+- `quote` - `'`, `"` or `` ` `` when `rawId` is quoted, otherwise `null`
 - `escapeReference(reference, options)` - Quote a reference; `minimal: true`
   allows ordinary prose on a text document line
 - `unescapeReference(reference)` - Decode a complete serialized reference
@@ -443,7 +498,11 @@ Container for grouping related links.
 
 #### `StreamParser`
 
-EventEmitter-based streaming parser for incremental parsing.
+Event-emitting streaming parser for incremental parsing. Its built-in emitter
+has the Node.js `EventEmitter` listener methods (`on`, `once`, `off`,
+`addListener`, `removeListener`, `prependListener`, `prependOnceListener`,
+`removeAllListeners`, `emit`, `listeners`, `listenerCount`, `eventNames`) and
+works in browsers without a polyfill. It is not an `instanceof EventEmitter`.
 
 - `constructor(options)` - Create a new streaming parser
   - `options.maxInputSize` - Maximum input size in bytes (default: 10MB)

package/README.ru.md

@@ -153,6 +153,38 @@ const group = new LinksGroup(parsed);
 console.log(group.format());
 ```
 
+### Как документ был записан (CST)
+
+Парсер сохраняет, как была записана каждая ссылка. Кавычки не меняют ссылку:
+`1` и `'1'` - одна и та же ссылка, поэтому сравнение, форматирование и JSON
+остаются прежними. Каждая разобранная связь хранит `rawId` - ID в точности
+так, как он записан, и `quote` - кавычку, в которую он заключён:
+
+```javascript
+import { Parser } from 'links-notation';
+
+const [link] = new Parser().parse("(t 1 '1')");
+const [, bare, quoted] = link.values;
+bare.equals(quoted); // true: это одна ссылка
+[bare.rawId, bare.quote]; // ['1', null]
+[quoted.rawId, quoted.quote]; // ["'1'", "'"]
+link.format(); // '(t 1 1)'
+```
+
+`rawId` равен `null` у связей без ID, у связей, созданных в коде, и у связей,
+построенных объединением путей по отступам. `new Parser({ syntax: false })`
+(режим AST) не сохраняет его.
+
+`parseCst(input)` возвращает конкретное синтаксическое дерево без потерь:
+каждый символ, включая комментарии, пустые строки, отступы, кавычки и
+переводы строк, принадлежит ровно одному токену, поэтому исходный текст
+всегда восстанавливается: `new Parser().parseCst(text).toString() === text`.
+Узел `document` содержит узлы `line`; строка содержит свои токены вместе с
+переводом строки; узел `group` содержит `(`, строки внутри и `)`. Токены
+ссылок хранят `value` (что означает ссылка) и `quote`. `parseCst` отклоняет
+ровно то, что отклоняет `parse`. Подробности - в
+[разборе issue 364](../docs/case-studies/issue-364/README.md).
+
 ### Потоковый парсер
 
 `StreamParser` принимает произвольные порции данных и отправляет события только
@@ -174,6 +206,13 @@ stream.end('следующая связь');
 `drain()`, `reset()` и ограничение размера незавершённой записи. См.
 [исполняемый пример](../examples/js_streaming_parser.js).
 
+Пакет не импортирует встроенные модули Node.js, поэтому сборщикам для браузера
+не нужны полифилы: например, `esbuild entry.js --bundle --platform=browser`.
+Встроенный в `StreamParser` эмиттер поддерживает методы подписки
+`EventEmitter` из Node.js (`on`, `once`, `off`, `removeListener`, `emit`,
+`listenerCount` и другие). До версии 0.27.1 `StreamParser` импортировал модуль
+`events`, и для браузерной сборки требовался пакет-полифил `events`.
+
 ## Примеры синтаксиса
 
 ### Дуплеты (2-кортежи)
@@ -291,6 +330,9 @@ console.log(formatLinks(plain.parse('# a b\n'))); // (# a b)
     отклоняется с `ParseError`, а не разбирается рекурсивно, пока не кончится стек
 - `initialize()` - Инициализация парсера (асинхронно)
 - `parse(input)` - Парсинг строки Lino и возвращение связей
+- `parseCst(input)` - Конкретное синтаксическое дерево без потерь (`CstNode`)
+  - `options.syntax` - Со значением `false` (режим AST) связи не хранят `rawId`
+    (по умолчанию: `true`)
 
 #### `Link`
 
@@ -300,6 +342,9 @@ console.log(formatLinks(plain.parse('# a b\n'))); // (# a b)
 - `toString()` - Преобразование связи в строковый формат
 - `id` - Идентификатор связи
 - `values` - Массив дочерних значений/связей
+- `rawId` - ID в точности так, как он записан в документе, или `null`;
+  `equals`, `format` и JSON его не учитывают
+- `quote` - `'`, `"` или `` ` ``, если `rawId` в кавычках, иначе `null`
 
 #### `LinksGroup`