feat: replace the hand-rolled N3 parser with N3.js across the Turtle/N3 family

Documentation/turtle-intro.html

@@ -302,7 +302,21 @@ <h3>Extensions in rdflib</h3>
   generally, but are shortcts for test data and quick scripts.
   rdflib.js will understand these sytatax but never generate them
 </p>
+<p><b>Update for rdflib 3.0:</b> the parser was replaced by
+  <a href="https://github.com/rdfjs/N3.js">N3.js</a>, and the first two
+  extensions below &mdash; naked dates/date-times and
+  <tt>is</tt> &hellip; <tt>of</tt> &mdash; were <b>removed</b>: they now
+  raise a parse error under <em>every</em> content type, including
+  <tt>text/n3</tt>. They are kept here for historical reference, each with
+  its standard replacement. The local empty-prefix default (the third
+  extension) is still supported.
+</p>
 <h4>Naked Dates</h4>
+<p><b>Removed in rdflib 3.0.</b> Write the standard typed literals instead:
+  <tt>"2018-02-31"^^xsd:date</tt> and
+  <tt>"2018-02-31T08:24:00.0Z"^^xsd:dateTime</tt>
+  (with <tt>@prefix xsd: &lt;http://www.w3.org/2001/XMLSchema#&gt;.</tt>).
+</p>
 <table>
   <tr>
     <td><pre>
@@ -340,6 +354,11 @@ <h4>Reverse properties</h4>
 <p>The <tt>is</tt> ... <tt>of</tt> syntax was in the original N3 language
   which Turtle was derived from but unfortunately left out of the turtle standard.
 </p>
+<p><b>Removed in rdflib 3.0</b> (the modern N3 Community Group grammar
+  dropped it too). Write the inverse triple instead, e.g.
+  <tt>:grampa fam:child :alice .</tt> rather than
+  <tt>:alice is fam:child of :grampa .</tt>
+</p>
 <h4>Local document prefix</h4>
 <p>It is handy to define the empty string prefix <tt>:</tt>
   as being for the local document, so it can be used for local identifiers.

reference/README.md

@@ -0,0 +1,17 @@
+# reference/ — archived pre-TypeScript relics
+
+The files in this directory are **historical reference copies only**. They are
+not part of the build, are not exported by the package, and are not expected
+to run.
+
+In particular, `dumpParser.js`, `ldpatchParser.js` and `fetcher-classes.js`
+build on the legacy hand-rolled `N3Parser`, which was **removed in rdflib 3.0**
+(replaced by [N3.js](https://github.com/rdfjs/N3.js); see PR #831). The
+`N3Parser` export is now a stub that throws with a pointer to `parse()`.
+Anything here that constructs `$rdf.N3Parser(...)` or requires
+`./n3parser` documents an API that no longer exists — use
+`parse(text, store, baseURI, contentType)` or the
+[`n3`](https://www.npmjs.com/package/n3) package directly instead.
+
+The `.coffee` files predate the 2015-era JavaScript port and are kept for
+archaeology only.

src/fetcher.ts

@@ -27,7 +27,6 @@
  */
 import IndexedFormula from './store'
 import log from './log'
-import N3Parser from './n3parser'
 import RDFlibNamedNode from './named-node'
 import Namespace from './namespace'
 import rdfParse from './parse'
@@ -155,7 +154,9 @@ export interface AutoInitOptions extends RequestInit{
   forceContentType?: ContentType
   /**
    * Load the data even if loaded before.
-   * Also sets the `Cache-Control:` header to `no-cache`
+   * Also sets the `Cache-Control:` header to `no-cache`, and (in
+   * `Fetcher.load`) implies `clearPreviousData: true` unless that option is
+   * explicitly set to `false`.
    */
   force?: boolean
   /**
@@ -592,20 +593,24 @@ class N3Handler extends Handler {
     } & Options,
     response: ExtendedResponse
   ): ExtendedResponse | Promise<FetchError> {
-    // Parse the text of this N3 file
+    // Parse the text of this Turtle or N3 file, through the same parse()
+    // entry point (and N3.js-based parser) as everything else.
     let kb = fetcher.store
-    let p = N3Parser(kb, kb, options.original.value, options.original.value,
-      null, null, '', null)
-    //                p.loadBuf(xhr.responseText)
+    const normalized = (fetcher.normalizedContentType(options as AutoInitOptions, response.headers) || '').split(';')[0]
+    // The handler's pattern also matches legacy aliases such as
+    // application/rdf+n3 or text/x-turtle; normalize them to the canonical
+    // content type of the same syntax.
+    const contentType = /n3/.test(normalized) ? 'text/n3' : 'text/turtle'
     try {
-      p.loadBuf(responseText)
+      rdfParse(responseText, kb, options.original.value, contentType)
     } catch (err) {
       let msg = 'Error trying to parse ' + options.resource +
         ' as Notation3:\n' + err  // not err.stack -- irrelevant
       return fetcher.failFetch(options, msg, 'parse_error', response)
     }
 
-    fetcher.addStatus(options.req, 'N3 parsed: ' + p.statementCount + ' triples in ' + p.lines + ' lines.')
+    const statementCount = kb.statementsMatching(null, null, null, options.original).length
+    fetcher.addStatus(options.req, 'N3 parsed: ' + statementCount + ' triples in ' + responseText.split('\n').length + ' lines.')
     fetcher.store.add(options.original, ns.rdf('type'), ns.link('RDFDocument'), fetcher.appNode)
 
     return fetcher.doneFetch(options, this.response)
@@ -939,7 +944,10 @@ export default class Fetcher implements CallbackifyInterface {
    *   force the data to be treated as this content-type (for reads)
    *
    * @param [options.force] {boolean} Load the data even if loaded before.
-   *   Also sets the `Cache-Control:` header to `no-cache`
+   *   Also sets the `Cache-Control:` header to `no-cache`, and implies
+   *   `clearPreviousData: true` unless that option is explicitly set to
+   *   `false` (re-parsing without clearing would duplicate blank-node
+   *   subgraphs, as parsed blank-node labels are not stable across parses)
    *
    * @param [options.baseURI=docuri] {Node|string} Original uri to preserve
    *   through proxying etc (`xhr.original`).
@@ -964,6 +972,12 @@ export default class Fetcher implements CallbackifyInterface {
     options: Options = {}
   ): T extends Array<string | NamedNode> ? Promise<Result[]> : Promise<Result> {
     options = Object.assign({}, options) // Take a copy as we add stuff to the options!!
+    // `force` implies `clearPreviousData` unless the caller opts out:
+    // blank-node labels are not stable across parses, so re-parsing without
+    // clearing would duplicate blank-node subgraphs
+    if (options.force && options.clearPreviousData === undefined) {
+      options.clearPreviousData = true
+    }
     if (uri instanceof Array) {
       return Promise.all(uri.map((x) => {
         return this.load(x, Object.assign({}, options)) as unknown as Promise<Result>

src/formula.ts

@@ -677,7 +677,8 @@ export default class Formula extends Node {
   }
 
   /**
-   * Used by the n3parser to generate list elements
+   * Creates a collection (or an rdf:first/rest chain when the factory has no
+   * collection support) from a list of values
    * @param values - The values of the collection
    * @param context - The store
    * @return {BlankNode|Collection} - The term for the statement

src/index.ts

@@ -9,7 +9,6 @@ import Store from './store'
 import jsonParser from './jsonparser'
 import Literal from './literal'
 import log from './log'
-import N3Parser from './n3parser'
 import NamedNode from './named-node'
 import Namespace from './namespace'
 import Node from './node'
@@ -60,8 +59,22 @@ const term = Node.fromValue
 // it exports the _current_ value of nextId, which is always 0
 const NextId = BlankNode.nextId
 
+/**
+ * @deprecated The hand-rolled N3 parser was removed in rdflib 3.0 in favour
+ * of N3.js. This stub only exists to fail loudly with a pointer: use
+ * `parse(text, store, base, contentType)` (or the `n3` package directly)
+ * instead. Calling or constructing it always throws.
+ */
+function N3Parser (): never {
+  throw new Error(
+    'N3Parser was removed in rdflib 3.0; use parse(text, store, base, contentType) or the n3 package directly'
+  )
+}
+
 export * from './utils/terms'
+export { isTrue, literalToBoolean, literalToNumber } from './utils/literalValue'
 export type { AutoInitOptions, ExtendedResponse, FetchError } from './fetcher'
+export type { ParseOptions } from './parse'
 export {
   BlankNode,
   Collection,

src/literal.ts

@@ -7,6 +7,7 @@ import {
   ValueType
 } from './types'
 import { isLiteral } from './utils/terms'
+import { literalToBoolean, literalToNumber } from './utils/literalValue'
 import XSD from './xsd-internal'
 import { Literal as TFLiteral, Term } from './tf-types'
 
@@ -163,6 +164,32 @@ export default class Literal extends Node implements TFLiteral {
     return new Literal(strValue, null, datatype)
   }
 
+  /**
+   * Reads an `xsd:boolean` literal in value space, the inverse of
+   * {@link fromBoolean}, accepting every valid lexical form (`"true"`,
+   * `"1"`, `"false"`, `"0"`). Returns `undefined` for non-literals,
+   * other datatypes and ill-typed lexical forms.
+   *
+   * The parser preserves source lexical forms; compare booleans with this
+   * (or {@link isTrue}) rather than against one spelling of `term.value`.
+   * @param term - The term to read; may be `null`/`undefined`
+   */
+  static toBoolean (term: Term | null | undefined): boolean | undefined {
+    return literalToBoolean(term)
+  }
+
+  /**
+   * Reads a numeric (`xsd:decimal`/integer-family/floating-point) literal in
+   * value space, the inverse of {@link fromNumber}, accepting every valid
+   * lexical form (`"12"`, `"12.0"`, `"1.2e1"` all read as `12`). Returns
+   * `undefined` for non-literals, non-numeric datatypes and ill-typed
+   * lexical forms.
+   * @param term - The term to read; may be `null`/`undefined`
+   */
+  static toNumber (term: Term | null | undefined): number | undefined {
+    return literalToNumber(term)
+  }
+
   /**
    * Builds a literal node from an input value
    * @param value - The input value