eyeling 1.23.3 → 1.23.5

package/HANDBOOK.md

@@ -1902,6 +1902,8 @@ node eyeling.js --builtin examples/builtin/queens.js examples/queens.n3
 
 Examples that do not need a custom builtin should not add a matching file under `examples/builtin/`. Examples that do need one should ship it there and let the examples test runner load it uniformly. For example, `examples/sudoku.n3` is paired with `examples/builtin/sudoku.js`, and `examples/queens.n3` is paired with `examples/builtin/queens.js`.
 
+The browser playground follows the same convention for URL-loaded repository examples: when a loaded URL looks like `.../examples/name.n3`, the playground tries to fetch `.../examples/builtin/name.js` and register it before reasoning. If no matching builtin file exists, the N3 program runs normally.
+
 ### 14.2 The bundled Node CLI/runtime (`eyeling.js`)
 
 The bundle contains the whole engine. The CLI path is the “canonical behavior”:
@@ -1965,7 +1967,7 @@ It deliberately does **not** expose `loadBuiltinModule(...)`, because loading bu
 
 For browser apps, prefer running Eyeling in a **Web Worker** and importing `eyeling/browser` there.
 
-### 14.3 `lib/entry.js`: bundler-friendly exports
+### 14.4 `lib/entry.js`: bundler-friendly exports
 
 `lib/entry.js` exports:
 
@@ -1974,14 +1976,14 @@ For browser apps, prefer running Eyeling in a **Web Worker** and importing `eyel
 
 `rdfjs` is a small built-in RDF/JS `DataFactory`, so browser / worker code can construct quads without pulling in another package first.
 
-### 14.4 JavaScript API
+### 14.5 JavaScript API
 
 Eyeling exposes two JavaScript entry styles:
 
 - `reason(...)` from `index.js` when you want the same text output as the CLI
 - `reasonStream(...)` / `reasonRdfJs(...)` from the Node bundle or `eyeling/browser` when you want in-process reasoning and structured RDF/JS results
 
-#### 14.4.1 npm helper: `reason(...)`
+#### 14.5.1 npm helper: `reason(...)`
 
 The npm `reason(...)` function does something intentionally simple and robust:
 
@@ -2034,7 +2036,7 @@ Notes:
 - By default, the npm helper keeps output machine-friendly (`proofComments: false`).
 - Use this path when you want CLI-equivalent behavior inside JavaScript.
 
-#### 14.4.2 RDF-JS and Eyeling rule-object interoperability
+#### 14.5.2 RDF-JS and Eyeling rule-object interoperability
 
 The JavaScript APIs accept four input styles:
 
@@ -2112,7 +2114,7 @@ console.log(out);
 
 You can also pass a full AST bundle directly, for example `[prefixes, triples, forwardRules, backwardRules]`.
 
-#### 14.4.3 In-process bundle API: `reasonStream(...)` and `reasonRdfJs(...)`
+#### 14.5.3 In-process bundle API: `reasonStream(...)` and `reasonRdfJs(...)`
 
 Use the bundle entry if you want structured results while the engine is running instead of final CLI text after the fact.
 
@@ -2151,7 +2153,7 @@ Use these entry points when you need one or more of the following:
 - derived results consumed as RDF/JS quads
 - streaming derived RDF/JS quads during reasoning
 
-### 14.5 Choosing the right entry point
+### 14.6 Choosing the right entry point
 
 A practical rule of thumb:
 
@@ -2392,7 +2394,7 @@ Run it explicitly like this:
 eyeling --builtin examples/builtin/sudoku.js examples/sudoku.n3
 ```
 
-`npm run test:examples` uses the same convention automatically: when it sees `examples/builtin/sudoku.js` next to `examples/sudoku.n3`, it loads that module for the Sudoku example.
+`npm run test:examples` uses the same convention automatically: when it sees `examples/builtin/sudoku.js` next to `examples/sudoku.n3`, it loads that module for the Sudoku example. The browser playground uses the convention too for URL-loaded repository examples, so loading the raw `examples/sudoku.n3` URL also fetches and registers the matching `examples/builtin/sudoku.js` module.
 
 That example is useful for two reasons:
 

package/dist/browser/eyeling.browser.js

@@ -8702,10 +8702,21 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
       deref.setEnforceHttpsEnabled(!!enforceHttps);
       proofCommentsEnabled = !!proof;
 
