eyeprolog 1.1.6 → 1.1.7

package/README.md

@@ -45,6 +45,15 @@ Programs may declare their default queries with `%% goal:` comments.
 Double-quoted text follows the ISO `double_quotes` flag and defaults to a
 proper list of one-character atoms (`chars`), matching Trealla and Scryer.
 
+Portable unit tests can be embedded as quads—a query followed by its expected
+top-level answer—and run with `eyeprolog --quads program.pl`:
+
+```prolog
+member_test ?- member(X, [prolog, logic]).
+   X = prolog
+;  X = logic.
+```
+
 ## ISO modules and definite clause grammars
 
 EyeProlog implements ISO/IEC 13211-2 modules and the grammar rules and

package/examples/book/README.md

@@ -242,3 +242,7 @@ npm run generate
 - [03-answer-3.pl](chapter-39/03-answer-3.pl)
 - [04-cost.pl](chapter-39/04-cost.pl)
 - [05-message.pl](chapter-39/05-message.pl)
+
+## Chapter 40: Running EyeProlog: command line and corpus
+
+- [01-color.pl](chapter-40/01-color.pl) — Embedded quad tests

package/examples/book/chapter-40/01-color.pl

@@ -0,0 +1,10 @@
+% From The Art of EyeProlog, Chapter 40 — Embedded quad tests.
+color(red).
+color(green).
+
+colors ?- color(X).
+   X = red
+;  X = green.
+
+?- color(blue).
+   false.

package/index.d.ts

@@ -55,6 +55,29 @@ export interface EyePrologClause {
   module?: string;
 }
 
