eyeling 1.27.8 → 1.28.0

package/lib/rdfjs.js

@@ -9,6 +9,7 @@
 
 const {
   XSD_NS,
+  LOG_NS,
   Literal: InternalLiteral,
   Iri,
   Blank,
@@ -19,6 +20,7 @@ const {
   Triple,
   Rule,
   PrefixEnv,
+  annotateQuotedGraphTerm,
   literalParts,
 } = require('./prelude');
 const { termToN3, tripleToN3 } = require('./printing');
@@ -322,6 +324,49 @@ function internalRdf12TermToRdfJs(term, factory, position) {
   return internalTermToRdfJs(term, rdfFactory, position);
 }
 
+function isDefaultGraphTerm(term) {
+  return isRdfJsTerm(term) && term.termType === 'DefaultGraph';
+}
+
+function assertDefaultGraphForRdfJsQuadTerm(term, position) {
+  if (!isDefaultGraphTerm(term.graph)) {
+    throw new TypeError(`RDF/JS Quad terms with named graphs are not supported in ${position}`);
+  }
+}
+
+function rdfJsGraphNameToInternal(term, position = 'quad.graph') {
+  assertSupportedRdfJsTerm(term, position);
+  switch (term.termType) {
+    case 'NamedNode':
+      return new Iri(term.value);
+    case 'BlankNode':
+      return new Blank(`_:${term.value}`);
+    case 'DefaultGraph':
+      return null;
+    default:
+      throw new TypeError(`Invalid RDF graph termType ${term.termType}`);
+  }
+}
+
+function internalGraphNameToRdfJs(term, factory, position = 'graph') {
+  if (term instanceof Iri || term instanceof Blank) return internalTermToRdfJs(term, factory, position);
+  return unsupportedRdfJsTerm(term, position);
+}
+
+function graphKey(term) {
+  return `${term.termType}:${term.value}`;
+}
+
+function isInternalLogNameOfTriple(triple) {
+  return (
+    triple instanceof Triple &&
+    (triple.s instanceof Iri || triple.s instanceof Blank) &&
+    triple.p instanceof Iri &&
+    triple.p.value === LOG_NS + 'nameOf' &&
+    triple.o instanceof GraphTerm
+  );
+}
+
 function assertRdfJsQuadShape(subject, predicate, object, graph) {
   if (!['NamedNode', 'BlankNode', 'Quad'].includes(subject.termType)) {
     throw new TypeError(`Invalid RDF subject termType ${subject.termType}`);
@@ -350,13 +395,22 @@ function internalTripleToRdfJsQuadInGraph(triple, graph, factory) {
 function internalTripleToRdfJsQuad(triple, factory) {
   const rdfFactory = getDataFactory(factory);
   return rdfFactory.quad(
-    internalTermToRdfJs(triple.s, rdfFactory, 'subject'),
+    internalRdf12TermToRdfJs(triple.s, rdfFactory, 'subject'),
     internalTermToRdfJs(triple.p, rdfFactory, 'predicate'),
-    internalTermToRdfJs(triple.o, rdfFactory, 'object'),
+    internalRdf12TermToRdfJs(triple.o, rdfFactory, 'object'),
     rdfFactory.defaultGraph(),
   );
 }
 
+function internalTripleToRdfJsQuads(triple, factory) {
+  const rdfFactory = getDataFactory(factory);
+  if (isInternalLogNameOfTriple(triple)) {
+    const graph = internalGraphNameToRdfJs(triple.s, rdfFactory, 'graph');
+    return (triple.o.triples || []).map((inner) => internalTripleToRdfJsQuadInGraph(inner, graph, rdfFactory));
+  }
+  return [internalTripleToRdfJsQuad(triple, rdfFactory)];
+}
+
 function escapeStringForN3(value) {
   return JSON.stringify(String(value));
 }
@@ -388,7 +442,14 @@ function rdfJsTermToN3(term, position = 'term') {
       return `${lexical}^^<${datatype}>`;
     }
     case 'Quad':
-      throw new TypeError(`Quoted triple terms are not supported in ${position}`);
+      if (String(position).endsWith('.predicate') || position === 'quad.predicate' || position === 'predicate') {
+        throw new TypeError(`Quoted triple terms are not valid RDF predicates in ${position}`);
+      }
+      assertDefaultGraphForRdfJsQuadTerm(term, position);
+      return `{ ${rdfJsTermToN3(term.subject, `${position}.subject`)} ${rdfJsTermToN3(
+        term.predicate,
+        `${position}.predicate`,
+      )} ${rdfJsTermToN3(term.object, `${position}.object`)} . }`;
     default:
       throw new TypeError(`Unsupported RDF/JS termType ${JSON.stringify(term.termType)} in ${position}`);
   }
@@ -408,8 +469,21 @@ function rdfJsTermToInternal(term, position = 'term') {
       return new InternalLiteral(rdfJsTermToN3(term, position));
     case 'DefaultGraph':
       throw new TypeError(`DefaultGraph is not a valid standalone N3 term in ${position}`);
-    case 'Quad':
-      throw new TypeError(`Quoted triple terms are not supported in ${position}`);
+    case 'Quad': {
+      if (String(position).endsWith('.predicate') || position === 'quad.predicate' || position === 'predicate') {
+        throw new TypeError(`Quoted triple terms are not valid RDF predicates in ${position}`);
+      }
+      assertDefaultGraphForRdfJsQuadTerm(term, position);
+      return annotateQuotedGraphTerm(
+        new GraphTerm([
+          new Triple(
+            rdfJsTermToInternal(term.subject, `${position}.subject`),
+            rdfJsTermToInternal(term.predicate, `${position}.predicate`),
+            rdfJsTermToInternal(term.object, `${position}.object`),
+          ),
+        ]),
+      );
+    }
     default:
       throw new TypeError(`Unsupported RDF/JS termType ${JSON.stringify(term.termType)} in ${position}`);
   }
@@ -417,22 +491,58 @@ function rdfJsTermToInternal(term, position = 'term') {
 
 function rdfJsQuadToInternalTriple(quad) {
   if (!isRdfJsQuad(quad)) throw new TypeError('Expected an RDF/JS Quad');
-  if (quad.graph.termType !== 'DefaultGraph') {
-    throw new TypeError('Named graph quads are not supported by Eyeling input; use the default graph only');
-  }
-  return new Triple(
+  const inner = new Triple(
     rdfJsTermToInternal(quad.subject, 'quad.subject'),
     rdfJsTermToInternal(quad.predicate, 'quad.predicate'),
     rdfJsTermToInternal(quad.object, 'quad.object'),
   );
+  const graph = rdfJsGraphNameToInternal(quad.graph, 'quad.graph');
+  if (!graph) return inner;
+  return new Triple(graph, new Iri(LOG_NS + 'nameOf'), annotateQuotedGraphTerm(new GraphTerm([inner])));
+}
+
+function rdfJsQuadsToInternalTriples(quads) {
+  const out = [];
+  const namedGraphs = new Map();
+
+  for (const quad of quads) {
+    if (!isRdfJsQuad(quad)) throw new TypeError('Expected an RDF/JS Quad');
+    const inner = new Triple(
+      rdfJsTermToInternal(quad.subject, 'quad.subject'),
+      rdfJsTermToInternal(quad.predicate, 'quad.predicate'),
+      rdfJsTermToInternal(quad.object, 'quad.object'),
+    );
+    const graph = rdfJsGraphNameToInternal(quad.graph, 'quad.graph');
+    if (!graph) {
+      out.push(inner);
+      continue;
+    }
+
+    const key = graphKey(quad.graph);
+    let group = namedGraphs.get(key);
+    if (!group) {
+      group = { graph, triples: [] };
+      namedGraphs.set(key, group);
+    }
+    group.triples.push(inner);
+  }
+
+  for (const { graph, triples } of namedGraphs.values()) {
+    out.push(new Triple(graph, new Iri(LOG_NS + 'nameOf'), annotateQuotedGraphTerm(new GraphTerm(triples))));
+  }
+
+  return out;
 }
 
 function rdfJsQuadToN3(quad) {
   if (!isRdfJsQuad(quad)) throw new TypeError('Expected an RDF/JS Quad');
-  if (quad.graph.termType !== 'DefaultGraph') {
-    throw new TypeError('Named graph quads are not supported by Eyeling input; use the default graph only');
-  }
-  return `${rdfJsTermToN3(quad.subject, 'quad.subject')} ${rdfJsTermToN3(quad.predicate, 'quad.predicate')} ${rdfJsTermToN3(quad.object, 'quad.object')}.`;
+  return tripleToN3(rdfJsQuadToInternalTriple(quad), PrefixEnv.newDefault());
+}
+
+function rdfJsQuadsToN3(quads) {
+  return rdfJsQuadsToInternalTriples(quads)
+    .map((triple) => tripleToN3(triple, PrefixEnv.newDefault()))
+    .join('\n');
 }
 
 function collectIterableToArray(iterable, label) {
@@ -477,6 +587,11 @@ function getPrefixesText(input) {
   return '';
 }
 
+function getN3Text(input) {
+  if (!isObject(input)) return '';
+  return typeof input.n3 === 'string' ? input.n3 : '';
+}
+
 function joinN3Sections(parts) {
   return parts
     .filter((part) => typeof part === 'string' && part.length > 0)
@@ -745,7 +860,7 @@ function appendSyncQuadFacts(doc, input) {
   const quads = collectIterableToArray(quadsInfo.value, quadsInfo.label);
   return {
     ...doc,
-    triples: doc.triples.concat(quads.map((quad) => rdfJsQuadToInternalTriple(quad))),
+    triples: doc.triples.concat(rdfJsQuadsToInternalTriples(quads)),
   };
 }
 
@@ -755,7 +870,7 @@ async function appendAsyncQuadFacts(doc, input) {
   const quads = await collectAsyncIterableToArray(quadsInfo.value, quadsInfo.label);
   return {
     ...doc,
-    triples: doc.triples.concat(quads.map((quad) => rdfJsQuadToInternalTriple(quad))),
+    triples: doc.triples.concat(rdfJsQuadsToInternalTriples(quads)),
   };
 }
 
@@ -774,13 +889,13 @@ async function normalizeParsedReasonerInputAsync(input) {
 function normalizeReasonerInputSync(input) {
   if (typeof input === 'string') return input;
   const parsed = normalizeParsedReasonerInputSync(input);
-  if (parsed) return serializeEyelingDocument(parsed);
+  const n3Text = getN3Text(input);
+  if (parsed) return joinN3Sections([n3Text, serializeEyelingDocument(parsed)]);
   if (!isObject(input)) {
     throw new TypeError(
       'Reasoner input must be an N3 string, an Eyeling AST/rule object, or an object containing RDF/JS quads plus optional rules',
     );
   }
-  if (typeof input.n3 === 'string') return input.n3;
 
   const quadsInfo = pickInputQuadIterable(input);
   const rulesText = getRulesText(input);
@@ -788,25 +903,25 @@ function normalizeReasonerInputSync(input) {
   const prefixesText = getPrefixesText(input);
 
   if (!quadsInfo) {
-    if (rulesText || factsText || prefixesText) return joinN3Sections([prefixesText, factsText, rulesText]);
+    if (n3Text || rulesText || factsText || prefixesText) return joinN3Sections([prefixesText, n3Text, factsText, rulesText]);
     throw new TypeError('Input object must provide n3 text, Eyeling AST/rule objects, or RDF/JS quads/facts/dataset');
   }
 
   const quads = collectIterableToArray(quadsInfo.value, quadsInfo.label);
-  const quadText = quads.map((quad) => rdfJsQuadToN3(quad)).join('\n');
-  return joinN3Sections([prefixesText, factsText, quadText, rulesText]);
+  const quadText = rdfJsQuadsToN3(quads);
+  return joinN3Sections([prefixesText, n3Text, factsText, quadText, rulesText]);
 }
 
 async function normalizeReasonerInputAsync(input) {
   if (typeof input === 'string') return input;
   const parsed = await normalizeParsedReasonerInputAsync(input);
-  if (parsed) return serializeEyelingDocument(parsed);
+  const n3Text = getN3Text(input);
+  if (parsed) return joinN3Sections([n3Text, serializeEyelingDocument(parsed)]);
   if (!isObject(input)) {
     throw new TypeError(
       'Reasoner input must be an N3 string, an Eyeling AST/rule object, or an object containing RDF/JS quads plus optional rules',
     );
   }
-  if (typeof input.n3 === 'string') return input.n3;
 
   const quadsInfo = pickInputQuadIterable(input);
   const rulesText = getRulesText(input);
@@ -814,13 +929,13 @@ async function normalizeReasonerInputAsync(input) {
   const prefixesText = getPrefixesText(input);
 
   if (!quadsInfo) {
-    if (rulesText || factsText || prefixesText) return joinN3Sections([prefixesText, factsText, rulesText]);
+    if (n3Text || rulesText || factsText || prefixesText) return joinN3Sections([prefixesText, n3Text, factsText, rulesText]);
     throw new TypeError('Input object must provide n3 text, Eyeling AST/rule objects, or RDF/JS quads/facts/dataset');
   }
 
   const quads = await collectAsyncIterableToArray(quadsInfo.value, quadsInfo.label);
-  const quadText = quads.map((quad) => rdfJsQuadToN3(quad)).join('\n');
-  return joinN3Sections([prefixesText, factsText, quadText, rulesText]);
+  const quadText = rdfJsQuadsToN3(quads);
+  return joinN3Sections([prefixesText, n3Text, factsText, quadText, rulesText]);
 }
 
 module.exports = {
@@ -831,8 +946,10 @@ module.exports = {
   rdfJsTermToN3,
   rdfJsQuadToN3,
   rdfJsQuadToInternalTriple,
+  rdfJsQuadsToInternalTriples,
   internalTermToRdfJs,
   internalTripleToRdfJsQuad,
+  internalTripleToRdfJsQuads,
   internalTripleToRdfJsQuadInGraph,
   normalizeParsedReasonerInputSync,
   normalizeReasonerInputSync,

package/notes/rdf12-roundtrip.md

@@ -0,0 +1,231 @@
+# Eyeling RDF 1.2 Compatibility Mode and Roundtripping
+
+## Summary
+
+Eyeling does **not** implement RDF 1.2 as a separate internal data model. RDF/TriG compatibility is an opt-in **syntax-normalization layer** in `lib/lexer.js`.
+
+When parsing with RDF mode enabled, Eyeling rewrites RDF 1.2/TriG surface syntax into ordinary N3 syntax. The normal parser and reasoner then operate on Eyeling's existing N3 AST. On output, `lib/printing.js` can print some N3 graph terms back as RDF 1.2 triple terms.
+
+The flow is:
+
+```text
+RDF 1.2 / TriG input
+  -- lex(input, { rdf: true }) / normalizeRdfCompatibility() -->
+normalized N3 text
+  -- Parser -->
+Eyeling N3 AST
+  -- reasoner -->
+derived N3 facts
+  -- tripleToRdfCompatible() -->
+RDF-compatible output
+```
+
+## Main internal representation
+
+RDF 1.2 triple terms are represented as **singleton N3 graph terms**.
+
+Input:
+
+```turtle
+:obs rdf:reifies <<( :s :p :o )>> .
+```
+
+Normalized N3:
+
+```n3
+:obs rdf:reifies { :s :p :o } .
+```
+
+Conceptual AST shape:
+
+```js
+Triple(
+  Iri(':obs'),
+  Iri('rdf:reifies'),
+  GraphTerm([
+    Triple(Iri(':s'), Iri(':p'), Iri(':o'))
+  ])
+)
+```
+
+So the core mapping is:
+
+```text
+<<( S P O )>>  <=>  { S P O }
+```
+
+But internally, Eyeling keeps only the N3 side: a `GraphTerm` containing one `Triple`.
+
+## Reifier sugar
+
+RDF 1.2 reifier syntax is desugared by `convertTripleTerms()` in `lib/lexer.js`.
+
+Input:
+
+```turtle
+<< :s :p :o ~ :r >> :source :doc .
+```
+
+Normalized shape:
+
+```n3
+{ :s :p :o } :source :doc .
+:r <http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies> { :s :p :o } .
+```
+
+So the reifier is preserved structurally, but not as a special AST node. It becomes an ordinary `rdf:reifies` triple whose object is the singleton graph term.
+
+## Annotation syntax
+
+Annotation syntax is handled by `convertAnnotations()` in `lib/lexer.js`.
+
+Input:
+
+```turtle
+:s :p :o ~ :r {| :source :doc |} .
+```
+
+Normalized N3:
+
+```n3
+:s :p :o .
+:r <http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies> { :s :p :o } .
+:r :source :doc .
+```
+
+If an annotation block exists without an explicit reifier, the lexer generates a blank node such as `_:rdfAnnotation1`.
+
+## TriG named graphs
+
+TriG-style named graph blocks are normalized by `normalizeNamedGraphs()`.
+
+Input:
+
+```trig
+:g {
+  :s :p :o .
+}
+```
+
+Normalized N3:
+
+```n3
+:g <http://www.w3.org/2000/10/swap/log#nameOf> {
+  :s :p :o .
+} .
+```
+
+A top-level default graph block is unwrapped:
+
+```trig
+{
+  :s :p :o .
+}
+```
+
+becomes:
+
+```n3
+:s :p :o .
+```
+
+## Reasoning model
+
+After normalization, RDF 1.2 constructs are ordinary N3 terms. For example, this rule can match reified RDF 1.2 triples:
+
+```n3
+{ ?r rdf:reifies { ?s ?p ?o } }
+=>
+{ ?r :mentionsSubject ?s } .
+```
+
+That works because the RDF triple term has already become an N3 graph term.
+
+## Output and roundtrip
+
+RDF-compatible output is implemented in `lib/printing.js` by:
+
+- `termToRdfCompatible()`
+- `tripleToRdfCompatible()`
+- `rdfCompatibleGraphBlock()`
+
+A `GraphTerm` is printed back as an RDF 1.2 triple term only if it is a singleton graph containing one RDF-compatible triple:
+
+```js
+GraphTerm([
+  Triple(subject, predicate, object)
+])
+```
+
+with:
+
+```text
+subject   = IRI or blank node
+predicate = IRI
+object    = IRI, blank node, or literal
+```
+
+Then:
+
+```n3
+:obs rdf:reifies { :s :p :o } .
+```
+
+can print as:
+
+```turtle
+:obs rdf:reifies <<( :s :p :o )>> .
+```
+
+And:
+
+```n3
+:g log:nameOf {
+  :s :p :o .
+} .
+```
+
+can print as:
+
+```trig
+:g {
+    :s :p :o .
+}
+```
+
+## What roundtrip means
+
+The roundtrip is **structural**, not lexical.
+
+Eyeling can roundtrip the meaning of RDF 1.2 triple terms through its N3 representation:
+
+```text
+RDF 1.2 triple term
+  <<( :s :p :o )>>
+
+N3 internal representation
+  { :s :p :o }
+
+RDF-compatible output
+  <<( :s :p :o )>>
+```
+
+But it does not preserve exact source spelling, whitespace, prefix layout, or whether the user originally wrote explicit `rdf:reifies`, triple-term sugar, or annotation syntax.
+
+## Limitations
+
+Only singleton graph terms that are RDF-compatible are printed back as `<<( ... )>>`.
+
+These remain ordinary N3 graph terms on output:
+
+```n3
+{ :s :p :o . :x :y :z . }
+```
+
+because the graph has more than one triple.
+
+Also, graph terms containing N3-only constructs, variables, or nested formula objects are not valid RDF 1.2 triple terms and therefore remain N3.
+
+## One-line takeaway
+
+Eyeling maps RDF 1.2 triple terms to singleton N3 `GraphTerm`s, maps TriG named graphs to `log:nameOf` triples, reasons over the normal N3 AST, and prints singleton RDF-compatible graph terms back as `<<( ... )>>` when possible.