eyeling 1.10.10 → 1.10.12

package/HANDBOOK.md

@@ -26,6 +26,7 @@
 - [Chapter 15 — A worked example: Socrates, step by step](#ch15)
 - [Chapter 16 — Extending Eyeling (without breaking it)](#ch16)
 - [Epilogue](#epilogue)
+- [Appendix A — Eyeling user notes](#app-a)
 
 ---
 
@@ -1700,3 +1701,133 @@ If you remember only one sentence from this handbook, make it this:
 
 Everything else is engineering detail — interesting, careful, sometimes subtle — but always in service of that core shape.
 
+---
+
+<a id="app-a"></a>
+## Appendix A — Eyeling user notes
+
+This appendix is a compact, user-facing reference for **running Eyeling** and **writing inputs that work well**.
+For deeper explanations and implementation details, follow the chapter links in each section.
+
+### A.1 Install and run
+
+Eyeling is distributed as an npm package.
+
+- Run without installing:
+
+  ```bash
+  npx eyeling --help
+  npx eyeling yourfile.n3
+  ```
+
+- Or install globally:
+
+  ```bash
+  npm i -g eyeling
+  eyeling yourfile.n3
+  ```
+
+See also: [Chapter 14 — Entry points: CLI, bundle exports, and npm API](#ch14).
+
+### A.2 What Eyeling prints
+
+By default, Eyeling prints **newly derived forward facts** (the heads of fired `=>` rules), serialized as N3.
+It does **not** reprint your input facts.
+
+For proof/explanation output and output modes, see:
+- [Chapter 13 — Printing, proofs, and the user-facing output](#ch13)
+
+### A.3 CLI quick reference
+
+The authoritative list is always:
+
+```bash
+eyeling --help
+```
+
+Options:
+```
+  -a, --ast                    Print parsed AST as JSON and exit.
+  -d, --deterministic-skolem   Make log:skolem stable across reasoning runs.
+  -e, --enforce-https          Rewrite http:// IRIs to https:// for log dereferencing builtins.
+  -h, --help                   Show this help and exit.
+  -p, --proof-comments         Enable proof explanations.
+  -r, --strings                Print log:outputString strings (ordered by key) instead of N3 output.
+  -s, --super-restricted       Disable all builtins except => and <=.
+  -t, --stream                 Stream derived triples as soon as they are derived.
+  -v, --version                Print version and exit.
+```
+
+See also:
+- [Chapter 13 — Printing, proofs, and the user-facing output](#ch13)
+- [Chapter 12 — Dereferencing and web-like semantics](#ch12)
+
+### A.4 N3 syntax notes that matter in practice
+
+Eyeling implements a practical N3 subset centered around facts and rules.
+
+- A **fact** is a triple ending in `.`:
+
+  ```n3
+  :alice :knows :bob .
+  ```
+
+- A **forward rule**:
+
+  ```n3
+  { ?x :p ?y } => { ?y :q ?x } .
+  ```
+
+- A **backward rule**:
+
+  ```n3
+  { ?x :ancestor ?z } <= { ?x :parent ?z } .
+  ```
+
+Quoted graphs/formulas use `{ ... }`. Inside a quoted formula, directive scope matters:
+
+- `@prefix/@base` and `PREFIX/BASE` directives may appear at top level **or inside `{ ... }`**, and apply to the formula they occur in (formula-local scoping).
+
+For the formal grammar, see the N3 spec grammar:
+- https://w3c.github.io/N3/spec/#grammar
+
+See also:
+- [Chapter 4 — From characters to AST: lexing and parsing](#ch04)
+
+### A.5 Builtins
+
+Eyeling supports a built-in “standard library” across namespaces like `log:`, `math:`, `string:`, `list:`, `time:`, `crypto:`.
+
+References:
+- W3C N3 Built-ins overview: https://w3c.github.io/N3/reports/20230703/builtins.html
+- Eyeling implementation details: [Chapter 11 — Built-ins as a standard library](#ch11)
+- The shipped builtin catalogue: `eyeling-builtins.ttl` (in this repo)
+
+If you are running untrusted inputs, consider `--super-restricted` to disable all builtins except implication.
+
+### A.6 Skolemization and `log:skolem`
+
+When forward rule heads contain blank nodes (existentials), Eyeling replaces them with generated Skolem IRIs so derived facts are ground.
+
+See:
+- [Chapter 9 — Forward chaining: saturation, skolemization, and meta-rules](#ch09)
+
+### A.7 Networking and `log:semantics`
+
+`log:content`, `log:semantics`, and related builtins dereference IRIs and parse retrieved content.
+This is powerful, but it is also I/O.
+
+See:
+- [Chapter 12 — Dereferencing and web-like semantics](#ch12)
+
+Safety tip:
+- Use `--super-restricted` if you want to ensure *no* dereferencing (and no other builtins) can run.
+
+### A.8 Embedding Eyeling in JavaScript
+
+If you depend on Eyeling as a library, the package exposes:
+- a CLI wrapper API (`reason(...)`), and
+- in-process engine entry points (via the bundle exports).
+
+See:
+- [Chapter 14 — Entry points: CLI, bundle exports, and npm API](#ch14)

package/examples/get-uuid.n3

@@ -3,6 +3,7 @@
 # Example from Wout Slabbinck
 # ===========================
 
+@prefix list: <http://www.w3.org/2000/10/swap/list#> .
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix string: <http://www.w3.org/2000/10/swap/string#> .
 @prefix log: <http://www.w3.org/2000/10/swap/log#> .
@@ -12,16 +13,20 @@
 
 # uuid backward rule (component)
 {
-   ?input :getUUID ?urnUuid 
+   ?input :getUUID ?urnUuid
 }
-<= 
+<=
 {
+   # 0. add some skolem uri to introduce randomness when there are multiple runs with the same ID
+  ( "test" ) log:skolem ?skolem .
+  (?input (?skolem) ) list:append ?newList .
+
    # 1. Convert input to a stable string
-   ?input :listToString ?inputString .
-   
+   ?newList :listToString ?inputString .
+
    # 2. Generate a stable hash (works identically in 2026 eyeJS and Eyeling)
     ?inputString  crypto:sha ?hash .
-   
+
    # 3. Format the hash into a UUID-compliant structure (8-4-4-4-12)
    ( ?hash "^(.{8}).*$" ) string:scrape ?p1 .
    ( ?hash "^.{8}(.{4}).*$" ) string:scrape ?p2 .
@@ -29,7 +34,7 @@
    ( ?hash "^.{16}(.{4}).*$" ) string:scrape ?p4 .
    ( ?hash "^.{20}(.{12}).*$" ) string:scrape ?p5 .
    ( "urn:uuid:" ?p1 "-" ?p2 "-" ?p3 "-" ?p4 "-" ?p5 ) string:concatenation ?urnUuidString .
-   
+
    # 4. Cast the final string to a URI
    ?urnUuid log:uri ?urnUuidString .
 } .
@@ -38,16 +43,16 @@
 { () :listToString "" } <= { } .
 
 # 2. Recursive Case: Process list using rdf:first and rdf:rest
-{   ?list :listToString ?result } <= {
+{ ?list :listToString ?result } <= {
     ?list rdf:first ?head .
     ?list rdf:rest ?tail .
-    
+
     # Convert the current URI to a string
     ?head log:uri ?headStr .
-    
+
     # Recursively convert the tail of the list
     ?tail :listToString ?tailStr .
-    
+
     # Combine head and tail strings
     ( ?headStr ?tailStr ) string:concatenation ?result .
 } .
@@ -55,11 +60,10 @@
 <test> a odrl:Policy  .
 <lol> a odrl:Policy .
 
-{    
+{
     ?policy a odrl:Policy .
     ( ?policy ) :getUUID ?urnUuid .
 }
 =>
-{
-    ?urnUuid <a> <b> .
-} .
+{ ?urnUuid <a> <b> } .
+

package/examples/output/get-uuid.n3

@@ -1,2 +1,2 @@
-<urn:uuid:a94a8fe5-ccb1-9ba6-1c4c-0873d391e987> <a> <b> .
-<urn:uuid:40392603-3d00-1b52-79df-37cbbe5287b7> <a> <b> .
+<urn:uuid:ad88d7b6-5b37-4eeb-a044-7bca1ffc366c> <a> <b> .
+<urn:uuid:37d41865-0910-9953-46c7-01359fbab6fa> <a> <b> .

package/eyeling.js

@@ -493,6 +493,10 @@ function __fetchHttpTextViaSubprocess(url) {
         path: uu.pathname + uu.search,
         headers: {
           'accept': 'text/n3, text/turtle, application/n-triples, application/n-quads, text/plain;q=0.1, */*;q=0.01',
+          // Ask for an uncompressed response when possible; some servers send
+          // compressed bodies that are not valid UTF-8 text for the parser.
+          // We still handle common encodings below if they are returned anyway.
+          'accept-encoding': 'identity',
           'user-agent': 'eyeling-log-builtins'
         }
       };
@@ -509,10 +513,29 @@ function __fetchHttpTextViaSubprocess(url) {
           console.error('HTTP status ' + sc);
           process.exit(4);
         }
-        res.setEncoding('utf8');
-        let data = '';
-        res.on('data', (c) => { data += c; });
-        res.on('end', () => { process.stdout.write(data); });
+        const chunks = [];
+        res.on('data', (c) => { chunks.push(c); });
+        res.on('end', () => {
+          try {
+            const { Buffer } = require('buffer');
+            const zlib = require('zlib');
+            const buf = Buffer.concat(chunks);
+            const enc = ((res.headers && res.headers['content-encoding']) || '').toString().toLowerCase();
+            let out = buf;
+            if (enc.includes('gzip')) out = zlib.gunzipSync(buf);
+            else if (enc.includes('deflate')) out = zlib.inflateSync(buf);
+            else if (enc.includes('br')) out = zlib.brotliDecompressSync(buf);
+            process.stdout.write(out.toString('utf8'));
+          } catch (e) {
+            // Best-effort fallback: treat as UTF-8.
+            try {
+              const { Buffer } = require('buffer');
+              process.stdout.write(Buffer.concat(chunks).toString('utf8'));
+            } catch {
+              process.exit(6);
+            }
+          }
+        });
       });
       req.on('error', (e) => { console.error(e && e.message ? e.message : String(e)); process.exit(5); });
       req.end();
@@ -7308,6 +7331,46 @@ class Parser {
   parseGraph() {
     const triples = [];
     while (this.peek().typ !== 'RBrace') {
+      // N3 allows @prefix/@base and SPARQL-style PREFIX/BASE directives anywhere
+      // outside of a triple. This includes inside quoted graph terms.
+      // These directives affect parsing (prefix/base resolution) but do not emit triples.
+      if (this.peek().typ === 'AtPrefix') {
+        this.next();
+        this.parsePrefixDirective();
+        continue;
+      }
+      if (this.peek().typ === 'AtBase') {
+        this.next();
+        this.parseBaseDirective();
+        continue;
+      }
+      if (
+        this.peek().typ === 'Ident' &&
+        typeof this.peek().value === 'string' &&
+        this.peek().value.toLowerCase() === 'prefix' &&
+        this.toks[this.pos + 1] &&
+        this.toks[this.pos + 1].typ === 'Ident' &&
+        typeof this.toks[this.pos + 1].value === 'string' &&
+        this.toks[this.pos + 1].value.endsWith(':') &&
+        this.toks[this.pos + 2] &&
+        (this.toks[this.pos + 2].typ === 'IriRef' || this.toks[this.pos + 2].typ === 'Ident')
+      ) {
+        this.next();
+        this.parseSparqlPrefixDirective();
+        continue;
+      }
+      if (
+        this.peek().typ === 'Ident' &&
+        typeof this.peek().value === 'string' &&
+        this.peek().value.toLowerCase() === 'base' &&
+        this.toks[this.pos + 1] &&
+        (this.toks[this.pos + 1].typ === 'IriRef' || this.toks[this.pos + 1].typ === 'Ident')
+      ) {
+        this.next();
+        this.parseSparqlBaseDirective();
+        continue;
+      }
+
       const left = this.parseTerm();
       if (this.peek().typ === 'OpImplies') {
         this.next();

package/lib/deref.js

@@ -162,6 +162,10 @@ function __fetchHttpTextViaSubprocess(url) {
         path: uu.pathname + uu.search,
         headers: {
           'accept': 'text/n3, text/turtle, application/n-triples, application/n-quads, text/plain;q=0.1, */*;q=0.01',
+          // Ask for an uncompressed response when possible; some servers send
+          // compressed bodies that are not valid UTF-8 text for the parser.
+          // We still handle common encodings below if they are returned anyway.
+          'accept-encoding': 'identity',
           'user-agent': 'eyeling-log-builtins'
         }
       };
@@ -178,10 +182,29 @@ function __fetchHttpTextViaSubprocess(url) {
           console.error('HTTP status ' + sc);
           process.exit(4);
         }
-        res.setEncoding('utf8');
-        let data = '';
-        res.on('data', (c) => { data += c; });
-        res.on('end', () => { process.stdout.write(data); });
+        const chunks = [];
+        res.on('data', (c) => { chunks.push(c); });
+        res.on('end', () => {
+          try {
+            const { Buffer } = require('buffer');
+            const zlib = require('zlib');
+            const buf = Buffer.concat(chunks);
+            const enc = ((res.headers && res.headers['content-encoding']) || '').toString().toLowerCase();
+            let out = buf;
+            if (enc.includes('gzip')) out = zlib.gunzipSync(buf);
+            else if (enc.includes('deflate')) out = zlib.inflateSync(buf);
+            else if (enc.includes('br')) out = zlib.brotliDecompressSync(buf);
+            process.stdout.write(out.toString('utf8'));
+          } catch (e) {
+            // Best-effort fallback: treat as UTF-8.
+            try {
+              const { Buffer } = require('buffer');
+              process.stdout.write(Buffer.concat(chunks).toString('utf8'));
+            } catch {
+              process.exit(6);
+            }
+          }
+        });
       });
       req.on('error', (e) => { console.error(e && e.message ? e.message : String(e)); process.exit(5); });
       req.end();

package/lib/parser.js

@@ -461,6 +461,46 @@ class Parser {
   parseGraph() {
     const triples = [];
     while (this.peek().typ !== 'RBrace') {
+      // N3 allows @prefix/@base and SPARQL-style PREFIX/BASE directives anywhere
+      // outside of a triple. This includes inside quoted graph terms.
+      // These directives affect parsing (prefix/base resolution) but do not emit triples.
+      if (this.peek().typ === 'AtPrefix') {
+        this.next();
+        this.parsePrefixDirective();
+        continue;
+      }
+      if (this.peek().typ === 'AtBase') {
+        this.next();
+        this.parseBaseDirective();
+        continue;
+      }
+      if (
+        this.peek().typ === 'Ident' &&
+        typeof this.peek().value === 'string' &&
+        this.peek().value.toLowerCase() === 'prefix' &&
+        this.toks[this.pos + 1] &&
+        this.toks[this.pos + 1].typ === 'Ident' &&
+        typeof this.toks[this.pos + 1].value === 'string' &&
+        this.toks[this.pos + 1].value.endsWith(':') &&
+        this.toks[this.pos + 2] &&
+        (this.toks[this.pos + 2].typ === 'IriRef' || this.toks[this.pos + 2].typ === 'Ident')
+      ) {
+        this.next();
+        this.parseSparqlPrefixDirective();
+        continue;
+      }
+      if (
+        this.peek().typ === 'Ident' &&
+        typeof this.peek().value === 'string' &&
+        this.peek().value.toLowerCase() === 'base' &&
+        this.toks[this.pos + 1] &&
+        (this.toks[this.pos + 1].typ === 'IriRef' || this.toks[this.pos + 1].typ === 'Ident')
+      ) {
+        this.next();
+        this.parseSparqlBaseDirective();
+        continue;
+      }
+
       const left = this.parseTerm();
       if (this.peek().typ === 'OpImplies') {
         this.next();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.10.10",
+  "version": "1.10.12",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [
@@ -40,6 +40,7 @@
     "test:api": "node test/api.test.js",
     "test:n3gen": "node test/n3gen.test.js",
     "test:examples": "node test/examples.test.js",
+    "test:manifest": "node test/manifest.test.js",
     "test:package": "node test/package.test.js",
     "test": "npm run build && npm run test:packlist && npm run test:api && npm run test:n3gen && npm run test:examples",
     "preversion": "npm test",