+export interface EyePrologQuad {
+  kind: 'quad';
+  id: EyePrologTerm | null;
+  query: EyePrologTerm;
+  answers: EyePrologTerm[];
+  module?: string;
+  source: { filename: string; line: number };
+}
+
+export interface EyePrologQuadResult {
+  ok: boolean;
+  kind?: 'failed' | 'malformed' | 'bad_identifier' | 'unsupported';
+  expected?: EyePrologTerm;
+}
+
+export interface EyePrologQuadRunResult {
+  stdout: string;
+  total: number;
+  passed: number;
+  failed: number;
+  results: EyePrologQuadResult[];
+}
+
 export interface EyePrologPredicateGroup {
   name: string;
   arity: number;
@@ -94,6 +117,7 @@ export class Program {
   groups: Map<string, EyePrologPredicateGroup>;
   modules: Map<string, { name: string; exports: Map<string, unknown>; filename: string }>;
   moduleImports: Map<string, Map<string, string>>;
+  quads: EyePrologQuad[];
   doubleQuotes: 'chars' | 'codes' | 'atom';
   negationDependencies: Array<{ from: string; to: string; negative: boolean }>;
   negationStratificationErrors: Array<{ from: string; to: string }>;
@@ -186,8 +210,8 @@ export function numberTextFromDouble(value: number): string | null;
 export function compareNumberText(left: string, right: string): number;
 
 export function makeProgram(source: string, options?: EyePrologRunOptions): Program;
-export function parseClauses(source: string, options?: EyePrologRunOptions): EyePrologClause[];
-export function parseProgramText(source: string, options?: EyePrologRunOptions): EyePrologClause[];
+export function parseClauses(source: string, options?: EyePrologRunOptions): Array<EyePrologClause | EyePrologQuad>;
+export function parseProgramText(source: string, options?: EyePrologRunOptions): Array<EyePrologClause | EyePrologQuad>;
 export function parseGoalText(source: string, options?: EyePrologRunOptions): EyePrologTerm;
 export function createDefaultRegistry(): BuiltinRegistry;
 export function createEyePrologRegistry(): BuiltinRegistry;
@@ -208,6 +232,7 @@ export class HaltSignal extends Error {
   constructor(code?: number);
 }
 export function run(source: string | Program, options?: EyePrologRunOptions): EyePrologRunResult;
+export function runQuads(source: string | Program, options?: EyePrologRunOptions & { initialize?: boolean }): EyePrologQuadRunResult;
 export function whyProof(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): { ok: boolean; text: string };
 export function whyNoProof(goal: EyePrologTerm): string;
 export function explainProof(program: Program, goal: EyePrologTerm, options?: EyePrologRunOptions): { ok: boolean; text: string };
@@ -269,6 +294,7 @@ declare const eyeprolog: {
   eyePrologNativeLibraryIndicators: typeof eyePrologNativeLibraryIndicators;
   eyePrologPortableLibraryIndicators: typeof eyePrologPortableLibraryIndicators;
   run: typeof run;
+  runQuads: typeof runQuads;
   whyProof: typeof whyProof;
   whyNoProof: typeof whyNoProof;
   explainProof: typeof explainProof;

package/package.json

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

package/src/cli.js

@@ -24,6 +24,7 @@ export async function main(argv) {
   const options = {
     files: [],
     proof: false,
+    quads: false,
     stats: false,
     version: false,
     warnings: false,
@@ -42,6 +43,8 @@ export async function main(argv) {
       return;
     } else if (!endOptions && (arg === '--proof' || arg === '-p')) {
       options.proof = true;
+    } else if (!endOptions && (arg === '--quads' || arg === '-q')) {
+      options.quads = true;
     } else if (!endOptions && (arg === '--stats' || arg === '-s')) {
       options.stats = true;
     } else if (!endOptions && (arg === '--version' || arg === '-v')) {
@@ -55,13 +58,14 @@ export async function main(argv) {
     } else if (!endOptions && arg.startsWith('-') && !arg.startsWith('--') && arg.length > 2) {
       const flags = arg.slice(1);
       for (const flag of flags) {
-        if (!'hpsvw'.includes(flag)) throw new Error(`unknown option: ${arg}`);
+        if (!'hpqsvw'.includes(flag)) throw new Error(`unknown option: ${arg}`);
       }
       if (flags.includes('h')) {
         await usage(process.stdout);
         return;
       }
       if (flags.includes('p')) options.proof = true;
+      if (flags.includes('q')) options.quads = true;
       if (flags.includes('s')) options.stats = true;
       if (flags.includes('v')) options.version = true;
       if (flags.includes('w')) options.warnings = true;
@@ -102,7 +106,7 @@ export async function main(argv) {
     }
   }
 
-  if (options.goals.length === 0) {
+  if (options.goals.length === 0 && !options.quads) {
     for (const source of sourceParts) options.goals.push(...goalsFromSource(source.text));
   }
 
@@ -111,12 +115,17 @@ export async function main(argv) {
 
   if (options.warnings) printWarnings(program);
 
-  await runDefault(engine, program, options);
+  if (!options.quads || options.goals.length > 0) await runDefault(engine, program, options);
+  if (options.quads) {
+    const result = engine.runQuads(program, { initialize: options.goals.length === 0 });
+    process.stdout.write(result.stdout);
+    if (result.failed > 0) process.exitCode = 1;
+  }
 }
 
 async function loadEngine() {
   if (engineModule == null) {
-    const [term, parser, program, solver, iso, library, write] = await Promise.all([
+    const [term, parser, program, solver, iso, library, write, quads] = await Promise.all([
       import('./term.js'),
       import('./parser.js'),
       import('./program.js'),
@@ -124,8 +133,9 @@ async function loadEngine() {
       import('./iso.js'),
       import('./standard-library.js'),
       import('./write.js'),
+      import('./quads.js'),
     ]);
-    engineModule = { ...term, ...parser, ...program, ...solver, ...iso, ...library, ...write };
+    engineModule = { ...term, ...parser, ...program, ...solver, ...iso, ...library, ...write, ...quads };
   }
   return engineModule;
 }
@@ -207,6 +217,7 @@ Input:
 Options:
   -h, --help            Show this help text and exit.
   -p, --proof           Enable proof explanations.
+  -q, --quads           Run embedded quad tests and fail if any do not hold.
   -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.

package/src/index.js

@@ -20,6 +20,7 @@ export {
   eyePrologPortableLibraryIndicators,
 } from './standard-library.js';
 export { StreamManager } from './io.js';
+export { runQuads } from './quads.js';
 
 import { ATOM, COMPOUND, VAR, Env, copyResolved, termIsGround, termToString } from './term.js';
 import { Program } from './program.js';

package/src/parser.js

@@ -277,6 +277,14 @@ class Parser {
     const line = this.line;
     const ch = this.peek();
     if (!ch) return { type: TOK.EOF, text: '', line };
+    if (this.source.startsWith('...', this.pos) && this.peek(3) !== '.') {
+      this.pos += 3;
+      return { type: TOK.ATOM, text: '...', line };
+    }
+    if (ch === '?' && this.peek(1) === '-') {
+      this.pos += 2;
+      return { type: TOK.ATOM, text: '?-', line };
+    }
     if (ch === '!') {
       this.take();
       return { type: TOK.ATOM, text: '!', line };
@@ -591,12 +599,47 @@ class Parser {
     }
     throw new Error(`parse line ${this.token.line}: bad term`);
   }
+  sourceLineIsIndented(line) {
+    let start = 0;
+    for (let current = 1; current < line; current++) {
+      const newline = this.source.indexOf('\n', start);
+      if (newline < 0) return false;
+      start = newline + 1;
+    }
+    return this.source[start] === ' ' || this.source[start] === '\t';
+  }
+  parseQuad(id, line, accept) {
+    const query = this.parseTerm(0, true);
+    this.expect(TOK.DOT, '.');
+    this.advance();
+
+    const answers = [];
+    while (this.token.type !== TOK.EOF && this.sourceLineIsIndented(this.token.line)) {
+      answers.push(this.parseTerm(0, true));
+      this.expect(TOK.DOT, '.');
+      this.advance();
+    }
+    if (answers.length === 0) throw new Error(`parse line ${line}: quad requires an indented answer description`);
+
+    accept({
+      kind: 'quad',
+      id,
+      query,
+      answers,
+      source: { filename: this.filename, line },
+    });
+  }
   parseProgram(emit = null) {
     const clauses = emit ? null : [];
     let clauseNumber = 0;
     const accept = emit ?? ((clause) => clauses.push(clause));
     while (this.token.type !== TOK.EOF) {
       const line = this.token.line;
+      if (this.operatorTokenName() === '?-') {
+        this.advance();
+        this.parseQuad(null, line, accept);
+        continue;
+      }
       if (this.token.type === TOK.IF) {
         this.advance();
         const directive = this.parseTerm();
@@ -622,6 +665,11 @@ class Parser {
         continue;
       }
       let head = this.parseTerm(3);
+      if (this.operatorTokenName() === '?-') {
+        this.advance();
+        this.parseQuad(head, line, accept);
+        continue;
+      }
       // ISO/IEC TS 13211-3 grammar rules use -->/2 at the same top-level
       // priority as clauses.  The left side may include an unparenthesized
       // semicontext: NonTerminal, Terminals --> Body.

package/src/program.js

@@ -104,6 +104,7 @@ export class Program {
       this.defineOperator(priority, specifier, name);
     }
     this.initializations = [];
+    this.quads = [];
     this.prologFlagDirectives = [];
     this.charConversionDirectives = [];
     this.doubleQuotes = options.doubleQuotes ?? 'chars';
@@ -471,6 +472,12 @@ class ProgramBuilder {
     let lastGroup = this.lastGroup;
 
     for (const clause of clauses) {
+      if (clause?.kind === 'quad') {
+        const module = clause.module ?? 'user';
+        annotateGoalModule(clause.query, module);
+        program.quads.push({ ...clause, module });
+        continue;
+      }
       clause.index = program.clauses.length;
       program.clauses.push(clause);
 
@@ -664,6 +671,12 @@ function loadSourceIntoBuilder(builder, source, options, ensured, loadedModules,
     batch.length = 0;
   };
   const accept = (clause) => {
+    if (clause?.kind === 'quad') {
+      flush();
+      clause.module = context.module;
+      builder.addClauses([clause]);
+      return;
+    }
     const grammarClause = expandDcgRuleClause(clause, context.module);
     if (grammarClause) clause = grammarClause;
     const moduleDeclaration = moduleDirective(clause);

package/src/quads.js

@@ -0,0 +1,368 @@
+// Embedded quad tests: a query followed by one or more answer descriptions.
+// The syntax follows the portable "queries using answer descriptions" format
+// used by Trealla and the ISO Prolog working examples linked from issue #1.
+import {
+  ATOM, COMPOUND, VAR, Env, atom, compound, copyResolved, deref,
+  flattenConjunction, properListItems, termIsGround,
+  unify, variable,
+} from './term.js';
+import { parseGoalText } from './parser.js';
+import { Program } from './program.js';
+import { Solver } from './solver.js';
+import { getEyePrologRegistry } from './standard-library.js';
+import { formatTermForWrite } from './write.js';
+
+export function runQuads(source, options = {}) {
+  const program = source instanceof Program
+    ? source
+    : Program.parse(source, { ...options, sourceMetadata: true });
+  const quads = program.quads ?? [];
+  if (quads.length === 0) {
+    return { stdout: 'quads: nothing to run.\n', total: 0, passed: 0, failed: 0, results: [] };
+  }
+
+  if (options.initialize !== false) {
+    const initializer = new Solver(program, {
+      ...options,
+      registry: options.registry ?? getEyePrologRegistry(),
+      ioOptions: { write: () => {} },
+    });
+    initializer.runInitializations();
+  }
+
+  const results = [];
+  const lines = [];
+  for (const quad of quads) {
+    const result = checkQuad(program, quad, options);
+    results.push(result);
+    if (!result.ok) lines.push(formatFailure(program, quad, result));
+  }
+  const passed = results.filter((result) => result.ok).length;
+  const failed = results.length - passed;
+  lines.push(`quads: ${results.length} run, ${passed} passed, ${failed} failed.\n`);
+  return { stdout: lines.join(''), total: results.length, passed, failed, results };
+}
+
+function checkQuad(program, quad, options) {
+  if (quad.id != null && !termIsGround(quad.id, new Env())) {
+    return { ok: false, kind: 'bad_identifier', expected: quad.id };
+  }
+  for (const description of quad.answers) {
+    const checked = checkDescription(program, quad, description, options);
+    if (!checked.ok) return checked;
+  }
+  return { ok: true };
+}
+
+function checkDescription(program, quad, description, options) {
+  const alternatives = splitOperator(description, '|');
+  for (const alternative of alternatives) {
+    const malformed = malformedAlternative(quad.query, alternative);
+    if (malformed != null) return { ok: false, kind: 'malformed', expected: malformed };
+  }
+  let unsupported = null;
+  for (const alternative of alternatives) {
+    const checked = checkAlternative(program, quad, alternative, options);
+    if (checked.ok) return checked;
+    if (checked.kind === 'unsupported') unsupported ??= checked;
+  }
+  return unsupported ?? { ok: false, kind: 'failed', expected: description };
+}
+
+function checkAlternative(program, quad, alternative, options) {
+  const leaves = splitOperator(alternative, ';').map(describeLeaf);
+  if (leaves.some((leaf) => leaf.sto)) return { ok: true };
+  const unsupported = leaves.find((leaf) => leaf.unsupported != null)?.unsupported;
+  if (unsupported != null) {
+    return { ok: false, kind: 'unsupported', expected: unsupported };
+  }
+
+  const inputSpecs = [...new Set(leaves.filter((leaf) => leaf.input != null).map((leaf) => leaf.input))];
+  if (inputSpecs.length > 1) return { ok: false, kind: 'malformed', expected: alternative };
+  const input = inputSpecs[0] ?? '';
+  if (inputSpecs.length > 0 && leaves.length !== 1) return { ok: false };
+  const moreAt = leaves.findIndex((leaf) => leaf.more);
+  const describedCount = moreAt < 0 ? leaves.length : moreAt + (leaves[moreAt].hasExpectation ? 1 : 0);
+  const maxSolutions = inputSpecs.length > 0
+    ? 1
+    : moreAt < 0 ? describedCount + 1 : Math.max(describedCount, 1);
+  const actual = executeQuery(program, quad.query, input, maxSolutions, options);
+
+  if (inputSpecs.length > 0) {
+    const leaf = leaves[0];
+    const matches = actual.inputPosition === input.length && matchLeaf(quad.query, leaf, actual, 0);
+    return { ok: leaf.unexpected ? !matches : matches };
+  }
+
+  let position = 0;
+  for (const leaf of leaves) {
+    if (leaf.more && !leaf.hasExpectation) return { ok: true };
+    const matches = matchLeaf(quad.query, leaf, actual, position);
+    if (leaf.unexpected ? matches : !matches) return { ok: false };
+    if (leaf.more) return { ok: true };
+    if (!leaf.unexpected && (leaf.false || leaf.error != null)) {
+      return { ok: position === leaves.length - 1 };
+    }
+    position++;
+  }
+
+  const ended = position >= actual.solutions.length && actual.error == null;
+  return { ok: ended };
+}
+
+function malformedAlternative(query, alternative) {
+  const queryNames = new Set(namedVariables(query).map((variable) => variable.name));
+  for (const leaf of splitOperator(alternative, ';').map(describeLeaf)) {
+    if (leaf.malformed != null) return leaf.malformed;
+    const names = new Set();
+    for (const binding of leaf.bindings) {
+      const name = binding.args[0].name;
+      if (!queryNames.has(name) || names.has(name)) return binding;
+      names.add(name);
+    }
+    if (!leaf.sto) {
+      for (const binding of leaf.bindings) {
+        if (namedVariables(binding.args[1]).some((variable) => names.has(variable.name))) return binding;
+      }
+    }
+  }
+  return null;
+}
+
+function describeLeaf(term) {
+  const leaf = {
+    bindings: [],
+    unexpected: false,
+    more: false,
+    sto: false,
+    false: false,
+    truth: false,
+    error: null,
+    input: null,
+    output: null,
+    unsupported: null,
+    malformed: null,
+    hasExpectation: false,
+  };
+  for (const item of flattenConjunction(term)) {
+    if (item.type === ATOM) {
+      if (item.name === 'unexpected' || item.name === 'inattendue') leaf.unexpected = true;
+      else if (item.name === '...' || item.name === 'ad_infinitum') leaf.more = true;
+      else if (item.name === 'sto') leaf.sto = true;
+      else if (item.name === 'loops' || item.name === 'waits' || item.name === 'other_answer_sequence') {
+        leaf.unsupported ??= item;
+      } else if (item.name === 'false') leaf.false = true;
+      else if (item.name === 'true') leaf.truth = true;
+      else if (isErrorDescription(item)) leaf.error = item;
+      else leaf.malformed ??= item;
+      continue;
+    }
+    if (item.type === COMPOUND && item.name === '=' && item.arity === 2) {
+      if (item.args[0].type !== VAR) leaf.malformed ??= item;
+      else leaf.bindings.push(item);
+      continue;
+    }
+    if (item.type === COMPOUND && item.name === 'inputs' && item.arity === 1) {
+      const text = characterText(item.args[0]);
+      if (text == null || leaf.input != null) leaf.malformed ??= item;
+      else leaf.input = text;
+      continue;
+    }
+    if (item.type === COMPOUND && item.name === 'outputs' && item.arity === 1) {
+      const text = characterText(item.args[0]);
+      if (text == null || leaf.output != null) leaf.malformed ??= item;
+      else leaf.output = text;
+      continue;
+    }
+    if (item.type === COMPOUND && item.name === 'peeks' && item.arity === 1) {
+      leaf.unsupported ??= item;
+      continue;
+    }
+    if (isErrorDescription(item)) leaf.error = item;
+    else leaf.malformed ??= item;
+  }
+  leaf.hasExpectation = leaf.bindings.length > 0 || leaf.truth || leaf.false || leaf.error != null || leaf.output != null;
+  if (!leaf.hasExpectation && !leaf.more && !leaf.sto && leaf.unsupported == null) leaf.malformed ??= term;
+  if ([leaf.false, leaf.truth, leaf.error != null].filter(Boolean).length > 1) leaf.malformed ??= term;
+  return leaf;
+}
+
+function executeQuery(program, query, input, maxSolutions, options) {
+  let pendingOutput = '';
+  const solver = new Solver(program, {
+    ...options,
+    registry: options.registry ?? getEyePrologRegistry(),
+    solutionLimit: Math.max(1, maxSolutions),
+    ioOptions: {
+      input,
+      write: (text) => { pendingOutput += String(text); },
+    },
+  });
+  const solutions = [];
+  let error = null;
+  let tailOutput = '';
+  try {
+    const iterator = solver.solve([query], new Env(), 0);
+    while (solutions.length < maxSolutions) {
+      pendingOutput = '';
+      const result = iterator.next();
+      if (result.done) {
+        tailOutput += pendingOutput;
+        break;
+      }
+      solutions.push({ env: result.value, output: pendingOutput });
+    }
+  } catch (caught) {
+    error = { term: errorTerm(caught), output: pendingOutput };
+  }
+  const inputPosition = solver.io.resolve('user_input')?.position ?? 0;
+  return { solutions, error, tailOutput, inputPosition };
+}
+
+function matchLeaf(query, leaf, actual, position) {
+  if (leaf.false) {
+    return position >= actual.solutions.length && actual.error == null && outputMatches(leaf.output, actual.tailOutput);
+  }
+  if (leaf.error != null) {
+    return position === actual.solutions.length && actual.error != null &&
+      errorMatches(leaf.error, actual.error.term) && outputMatches(leaf.output, actual.error.output);
+  }
+  const solution = actual.solutions[position];
+  if (!solution || !outputMatches(leaf.output, solution.output)) return false;
+  return substitutionMatches(query, leaf.bindings, solution.env);
+}
+
+function substitutionMatches(query, bindings, actualEnv) {
+  const queryVariables = namedVariables(query);
+  const queryNames = new Set(queryVariables.map((variable) => variable.name));
+  const expectedEnv = new Env();
+  const rebound = new Set();
+  for (const binding of bindings) {
+    const variable = binding.args[0];
+    if (!queryNames.has(variable.name) || rebound.has(variable.name)) return false;
+    rebound.add(variable.name);
+    if (!unify(variable, binding.args[1], expectedEnv)) return false;
+  }
+  const expected = compound('$quad_answer', queryVariables.map((variable) => copyResolved(variable, expectedEnv)));
+  const actual = compound('$quad_answer', queryVariables.map((variable) => copyResolved(variable, actualEnv)));
+  return patternVariant(expected, new Env(), actual, new Env());
+}
+
+function namedVariables(term) {
+  const found = [];
+  const seen = new Set();
+  const stack = [term];
+  while (stack.length) {
+    const current = stack.pop();
+    if (current.type === VAR) {
+      if (!current.name.startsWith('__anon') && !seen.has(current.name)) {
+        seen.add(current.name);
+        found.push(current);
+      }
+    } else {
+      for (let index = current.args.length - 1; index >= 0; index--) stack.push(current.args[index]);
+    }
+  }
+  return found;
+}
+
+function patternVariant(pattern, patternEnv, actual, actualEnv, pairs = new Map(), reverse = new Map()) {
+  pattern = deref(pattern, patternEnv);
+  actual = deref(actual, actualEnv);
+  if (pattern.type === ATOM && pattern.name === '...') return true;
+  if (pattern.type === VAR || actual.type === VAR) {
+    if (pattern.type !== VAR || actual.type !== VAR) return false;
+    const paired = pairs.get(pattern.name);
+    const reversed = reverse.get(actual.name);
+    if (paired != null || reversed != null) return paired === actual.name && reversed === pattern.name;
+    pairs.set(pattern.name, actual.name);
+    reverse.set(actual.name, pattern.name);
+    return true;
+  }
+  if (pattern.type !== actual.type || pattern.name !== actual.name || pattern.arity !== actual.arity) return false;
+  for (let index = 0; index < pattern.arity; index++) {
+    if (!patternVariant(pattern.args[index], patternEnv, actual.args[index], actualEnv, pairs, reverse)) return false;
+  }
+  return true;
+}
+
+function errorTerm(error) {
+  if (error?.name === 'ThrownTerm' && error.term) return compound('$quad_thrown', [error.term]);
+  if (error?.name === 'PrologError') {
+    let formal;
+    try {
+      formal = parseGoalText(error.formal);
+    } catch (_) {
+      formal = atom(error.formal ?? 'system_error');
+    }
+    if (error.culprit != null) formal = formal.type === COMPOUND
+      ? compound(formal.name, [...formal.args, error.culprit])
+      : compound(formal.name, [error.culprit]);
+    return compound('error', [formal, variable('$quad_context')]);
+  }
+  return compound('error', [atom('system_error'), variable('$quad_context')]);
+}
+
+function errorMatches(expected, actual) {
+  if (expected.type === COMPOUND && expected.name === 'throw' && expected.arity === 1 &&
+      actual.type === COMPOUND && actual.name === '$quad_thrown' && actual.arity === 1) {
+    return patternVariant(expected.args[0], new Env(), actual.args[0], new Env());
+  }
+  if (actual.type !== COMPOUND || actual.name !== 'error' || actual.arity !== 2) return false;
+  if (expected.type === COMPOUND && expected.name === 'error' && expected.arity === 2) {
+    return patternVariant(expected, new Env(), actual, new Env());
+  }
+  return patternVariant(expected, new Env(), actual.args[0], new Env());
+}
+
+function isErrorDescription(term) {
+  if (term.type === ATOM) return ['instantiation_error', 'system_error'].includes(term.name);
+  return term.type === COMPOUND && [
+    'error', 'throw', 'type_error', 'domain_error', 'existence_error',
+    'permission_error', 'evaluation_error', 'representation_error',
+    'resource_error', 'syntax_error', 'uninstantiation_error',
+  ].includes(term.name);
+}
+
+function characterText(term) {
+  const items = properListItems(term, new Env());
+  if (items == null) return null;
+  let text = '';
+  for (const item of items) {
+    if (item.type === ATOM && Array.from(item.name).length === 1) text += item.name;
+    else if (item.type === 'number' && /^\d+$/.test(item.name)) text += String.fromCodePoint(Number(item.name));
+    else return null;
+  }
+  return text;
+}
+
+function outputMatches(expected, actual) {
+  return expected == null || expected === actual;
+}
+
+function splitOperator(term, name) {
+  if (term.type === COMPOUND && term.name === name && term.arity === 2) {
+    return [term.args[0], ...splitOperator(term.args[1], name)];
+  }
+  return [term];
+}
+
+function formatFailure(program, quad, result) {
+  const source = quad.source ?? { filename: '<input>', line: 1 };
+  const label = quad.id == null ? '' : `${formatQuadTerm(program, quad.id)}, `;
+  const reason = result.kind === 'malformed' ? 'MALFORMED'
+    : result.kind === 'bad_identifier' ? 'BAD_ID'
+      : result.kind === 'unsupported' ? 'UNSUPPORTED'
+        : 'FAILED';
+  const expected = result.expected ?? quad.answers[0];
+  return `quads: ${reason} ${label}${source.filename}:${source.line}\n` +
+    `   ?- ${formatQuadTerm(program, quad.query)}.\n` +
+    `   expected: ${formatQuadTerm(program, expected)}.\n`;
+}
+
+function formatQuadTerm(program, term) {
+  return formatTermForWrite(term, new Env(), {
+    quoted: true,
+    operators: [...program.operators.values()],
+  });
+}

package/src/write.js

@@ -9,6 +9,7 @@ const graphicAtomCharacters = new Set('!#$&*+-/<=>@^~\\'.split(''));
 function atomNeedsQuotes(name) {
   if (!name) return true;
   if (name === '[]' || name === '{}') return false;
+  if (name === '...') return false;
   if (name === '\\+' || name === '+' || name === '-' || name === '\\') return true;
   if (/^[a-z][A-Za-z0-9_]*$/.test(name)) return false;
   for (const ch of name) if (!graphicAtomCharacters.has(ch)) return true;

package/test/run-regression.mjs

@@ -183,6 +183,81 @@ why(
         assertNotIncludes(result.stdout, 'no_proof', 'stdout');
       },
     },
+    {
+      name: 'parser records embedded quads without indexing them as clauses',
+      run: () => {
+        const source = `p(1).\n\nnamed ?- p(X).\n   X = 1.\n\nq(2).\n`;
+        const program = Program.parseSources([{ text: source, filename: 'embedded-quads.pl' }]);
+        assertEqual(program.clauses.length, 2, 'ordinary clause count');
+        assertEqual(program.quads.length, 1, 'quad count');
+        assertEqual(program.quads[0].id.name, 'named', 'quad label');
+        assertEqual(program.quads[0].source.filename, 'embedded-quads.pl', 'quad filename');
+        assertEqual(program.quads[0].source.line, 3, 'quad line');
+        assertEqual(Boolean(program.findGroup('p', 1)), true, 'preceding clause indexed');
+        assertEqual(Boolean(program.findGroup('q', 1)), true, 'following clause indexed');
+        assertEqual(Boolean(program.findGroup('?-', 2)), false, 'quad is inert');
+      },
+    },
+    {
+      name: 'runQuads checks portable answer descriptions',
+      run: () => {
+        const source = `p(1).\np(2).\np(3).\n\n` +
+          `ordered ?- p(X).\n   X = 1 ; X = 2 ; X = 3.\n\n` +
+          `?- p(4).\n   false.\n\n` +
+          `?- X = 1.\n   X = 2, unexpected.\n\n` +
+          `?- p(X).\n   X = 1, ... .\n\n` +
+          `?- atom_length(1, L).\n   type_error(atom, 1).\n\n` +
+          `?- atom_length(1, L).\n   error(type_error(atom, 1), _).\n\n` +
+          `?- throw(ball).\n   throw(ball).\n\n` +
+          `?- write(ok), nl.\n   outputs("ok\\n"), true.\n\n` +
+          `?- get_char(C).\n   inputs("a"), C = a.\n\n` +
+          `?- get_char(C).\n   inputs("ab"), C = a, unexpected.\n\n` +
+          `?- X = 1.\n   X = 2, unexpected.\n   X = 1.\n\n` +
+          `?- catch(throw(ball), E, true).\n   E = ball | error(system_error, ...).\n`;
+        const result = publicApi.runQuads(Program.parseSources([{ text: source, filename: 'quads.pl' }]));
+        assertEqual(result.total, 12, 'quad total');
+        assertEqual(result.passed, 12, 'quad passed');
+        assertEqual(result.failed, 0, 'quad failed');
+        assertEqual(result.stdout, 'quads: 12 run, 12 passed, 0 failed.\n', 'quad report');
+      },
+    },
+    {
+      name: 'runQuads rejects malformed answer substitutions',
+      run: () => {
+        const source = `?- X = f(Y), Y = 1.\n   X = f(Y), Y = 1.\n`;
+        const result = publicApi.runQuads(Program.parseSources([{ text: source, filename: 'malformed-quad.pl' }]));
+        assertEqual(result.total, 1, 'quad total');
+        assertEqual(result.failed, 1, 'quad failed');
+        assertIncludes(result.stdout, 'quads: MALFORMED malformed-quad.pl:1', 'malformed report');
+      },
+    },
+    {
+      name: 'runQuads reports annotations that cannot be checked safely',
+      run: () => {
+        const result = publicApi.runQuads(`?- repeat, fail.\n   loops.\n`);
+        assertEqual(result.results[0].kind, 'unsupported', 'quad result');
+        assertIncludes(result.stdout, 'quads: UNSUPPORTED <input>:1', 'unsupported report');
+      },
+    },
+    {
+      name: '--quads runs embedded tests and reports failures through exit status',
+      run: () => {
+        const passing = runCli(['--quads', '-'], {
+          input: `p(ok).\n\nsmoke ?- p(X).\n   X = ok.\n`,
+        });
+        assertEqual(passing.status, 0, 'passing quad exit status');
+        assertEqual(passing.stdout, 'quads: 1 run, 1 passed, 0 failed.\n', 'passing quad stdout');
+        assertEqual(passing.stderr, '', 'passing quad stderr');
+
+        const failing = runCli(['-q', '-'], {
+          input: `p(actual).\n\nsmoke ?- p(X).\n   X = expected.\n`,
+        });
+        assertEqual(failing.status, 1, 'failing quad exit status');
+        assertIncludes(failing.stdout, 'quads: FAILED smoke, <stdin>:3', 'failing quad report');
+        assertIncludes(failing.stdout, 'quads: 1 run, 0 passed, 1 failed.', 'failing quad summary');
+        assertEqual(failing.stderr, '', 'failing quad stderr');
+      },
+    },
     {
       name: 'seeded random/3 sequence is reproducible',
       run: () => {
@@ -212,6 +287,7 @@ why(
         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, '-q, --quads', 'stdout');
         assertIncludes(result.stdout, '-s, --stats', 'stdout');
         assertIncludes(result.stdout, '-v, --version', 'stdout');
         assertIncludes(result.stdout, '-w, --warnings', 'stdout');

package/the-art-of-eyeprolog.md

@@ -6072,13 +6072,14 @@ make the observed question explicit.
 | --- | --- |
 | `-h`, `--help` | Show usage |
 | `-p`, `--proof` | Print `why/2` explanations |
+| `-q`, `--quads` | Run embedded quad tests and fail if any do not hold |
 | `-s`, `--stats` | Print solver counters to stderr |
 | `-v`, `--version` | Print the package version |
 | `-w`, `--warnings` | Print non-fatal portability warnings |
 | `-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`.
+Short flags may be combined, so `-pqw` is equivalent to `-p -q -w`.
 
 Inputs may be local files, HTTP(S) URLs, or one `-` for stdin. The bare command
 `eyeprolog` starts the REPL. When options are present but no input is named,
@@ -6113,6 +6114,56 @@ they do not corrupt that logical stream. A successful run normally exits with
 status zero; loading, syntax, option, and other uncaught errors use status `1`. `halt/0-1` can deliberately choose the
 process status from inside a program.
 
+### Embedded quad tests
+
+A quad places a query directly before a description of its expected top-level
+answer. The answer is ordinary Prolog syntax rather than quoted text or a
+comment, so a small test reads like the interaction it checks:
+
+```eyeprolog
+color(red).
+color(green).
+
+colors ?- color(X).
+   X = red
+;  X = green.
+
+?- color(blue).
+   false.
+```
+
+Run all quads in a file with `eyeprolog --quads file.pl` or `eyeprolog -q
+file.pl`. A label such as `colors` is optional. Loading the file normally only
+records its quads; it does not execute them or add their queries and answers as
+program clauses. A quad run prints a summary and exits with status `1` when any
+description fails.
+
+Answer descriptions support ordered answers separated by `;`, acceptable
+alternatives separated by `|`, `true`, `false`, standard error descriptions,
+and the `unexpected` annotation for an answer that must not occur (`inattendue`
+is its synonym). `...` and `ad_infinitum` accept further answers. Multiple
+indented descriptions after one query must all hold. `inputs/1` supplies and
+checks consumed characters; `outputs/1` checks emitted characters. `sto` marks
+an answer description that this finite-tree implementation skips. The
+nontermination and advanced stream annotations `loops`, `peeks/1`, and `waits`,
+and the unordered `other_answer_sequence` annotation, are not executed by the
+current runner.
+
+The JavaScript API exposes the same operation without process I/O:
+
+```js
+import { Program, runQuads } from 'eyeprolog';
+
+const program = Program.parse(source);
+const report = runQuads(program);
+console.log(report.passed, report.failed, report.stdout);
+```
+
+The syntax follows the “queries using answer descriptions” convention used by
+Trealla and the ISO Prolog working examples. Because answer descriptions are
+layout-sensitive, indent every description while keeping ordinary clause heads
+and the next quad query at the left margin.
+
 Statistics are comparative evidence, not a score in isolation. Preserve the
 program, input, runtime version, selected query, answers, and counters together.
 An optimization is acceptable only when the intended answers remain unchanged