eyeling 1.29.2 → 1.30.0

package/index.d.ts

@@ -169,6 +169,8 @@ declare module 'eyeling' {
     store?: string | StoreOptions;
     storePath?: string;
     storeClear?: boolean;
+    rdf?: boolean;
+    rdfSurfaces?: boolean;
   }
 
   export interface BuiltinRegistrationContext {
@@ -191,6 +193,8 @@ declare module 'eyeling' {
     includeInputFactsInClosure?: boolean;
     enforceHttps?: boolean;
     rdfjs?: boolean;
+    rdf?: boolean;
+    rdfSurfaces?: boolean;
     dataFactory?: RdfJsDataFactory | null;
     skipUnsupportedRdfJs?: boolean;
     builtinModules?: string | string[];

package/index.js

@@ -40,7 +40,8 @@ function reason(opt = {}, input = '') {
     else args.push('--no-proof-comments');
   }
 
-  if (opt.rdf) args.push('--rdf');
+  if (opt.rdf || opt.rdfSurfaces) args.push('--rdf');
+  if (opt.rdfSurfaces) args.push('--rdf-surfaces');
 
   if (typeof opt.store === 'string' && opt.store) args.push('--store', opt.store);
   else if (opt.store && typeof opt.store === 'object') {

package/lib/builtins.js

@@ -30,6 +30,8 @@ const {
   PrefixEnv,
   literalParts,
   copyQuotedGraphMetadata,
+  isInternalBlankVarName,
+  internalBlankVarSuffix,
 } = require('./prelude');
 
 const { decodeN3StringEscapes } = require('./lexer');
@@ -132,6 +134,127 @@ function __assertBuiltinHandlerResult(iri, out) {
   }
 }
 
+function collectVarNamesInTerm(t, acc) {
+  if (t instanceof Var) {
+    acc.add(t.name);
+    return;
+  }
+  if (t instanceof ListTerm) {
+    for (const e of t.elems) collectVarNamesInTerm(e, acc);
+    return;
+  }
+  if (t instanceof OpenListTerm) {
+    for (const e of t.prefix) collectVarNamesInTerm(e, acc);
+    acc.add(t.tailVar);
+    return;
+  }
+  if (t instanceof GraphTerm) {
+    for (const tr of t.triples) collectVarNamesInTriple(tr, acc);
+  }
+}
+
+function collectVarNamesInTriple(tr, acc) {
+  collectVarNamesInTerm(tr.s, acc);
+  collectVarNamesInTerm(tr.p, acc);
+  collectVarNamesInTerm(tr.o, acc);
+}
+
+function cloneSubstWithMappedKeys(subst, keyMap, externalizeTerm) {
+  const out = Object.create(null);
+  for (const [key, val] of Object.entries(subst || {})) {
+    out[keyMap.get(key) || key] = externalizeTerm ? externalizeTerm(val) : val;
+  }
+  return out;
+}
+
+function hasInternalBlankVarInSubst(subst) {
+  for (const key of Object.keys(subst || {})) {
+    if (isInternalBlankVarName(key)) return true;
+  }
+  return false;
+}
+
+function makeCustomBuiltinPublicBridge(goal, subst) {
+  const used = new Set(Object.keys(subst || {}).filter((name) => !isInternalBlankVarName(name)));
+  collectVarNamesInTriple(goal, used);
+  for (const name of Array.from(used)) {
+    if (isInternalBlankVarName(name)) used.delete(name);
+  }
+
+  const internalNames = new Set();
+  collectVarNamesInTriple(goal, internalNames);
+  for (const key of Object.keys(subst || {})) internalNames.add(key);
+  for (const name of Array.from(internalNames)) {
+    if (!isInternalBlankVarName(name)) internalNames.delete(name);
+  }
+
+  if (internalNames.size === 0 && !hasInternalBlankVarInSubst(subst)) return null;
+
+  const internalToPublic = new Map();
+  const publicToInternal = new Map();
+
+  function allocatePublicName(internalName) {
+    const suffix = internalBlankVarSuffix(internalName) || String(internalToPublic.size + 1);
+    const base = /^[$A-Za-z_][0-9A-Za-z_]*$/u.test(`_b${suffix}`) ? `_b${suffix}` : `_b${internalToPublic.size + 1}`;
+    let name = base;
+    let n = 1;
+    while (used.has(name) || publicToInternal.has(name)) {
+      n += 1;
+      name = `${base}_${n}`;
+    }
+    used.add(name);
+    internalToPublic.set(internalName, name);
+    publicToInternal.set(name, internalName);
+    return name;
+  }
+
+  for (const name of internalNames) allocatePublicName(name);
+
+  function externalName(name) {
+    if (!isInternalBlankVarName(name)) return name;
+    return internalToPublic.get(name) || allocatePublicName(name);
+  }
+
+  function externalizeTerm(t) {
+    if (t instanceof Var) return new Var(externalName(t.name));
+    if (t instanceof ListTerm) return new ListTerm(t.elems.map(externalizeTerm));
+    if (t instanceof OpenListTerm) return new OpenListTerm(t.prefix.map(externalizeTerm), externalName(t.tailVar));
+    if (t instanceof GraphTerm) {
+      const triples = t.triples.map((tr) => new Triple(externalizeTerm(tr.s), externalizeTerm(tr.p), externalizeTerm(tr.o)));
+      return copyQuotedGraphMetadata(t, new GraphTerm(triples));
+    }
+    return t;
+  }
+
+  function internalizeTerm(t) {
+    if (t instanceof Var) return new Var(publicToInternal.get(t.name) || t.name);
+    if (t instanceof ListTerm) return new ListTerm(t.elems.map(internalizeTerm));
+    if (t instanceof OpenListTerm) return new OpenListTerm(t.prefix.map(internalizeTerm), publicToInternal.get(t.tailVar) || t.tailVar);
+    if (t instanceof GraphTerm) {
+      const triples = t.triples.map((tr) => new Triple(internalizeTerm(tr.s), internalizeTerm(tr.p), internalizeTerm(tr.o)));
+      return copyQuotedGraphMetadata(t, new GraphTerm(triples));
+    }
+    return t;
+  }
+
+  function internalizeDelta(delta) {
+    const out = Object.create(null);
+    for (const [key, val] of Object.entries(delta || {})) {
+      out[publicToInternal.get(key) || key] = internalizeTerm(val);
+    }
+    return out;
+  }
+
+  return {
+    goal: new Triple(externalizeTerm(goal.s), externalizeTerm(goal.p), externalizeTerm(goal.o)),
+    subst: cloneSubstWithMappedKeys(subst, internalToPublic, externalizeTerm),
+    internalizeResults(out) {
+      if (out == null) return out;
+      return out.map(internalizeDelta);
+    },
+  };
+}
+
 function apiTermToN3(term, prefixes = PrefixEnv.newDefault()) {
   return termToN3(term, prefixes || PrefixEnv.newDefault());
 }
@@ -231,10 +354,11 @@ function __evalRegisteredBuiltin(pv, goal, subst, facts, backRules, depth, varGe
   const handler = __customBuiltinHandlers.get(pv);
   if (typeof handler !== 'function') return null;
 
+  const bridge = makeCustomBuiltinPublicBridge(goal, subst);
   const ctx = {
     iri: pv,
-    goal,
-    subst,
+    goal: bridge ? bridge.goal : goal,
+    subst: bridge ? bridge.subst : subst,
     facts,
     backRules,
     depth,
@@ -244,7 +368,8 @@ function __evalRegisteredBuiltin(pv, goal, subst, facts, backRules, depth, varGe
   };
 
   try {
-    const out = handler(ctx);
+    const raw = handler(ctx);
+    const out = bridge ? bridge.internalizeResults(raw) : raw;
     if (out == null) return [];
     __assertBuiltinHandlerResult(pv, out);
     return out;

package/lib/cli.js

@@ -685,7 +685,7 @@ async function ingestLineBasedRdfSourceToStore(sourceLabel, store, { rdfMode = t
 }
 
 
-async function runStreamMessagesMode(sourceLabels, { rdfMode, storeName = null, storePath = null, storeClear = false } = {}) {
+async function runStreamMessagesMode(sourceLabels, { rdfMode, rdfSurfacesMode = false, storeName = null, storePath = null, storeClear = false } = {}) {
   const ordinarySourceLabels = [];
   const messageSourceLabels = [];
 
@@ -723,6 +723,7 @@ async function runStreamMessagesMode(sourceLabels, { rdfMode, storeName = null,
           keepSourceArtifacts: false,
           sourceLocations: false,
           rdf: rdfMode,
+          rdfSurfaces: rdfSurfacesMode,
         }),
       );
     } catch (e) {
@@ -756,6 +757,7 @@ async function runStreamMessagesMode(sourceLabels, { rdfMode, storeName = null,
               keepSourceArtifacts: false,
               sourceLocations: false,
               rdf: false,
+              rdfSurfaces: false,
             });
           } catch (e) {
             if (e && e.name === 'N3SyntaxError') {
@@ -810,6 +812,7 @@ async function main() {
       `  -h, --help                   Show this help and exit.\n` +
       `  -p, --proof                  Enable proof explanations.\n` +
       `  -r, --rdf                    Enable RDF/TriG input/output compatibility.\n` +
+      `      --rdf-surfaces           Enable RDF Surfaces %not[...%] syntax (implies --rdf).\n` +
       `      --stream-messages        Process RDF Message Logs one message at a time under -r.\n` +
       `      --store <name>           Use an optional persistent fact store.\n` +
       `      --store-clear            Clear the named store before this run.\n` +
@@ -885,7 +888,8 @@ async function main() {
   const showAst = argv.includes('--ast') || argv.includes('-a');
   const streamMode = argv.includes('--stream') || argv.includes('-t');
   const streamMessagesMode = argv.includes('--stream-messages');
-  const rdfMode = argv.includes('--rdf') || argv.includes('-r');
+  const rdfSurfacesMode = argv.includes('--rdf-surfaces');
+  const rdfMode = argv.includes('--rdf') || argv.includes('-r') || rdfSurfacesMode;
   const storeName = argv.__storeName || null;
   const storePath = argv.__storePath || null;
   const storeClear = argv.includes('--store-clear');
@@ -954,7 +958,7 @@ async function main() {
   }
 
   if (streamMessagesMode) {
-    await runStreamMessagesMode(sourceLabels, { rdfMode, storeName, storePath, storeClear });
+    await runStreamMessagesMode(sourceLabels, { rdfMode, rdfSurfacesMode, storeName, storePath, storeClear });
     return;
   }
 
@@ -1008,6 +1012,7 @@ async function main() {
                 keepSourceArtifacts: false,
                 sourceLocations: false,
                 rdf: rdfMode,
+                rdfSurfaces: rdfSurfacesMode,
               }),
             );
           } catch (e) {
@@ -1020,7 +1025,7 @@ async function main() {
         }
 
         const mergedRuleDocument = mergeParsedDocuments(parsedRuleSources);
-        const result = await engine.runStoreBacked(mergedRuleDocument, store, { rdf: rdfMode });
+        const result = await engine.runStoreBacked(mergedRuleDocument, store, { rdf: rdfMode, rdfSurfaces: rdfSurfacesMode });
         const outTriples = result.queryMode ? result.queryTriples || [] : (result.derived || []).map((df) => df.fact);
         if (result.queryMode) {
           const bodyText = engine.prettyPrintQueryTriples(outTriples, result.prefixes);
@@ -1055,6 +1060,7 @@ async function main() {
           keepSourceArtifacts: false,
           sourceLocations: engine.getProofCommentsEnabled(),
           rdf: rdfMode,
+          rdfSurfaces: rdfSurfacesMode,
         }),
       );
     } catch (e) {
@@ -1155,6 +1161,7 @@ function factsContainOutputStrings(triplesForOutput) {
       {
         proof: engine.getProofCommentsEnabled(),
         rdf: rdfMode,
+        rdfSurfaces: rdfSurfacesMode,
         store: { name: storeName, clear: storeClear, path: storePath || undefined },
       },
     );

package/lib/engine.js

@@ -3623,12 +3623,14 @@ function reasonStream(input, opts = {}) {
     skipUnsupportedRdfJs = false,
     builtinModules = null,
     rdf = false,
+    rdfSurfaces = false,
     sourceLabel = '<input>',
   } = opts;
 
-  const useRdfCompatibility = !!rdf;
+  const useRdfCompatibility = !!rdf || !!rdfSurfaces;
+  const useRdfSurfaces = !!rdfSurfaces;
 
-  const parsedSourceList = parseN3SourceList(input, { baseIri, rdf: useRdfCompatibility, sourceLocations: proof });
+  const parsedSourceList = parseN3SourceList(input, { baseIri, rdf: useRdfCompatibility, rdfSurfaces: useRdfSurfaces, sourceLocations: proof });
   const parsedTextInput = (!parsedSourceList && proof && typeof input === 'string')
     ? parseN3Text(input, {
         baseIri: baseIri || '',
@@ -3636,6 +3638,7 @@ function reasonStream(input, opts = {}) {
         keepSourceArtifacts: false,
         sourceLocations: true,
         rdf: useRdfCompatibility,
+        rdfSurfaces: useRdfSurfaces,
       })
     : null;
   const hasInlineN3 = input && typeof input === 'object' && !Array.isArray(input) && typeof input.n3 === 'string';
@@ -3680,6 +3683,7 @@ function reasonStream(input, opts = {}) {
       keepSourceArtifacts: false,
       sourceLocations: proof,
       rdf: useRdfCompatibility,
+      rdfSurfaces: useRdfSurfaces,
     });
     prefixes = directDoc.prefixes;
     triples = directDoc.triples;
@@ -3791,10 +3795,11 @@ async function __parseRunAsyncInput(input, opts) {
     baseIri = null,
     proof = false,
     rdf = false,
+    rdfSurfaces = false,
     sourceLabel = '<input>',
   } = opts || {};
 
-  const parsedSourceList = parseN3SourceList(input, { baseIri, rdf: !!rdf, sourceLocations: !!proof });
+  const parsedSourceList = parseN3SourceList(input, { baseIri, rdf: !!rdf || !!rdfSurfaces, rdfSurfaces: !!rdfSurfaces, sourceLocations: !!proof });
   if (parsedSourceList) return parsedSourceList;
 
   const parsedObject = await normalizeParsedReasonerInputAsync(input);
@@ -3809,7 +3814,8 @@ async function __parseRunAsyncInput(input, opts) {
     label: sourceLabel || '<input>',
     keepSourceArtifacts: false,
     sourceLocations: !!proof,
-    rdf: !!rdf,
+    rdf: !!rdf || !!rdfSurfaces,
+    rdfSurfaces: !!rdfSurfaces,
   });
 }
 
@@ -3885,7 +3891,8 @@ async function __proveGoalsAgainstStore(goals, subst, store, backRules, localFac
 async function runStoreBacked(input, store, opts = {}) {
   const parsed = parseN3SourceList(input, {
     baseIri: opts.baseIri || null,
-    rdf: !!opts.rdf,
+    rdf: !!opts.rdf || !!opts.rdfSurfaces,
+    rdfSurfaces: !!opts.rdfSurfaces,
     sourceLocations: !!opts.proof,
   }) || input;
 
@@ -3930,7 +3937,7 @@ async function runStoreBacked(input, store, opts = {}) {
   }
 
   let queryTriples = [];
-  const queryDerived = [];
+  let queryDerived = [];
   if (qrules.length) {
     for (const r of qrules) {
       const solutions = await __proveGoalsAgainstStore(r.premise || [], __emptySubst(), store, brules, triples, 0, varGen, {});
@@ -4002,7 +4009,8 @@ async function runAsync(input, opts = {}) {
   if (!storeConfig) {
     const normalizedInput = parseN3SourceList(input, {
       baseIri: runOpts.baseIri || null,
-      rdf: !!runOpts.rdf,
+      rdf: !!runOpts.rdf || !!runOpts.rdfSurfaces,
+      rdfSurfaces: !!runOpts.rdfSurfaces,
       sourceLocations: !!runOpts.proof,
     }) || (await normalizeReasonerInputAsync(input));
     return reasonStream(normalizedInput, runOpts);

package/lib/lexer.js

@@ -7,6 +7,8 @@
 
 'use strict';
 
+const { normalizeRdfSurfaces } = require('./rdf_surfaces');
+
 class Token {
   constructor(typ, value = null, offset = null) {
     this.typ = typ;
@@ -1347,7 +1349,9 @@ function isNumericLikeIdentifier(word) {
 
 function lex(inputText, opts = {}) {
   const rdf = !!(opts && opts.rdf);
+  const rdfSurfaces = !!(opts && opts.rdfSurfaces);
   if (rdf) inputText = normalizeRdfCompatibility(inputText);
+  if (rdfSurfaces) inputText = normalizeRdfSurfaces(inputText);
   // Avoid copying large ASCII/BMP inputs into an Array.  Array.from() is
   // only needed when the text contains surrogate pairs and we want the old
   // code-point iteration behavior for non-BMP characters.

package/lib/multisource.js

@@ -172,9 +172,10 @@ function parseN3Text(text, opts = {}) {
     collectUsedPrefixes = false,
     sourceLocations = false,
     rdf = false,
+    rdfSurfaces = false,
   } = opts || {};
 
-  if (rdf) {
+  if (rdf && !rdfSurfaces) {
     const fastDoc = tryParseFastRdfText(text, { baseIri, label });
     if (fastDoc) {
       if (sourceLocations) annotateParsedSourceLocations(fastDoc, text, label);
@@ -183,7 +184,7 @@ function parseN3Text(text, opts = {}) {
     }
   }
 
-  const tokens = lex(text, { rdf });
+  const tokens = lex(text, { rdf, rdfSurfaces });
   const parser = new Parser(tokens);
   if (baseIri) parser.prefixes.setBase(baseIri);
   const [prefixes, triples, frules, brules, logQueryRules] = parser.parseDocument();
@@ -382,7 +383,8 @@ function parseN3SourceList(input, opts = {}) {
       collectUsedPrefixes: true,
       keepSourceArtifacts: !!opts.keepSourceArtifacts,
       sourceLocations: !!opts.sourceLocations,
-      rdf: !!opts.rdf,
+      rdf: !!opts.rdf || !!opts.rdfSurfaces,
+      rdfSurfaces: !!opts.rdfSurfaces,
     }),
   );
   return mergeParsedDocuments(parsed, {

package/lib/prelude.js

@@ -25,6 +25,21 @@ const DT_NS = 'https://eyereasoner.github.io/eyeling/datatype#';
 const SKOLEM_NS = 'https://eyereasoner.github.io/.well-known/genid/';
 const RDF_JSON_DT = RDF_NS + 'JSON';
 
+// Private rule-lifting variable prefix used for blank nodes that appear in
+// rule-body patterns.  The prefix is intentionally not spellable in N3 input,
+// but public extension APIs should present these variables with stable,
+// ordinary names and translate them back internally.
+const INTERNAL_BLANK_VAR_PREFIX = '\uE000eyeling_b';
+
+function isInternalBlankVarName(name) {
+  return typeof name === 'string' && name.startsWith(INTERNAL_BLANK_VAR_PREFIX);
+}
+
+function internalBlankVarSuffix(name) {
+  if (!isInternalBlankVarName(name)) return '';
+  return name.slice(INTERNAL_BLANK_VAR_PREFIX.length);
+}
+
 function parseUriReferenceForResolution(uri) {
   // RFC 3986 Appendix B-style component parser, with the scheme tightened to
   // the RFC scheme grammar. Capturing delimiter presence matters: `?` with an
@@ -728,6 +743,9 @@ module.exports = {
   DT_NS,
   SKOLEM_NS,
   RDF_JSON_DT,
+  INTERNAL_BLANK_VAR_PREFIX,
+  isInternalBlankVarName,
+  internalBlankVarSuffix,
   resolveIriRef,
   literalParts,
   normalizeLiteralForTid,