links-notation 0.18.0 → 0.20.0

package/README.md

@@ -147,6 +147,45 @@ const group = new LinksGroup(parsed);
 console.log(group.format());
 ```
 
+### 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:
+
+- Large files that don't fit in memory
+- Network streaming (TCP/HTTP)
+- Real-time processing of incoming data
+
+```javascript
+import { StreamParser } from 'links-notation';
+
+const parser = new StreamParser({ collect: false, maxBufferSize: 1024 * 1024 });
+
+// Listen for parsed links
+parser.on('link', (link) => {
+  console.log('Parsed link:', link.toString());
+});
+
+// Listen for errors with location information
+parser.on('error', (error) => {
+  console.error(
+    `Error at line ${error.line}, col ${error.column}: ${error.message}`
+  );
+});
+
+// Feed data incrementally (e.g., from network chunks)
+parser.write('papa (lovesMama: loves mama)\n');
+parser.write('son lovesMama\n');
+parser.write('daughter lovesMama\n');
+
+// Finish the last record. Links are not retained when collection is disabled.
+parser.end();
+```
+
+`StreamParser.parse(chunks)` and `StreamParser.parseAsync(chunks)` expose native
+sync and async iterables. The parser also provides `position()`, `drain()`,
+`reset()`, and a maximum unresolved-record size. See the
+[streaming parser example](../examples/js_streaming_parser.js).
+
 ### TypeScript Usage Examples
 
 ```typescript
@@ -252,6 +291,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 +332,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,6 +353,19 @@ Container for grouping related links.
 - `constructor(links)` - Create a new group
 - `format()` - Format the group as a string
 
+#### `StreamParser`
+
+EventEmitter-based streaming parser for incremental parsing.
+
+- `constructor(options)` - Create a new streaming parser
+  - `options.maxInputSize` - Maximum input size in bytes (default: 10MB)
+  - `options.maxDepth` - Maximum nesting depth (default: 1000)
+- `write(chunk)` - Feed a chunk of data to the parser
+- `end()` - Finish parsing and return all parsed links
+- `position()` - Get current parsing position (line, column, offset)
+- Event: `'link'` - Emitted when a link is parsed (callback receives Link object)
+- Event: `'error'` - Emitted on parse error (callback receives Error with line/column info)
+
 #### `ParseError`
 
 Thrown by `parse(input)` when the document does not parse. The message says
@@ -288,7 +375,7 @@ where the document stopped making sense and quotes the offending line:
 import { Parser, ParseError } from 'links-notation';
 
 try {
-  new Parser().parse('# ok line\n# break: two\nci_gate x\n');
+  new Parser().parse('ci_gate x\nstage: rust: nextest\n');
 } catch (error) {
   console.error(error.message);
   if (error instanceof ParseError) {
@@ -298,9 +385,9 @@ try {
 ```
 
 ```text
-Syntax error at line 2, column 8: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
-2 | # break: two
-  |        ^
+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

package/README.ru.md

@@ -105,6 +105,27 @@ const group = new LinksGroup(parsed);
 console.log(group.format());
 ```
 
+### Потоковый парсер
+
+`StreamParser` принимает произвольные порции данных и отправляет события только
+для завершённых связей верхнего уровня. Отключите накопление для обработки с
+ограниченной памятью.
+
+```javascript
+import { StreamParser } from 'links-notation';
+
+const stream = new StreamParser({ collect: false, maxBufferSize: 1024 * 1024 });
+stream.on('link', (link) => console.log(link.toString()));
+stream.on('error', (error) => console.error(error));
+stream.write('профиль:\n  имя Ада\n');
+stream.end('следующая связь');
+```
+
+`StreamParser.parse(chunks)` и `StreamParser.parseAsync(chunks)` предоставляют
+нативные синхронные и асинхронные итераторы. Также доступны `position()`,
+`drain()`, `reset()` и ограничение размера незавершённой записи. См.
+[исполняемый пример](../examples/js_streaming_parser.js).
+
 ## Примеры синтаксиса
 
 ### Дуплеты (2-кортежи)
@@ -171,6 +192,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 +233,8 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 
 Основной класс парсера для преобразования строк в связи.
 
+- `constructor(options)` - Создать парсер; `options.comments` со значением
+  `false` читает `#` как обычный символ, а не как начало комментария
 - `initialize()` - Инициализация парсера (асинхронно)
 - `parse(input)` - Парсинг строки Lino и возвращение связей
 
@@ -207,7 +263,7 @@ console.log(formatLinks(links)); // (value ((id 1) (label one)))
 import { Parser, ParseError } from 'links-notation';
 
 try {
-  new Parser().parse('# ok line\n# break: two\nci_gate x\n');
+  new Parser().parse('ci_gate x\nstage: rust: nextest\n');
 } catch (error) {
   console.error(error.message);
   if (error instanceof ParseError) {
@@ -217,9 +273,9 @@ try {
 ```
 
 ```text
-Syntax error at line 2, column 8: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
-2 | # break: two
-  |        ^
+Syntax error at line 2, column 12: Expected "(", [ \t], [\r\n], or [^ \t\n\r(:)] but ":" found.
+2 | stage: rust: nextest
+  |            ^
 ```
 
 - `offset` - Смещение сломанной позиции от начала документа