+      function registerBuiltinModuleOption(mod, index) {
+        if (!mod) return;
+        if (typeof mod === 'string') {
+          loadBuiltinModule(mod);
+          return;
+        }
+        registerBuiltinModule(mod, `<reasonStream builtinModules[${index}]>`);
+      }
+
       if (Array.isArray(builtinModules)) {
-        for (const spec of builtinModules) loadBuiltinModule(spec);
-      } else if (typeof builtinModules === 'string' && builtinModules) {
-        loadBuiltinModule(builtinModules);
+        for (let i = 0; i < builtinModules.length; i += 1) {
+          registerBuiltinModuleOption(builtinModules[i], i);
+        }
+      } else {
+        registerBuiltinModuleOption(builtinModules, 0);
       }
 
       let prefixes, triples, frules, brules, logQueryRules;
@@ -8989,6 +9000,11 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
       tripleToN3: engine.tripleToN3,
       collectOutputStringsFromFacts: engine.collectOutputStringsFromFacts,
       prettyPrintQueryTriples: engine.prettyPrintQueryTriples,
+      registerBuiltin: engine.registerBuiltin,
+      unregisterBuiltin: engine.unregisterBuiltin,
+      registerBuiltinModule: engine.registerBuiltinModule,
+      loadBuiltinModule: engine.loadBuiltinModule,
+      listBuiltinIris: engine.listBuiltinIris,
       getEnforceHttpsEnabled: engine.getEnforceHttpsEnabled,
       setEnforceHttpsEnabled: engine.setEnforceHttpsEnabled,
       getProofCommentsEnabled: engine.getProofCommentsEnabled,
@@ -11142,6 +11158,37 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
 
     const __literalPartsCache = new Map(); // lit string -> [lex, dt]
 
