n3 2.7.12 → 2.9.0

package/README.md

@@ -129,12 +129,12 @@ the callback is invoked one last time with `null` for `quad`
 and a hash of prefixes as third argument.
 <br>
 
-Alternatively, an object can be supplied, where `onQuad`, `onPrefix` and `onComment` are used to listen for `quads`, `prefixes` and `comments` as follows:
+Alternatively, an object can be supplied with named callbacks for quads, prefixes, comments, and token processing:
 ```JavaScript
 const parser = new N3.Parser();
 
 parser.parse(tomAndJerry, {
-  // onQuad (required) accepts a listener of type (quad: RDF.Quad) => void
+  // onQuad (optional) receives errors, quads, and completion
   onQuad: (err, quad) => { console.log(quad); },
   // onPrefix (optional) accepts a listener of type (prefix: string, iri: NamedNode) => void
   onPrefix: (prefix, iri) => { console.log(prefix, 'expands to', iri.value); },
@@ -143,6 +143,17 @@ parser.parse(tomAndJerry, {
 });
 ```
 
+`onToken(token)` runs immediately before a lexer token is processed, and
+`onTokenEnd(token)` runs immediately afterwards, including when processing throws.
+
+```JavaScript
+const tokens = [];
+const quads = parser.parse('<a> <b> "hello"@en.', {
+  onToken: token => tokens.push(token),
+  onTokenEnd: token => { /* Finish per-token bookkeeping here. */ },
+});
+```
+
 If no callbacks are provided, parsing happens synchronously returning an array of quads:
 
 ```JavaScript
@@ -464,6 +475,39 @@ The store provides the following search methods
 - `getGraphs` returns an array of unique graphs occurring in matching quad
 - `forGraphs` executes a callback on unique graphs occurring in matching quads
 
+### Configuring `match()` semantics
+
+The behaviour of `match()` can be configured as a store-wide default or per-call as follows:
+
+```JavaScript
+import { Store, DataFactory } from 'n3';
+const { namedNode } = DataFactory;
+
+const store = new Store([], { matchSemantics: 'snapshot' });
+const snapshot = store.match(namedNode('s'));
+const forwarded = store.match(namedNode('s'), null, null, null, { matchSemantics: 'forwarded' });
+```
+
+Supported values:
+
+- `'lazy'` (default) — the view (return value of `Store#match`) reflects the
+  parent store until the first operation that materializes it (a mutation, or a
+  materializing read such as `size` or `has`), after which it is frozen to a
+  snapshot. Parent mutations made before that point remain visible in the view.
+  In the next major version, only mutating operations will materialize a lazy
+  view.
+- `'snapshot'` — the view reflects the parent contents *at the time of*
+  `match()`. Later parent mutations never affect it. This is the most
+  spec-correct interpretation of an RDF/JS dataset and will become the default
+  in the next major version.
+- `'forwarded'` — the view always reflects the parent state, and mutations to the view are written through to the parent. Attempts to mutate on the view which do not match the views `#match` pattern result in an error.
+
+A sub-view inherits its parent's `matchSemantics`.
+
+For `'snapshot'` and `'forwarded'`, an iteration (synchronous or via the
+stream) that is already in progress keeps a stable view of the quads as of when it started.
+
+
 ## Reasoning
 
 N3.js supports reasoning as follows: