n3 3.0.0-alpha.4 → 3.0.0-alpha.6

package/README.md

@@ -158,6 +158,20 @@ const quads = parser.parse('<a> <b> "hello"@en.', {
 });
 ```
 
+Packages that extend a format with their own directives can register their names with the `directives` option.
+Between statements (outside graph blocks and formulas), a registered directive is accepted
+as `@name .` in Turtle, TriG and N3, and as `NAME` (case-insensitive) in all formats, including N-Triples and N-Quads.
+`onDirective(name)` receives each one in order with the quads, and `N3.StreamParser` emits them as `directive` events.
+Names consist of letters only, and cannot be words that already have a meaning in the grammar, such as `prefix` or `a`.
+
+```JavaScript
+const parser = new N3.Parser({ format: 'N-Quads', directives: ['message'] });
+parser.parse('<a> <b> <c> .\nMESSAGE\n<a> <b> <d> .\n', {
+  onQuad: (error, quad) => { /* … */ },
+  onDirective: name => { console.log('end of a message'); },
+});
+```
+
 If no callbacks are provided, parsing happens synchronously returning an array of quads:
 
 ```JavaScript
@@ -234,6 +248,13 @@ of also rescoping blank node labels in lists and blank node property lists:
 const parser = new N3.Parser({ format: 'N3', formulaScopedBlankNodes: false });
 ```
 
+The parser rejects triple terms nested more than 1024 levels deep,
+so that the resulting quads stay within what the store and writer can traverse.
+The `maxTripleTermDepth` option changes this limit (`Infinity` removes it):
+```JavaScript
+const parser = new N3.Parser({ maxTripleTermDepth: 64 });
+```
+
 ### From an RDF stream to quads
 
 `N3.Parser` can parse [Node.js streams](http://nodejs.org/api/stream.html) as they grow,
@@ -335,6 +356,30 @@ A `baseIRI` argument makes the writer abbreviate IRIs relative to that base in T
 const writer = new N3.Writer({ baseIRI: 'http://example.org/', writeBase: false });
 ```
 
+A `version` argument writes an RDF 1.2 version directive at the top of the document,
+as `@version "1.2".` in Turtle/TriG or `VERSION "1.2"` in N-Triples/N-Quads.
+The constructor throws for a label that contains quotes, backslashes, control characters, or unpaired surrogates.
+
+```JavaScript
+const writer = new N3.Writer({ version: '1.2' });
+```
+
+Packages that add their own syntax can extend `N3.Writer`.
+`this._endStatement()` finishes the pending statement (and closes an open graph block),
+`this._write(text, done)` writes text to the output,
+and `this._lineMode` tells whether the output is N-Triples or N-Quads.
+
+```JavaScript
+class GroupWriter extends N3.Writer {
+  addGroup(quads, done) {
+    for (const quad of quads)
+      this.addQuad(quad);
+    this._endStatement();
+    this._write(this._lineMode ? 'GROUP\n' : '@group .\n', done);
+  }
+}
+```
+
 ### From quads to an RDF stream
 
 `N3.Writer` can also write quads to a Node.js stream through `addQuad`.
@@ -566,6 +611,17 @@ Both budgets are unbounded by default;
 `reason()` throws when one is exceeded,
 leaving any quads derived up to that point in the store.
 
+## Extensions
+The following packages build on N3.js to support formats or features beyond the W3C specifications listed under [Compatibility](#compatibility).
+They are maintained separately from N3.js; please report issues with them in their own repositories.
+
+| Package | Description |
+| ------- | ----------- |
+| [n3.js-messages](https://www.npmjs.com/package/n3.js-messages) | Parses and writes [RDF Messages](https://w3c-cg.github.io/rsp/spec/messages) (message-delimited Turtle, TriG, N-Triples and N-Quads). |
+| [@jeswr/n3-provenance](https://github.com/jeswr/n3-provenance) | Experimental. Maps the terms of parsed quads back to their source positions in the input document. Terms that the parser generates, such as list nodes and reification scaffolding, have no position. It builds on the parser's `onToken` and `onTokenEnd` callbacks, but also subclasses private parser and index internals, so it is pinned to a specific N3.js revision. |
+
+To list a package here, open a pull request that adds a row to this table.
+
 ## Compatibility
 ### Format specifications
 The N3.js parser and writer is fully compatible with the following W3C specifications: