eyeprolog 1.1.20 → 1.1.22

package/conformance-report.md

@@ -11,7 +11,7 @@ This report summarizes the file-based conformance corpus under `test/conformance
 | builtins | 11 | 0 | 0 | 0 | 11 |
 | context | 11 | 0 | 0 | 0 | 11 |
 | control | 15 | 0 | 0 | 0 | 15 |
-| iso | 165 | 209 | 0 | 0 | 374 |
+| iso | 166 | 209 | 0 | 0 | 375 |
 | lists | 52 | 3 | 0 | 0 | 55 |
 | modules | 2 | 0 | 0 | 0 | 2 |
 | negation | 8 | 0 | 19 | 0 | 27 |
@@ -23,4 +23,4 @@ This report summarizes the file-based conformance corpus under `test/conformance
 | terms | 26 | 3 | 0 | 0 | 29 |
 | unification | 18 | 0 | 0 | 0 | 18 |
 | variables | 16 | 9 | 0 | 0 | 25 |
-| **Total** | **480** | **260** | **19** | **21** | **780** |
+| **Total** | **481** | **260** | **19** | **21** | **781** |

package/package.json

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

package/src/iso.js

@@ -48,7 +48,7 @@ export const isoBuiltins = {
     registry.add('!', 0, succeed, { deterministic: true });
 
     registry.add('=', 2, unification, { deterministic: true });
-    registry.add('unify_with_occurs_check', 2, unification, { deterministic: true });
+    registry.add('unify_with_occurs_check', 2, unificationWithOccursCheck, { deterministic: true });
     registry.add('\\=', 2, nonUnification, { deterministic: true });
     registry.add('subsumes_term', 2, subsumesTermBuiltin, { deterministic: true });
     registry.add('==', 2, identity, { deterministic: true });
@@ -178,6 +178,14 @@ function* unification({ goal, env }) {
   const next = env.clone();
   if (unify(goal.args[0], goal.args[1], next)) yield next;
 }
+function* unificationWithOccursCheck({ goal, env }) {
+  const next = env.clone();
+  // ISO unify_with_occurs_check/2 always performs finite-tree unification.
+  // The implementation-specific occurs_check=error mode applies to normal
+  // unification, but must not turn this ISO predicate's ordinary failure into
+  // an exception.
+  if (unify(goal.args[0], goal.args[1], next, { occursCheck: 'fail' })) yield next;
+}
 function* nonUnification({ goal, env }) {
   if (!unify(goal.args[0], goal.args[1], env.clone())) yield env;
 }
@@ -1776,6 +1784,7 @@ function* phraseBuiltin({ solver, goal, env }) {
   }
 }
 function formalErrorTerm(error) {
+  if (error.formalTerm != null) return compound('error', [error.formalTerm, atom('eyeprolog')]);
   const parse = (text) => {
     const open = text.indexOf('(');
     if (open === -1) return atom(text);

package/src/parser.js

@@ -225,6 +225,11 @@ class Parser {
   }
   operatorTokenName(token = this.token) {
     if (token.type === TOK.ATOM) return token.text;
+    // `:-` has its own token because it also introduces clauses/directives,
+    // but ISO 6.3.3.1 still permits an operator atom as an argument. Treat the
+    // token as the ordinary operator name while parsing terms; the surrounding
+    // grammar decides whether it is operator notation or atom data.
+    if (token.type === TOK.IF) return ':-';
     if (token.type === TOK.STRING && this.parserFlagState.doubleQuotes === 'atom') return token.text;
     return null;
   }
@@ -533,6 +538,14 @@ class Parser {
     return left;
   }
   parsePrefixTerm(minPrecedence = 0, allowBar = true) {
+    // `:-` is tokenized specially so the program grammar can recognize clause
+    // and directive markers. In term argument position, however, ISO 6.3.3.1
+    // permits an operator atom directly as an `arg`; a leading `:-` cannot be
+    // prefix operator notation at argument priority, so it denotes the atom.
+    if (this.token.type === TOK.IF) {
+      this.advance();
+      return atom(':-');
+    }
     const operatorName = this.operatorTokenName();
     if (operatorName != null && this.prefixOperators.get(operatorName)?.precedence >= minPrecedence) {
       const op = operatorName;

package/src/repl.js

@@ -413,6 +413,15 @@ function formatError(engine, state, error) {
     const env = new engine.Env();
     const variableNames = new Map();
     let generated = 0;
+    if (error.formalTerm != null) {
+      collectUnboundVariables(engine, error.formalTerm, env, variableNames, () => `_${letterName(generated++)}`);
+      const formal = engine.formatTermForWrite(error.formalTerm, env, {
+        quoted: true,
+        operators: [...state.program.operators.values()],
+        variableNames,
+      });
+      return `error(${formal}).`;
+    }
     if (error.culprit != null) {
       collectUnboundVariables(engine, error.culprit, env, variableNames, () => `_${letterName(generated++)}`);
     }

package/src/solver.js

@@ -23,6 +23,12 @@ export function nextFreshId() {
   return ++freshCounter;
 }
 
+function raiseOccursCheckError(left, right, env) {
+  const error = new PrologError('occurs_check');
+  error.formalTerm = copyResolved(compound('occurs_check', [left, right]), env);
+  throw error;
+}
+
 export class Solver {
   constructor(program, options = {}) {
     this.registry = options.registry ?? getEyePrologRegistry();
@@ -37,6 +43,11 @@ export class Solver {
     this.solutionLimit = options.solutionLimit ?? 10000000;
     this.solutionsSeen = 0;
     this.prologFlags = options.prologFlags ?? defaultPrologFlags(this.registry?.eyePrologLibrary ? 'fail' : 'error');
+    this.occursCheckHandler = (left, right, env) => {
+      if (this.prologFlags.get('occurs_check')?.value?.name === 'error') {
+        raiseOccursCheckError(left, right, env);
+      }
+    };
     this.charConversions = options.charConversions ?? new Map();
     if (!options.prologFlags) {
       if (['chars', 'codes', 'atom'].includes(program.doubleQuotes)) {
@@ -140,6 +151,7 @@ export class Solver {
 
   *solve(goals, env = new Env(), depth = 0) {
     if (!Array.isArray(goals)) goals = [goals];
+    env.setOccursCheckHandler(this.occursCheckHandler);
 
     const savedActive = this.active;
     let registeredStack = null;
@@ -194,6 +206,7 @@ export class Solver {
 
       goals = frame.goals;
       env = frame.env;
+      env.setOccursCheckHandler(this.occursCheckHandler);
       depth = frame.depth;
       let active = frame.active;
 
@@ -474,6 +487,7 @@ function defaultPrologFlags(unknown = 'error') {
     ['max_arity', { value: compound('unbounded', []), allowed: ['unbounded'], changeable: false }],
     ['unknown', { value: compound(unknown, []), allowed: ['error', 'fail', 'warning'], changeable: true }],
     ['double_quotes', { value: compound('chars', []), allowed: ['chars', 'codes', 'atom'], changeable: true }],
+    ['occurs_check', { value: compound('true', []), allowed: ['true', 'error'], changeable: true }],
   ]);
 }
 

package/src/term.js

@@ -47,6 +47,7 @@ export class Env {
     };
     this._delays = null;
     this._clpz = null;
+    this._occursCheckHandler = null;
   }
   clone() {
     // Most speculative environments are either rejected without a binding or
@@ -58,8 +59,13 @@ export class Env {
     clone._state = this._state;
     clone._delays = this._delays;
     clone._clpz = this._clpz;
+    clone._occursCheckHandler = this._occursCheckHandler;
     return clone;
   }
+  setOccursCheckHandler(handler) {
+    this._occursCheckHandler = typeof handler === 'function' ? handler : null;
+    return this;
+  }
   has(name) {
     return this.get(name) !== undefined;
   }
@@ -207,11 +213,12 @@ function occurs(variableName, term, env) {
   return false;
 }
 
-export function unify(left, right, env) {
+export function unify(left, right, env, options = {}) {
   // Iterative unification avoids deep JavaScript recursion on long lists or
   // deeply nested compounds. The occurs check gives EyeProlog finite-tree
   // unification: a variable cannot be bound to a term containing itself.
   // Bindings are written into the supplied Env.
+  const occursCheckHandler = options.occursCheck === 'fail' ? null : env?._occursCheckHandler;
   const stack = [[left, right]];
   while (stack.length) {
     let [a, b] = stack.pop();
@@ -226,12 +233,18 @@ export function unify(left, right, env) {
       continue;
     }
     if (a.type === VAR) {
-      if (occurs(a.name, b, env)) return false;
+      if (occurs(a.name, b, env)) {
+        occursCheckHandler?.(a, b, env);
+        return false;
+      }
       env.bind(a.name, b);
       continue;
     }
     if (b.type === VAR) {
-      if (occurs(b.name, a, env)) return false;
+      if (occurs(b.name, a, env)) {
+        occursCheckHandler?.(b, a, env);
+        return false;
+      }
       env.bind(b.name, a);
       continue;
     }

package/test/conformance/README.md

@@ -94,7 +94,7 @@ Selected cases are adapted from the ISO and standard-core suites of Logtalk,
 Scryer Prolog, Trealla Prolog, and SWI-Prolog. Their upstream identifiers and licenses
 are recorded in [THIRD_PARTY.md](THIRD_PARTY.md).
 
-The corpus has 374 cases in `iso/` and 780 file-based conformance cases in
+The corpus has 375 cases in `iso/` and 781 file-based conformance cases in
 total. The generated `conformance-report.md` is the authoritative source for
 current category totals. Together with regression, documentation-sync, API,
 example, and book-example checks, `npm test` is the release gate.

package/test/conformance/cases/iso/operator_atoms_as_arguments.pl

@@ -0,0 +1,7 @@
+% ISO 6.3.3.1: an arg may be an atom which is an operator.
+
+%% goal: operator_atoms(Priority, Specifier, List)
+
+operator_atoms(Priority, Specifier, List) :-
+    current_op(Priority, Specifier, :-),
+    List = [:-,-].

package/test/conformance/expected/iso/exceptions_and_flags.pl

@@ -1,3 +1,3 @@
 answer(7, red, caught(eyeprolog), first, caught(eyeprolog)).
 answer(7, red, caught(eyeprolog), second, caught(eyeprolog)).
-flags(off, on, [pair(bounded, false), pair(integer_rounding_function, toward_zero), pair(char_conversion, on), pair(debug, off), pair(max_integer, unbounded), pair(min_integer, unbounded), pair(max_arity, unbounded), pair(unknown, fail), pair(double_quotes, chars)]).
+flags(off, on, [pair(bounded, false), pair(integer_rounding_function, toward_zero), pair(char_conversion, on), pair(debug, off), pair(max_integer, unbounded), pair(min_integer, unbounded), pair(max_arity, unbounded), pair(unknown, fail), pair(double_quotes, chars), pair(occurs_check, true)]).

package/test/conformance/expected/iso/operator_atoms_as_arguments.pl

@@ -0,0 +1,2 @@
+operator_atoms(1200, xfx, [':-', '-']).
+operator_atoms(1200, fx, [':-', '-']).

package/test/run-regression.mjs

@@ -522,6 +522,40 @@ c4 ?- call((!;1)).
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'occurs_check error mode detects STO while ISO occurs-check unification still fails',
+      run: () => {
+        const filename = path.join(tmp, `occurs-check-${++tmpCounter}.pl`);
+        fs.writeFileSync(filename, ':- set_prolog_flag(occurs_check, error).\nsame(X, X).\n');
+        const result = runCli([], {
+          input:
+            'current_prolog_flag(occurs_check, Mode).\n' +
+            'set_prolog_flag(occurs_check, error).\n' +
+            'X = f(X).\n' +
+            'catch((Y = g(Y)), E, true).\n' +
+            'unify_with_occurs_check(Z, h(Z)).\n' +
+            `[${sourceAtom(filename)}].\n` +
+            'same(W, k(W)).\n' +
+            'set_prolog_flag(occurs_check, true).\n' +
+            'Q = q(Q).\n' +
+            'halt.\n',
+        });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout,
+          '?-    Mode = true.\n' +
+          '?-    true.\n' +
+          '?-    error(occurs_check(_A, f(_A))).\n' +
+          '?-    E = error(occurs_check(_A, g(_A)), eyeprolog).\n' +
+          '?-    false.\n' +
+          '?-    true.\n' +
+          '?-    error(occurs_check(_A, k(_A))).\n' +
+          '?-    true.\n' +
+          '?-    false.\n' +
+          '?- ',
+          'stdout');
+        assertEqual(result.stderr, '', 'stderr');
+      },
+    },
     {
       name: 'REPL enumerates and stops answers like the Scryer top level',
       run: () => {
@@ -906,6 +940,16 @@ c4 ?- call((!;1)).
         assertEqual(program.findGroup('b', 0).clauses.length, 1, 'b/0 count');
       },
     },
+    {
+      name: 'ISO operator atoms are valid functional and list arguments',
+      run: () => {
+        const source = [
+          'operator_argument(ok) :- current_op(1200, xfx, :-), [:-,-] = [:-,-].',
+          '',
+        ].join('\n');
+        assertEqual(run(source, { goal: 'operator_argument(ok)' }).stdout, 'operator_argument(ok).\n', 'operator argument syntax');
+      },
+    },
     {
       name: 'term input keeps dotted operators intact and uses program operators',
       run: () => {

package/the-art-of-eyeprolog.md

@@ -780,6 +780,27 @@ fails rather than constructing a cyclic term:
 (X = wrapper(X)).
 ```
 
+ISO classifies unifications whose outcome depends on an occurs check as
+subject-to-occurs-check (STO). EyeProlog's default remains the sound finite-tree
+behavior above. For diagnosis, EyeProlog additionally provides the
+implementation-specific flag `occurs_check`; setting it to `error` turns a
+normal unification that would otherwise fail because of the occurs check into
+an exception:
+
+```eyeprolog
+:- set_prolog_flag(occurs_check, error).
+
+sto_example :- X = wrapper(X).
+% error(occurs_check(_A, wrapper(_A)))
+```
+
+The supported values are `true` (the default finite-tree behavior) and `error`
+(STO detection). EyeProlog deliberately does not provide `occurs_check=false`,
+because its term model does not construct cyclic terms. The ISO predicate
+`unify_with_occurs_check/2` is independent of the diagnostic flag: it continues
+to perform finite-tree unification and fails on `unify_with_occurs_check(X,
+wrapper(X))` even when `occurs_check` is `error`.
+
 ### Meaning is not the search strategy
 
 EyeProlog's evaluator is goal-directed. It resolves selected goals against facts,
@@ -5099,7 +5120,11 @@ The fact is exactly `reports(sensor_7, temperature)`. Priority determines
 binding strength, and `fx`, `fy`, `xf`, `yf`, `xfx`, `xfy`, and `yfx`
 determine position and associativity. `current_op/3` inspects the table;
 `op(0, Specifier, Name)` removes a definition. Because declarations affect
-parsing of subsequent text, place them before their first use.
+parsing of subsequent text, place them before their first use. ISO argument
+syntax also permits an atom that is currently an operator to appear directly
+as a functional argument or list element, so forms such as
+`current_op(Priority, Specifier, :-)` and `[:-,-]` are valid without quoting
+or parenthesizing those operator atoms.
 
 Run [`iso-dynamic-database.pl`](https://github.com/eyereasoner/eyeprolog/blob/main/examples/iso-dynamic-database.pl)
 for an explicitly stateful queue and
@@ -5610,11 +5635,14 @@ silently changing a static program.
 | `max_arity` | `unbounded` | `unbounded` | no |
 | `unknown` | `fail` | `error`, `fail`, `warning` | yes |
 | `double_quotes` | `chars` | `chars`, `codes`, `atom` | yes |
+| `occurs_check` | `true` | `true`, `error` | yes |
 
 The isolated ISO-only registry defaults `unknown` to `error`; the normal
-EyeProlog environment defaults it to `fail`. Operator and flag
-directives are processed per program rather than changing global JavaScript
-state. The `double_quotes` setting affects subsequent source text, included
+EyeProlog environment defaults it to `fail`. The `occurs_check` flag is an
+EyeProlog diagnostic extension rather than an ISO-defined core flag; its
+`true` default preserves the engine's finite-tree unification, while `error`
+reports STO attempts. Operator and flag directives are processed per program
+rather than changing global JavaScript state. The `double_quotes` setting affects subsequent source text, included
 files, command-line and API goal text, and terms read by `read_term/*`:
 
 ```text
@@ -6821,7 +6849,7 @@ node test/run-conformance-report.mjs
 ```
 
 The complete suite must pass before release. The file-based conformance corpus
-contains 780 cases, including 374 focused ISO
+contains 781 cases, including 375 focused ISO
 cases derived from the success, failure, mode, and error behavior in
 ISO/IEC 13211-1 clauses 7 and 8, Part 2 modules, and Part 3 grammar rules.
 Separate exact-output suites check 189 normal