eyeling 1.18.1 → 1.19.0

package/HANDBOOK.md

@@ -1777,12 +1777,16 @@ Install from npm:
 npm i eyeling
 ```
 
-Run a file:
+Run a self-contained example from stdin:
 
 ```bash
-npx eyeling examples/socrates.n3
+echo '@prefix : <http://example.org/> .
+:Socrates a :Man .
+{ ?x a :Man } => { ?x a :Mortal } .' | npx eyeling
 ```
 
+You can also pass a file path, or `-` to read explicitly from stdin.
+
 Show the available options:
 
 ```bash
@@ -1823,6 +1827,8 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 - `-t`, `--stream` — stream derived triples as soon as they are derived.
 - `-v`, `--version` — print version and exit.
 - `-h`, `--help` — show usage.
+- With no positional argument, Eyeling reads from stdin when input is piped.
+- Use `-` as the input path to read explicitly from stdin.
 
 ### 14.3 `lib/entry.js`: bundler-friendly exports
 
@@ -1833,7 +1839,14 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 
 `rdfjs` is a small built-in RDF/JS `DataFactory`, so browser / worker code can construct quads without pulling in another package first.
 
-### 14.4 `index.js`: the npm API wrapper
+### 14.4 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 bundle entry when you want in-process reasoning and structured RDF/JS results
+
+#### 14.4.1 npm helper: `reason(...)`
 
 The npm `reason(...)` function does something intentionally simple and robust:
 
@@ -1844,119 +1857,141 @@ The npm `reason(...)` function does something intentionally simple and robust:
 
 This keeps the observable output identical to the CLI while still allowing richer JS-side inputs.
 
-In particular, the npm API now accepts:
-
-- raw N3 strings
-- RDF/JS fact inputs (`quads`, `facts`, or `dataset`)
-- Eyeling rule objects or full AST bundles like `[prefixes, triples, frules, brules]`
+CommonJS:
 
-For structured JavaScript input, rules are supplied as current Eyeling `Rule` / `Triple` object graphs or as JSON-serialized `--ast` output with `_type` markers.
+```js
+const { reason } = require('eyeling');
 
-If you want to use N3 source text, pass the whole input as a plain N3 string.
+const input = `
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
+@prefix : <http://example.org/socrates#>.
 
-#### 14.4.1 RDF/JS quads as fact input
+:Socrates a :Human.
+:Human rdfs:subClassOf :Mortal.
 
-Eyeling can take RDF/JS quads directly as its fact input. At the npm API boundary, the input object may provide any of:
+{ ?s a ?A. ?A rdfs:subClassOf ?B. } => { ?s a ?B. }.
+`;
 
-- `quads`
-- `facts`
-- `dataset`
+console.log(reason({ proofComments: false }, input));
+```
 
-Each is treated as an iterable of RDF/JS **default-graph** quads and converted into Eyeling’s internal triple form before reasoning starts.
+ESM:
 
 ```js
-const { reason, rdfjs } = require('eyeling');
+import eyeling from 'eyeling';
 
-const input = {
-  quads: [
-    rdfjs.quad(
-      rdfjs.namedNode('http://example.org/Socrates'),
-      rdfjs.namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
-      rdfjs.namedNode('http://example.org/Human'),
-    ),
-  ],
-  n3: `
-    @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
-    @prefix : <http://example.org/>.
-    :Human rdfs:subClassOf :Mortal.
-    { ?x a ?c. ?c rdfs:subClassOf ?d. } => { ?x a ?d. }.
-  `,
-};
+const input = `
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
+@prefix : <http://example.org/socrates#>.
+
+:Socrates a :Human.
+:Human rdfs:subClassOf :Mortal.
+
+{ ?s a ?A. ?A rdfs:subClassOf ?B. } => { ?s a ?B. }.
+`;
 
-const out = reason(input);
+console.log(eyeling.reason({ proofComments: false }, input));
 ```
 
-The important point is architectural: RDF/JS quads can be used as the **fact channel**, while rules may still come from N3 text or Eyeling rule objects. Named-graph quads are intentionally rejected here; Eyeling’s input model is triple-oriented and expects the default graph only.
+Notes:
+
+- `reason()` returns the same textual output you would get from the CLI for the same input and options.
+- 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.4.2 Passing Eyeling rule objects directly
+The JavaScript APIs accept three input styles:
 
-The JS API also accepts Eyeling rule objects directly, so you do not have to serialize everything back into N3 first.
+1. plain N3 text
+2. RDF/JS fact input (`quads`, `facts`, or `dataset`)
+3. Eyeling rule objects or full AST bundles
 
