eyeprolog 1.1.2 → 1.1.4

package/README.md

@@ -25,6 +25,18 @@ EyeProlog requires Node.js 18 or newer.
 
 ```sh
 npm install --global eyeprolog
+eyeprolog
+?- use_module(library(lists)).
+   true.
+?- member(X, [prolog, logic]).
+   X = prolog
+;  X = logic.
+?- halt.
+```
+
+For a non-interactive run:
+
+```sh
 printf 'human(socrates).\nmortal(X) :- human(X).\n' |
   eyeprolog --proof --goal 'mortal(socrates)' -
 ```

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",

package/src/cli.js

@@ -10,7 +10,14 @@ let explanationModule = null;
 
 export async function main(argv) {
   if (argv.length === 0) {
-    await usage(process.stdout);
+    const engine = await loadEngine();
+    const { runRepl } = await import('./repl.js');
+    const exitCode = await runRepl(engine, {
+      input: process.stdin,
+      output: process.stdout,
+      errorOutput: process.stderr,
+    });
+    if (exitCode !== 0) process.exitCode = exitCode;
     return;
   }
 
@@ -41,9 +48,9 @@ export async function main(argv) {
       options.version = true;
     } else if (!endOptions && (arg === '--warnings' || arg === '-w')) {
       options.warnings = true;
-    } else if (!endOptions && arg === '--goal') {
+    } else if (!endOptions && (arg === '--goal' || arg === '-g')) {
       const goal = argv[++i];
-      if (goal == null) throw new Error('option --goal requires a goal');
+      if (goal == null) throw new Error(`option ${arg} requires a goal`);
       options.goals.push(goal);
     } else if (!endOptions && arg.startsWith('-') && !arg.startsWith('--') && arg.length > 2) {
       const flags = arg.slice(1);
@@ -109,15 +116,16 @@ export async function main(argv) {
 
 async function loadEngine() {
   if (engineModule == null) {
-    const [term, parser, program, solver, iso, library] = await Promise.all([
+    const [term, parser, program, solver, iso, library, write] = await Promise.all([
       import('./term.js'),
       import('./parser.js'),
       import('./program.js'),
       import('./solver.js'),
       import('./iso.js'),
       import('./standard-library.js'),
+      import('./write.js'),
     ]);
-    engineModule = { ...term, ...parser, ...program, ...solver, ...iso, ...library };
+    engineModule = { ...term, ...parser, ...program, ...solver, ...iso, ...library, ...write };
   }
   return engineModule;
 }
@@ -186,8 +194,12 @@ async function usage(stream) {
   stream.write(`eyeprolog ${await packageVersion()}
 
 Usage:
+  eyeprolog
   eyeprolog [options] [file-or-url.pl|- ...]
 
+Interactive:
+  With no arguments, start a Prolog REPL. Use eyeprolog -h for help.
+
 Input:
   file-or-url.pl        Read an EyeProlog program from a local file or http(s) URL.
   -                     Read an EyeProlog program from standard input.
@@ -198,7 +210,7 @@ Options:
   -s, --stats           Print solver statistics to stderr after execution.
   -v, --version         Show the package version and exit.
   -w, --warnings        Print non-fatal portability warnings to stderr.
-  --goal goal           Solve goal and print its ground answers; may be repeated.
+  -g, --goal goal       Solve goal and print its ground answers; may be repeated.
                         If omitted, use %% goal: comments from the inputs.
   --                    Stop option parsing; following arguments are treated as files.
 `);

package/src/repl.js

@@ -0,0 +1,412 @@
+// Interactive top level for the eyeprolog command.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+
+const ANSWER_HELP = `
+SPACE, "n" or ";": next solution, if any
+RETURN or ".": stop enumeration
+"a": enumerate all solutions
+"f": enumerate the next 5 solutions
+"h": display this help message
+"w": write terms without depth limit
+"p": print terms with depth limit
+`;
+
+export async function runRepl(engine, options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const errorOutput = options.errorOutput ?? process.stderr;
+  const reader = new LineReader(input, output);
+  const sources = [];
+  let state = makeState(engine, sources, output);
+  let exitCode = 0;
+
+  try {
+    state.solver.runInitializations();
+    while (true) {
+      const text = await readQuery(reader);
+      if (text == null) break;
+      if (!text.trim()) continue;
+
+      try {
+        const goal = parseGoal(engine, state, text);
+        if (isUseModuleGoal(goal)) {
+          sources.push({ text: `:- ${text}.\n`, filename: '<repl>' });
+          state = makeState(engine, sources, output);
+          state.solver.runInitializations();
+          output.write('   true.\n');
+          continue;
+        }
+        const consultFiles = consultDesignations(engine, goal);
+        if (consultFiles != null) {
+          for (const filename of consultFiles) sources.push(await readSource(filename));
+          state = makeState(engine, sources, output);
+          state.solver.runInitializations();
+          output.write('   true.\n');
+          continue;
+        }
+
+        const result = await solveQuery(engine, state, goal, reader, output);
+        if (result?.halted) {
+          exitCode = result.code;
+          break;
+        }
+      } catch (error) {
+        if (error?.name === 'HaltSignal') {
+          exitCode = error.code;
+          break;
+        }
+        output.write(`   ${formatError(error)}\n`);
+      }
+    }
+  } catch (error) {
+    errorOutput.write(`eyeprolog: ${error?.message ?? String(error)}\n`);
+    exitCode = 1;
+  } finally {
+    reader.close();
+  }
+
+  return exitCode;
+}
+
+class LineReader {
+  constructor(input, output) {
+    this.input = input;
+    this.output = output;
+    this.terminal = Boolean(input.isTTY && output.isTTY && typeof input.setRawMode === 'function');
+    this.history = [];
+    this.currentPrompt = '?- ';
+    this.open();
+  }
+
+  open() {
+    this.readline = createInterface({
+      input: this.input,
+      output: this.output,
+      terminal: Boolean(this.input.isTTY && this.output.isTTY),
+      prompt: this.currentPrompt,
+    });
+    if (this.terminal && this.history.length > 0) {
+      this.readline.history.push(...this.history);
+    }
+    this.lines = this.readline[Symbol.asyncIterator]();
+  }
+
+  async read(prompt) {
+    this.currentPrompt = prompt;
+    this.readline.setPrompt(prompt);
+    this.output.write(prompt);
+    const result = await this.lines.next();
+    return result.done ? null : result.value;
+  }
+
+  async readControl(prompt) {
+    if (!this.terminal) return this.read(prompt);
+    this.output.write(prompt);
+    this.history = [...this.readline.history];
+    this.currentPrompt = '?- ';
+    this.readline.close();
+    this.readline = null;
+    this.lines = null;
+    this.input.setRawMode(true);
+    this.input.resume();
+
+    const control = await new Promise((resolve, reject) => {
+      const cleanup = () => {
+        this.input.off('data', onData);
+        this.input.off('error', onError);
+      };
+      const onData = (data) => {
+        cleanup();
+        const text = String(data);
+        resolve(text === '\x04' ? null : text[0] ?? null);
+      };
+      const onError = (error) => {
+        cleanup();
+        reject(error);
+      };
+      this.input.once('data', onData);
+      this.input.once('error', onError);
+    });
+
+    this.input.setRawMode(false);
+    this.open();
+    return control;
+  }
+
+  close() {
+    if (this.input.isRaw) this.input.setRawMode(false);
+    this.readline?.close();
+  }
+}
+
+function makeState(engine, sources, output) {
+  const program = engine.Program.parseSources(sources);
+  const solver = new engine.Solver(program, {
+    registry: engine.getEyePrologRegistry(),
+    ioOptions: { write: (text) => output.write(String(text)) },
+  });
+  return { program: solver.program, solver };
+}
+
+async function readQuery(reader) {
+  let source = '';
+  let prompt = '?- ';
+  while (true) {
+    const line = await reader.read(prompt);
+    if (line == null) return source.trim() ? source : null;
+    source += `${line}\n`;
+    const end = terminalFullStop(source);
+    if (end >= 0) return source.slice(0, end);
+    prompt = '|    ';
+  }
+}
+
+function terminalFullStop(source) {
+  let quote = null;
+  let lineComment = false;
+  let blockComment = false;
+  let escaped = false;
+  let depth = 0;
+
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    const next = source[i + 1];
+    if (lineComment) {
+      if (ch === '\n') lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (ch === '*' && next === '/') {
+        blockComment = false;
+        i++;
+      }
+      continue;
+    }
+    if (quote != null) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === '\\') {
+        escaped = true;
+      } else if (ch === quote) {
+        if (next === quote) i++;
+        else quote = null;
+      }
+      continue;
+    }
+    if (ch === '%') {
+      lineComment = true;
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      blockComment = true;
+      i++;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === '`') {
+      quote = ch;
+      continue;
+    }
+    if ('([{'.includes(ch)) depth++;
+    else if (')]}'.includes(ch)) depth = Math.max(0, depth - 1);
+    else if (ch === '.' && depth === 0 && onlyLayoutAndComments(source.slice(i + 1))) return i;
+  }
+  return -1;
+}
+
+function onlyLayoutAndComments(source) {
+  return source.replace(/\s|%[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\//g, '').length === 0;
+}
+
+function parseGoal(engine, state, text) {
+  const goal = engine.parseGoalText(text, {
+    doubleQuotes: state.solver.prologFlags.get('double_quotes')?.value?.name ?? 'chars',
+    operatorDefinitions: [...state.program.operators.values()],
+  });
+  if (goal.type === 'var') throw new engine.PrologError('instantiation_error');
+  if (goal.type !== 'atom' && goal.type !== 'compound') {
+    throw new engine.PrologError('type_error(callable)', goal);
+  }
+  return goal;
+}
+
+function isUseModuleGoal(goal) {
+  return goal.type === 'compound' && goal.name === 'use_module' && [1, 2].includes(goal.arity);
+}
+
+function consultDesignations(engine, goal) {
+  if (goal.type === 'atom' && goal.name === '[]') return [];
+  if (goal.type !== 'compound' || goal.name !== '.' || goal.arity !== 2) return null;
+  const items = engine.properListItems(goal, new engine.Env());
+  if (items == null) return null;
+  return items.map((item) => {
+    if (item.type === 'var') throw new engine.PrologError('instantiation_error');
+    if (item.type !== 'atom') throw new engine.PrologError('type_error(atom)', item);
+    return item.name;
+  });
+}
+
+async function readSource(designation) {
+  let filename = path.resolve(designation);
+  try {
+    await fs.access(filename);
+  } catch (error) {
+    if (path.extname(filename)) throw error;
+    filename += '.pl';
+  }
+  return {
+    text: await fs.readFile(filename, 'utf8'),
+    filename: path.basename(filename),
+    baseDir: path.dirname(filename),
+  };
+}
+
+async function solveQuery(engine, state, goal, reader, output) {
+  const variables = queryVariables(goal);
+  const solver = state.solver;
+  solver.solutionsSeen = 0;
+  const solutions = solver.solve([goal], new engine.Env(), 0);
+  let current = pullSolution(solver, solutions);
+  if (current.error) {
+    if (current.error?.name === 'HaltSignal') return { halted: true, code: current.error.code };
+    throw current.error;
+  }
+
+  if (current.result.done) {
+    output.write('   false.\n');
+    return null;
+  }
+
+  let automatic = 0;
+  let firstAnswer = true;
+  while (!current.result.done) {
+    const next = pullSolution(solver, solutions);
+    output.write(current.output);
+    output.write(`${firstAnswer ? '   ' : ''}${formatAnswer(engine, state, variables, current.result.value)}`);
+    firstAnswer = false;
+    if (!next.error && next.result.done) {
+      output.write('.\n');
+      return null;
+    }
+
+    if (automatic > 0 || automatic === Infinity) {
+      if (automatic !== Infinity) automatic--;
+      output.write('\n;  ');
+    } else {
+      while (true) {
+        const controlLine = await reader.readControl('\n;  ');
+        if (controlLine == null || controlLine === '' || controlLine === '\r' || controlLine === '\n' ||
+            controlLine.trimStart().startsWith('.')) {
+          if (typeof solutions.return === 'function') solutions.return();
+          output.write('... .\n');
+          return null;
+        }
+        const control = controlLine === ' ' ? ' ' : controlLine.trimStart()[0];
+        if (control === ';' || control === 'n' || control === ' ') break;
+        if (control === 'a') {
+          automatic = Infinity;
+          break;
+        }
+        if (control === 'f') {
+          automatic = 4;
+          break;
+        }
+        if (control === 'w' || control === 'p') {
+          output.write(`${formatAnswer(engine, state, variables, current.result.value)}`);
+          continue;
+        }
+        if (control === 'h') {
+          output.write(ANSWER_HELP);
+          continue;
+        }
+        output.write('Action? ');
+      }
+    }
+
+    if (next.error) {
+      output.write(next.output);
+      if (next.error?.name === 'HaltSignal') return { halted: true, code: next.error.code };
+      throw next.error;
+    }
+    current = next;
+  }
+  return null;
+}
+
+function pullSolution(solver, solutions) {
+  const stream = solver.io.resolve('user_output');
+  const originalWrite = stream?.write;
+  let captured = '';
+  if (stream) stream.write = (text) => { captured += String(text); };
+  try {
+    return { result: solutions.next(), output: captured };
+  } catch (error) {
+    return { error, output: captured };
+  } finally {
+    if (stream) stream.write = originalWrite;
+  }
+}
+
+function queryVariables(goal) {
+  const variables = [];
+  const seen = new Set();
+  const stack = [goal];
+  while (stack.length) {
+    const term = stack.pop();
+    if (term.type === 'var') {
+      if (!term.name.startsWith('__anon') && !seen.has(term.name)) {
+        seen.add(term.name);
+        variables.push(term);
+      }
+    } else {
+      for (let i = term.args.length - 1; i >= 0; i--) stack.push(term.args[i]);
+    }
+  }
+  return variables;
+}
+
+function formatAnswer(engine, state, variables, env) {
+  const bindings = [];
+  const names = new Map(variables.map((variable) => [variable.name, variable.name]));
+  let generated = 0;
+
+  for (const variable of variables) collectUnboundVariables(engine, variable, env, names, () => `_${letterName(generated++)}`);
+  for (const variable of variables) {
+    const value = engine.deref(variable, env);
+    if (value.type === 'var' && value.name === variable.name) continue;
+    bindings.push(`${variable.name} = ${engine.formatTermForWrite(value, env, {
+      quoted: true,
+      operators: [...state.program.operators.values()],
+      variableNames: names,
+    })}`);
+  }
+  return bindings.length === 0 ? 'true' : bindings.join(', ');
+}
+
+function collectUnboundVariables(engine, term, env, names, nextName) {
+  const stack = [term];
+  const seen = new Set();
+  while (stack.length) {
+    const current = engine.deref(stack.pop(), env);
+    if (current.type === 'var') {
+      if (!seen.has(current.name)) {
+        seen.add(current.name);
+        if (!names.has(current.name)) names.set(current.name, nextName());
+      }
+    } else {
+      for (let i = current.args.length - 1; i >= 0; i--) stack.push(current.args[i]);
+    }
+  }
+}
+
+function letterName(index) {
+  const letter = String.fromCharCode(65 + (index % 26));
+  const suffix = Math.floor(index / 26);
+  return suffix === 0 ? letter : `${letter}${suffix}`;
+}
+
+function formatError(error) {
+  const message = error?.message ?? String(error);
+  return message.endsWith('.') ? message : `${message}.`;
+}

package/test/run-regression.mjs

@@ -204,11 +204,13 @@ why(
       },
     },
     {
-      name: 'help with no arguments',
+      name: '-h shows CLI help',
       run: () => {
-        const result = runCli([]);
+        const result = runCli(['-h']);
         assertEqual(result.status, 0, 'exit status');
-        assertIncludes(result.stdout, 'Usage:\n  eyeprolog [options] [file-or-url.pl|- ...]', 'stdout');
+        assertIncludes(result.stdout, 'Usage:\n  eyeprolog\n  eyeprolog [options] [file-or-url.pl|- ...]', 'stdout');
+        assertIncludes(result.stdout, 'With no arguments, start a Prolog REPL.', 'stdout');
+        assertIncludes(result.stdout, '-g, --goal goal', 'stdout');
         assertIncludes(result.stdout, '-p, --proof', 'stdout');
         assertIncludes(result.stdout, '-s, --stats', 'stdout');
         assertIncludes(result.stdout, '-v, --version', 'stdout');
@@ -218,6 +220,68 @@ why(
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'bare CLI starts a REPL with truth, failure, and bindings',
+      run: () => {
+        const result = runCli([], { input: 'true.\nfalse.\nX = hello.\nhalt.\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, '?-    true.\n?-    false.\n?-    X = hello.\n?- ', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'REPL enumerates and stops answers like the Scryer top level',
+      run: () => {
+        const result = runCli([], {
+          input: '(X = a; X = b).\n;\n(X = one; X = two).\n\nhalt.\n',
+        });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, '?-    X = a\n;  X = b.\n?-    X = one\n;  ... .\n?- ', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'REPL accepts multiline period-terminated queries',
+      run: () => {
+        const result = runCli([], { input: '(X =\n  one).\nhalt.\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, '?- |       X = one.\n?- ', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'REPL consult shorthand loads local Prolog files',
+      run: () => {
+        const filename = path.join(tmp, `repl-consult-${++tmpCounter}.pl`);
+        fs.writeFileSync(filename, 'color(red).\ncolor(blue).\n');
+        const result = runCli([], {
+          input: `[${sourceAtom(filename)}].\ncolor(X).\n;\nhalt.\n`,
+        });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, '?-    true.\n?-    X = red\n;  X = blue.\n?- ', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'REPL use_module imports Part 2 library predicates',
+      run: () => {
+        const result = runCli([], {
+          input: 'append(X, Y, [1, 2, 3, 4]).\nuse_module(library(lists)).\nappend(X, Y, [1, 2, 3, 4]).\n\nhalt.\n',
+        });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, '?-    false.\n?-    true.\n?-    X = [], Y = [1, 2, 3, 4]\n;  ... .\n?- ', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: 'REPL halt status is returned by the CLI',
+      run: () => {
+        const result = runCli([], { input: 'halt(7).\n' });
+        assertEqual(result.status, 7, 'exit status');
+        assertEqual(result.stdout, '?- ', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
     {
       name: 'CLI loads an explicitly imported standard library module',
       run: () => {
@@ -303,6 +367,31 @@ why(
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: '-g supplies an explicit CLI goal',
+      run: () => {
+        const input = [
+          '%% goal: answer(metadata, X)',
+          'value(metadata, ignored).',
+          'value(explicit, selected).',
+          'answer(Kind, Value) :- value(Kind, Value).',
+          '',
+        ].join('\n');
+        const result = runCli(['-g', 'answer(explicit, X)', '-'], { input });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'answer(explicit, selected).\n', 'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
+    {
+      name: '-g requires a goal argument',
+      run: () => {
+        const result = runCli(['-g']);
+        assertEqual(result.status, 1, 'exit status');
+        assertEqual(result.stdout, '', 'stdout');
+        assertEqual(result.stderr, 'eyeprolog: option -g requires a goal\n', 'stderr');
+      },
+    },
 
     {
       name: '--proof enables query explanations',

package/the-art-of-eyeprolog.md

@@ -6015,19 +6015,44 @@ search behavior.
 </figure>
 
 ```text
+eyeprolog
 eyeprolog [options] [file-or-url.pl|- ...]
 ```
 
+### Interactive queries
+
+Run `eyeprolog` without arguments to enter the interactive top level. Queries
+may span lines and end with a full stop, as in Scryer Prolog:
+
+```text
+?- use_module(library(lists)).
+   true.
+?- member(X, [prolog, logic]).
+   X = prolog
+;  X = logic.
+?- halt.
+```
+
+When another answer exists in an interactive terminal, press `;`, Space, or
+`n` to ask for it immediately; no Return is needed. Return or `.` stops
+enumeration, `a` enumerates all remaining answers, `f` enumerates the next
+five, and `h` displays the answer-control help. A
+period-terminated query with no solutions prints `false.`; a solution without
+visible variable bindings prints `true.`. Use `[file].` or `['file.pl'].` to
+consult local source, and `halt.` or `halt(Status).` to leave the top level.
+Up and Down recall queries from the current session. Explicit `eyeprolog -h`
+displays command-line help.
+
 ### Selecting goals
 
 A Prolog source file states facts, rules, and ISO directives; the command line
-selects what to solve. Supply `--goal` followed by a callable Prolog goal:
+selects what to solve. Supply `-g` or `--goal` followed by a callable Prolog goal:
 
 ```sh
 eyeprolog --goal 'ancestor(ada, Who)' examples/ancestor.pl
 ```
 
-Repeat `--goal` to request several result relations in one run. EyeProlog prints
+Repeat `-g` or `--goal` to request several result relations in one run. EyeProlog prints
 their ground answers in the order the goals were supplied.
 
 For a self-running example, place the host goal in an ordinary comment:
@@ -6036,8 +6061,8 @@ For a self-running example, place the host goal in an ordinary comment:
 %% goal: ancestor(ada, Who)
 ```
 
-When no `--goal` option is present, the CLI reads these comments from all input
-sources and runs them in source order. An explicit `--goal` overrides them.
+When no `-g` or `--goal` option is present, the CLI reads these comments from all
+input sources and runs them in source order. An explicit goal option overrides them.
 Because `%% goal:` is a comment rather than a Prolog directive, another ISO
 processor may ignore it and the program remains portable Prolog text. External
 goals are still preferable when a script, shell history, or API call should
@@ -6050,14 +6075,14 @@ make the observed question explicit.
 | `-s`, `--stats` | Print solver counters to stderr |
 | `-v`, `--version` | Print the package version |
 | `-w`, `--warnings` | Print non-fatal portability warnings |
-| `--goal Goal` | Solve a callable goal; may be repeated; overrides `%% goal:` comments |
+| `-g`, `--goal Goal` | Solve a callable goal; may be repeated; overrides `%% goal:` comments |
 | `--` | Treat following arguments as inputs |
 
 Short flags may be combined, so `-pw` is equivalent to `-p -w`.
 
 Inputs may be local files, HTTP(S) URLs, or one `-` for stdin. The bare command
-`eyeprolog` prints help. When options are present but no input is named, stdin is
-used; writing `-` explicitly is clearer in scripts. Multiple sources are
+`eyeprolog` starts the REPL. When options are present but no input is named,
+stdin is used; writing `-` explicitly is clearer in scripts. Multiple sources are
 parsed as one program, so facts, rules, and directives can be separated across
 files. A relative `include/1` inside a local file resolves from that file's
 directory.