+    function quotedLiteralEndIndex(str) {
+      if (typeof str !== 'string' || str.length < 2) return -1;
+
+      const quote = str[0];
+      if (quote !== '"' && quote !== "'") return -1;
+
+      const delimLen = str.startsWith(quote.repeat(3)) ? 3 : 1;
+      const delim = quote.repeat(delimLen);
+
+      let i = delimLen;
+      while (i < str.length) {
+        // Stored literals may contain escaped quotes, e.g. \"...\"^^xsd:dateTime
+        // inside a plain string. Those must not terminate the outer lexical form.
+        if (str[i] === '\\') {
+          i += 2;
+          continue;
+        }
+
+        if (delimLen === 1) {
+          if (str[i] === quote) return i + 1;
+          i += 1;
+          continue;
+        }
+
+        if (str.startsWith(delim, i)) return i + delimLen;
+        i += 1;
+      }
+
+      return -1;
+    }
+
     function literalParts(lit) {
       // Avoid caching extremely large literals (notably huge numeric intermediates)
       // to prevent unbounded memory growth.
@@ -11159,24 +11206,21 @@ ${triples.map((tr) => `  ${tripleToN3(tr, prefixes)}`).join('\n')}
       let lex = lit;
       let dt = null;
 
-      const re = /^(['"]{1,3})([\s\S]*?)\1\^\^(.+)$/;
-      const match = lit.match(re);
-      if (match) {
-        lex = match[1] + match[2] + match[1];
-        dt = match[3];
+      const lexEnd = quotedLiteralEndIndex(lit);
+      if (lexEnd > 0 && lit.startsWith('^^', lexEnd)) {
+        lex = lit.slice(0, lexEnd);
+        dt = lit.slice(lexEnd + 2);
         if (dt.startsWith('<') && dt.endsWith('>')) {
           dt = dt.slice(1, -1);
         }
       }
 
       // Strip LANGTAG from the lexical form when present.
-      if (lex.length >= 2 && lex[0] === '"') {
-        const lastQuote = lex.lastIndexOf('"');
-        if (lastQuote > 0 && lastQuote < lex.length - 1 && lex[lastQuote + 1] === '@') {
-          const lang = lex.slice(lastQuote + 2);
-          if (/^[A-Za-z]+(?:-[A-Za-z0-9]+)*$/.test(lang)) {
-            lex = lex.slice(0, lastQuote + 1);
-          }
+      const langLexEnd = quotedLiteralEndIndex(lex);
+      if (langLexEnd > 0 && lex[0] === '"' && langLexEnd < lex.length && lex[langLexEnd] === '@') {
+        const lang = lex.slice(langLexEnd + 1);
+        if (/^[A-Za-z]+(?:-[A-Za-z0-9]+)*$/.test(lang)) {
+          lex = lex.slice(0, langLexEnd);
         }
       }
 

package/eyeling.js

@@ -8679,10 +8679,21 @@ function reasonStream(input, opts = {}) {
   deref.setEnforceHttpsEnabled(!!enforceHttps);
   proofCommentsEnabled = !!proof;
 
+  function registerBuiltinModuleOption(mod, index) {
+    if (!mod) return;
+    if (typeof mod === 'string') {
+      loadBuiltinModule(mod);
+      return;
+    }
+    registerBuiltinModule(mod, `<reasonStream builtinModules[${index}]>`);
+  }
+
   if (Array.isArray(builtinModules)) {
-    for (const spec of builtinModules) loadBuiltinModule(spec);
-  } else if (typeof builtinModules === 'string' && builtinModules) {
-    loadBuiltinModule(builtinModules);
+    for (let i = 0; i < builtinModules.length; i += 1) {
+      registerBuiltinModuleOption(builtinModules[i], i);
+    }
+  } else {
+    registerBuiltinModuleOption(builtinModules, 0);
   }
 
   let prefixes, triples, frules, brules, logQueryRules;
@@ -8967,6 +8978,11 @@ module.exports = {
   tripleToN3: engine.tripleToN3,
   collectOutputStringsFromFacts: engine.collectOutputStringsFromFacts,
   prettyPrintQueryTriples: engine.prettyPrintQueryTriples,
+  registerBuiltin: engine.registerBuiltin,
+  unregisterBuiltin: engine.unregisterBuiltin,
+  registerBuiltinModule: engine.registerBuiltinModule,
+  loadBuiltinModule: engine.loadBuiltinModule,
+  listBuiltinIris: engine.listBuiltinIris,
   getEnforceHttpsEnabled: engine.getEnforceHttpsEnabled,
   setEnforceHttpsEnabled: engine.setEnforceHttpsEnabled,
   getProofCommentsEnabled: engine.getProofCommentsEnabled,
@@ -11114,6 +11130,37 @@ const MAX_LITERAL_PARTS_CACHE_LEN = 1024;
 
 const __literalPartsCache = new Map(); // lit string -> [lex, dt]
 
+function quotedLiteralEndIndex(str) {
+  if (typeof str !== 'string' || str.length < 2) return -1;
+
+  const quote = str[0];
+  if (quote !== '"' && quote !== "'") return -1;
+
+  const delimLen = str.startsWith(quote.repeat(3)) ? 3 : 1;
+  const delim = quote.repeat(delimLen);
+
+  let i = delimLen;
+  while (i < str.length) {
+    // Stored literals may contain escaped quotes, e.g. \"...\"^^xsd:dateTime
+    // inside a plain string. Those must not terminate the outer lexical form.
+    if (str[i] === '\\') {
+      i += 2;
+      continue;
+    }
+
+    if (delimLen === 1) {
+      if (str[i] === quote) return i + 1;
+      i += 1;
+      continue;
+    }
+
+    if (str.startsWith(delim, i)) return i + delimLen;
+    i += 1;
+  }
+
+  return -1;
+}
+
 function literalParts(lit) {
   // Avoid caching extremely large literals (notably huge numeric intermediates)
   // to prevent unbounded memory growth.
@@ -11131,24 +11178,21 @@ function literalParts(lit) {
   let lex = lit;
   let dt = null;
 
-  const re = /^(['"]{1,3})([\s\S]*?)\1\^\^(.+)$/;
-  const match = lit.match(re);
-  if (match) {
-    lex = match[1] + match[2] + match[1];
-    dt = match[3];
+  const lexEnd = quotedLiteralEndIndex(lit);
+  if (lexEnd > 0 && lit.startsWith('^^', lexEnd)) {
+    lex = lit.slice(0, lexEnd);
+    dt = lit.slice(lexEnd + 2);
     if (dt.startsWith('<') && dt.endsWith('>')) {
       dt = dt.slice(1, -1);
     }
   }
 
   // Strip LANGTAG from the lexical form when present.
-  if (lex.length >= 2 && lex[0] === '"') {
-    const lastQuote = lex.lastIndexOf('"');
-    if (lastQuote > 0 && lastQuote < lex.length - 1 && lex[lastQuote + 1] === '@') {
-      const lang = lex.slice(lastQuote + 2);
-      if (/^[A-Za-z]+(?:-[A-Za-z0-9]+)*$/.test(lang)) {
-        lex = lex.slice(0, lastQuote + 1);
-      }
+  const langLexEnd = quotedLiteralEndIndex(lex);
+  if (langLexEnd > 0 && lex[0] === '"' && langLexEnd < lex.length && lex[langLexEnd] === '@') {
+    const lang = lex.slice(langLexEnd + 1);
+    if (/^[A-Za-z]+(?:-[A-Za-z0-9]+)*$/.test(lang)) {
+      lex = lex.slice(0, langLexEnd);
     }
   }
 

package/lib/engine.js

@@ -3384,10 +3384,21 @@ function reasonStream(input, opts = {}) {
   deref.setEnforceHttpsEnabled(!!enforceHttps);
   proofCommentsEnabled = !!proof;
 
+  function registerBuiltinModuleOption(mod, index) {
+    if (!mod) return;
+    if (typeof mod === 'string') {
+      loadBuiltinModule(mod);
+      return;
+    }
+    registerBuiltinModule(mod, `<reasonStream builtinModules[${index}]>`);
+  }
+
   if (Array.isArray(builtinModules)) {
-    for (const spec of builtinModules) loadBuiltinModule(spec);
-  } else if (typeof builtinModules === 'string' && builtinModules) {
-    loadBuiltinModule(builtinModules);
+    for (let i = 0; i < builtinModules.length; i += 1) {
+      registerBuiltinModuleOption(builtinModules[i], i);
+    }
+  } else {
+    registerBuiltinModuleOption(builtinModules, 0);
   }
 
   let prefixes, triples, frules, brules, logQueryRules;

package/lib/entry.js

@@ -34,6 +34,11 @@ module.exports = {
   tripleToN3: engine.tripleToN3,
   collectOutputStringsFromFacts: engine.collectOutputStringsFromFacts,
   prettyPrintQueryTriples: engine.prettyPrintQueryTriples,
+  registerBuiltin: engine.registerBuiltin,
+  unregisterBuiltin: engine.unregisterBuiltin,
+  registerBuiltinModule: engine.registerBuiltinModule,
+  loadBuiltinModule: engine.loadBuiltinModule,
+  listBuiltinIris: engine.listBuiltinIris,
   getEnforceHttpsEnabled: engine.getEnforceHttpsEnabled,
   setEnforceHttpsEnabled: engine.setEnforceHttpsEnabled,
   getProofCommentsEnabled: engine.getProofCommentsEnabled,

package/lib/prelude.js

@@ -43,6 +43,37 @@ const MAX_LITERAL_PARTS_CACHE_LEN = 1024;
 
 const __literalPartsCache = new Map(); // lit string -> [lex, dt]
 
+function quotedLiteralEndIndex(str) {
+  if (typeof str !== 'string' || str.length < 2) return -1;
+
+  const quote = str[0];
+  if (quote !== '"' && quote !== "'") return -1;
+
+  const delimLen = str.startsWith(quote.repeat(3)) ? 3 : 1;
+  const delim = quote.repeat(delimLen);
+
+  let i = delimLen;
+  while (i < str.length) {
+    // Stored literals may contain escaped quotes, e.g. \"...\"^^xsd:dateTime
+    // inside a plain string. Those must not terminate the outer lexical form.
+    if (str[i] === '\\') {
+      i += 2;
+      continue;
+    }
+
+    if (delimLen === 1) {
+      if (str[i] === quote) return i + 1;
+      i += 1;
+      continue;
+    }
+
+    if (str.startsWith(delim, i)) return i + delimLen;
+    i += 1;
+  }
+
+  return -1;
+}
+
 function literalParts(lit) {
   // Avoid caching extremely large literals (notably huge numeric intermediates)
   // to prevent unbounded memory growth.
@@ -60,24 +91,21 @@ function literalParts(lit) {
   let lex = lit;
   let dt = null;
 
-  const re = /^(['"]{1,3})([\s\S]*?)\1\^\^(.+)$/;
-  const match = lit.match(re);
-  if (match) {
-    lex = match[1] + match[2] + match[1];
-    dt = match[3];
+  const lexEnd = quotedLiteralEndIndex(lit);
+  if (lexEnd > 0 && lit.startsWith('^^', lexEnd)) {
+    lex = lit.slice(0, lexEnd);
+    dt = lit.slice(lexEnd + 2);
     if (dt.startsWith('<') && dt.endsWith('>')) {
       dt = dt.slice(1, -1);
     }
   }
 
   // Strip LANGTAG from the lexical form when present.
-  if (lex.length >= 2 && lex[0] === '"') {
-    const lastQuote = lex.lastIndexOf('"');
-    if (lastQuote > 0 && lastQuote < lex.length - 1 && lex[lastQuote + 1] === '@') {
-      const lang = lex.slice(lastQuote + 2);
-      if (/^[A-Za-z]+(?:-[A-Za-z0-9]+)*$/.test(lang)) {
-        lex = lex.slice(0, lastQuote + 1);
-      }
+  const langLexEnd = quotedLiteralEndIndex(lex);
+  if (langLexEnd > 0 && lex[0] === '"' && langLexEnd < lex.length && lex[langLexEnd] === '@') {
+    const lang = lex.slice(langLexEnd + 1);
+    if (/^[A-Za-z]+(?:-[A-Za-z0-9]+)*$/.test(lang)) {
+      lex = lex.slice(0, langLexEnd);
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.23.3",
+  "version": "1.23.5",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [

package/test/api.test.js

@@ -288,6 +288,33 @@ const cases = [
       assert.equal(String(out).trimEnd(), '^^');
     },
   },
+  {
+    name: '00c quoted string containing typed literal syntax remains plain string',
+    opt: { proofComments: false },
+    input: `
+@prefix : <http://example.org/>.
+
+:s :p """
+@prefix : <http://example.org/>.
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
+
+:Let :param \"2023-04-01T18:06:04Z\"^^xsd:dateTime .
+""".
+
+{
+  :s :p ?O.
+}
+=>
+{
+  :test :is ?O.
+}.
+`,
+    expect: [/^:test\s+:is\s+/m],
+    notExpect: [/\^\^<xsd:dateTime/],
+    check(out) {
+      assert.match(out, /\\"2023-04-01T18:06:04Z\\"\^\^xsd:dateTime \./);
+    },
+  },
   {
     name: '01 forward rule: p -> q',
     opt: { proofComments: false },

package/test/playground.test.js

@@ -488,6 +488,8 @@ async function main() {
     // Intercept CodeMirror + remote GitHub raw URLs (keep test deterministic).
     const localPkg = fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8');
     const localEyeling = fs.readFileSync(path.join(ROOT, 'eyeling.js'), 'utf8');
+    const localSudoku = fs.readFileSync(path.join(ROOT, 'examples', 'sudoku.n3'), 'utf8');
+    const localSudokuBuiltin = fs.readFileSync(path.join(ROOT, 'examples', 'builtin', 'sudoku.js'), 'utf8');
 
     const intercept = new Map([
       // CodeMirror assets (CDN)
@@ -517,6 +519,14 @@ async function main() {
         'https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/eyeling.js',
         { ct: 'application/javascript', body: localEyeling },
       ],
+      [
+        'https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/sudoku.n3',
+        { ct: 'text/plain', body: localSudoku },
+      ],
+      [
+        'https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/builtin/sudoku.js',
+        { ct: 'application/javascript', body: localSudokuBuiltin },
+      ],
     ]);
 
     await cdp.send(
@@ -641,6 +651,21 @@ async function main() {
       })()`);
     }
 
+    async function loadUrlIntoEditor(url) {
+      const payload = JSON.stringify(String(url));
+      await evalInPage(`(() => {
+        const input = document.getElementById('n3-uri');
+        const asBackground = document.getElementById('load-as-background');
+        const btn = document.getElementById('load-uri-btn');
+        if (!input) throw new Error('n3-uri input not found');
+        if (!btn) throw new Error('load-uri-btn not found');
+        input.value = ${payload};
+        if (asBackground) asBackground.checked = false;
+        btn.click();
+        return true;
+      })()`);
+    }
+
     async function waitForState(label, predicate, timeoutMs = 60000) {
       const deadline = Date.now() + timeoutMs;
       let last = { status: '', output: '', highlighted: [] };
@@ -731,6 +756,26 @@ ${JSON.stringify(last, null, 2)}`);
     );
     ok('playground renders log:outputString cleanly in Output');
 
+    // 5) URL-loaded repository examples should auto-load matching examples/builtin/<stem>.js.
+    await loadUrlIntoEditor('https://raw.githubusercontent.com/eyereasoner/eyeling/refs/heads/main/examples/sudoku.n3');
+    await waitForState(
+      'sudoku URL loaded with companion builtin',
+      (st) => /loaded n3 into the editor and loaded its example builtin/i.test(String(st.status || '')),
+      20000,
+    );
+    await clickRun();
+    const sudoku = await waitForState(
+      'URL-loaded Sudoku example completion',
+      (st) =>
+        String(st.status || '')
+          .trim()
+          .startsWith('Done') && /The puzzle is solved/i.test(String(st.output || '')),
+      60000,
+    );
+    assert.match(sudoku.output, /Completed grid/i, 'Expected Sudoku rendered output');
+    assert.match(sudoku.output, /unique valid Sudoku solution/i, 'Expected Sudoku builtin-backed result');
+    ok('playground auto-loads a companion example builtin for URL-loaded Sudoku');
+
     // Ensure no uncaught runtime exceptions.
     assert.equal(exceptions.length, 0, `Uncaught exceptions in demo.html: ${JSON.stringify(exceptions[0] || {})}`);