-That means an input such as this is valid:
+If you want to use N3 source text, pass the whole input as a plain string.
+
+For RDF/JS facts, the graph must be the default graph. Named-graph quads are rejected.
+
+If you already have rules in structured form, Eyeling rule objects can be passed directly in the API:
 
 ```js
-const { reason } = require('eyeling');
+const { reason, rdfjs } = require('eyeling');
 
-const input = {
-  triples: [
-    /* Eyeling Triple objects */
+const ex = 'http://example.org/';
+
+const rule = {
+  _type: 'Rule',
+  premise: [
+    {
+      _type: 'Triple',
+      s: { _type: 'Var', name: 'x' },
+      p: { _type: 'Iri', value: ex + 'parent' },
+      o: { _type: 'Var', name: 'y' },
+    },
   ],
-  forwardRules: [
-    /* Eyeling Rule objects */
-  ],
-  backwardRules: [
-    /* optional Eyeling Rule objects */
+  conclusion: [
+    {
+      _type: 'Triple',
+      s: { _type: 'Var', name: 'x' },
+      p: { _type: 'Iri', value: ex + 'ancestor' },
+      o: { _type: 'Var', name: 'y' },
+    },
   ],
+  isForward: true,
+  isFuse: false,
+  headBlankLabels: [],
 };
 
-const out = reason(input);
-```
-
-The accepted shapes are intentionally flexible:
+const out = reason(
+  { proofComments: false },
+  {
+    quads: [rdfjs.quad(rdfjs.namedNode(ex + 'alice'), rdfjs.namedNode(ex + 'parent'), rdfjs.namedNode(ex + 'bob'))],
+    rules: [rule],
+  },
+);
 
-- `triples`
-- `forwardRules` or `frules`
-- `backwardRules` or `brules`
-- `queryRules`, `logQueryRules`, or `qrules`
-- a full AST bundle like `[prefixes, triples, frules, brules, queryRules]`
+console.log(out);
+```
 
-So Eyeling rule objects can be passed directly in the API, either as separate arrays or bundled into the same object graph the parser itself uses.
+You can also pass a full AST bundle directly, for example `[prefixes, triples, forwardRules, backwardRules]`.
 
-#### 14.4.3 Consuming derived RDF/JS results
+#### 14.4.3 In-process bundle API: `reasonStream(...)` and `reasonRdfJs(...)`
 
-There are two main ways to consume derived results in RDF/JS form.
+Use the bundle entry if you want structured results while the engine is running instead of final CLI text after the fact.
 
-First, `reasonStream(...)` can emit RDF/JS quads **while reasoning runs**. Pass `rdfjs: true` and an `onDerived(...)` callback:
+`reasonStream(...)` can emit RDF/JS quads while reasoning runs:
 
 ```js
-const { reasonStream } = require('eyeling/lib/entry');
+import eyeling from './eyeling.js';
 
-reasonStream(input, {
-  rdfjs: true,
-  onDerived({ triple, quad }) {
-    // triple = Eyeling's N3 string form
-    // quad   = RDF/JS Quad for the same derived fact
+const result = eyeling.reasonStream(input, {
+  proof: false,
+  onDerived: ({ quad }) => {
+    if (quad) console.log(quad);
   },
 });
 ```
 
-This is the “push” interface: each newly derived forward fact is reported as soon as it is produced.
-
-Second, `reasonRdfJs(...)` exposes the same derived results as an **async stream of RDF/JS quads**:
+That same path also lets derived results be consumed as an async stream of RDF/JS quads:
 
 ```js
-const { reasonRdfJs } = require('eyeling/lib/entry');
-
-for await (const quad of reasonRdfJs(input)) {
-  // consume RDF/JS quads incrementally
+for await (const quad of eyeling.reasonRdfJs(input)) {
+  console.log(quad);
 }
 ```
 
-This is the “pull” interface: the consumer iterates an async iterable of quads instead of registering a callback.
+Use these entry points when you need one or more of the following:
+
+- RDF/JS quads as fact input
+- Eyeling rule objects passed directly from JavaScript
+- derived results consumed as RDF/JS quads
+- streaming derived RDF/JS quads during reasoning
+
+### 14.5 Choosing the right entry point
 
-One practical implication remains:
+A practical rule of thumb:
 
-- if you want _in-process_ access to the engine objects (facts arrays, derived proof objects), use `reasonStream` / `reasonRdfJs` from the bundle entry rather than the subprocess-based API.
+- if you want the same final text output as the CLI, use `reason(...)`
+- if you want in-process access to structured facts, quads, or streaming derivations, use `reasonStream(...)` / `reasonRdfJs(...)`
 
 ---
 

package/README.md

@@ -7,13 +7,14 @@ A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 ## Quick start
 
 ```bash
-npm i eyeling
-npx eyeling examples/socrates.n3
+echo '@prefix : <http://example.org/> .
+:Socrates a :Man .
+{ ?x a :Man } => { ?x a :Mortal } .' | npx eyeling
 ```
 
 ## Read more
 
 - **Handbook:** [eyereasoner.github.io/eyeling/HANDBOOK](https://eyereasoner.github.io/eyeling/HANDBOOK)
-- **Semantics:** [eyereasoner.github.io/eyeling/SEMANTICS](https://eyereasoner.github.io/eyeling/SEMANTICS)
 - **Playground:** [eyereasoner.github.io/eyeling/demo](https://eyereasoner.github.io/eyeling/demo)
+- **Semantics:** [eyereasoner.github.io/eyeling/SEMANTICS](https://eyereasoner.github.io/eyeling/SEMANTICS)
 - **Conformance report:** [codeberg.org/phochste/notation3tests/.../report.md](https://codeberg.org/phochste/notation3tests/src/branch/main/reports/report.md)

package/eyeling.js

@@ -4536,6 +4536,11 @@ function formatN3SyntaxError(err, text, path) {
 }
 
 // CLI entry point (invoked when eyeling.js is run directly)
+function readTextFromStdinSync() {
+  const fs = require('node:fs');
+  return fs.readFileSync(0, { encoding: 'utf8' });
+}
+
 function main() {
   // Drop "node" and script name; keep only user-provided args
   // Expand combined short options: -pt == -p -t
@@ -4555,7 +4560,8 @@ function main() {
 
   function printHelp(toStderr = false) {
     const msg =
-      `Usage: ${prog} [options] <file.n3>\n\n` +
+      `Usage: ${prog} [options] [file.n3|-]\n\n` +
+      `When no file is given and stdin is piped, read N3 from stdin.\n\n` +
       `Options:\n` +
       `  -a, --ast                    Print parsed AST as JSON and exit.\n` +
       `      --builtin <module.js>    Load a custom builtin module (repeatable).\n` +
@@ -4626,12 +4632,13 @@ function main() {
   }
 
   // Positional args (the N3 file)
-  if (positional.length === 0) {
+  const useImplicitStdin = positional.length === 0 && !process.stdin.isTTY;
+  if (positional.length === 0 && !useImplicitStdin) {
     printHelp(false);
     process.exit(0);
   }
-  if (positional.length !== 1) {
-    console.error('Error: expected exactly one input <file.n3>.');
+  if (positional.length > 1) {
+    console.error('Error: expected at most one input [file.n3|-].');
     printHelp(true);
     process.exit(1);
   }
@@ -4646,13 +4653,17 @@ function main() {
     }
   }
 
-  const filePath = positional[0];
+  const sourceLabel = useImplicitStdin || positional[0] === '-' ? '<stdin>' : positional[0];
   let text;
   try {
-    const fs = require('fs');
-    text = fs.readFileSync(filePath, { encoding: 'utf8' });
+    if (sourceLabel === '<stdin>') text = readTextFromStdinSync();
+    else {
+      const fs = require('node:fs');
+      text = fs.readFileSync(sourceLabel, { encoding: 'utf8' });
+    }
   } catch (e) {
-    console.error(`Error reading file ${JSON.stringify(filePath)}: ${e.message}`);
+    if (sourceLabel === '<stdin>') console.error(`Error reading stdin: ${e.message}`);
+    else console.error(`Error reading file ${JSON.stringify(sourceLabel)}: ${e.message}`);
     process.exit(1);
   }
 
@@ -4666,7 +4677,7 @@ function main() {
     engine.setTracePrefixes(prefixes);
   } catch (e) {
     if (e && e.name === 'N3SyntaxError') {
-      console.error(formatN3SyntaxError(e, text, filePath));
+      console.error(formatN3SyntaxError(e, text, sourceLabel));
       process.exit(1);
     }
     throw e;

package/lib/cli.js

@@ -45,6 +45,11 @@ function formatN3SyntaxError(err, text, path) {
 }
 
 // CLI entry point (invoked when eyeling.js is run directly)
+function readTextFromStdinSync() {
+  const fs = require('node:fs');
+  return fs.readFileSync(0, { encoding: 'utf8' });
+}
+
 function main() {
   // Drop "node" and script name; keep only user-provided args
   // Expand combined short options: -pt == -p -t
@@ -64,7 +69,8 @@ function main() {
 
   function printHelp(toStderr = false) {
     const msg =
-      `Usage: ${prog} [options] <file.n3>\n\n` +
+      `Usage: ${prog} [options] [file.n3|-]\n\n` +
+      `When no file is given and stdin is piped, read N3 from stdin.\n\n` +
       `Options:\n` +
       `  -a, --ast                    Print parsed AST as JSON and exit.\n` +
       `      --builtin <module.js>    Load a custom builtin module (repeatable).\n` +
@@ -135,12 +141,13 @@ function main() {
   }
 
   // Positional args (the N3 file)
-  if (positional.length === 0) {
+  const useImplicitStdin = positional.length === 0 && !process.stdin.isTTY;
+  if (positional.length === 0 && !useImplicitStdin) {
     printHelp(false);
     process.exit(0);
   }
-  if (positional.length !== 1) {
-    console.error('Error: expected exactly one input <file.n3>.');
+  if (positional.length > 1) {
+    console.error('Error: expected at most one input [file.n3|-].');
     printHelp(true);
     process.exit(1);
   }
@@ -155,13 +162,17 @@ function main() {
     }
   }
 
-  const filePath = positional[0];
+  const sourceLabel = useImplicitStdin || positional[0] === '-' ? '<stdin>' : positional[0];
   let text;
   try {
-    const fs = require('fs');
-    text = fs.readFileSync(filePath, { encoding: 'utf8' });
+    if (sourceLabel === '<stdin>') text = readTextFromStdinSync();
+    else {
+      const fs = require('node:fs');
+      text = fs.readFileSync(sourceLabel, { encoding: 'utf8' });
+    }
   } catch (e) {
-    console.error(`Error reading file ${JSON.stringify(filePath)}: ${e.message}`);
+    if (sourceLabel === '<stdin>') console.error(`Error reading stdin: ${e.message}`);
+    else console.error(`Error reading file ${JSON.stringify(sourceLabel)}: ${e.message}`);
     process.exit(1);
   }
 
@@ -175,7 +186,7 @@ function main() {
     engine.setTracePrefixes(prefixes);
   } catch (e) {
     if (e && e.name === 'N3SyntaxError') {
-      console.error(formatN3SyntaxError(e, text, filePath));
+      console.error(formatN3SyntaxError(e, text, sourceLabel));
       process.exit(1);
     }
     throw e;

package/package.json

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

package/test/api.test.js

@@ -1762,6 +1762,55 @@ _:x :hates { _:foo :making :mess }.
     },
     expect: [/http:\/\/example\.org\/ancestor/m],
   },
+  {
+    name: '67 CLI stdin: accepts piped N3 when no file argument is given',
+    run() {
+      const input = `@prefix : <http://example.org/> .
+:Socrates a :Man .
+{ ?x a :Man } => { ?x a :Mortal } .
+`;
+      const r = spawnSync(process.execPath, [path.join(ROOT, 'eyeling.js')], {
+        input,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      if (r.error) throw r.error;
+      if (r.status !== 0) {
+        const err = new Error(`CLI failed with exit ${r.status}`);
+        err.code = r.status;
+        err.stdout = r.stdout;
+        err.stderr = r.stderr;
+        throw err;
+      }
+      return r.stdout;
+    },
+    expect: [/:(?:Socrates)\s+a\s+:(?:Mortal)\s*\./],
+  },
+  {
+    name: '68 CLI stdin: accepts explicit - for stdin',
+    run() {
+      const input = `@prefix : <http://example.org/> .
+:Socrates a :Man .
+{ ?x a :Man } => { ?x a :Mortal } .
+`;
+      const r = spawnSync(process.execPath, [path.join(ROOT, 'eyeling.js'), '-'], {
+        input,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      if (r.error) throw r.error;
+      if (r.status !== 0) {
+        const err = new Error(`CLI failed with exit ${r.status}`);
+        err.code = r.status;
+        err.stdout = r.stdout;
+        err.stderr = r.stderr;
+        throw err;
+      }
+      return r.stdout;
+    },
+    expect: [/:(?:Socrates)\s+a\s+:(?:Mortal)\s*\./],
+  },
+
   {
     name: '240 custom builtin module can be loaded via --builtin',
     run() {