eyeprolog 1.3.14 → 1.3.16

package/README.md

@@ -201,6 +201,23 @@ noun --> [world] | [prolog].
 %% goal: phrase(sentence, Words)
 ```
 
+For a larger bidirectional example, see
+[`examples/dcg-expression-language.pl`](examples/dcg-expression-language.pl).
+It parses precedence-sensitive arithmetic into an AST, evaluates expressions
+with variables, generates tokens back from an AST with only the necessary
+parentheses, round-trips the generated form, and demonstrates `phrase/3`
+remainder handling.  The example uses accumulator nonterminals for
+left-associative operators, so state is handed repeatedly from one nonterminal
+to the next rather than hidden in host code.
+
+Deep finite DCG traversal is kept relational but does not have to consume one
+general solver frame per token.  In particular, the interoperable `...//0`
+helper from `library(iso_ext)` can scan a finite compact list iteratively, and a
+following grammar that is statically known to leave the DCG state unchanged can
+be continued without rebuilding a full clause-resolution frame for every
+suffix.  Open and remainder-producing uses still retain the ordinary DCG
+solutions and backtracking behavior.
+
 EyeProlog also adds 128 public library predicate indicators to its 129-entry ISO
 profile. **88 are implemented entirely as ordinary Prolog clauses** in focused
 modules under `src/lib/`; the remaining control predicates and finite-domain

package/examples/dcg-expression-language.pl

@@ -0,0 +1,147 @@
+% Parse, evaluate, and regenerate arithmetic expressions with a DCG.
+%
+% The parser builds an AST while respecting precedence and left associativity.
+% The additive_tail//2 and multiplicative_tail//2 nonterminals use an
+% accumulator instead of left recursion.  A second DCG pretty-prints an AST
+% with only the parentheses required to preserve its structure, making the
+% example useful in both directions.
+%% goal: dcg_expression_example(X0, X1)
+
+% expression//1: + and - are the lowest-precedence operators.
+expression(AST) -->
+  term(First),
+  additive_tail(First, AST).
+
+additive_tail(Left, AST) -->
+  ['+'],
+  term(Right),
+  { Next = add(Left, Right) },
+  additive_tail(Next, AST).
+additive_tail(Left, AST) -->
+  ['-'],
+  term(Right),
+  { Next = sub(Left, Right) },
+  additive_tail(Next, AST).
+additive_tail(AST, AST) --> [].
+
+% term//1: * and / bind more tightly than + and -.
+term(AST) -->
+  unary(First),
+  multiplicative_tail(First, AST).
+
+multiplicative_tail(Left, AST) -->
+  ['*'],
+  unary(Right),
+  { Next = mul(Left, Right) },
+  multiplicative_tail(Next, AST).
+multiplicative_tail(Left, AST) -->
+  ['/'],
+  unary(Right),
+  { Next = div(Left, Right) },
+  multiplicative_tail(Next, AST).
+multiplicative_tail(AST, AST) --> [].
+
+% Unary minus nests, so --x is represented as neg(neg(var(x))).
+unary(neg(AST)) --> ['-'], unary(AST).
+unary(AST) --> primary(AST).
+
+primary(lit(Number)) -->
+  [Number],
+  { number(Number) }.
+primary(var(Name)) -->
+  [Name],
+  { variable_name(Name) }.
+primary(AST) --> ['('], expression(AST), [')'].
+
+variable_name(x).
+variable_name(y).
+variable_name(z).
+
+% A small evaluator for the AST produced by the grammar.
+evaluate(lit(Number), _, Number).
+evaluate(var(Name), Environment, Value) :-
+  lookup(Name, Environment, Value).
+evaluate(neg(AST), Environment, Value) :-
+  evaluate(AST, Environment, Inner),
+  Value is -Inner.
+evaluate(add(Left, Right), Environment, Value) :-
+  evaluate(Left, Environment, L),
+  evaluate(Right, Environment, R),
+  Value is L + R.
+evaluate(sub(Left, Right), Environment, Value) :-
+  evaluate(Left, Environment, L),
+  evaluate(Right, Environment, R),
+  Value is L - R.
+evaluate(mul(Left, Right), Environment, Value) :-
+  evaluate(Left, Environment, L),
+  evaluate(Right, Environment, R),
+  Value is L * R.
+evaluate(div(Left, Right), Environment, Value) :-
+  evaluate(Left, Environment, L),
+  evaluate(Right, Environment, R),
+  Value is L / R.
+
+lookup(Name, [Name-Value|_], Value).
+lookup(Name, [_|Rest], Value) :-
+  lookup(Name, Rest, Value).
+
+% Precedence-aware generation.  The right operand is emitted at a stricter
+% minimum precedence than the left operand, preserving left associativity.
+emit_expression(AST) --> emit(AST, 0).
+
+emit(AST, Minimum) -->
+  { precedence(AST, Precedence),
+    parenthesize(Precedence, Minimum, Wrap) },
+  emit_wrapped(Wrap, AST).
+
+emit_wrapped(yes, AST) --> ['('], emit_node(AST), [')'].
+emit_wrapped(no, AST) --> emit_node(AST).
+
+emit_node(lit(Number)) --> [Number].
+emit_node(var(Name)) --> [Name].
+emit_node(neg(AST)) --> ['-'], emit(AST, 30).
+emit_node(add(Left, Right)) -->
+  emit(Left, 10), ['+'], emit(Right, 11).
+emit_node(sub(Left, Right)) -->
+  emit(Left, 10), ['-'], emit(Right, 11).
+emit_node(mul(Left, Right)) -->
+  emit(Left, 20), ['*'], emit(Right, 21).
+emit_node(div(Left, Right)) -->
+  emit(Left, 20), ['/'], emit(Right, 21).
+
+precedence(add(_, _), 10).
+precedence(sub(_, _), 10).
+precedence(mul(_, _), 20).
+precedence(div(_, _), 20).
+precedence(neg(_), 30).
+precedence(lit(_), 40).
+precedence(var(_), 40).
+
+parenthesize(Precedence, Minimum, yes) :- Precedence < Minimum.
+parenthesize(Precedence, Minimum, no) :- Precedence >= Minimum.
+
+% Parse a mixed-precedence expression.
+dcg_expression_example(parsed, AST) :-
+  phrase(expression(AST),
+         [2, '+', 3, '*', '(', 4, '-', 1, ')']).
+
+% Evaluate a parsed expression with variables.
+dcg_expression_example(evaluated, Value) :-
+  phrase(expression(AST), [x, '*', '(', y, '+', 2, ')', '-', z]),
+  evaluate(AST, [x-4, y-3, z-1], Value).
+
+% Generate the minimal parentheses needed to preserve a right-nested
+% subtraction tree, then parse the generated tokens back to the same AST.
+dcg_expression_example(round_trip, Tokens) :-
+  AST = sub(lit(20), sub(lit(5), lit(3))),
+  phrase(emit_expression(AST), Tokens),
+  phrase(expression(AST), Tokens).
+
+% phrase/3 lets a larger language parse an expression prefix and keep the rest.
+dcg_expression_example(remainder, Rest) :-
+  phrase(expression(mul(var(x), lit(2))),
+         [x, '*', 2, then, stop], Rest).
+
+% Missing closing parentheses are rejected.
+dcg_expression_example(rejected, malformed_parentheses) :-
+  \+ phrase(expression(_), [2, '*', '(', 3, '+', 4]).

package/examples/output/dcg-expression-language.pl

@@ -0,0 +1,5 @@
+dcg_expression_example(parsed, add(lit(2), mul(lit(3), sub(lit(4), lit(1))))).
+dcg_expression_example(evaluated, 19).
+dcg_expression_example(round_trip, [20, -, '(', 5, -, 3, ')']).
+dcg_expression_example(remainder, [then, stop]).
+dcg_expression_example(rejected, malformed_parentheses).

package/package.json

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

package/playground.html

@@ -481,6 +481,7 @@
           "critical-path-schedule",
           "cyclic-path",
           "dcg-command-parser",
+          "dcg-expression-language",
           "d3-group",
           "dairy-energy-balance",
           "data-negotiation",

package/src/solver.js

@@ -513,6 +513,23 @@ export class Solver {
           break;
         }
 
+        const betweenIterator = bundledBetweenIterator(this, group, goal, env);
+        if (betweenIterator != null) {
+          const firstResult = betweenIterator.next();
+          if (firstResult.done) break;
+          stack.push({
+            kind: 'resumeBuiltin',
+            iterator: betweenIterator,
+            goals: rest,
+            depth: depth + 1,
+            active,
+          });
+          goals = rest;
+          env = firstResult.value;
+          depth++;
+          continue;
+        }
+
         const memberIterator = bundledMemberIterator(this, group, goal, env);
         if (memberIterator != null) {
           const firstResult = memberIterator.next();
@@ -1216,6 +1233,53 @@ function pushWfsAnswerFrames(stack, model, group, goal, rest, env, depth, active
   }
 }
 
+function bundledBetweenIterator(solver, group, goal, env) {
+  if (solver.registry.eyePrologLibrary !== true ||
+      group.module !== 'prologue' || group.name !== 'between' || group.arity !== 3 ||
+      group.bundledLibrary !== true || group.clauses.length !== 1) {
+    return null;
+  }
+
+  // The portable Prologue definition is intentionally kept as the semantic
+  // source of between/3. Its recursive helper, however, carries the output
+  // variable through one fresh clause instance per integer. With persistent
+  // environments that builds a growing variable-alias chain, so dereferencing
+  // the generated value in the caller repeatedly revisits all earlier frames.
+  // Enumerate the canonical bundled relation directly while leaving user
+  // definitions and non-EyeProlog registries on the ordinary Prolog path.
+  return bundledBetweenSolutions(solver, goal, env);
+}
+
+function requireBetweenInteger(term, env) {
+  const value = deref(term, env);
+  if (value.type === VAR) throw new PrologError('instantiation_error');
+  if (value.type !== NUMBER || !isDecimalInteger(value.name)) {
+    throw new PrologError('type_error(integer)', value);
+  }
+  return BigInt(value.name);
+}
+
+function* bundledBetweenSolutions(solver, goal, env) {
+  const lower = requireBetweenInteger(goal.args[0], env);
+  const upper = requireBetweenInteger(goal.args[1], env);
+  const requested = deref(goal.args[2], env);
+
+  if (requested.type !== VAR) {
+    if (requested.type !== NUMBER || !isDecimalInteger(requested.name)) {
+      throw new PrologError('type_error(integer)', requested);
+    }
+    const value = BigInt(requested.name);
+    if (value >= lower && value <= upper) yield env;
+    return;
+  }
+
+  for (let value = lower; value <= upper; value++) {
+    const next = env.clone();
+    solver.stats.unify_calls++;
+    if (unify(goal.args[2], numberTerm(value), next)) yield next;
+  }
+}
+
 function bundledMemberIterator(solver, group, goal, env) {
   if (solver.registry.eyePrologLibrary !== true ||
       !['lists', 'prologue'].includes(group.module) || group.name !== 'member' || group.arity !== 2 ||

package/test/run-regression.mjs

@@ -2398,6 +2398,22 @@ child.stdin.write(\`consult(${consultedAtom}).\\n\`);
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'between/3 generated values avoid recursive environment chains (issue #52)',
+      run: () => {
+        const goalText = 'between(1, 1024, X), X < 0';
+        const program = Program.parse('', { autoloadGoals: [goalText] });
+        const solver = new Solver(program, { registry: getEyePrologRegistry() });
+        const goal = parseGoalText(goalText, {
+          operatorDefinitions: [...solver.program.operators.values()],
+        });
+        let answers = 0;
+        for (const _env of solver.solve([goal], new Env(), 0)) answers++;
+        assertEqual(answers, 0, 'positive generated values fail X < 0');
+        assertEqual(solver.stats.unify_calls, 1024, 'one output unification per generated integer');
+        assertEqual(solver.stats.max_depth <= 4, true, 'generation stays at bounded solver depth');
+      },
+    },
     {
       name: 'library(lists) length/2 stays relational and call_nth/2 autoloads (issue #28)',
       run: () => {

package/the-art-of-eyeprolog.md

@@ -5632,6 +5632,62 @@ that argument. A variable body raises `instantiation_error`; a non-callable
 body raises `type_error(callable)`. EyeProlog performs terminal-sequence checks
 and reports the portable ISO `type_error(list)` error term.
 
+#### A bidirectional expression grammar
+
+DCGs become more useful when the grammar produces a structured term rather than
+merely accepting a token list.  The checked
+[`dcg-expression-language.pl`](https://github.com/eyereasoner/eyeprolog/blob/main/examples/dcg-expression-language.pl)
+example implements a small arithmetic language in both directions.  Its parser
+respects precedence and left associativity while constructing an abstract syntax
+tree:
+
+```text
+expression(AST) -->
+  term(First),
+  additive_tail(First, AST).
+
+additive_tail(Left, AST) -->
+  ['+'], term(Right),
+  { Next = add(Left, Right) },
+  additive_tail(Next, AST).
+additive_tail(AST, AST) --> [].
+```
+
+The accumulator removes left recursion without moving parsing into JavaScript.
+A second DCG walks the AST in the other direction and emits only the parentheses
+needed to preserve its structure.  The example therefore exercises parsing,
+semantic actions, nonterminal-to-nonterminal state hand-off, generation,
+backtracking, `phrase/3` remainder handling, and AST-to-token-to-AST
+round-tripping.  The checked answers are in
+[`examples/output/dcg-expression-language.pl`](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/dcg-expression-language.pl).
+
+#### Deep sequence hand-off
+
+`library(iso_ext)` provides the common `...//0` helper, which describes an
+arbitrary number of input elements.  It is not part of ISO Part 3, but it is a
+useful interoperability and stress-test relation.  A compact hand-off test is:
+
+```text
+a --> ..., epsilon.
+epsilon --> [].
+```
+
+Here the remaining sequence is repeatedly passed from `...//0` to another
+nonterminal.  For a finite compact list, EyeProlog can scan the arbitrary
+sequence iteratively instead of consuming one ordinary solver depth level per
+list cell.  If the continuation is structurally proven to be a zero-width
+identity grammar such as `epsilon//0`, the hand-off can be continued without
+constructing a fresh general clause-resolution frame at every suffix.  The list
+spine is still traversed; this is a control/allocation optimization rather than
+an O(1) semantic shortcut.
+
+The optimization is deliberately narrow.  `phrase(..., Sequence, Rest)` still
+enumerates the valid remainders, open or non-compact inputs retain ordinary
+relational behavior, and grammars that can consume or constrain the remainder
+are not treated as identity continuations.  `time/1` can be used in normal mode
+to measure such runs; its inference counter records solver-level inferences and
+does not count every internal step of an optimized scanner.
+
 Part 3 leaves `\+//1` and standalone `->//2` implementation dependent.
 EyeProlog uses non-consuming negation (`\+ Body` tests from the current state)
 and threads the state produced by the condition into the then-grammar.
@@ -6895,7 +6951,7 @@ Review questions:
 </figure>
 
 The [examples directory](https://github.com/eyereasoner/eyeprolog/tree/main/examples/) is the book's executable companion. The
-top-level directory contains **211 self-contained runnable programs**. Every
+top-level directory contains **212 self-contained runnable programs**. Every
 source program has an exact answer file under
 [examples/output](https://github.com/eyereasoner/eyeprolog/tree/main/examples/output/), and **61 selected programs** have a checked
 explanation under [examples/proof](https://github.com/eyereasoner/eyeprolog/tree/main/examples/proof/). The thematic tables below link every top-level program and open the program
@@ -6953,6 +7009,7 @@ mode at a time.
 | [Atomic conversion](https://github.com/eyereasoner/eyeprolog/blob/main/examples/iso-atomic-conversion.pl) | Atom splitting, character atoms, Unicode codes, and numeric parsing. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/iso-atomic-conversion.pl) |
 | [Control and errors](https://github.com/eyereasoner/eyeprolog/blob/main/examples/iso-control-and-errors.pl) | `call/1`, `once/1`, cut, if-then-else, `throw/1`, and `catch/3`. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/iso-control-and-errors.pl) |
 | [DCG command parser](https://github.com/eyereasoner/eyeprolog/blob/main/examples/dcg-command-parser.pl) | A Part 3 grammar parses token lists into application terms, generates tokens, preserves a remainder, and rejects malformed input. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/dcg-command-parser.pl) |
+| [DCG expression language](https://github.com/eyereasoner/eyeprolog/blob/main/examples/dcg-expression-language.pl) | A precedence-aware bidirectional grammar builds arithmetic ASTs, evaluates variable expressions, regenerates minimally parenthesized tokens, round-trips syntax, and preserves a remainder. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/dcg-expression-language.pl) |
 | [Dynamic database](https://github.com/eyereasoner/eyeprolog/blob/main/examples/iso-dynamic-database.pl) | Initialization and ordered updates to a declared dynamic procedure. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/iso-dynamic-database.pl) · [proof](https://github.com/eyereasoner/eyeprolog/blob/main/examples/proof/iso-dynamic-database.pl) |
 | [Grouped solutions](https://github.com/eyereasoner/eyeprolog/blob/main/examples/iso-grouped-solutions.pl) | `findall/3`, `bagof/3`, `setof/3`, existential qualification, and `clause/2`. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/iso-grouped-solutions.pl) |
 | [Integer arithmetic](https://github.com/eyereasoner/eyeprolog/blob/main/examples/iso-integer-arithmetic.pl) | Integer quotient/remainder choices plus bit operations. | [answers](https://github.com/eyereasoner/eyeprolog/blob/main/examples/output/iso-integer-arithmetic.pl) |
@@ -7297,7 +7354,7 @@ hand.
 
 #### Running and extending the corpus
 
-Run all 211 normal answer goldens and the 61 selected proof goldens with:
+Run all 212 normal answer goldens and the 61 selected proof goldens with:
 
 ```sh
 npm run test:examples
@@ -7361,7 +7418,7 @@ The complete suite must pass before release. The file-based conformance corpus
 contains 791 cases, including 386 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 211 normal
+Separate exact-output suites check 212 normal
 examples and 61 proof examples; all extracted book programs are parsed and
 their declared goals are executed. The eight-case
 playground contract suite imports the production worker, sends real reasoning

package/why-eyeprolog.md

@@ -60,6 +60,14 @@ positive Datalog closures with a shared relation-wide table, but the admission
 heuristics are implementation details. Programs should rely on the documented
 semantics and finiteness conditions, not on a particular internal threshold.
 
+DCGs follow the same rule.  Their meaning remains the ISO Part 3 difference-list
+model, while finite sequence scans and proven zero-width hand-offs may use
+lighter internal control paths so deep grammars do not pay one general solver
+frame per token.  Relational remainder-producing modes are preserved.  The
+checked `examples/dcg-expression-language.pl` program shows the declarative side
+of that design: one grammar builds precedence-aware syntax trees and another
+generates minimally parenthesized token sequences back from them.
+
 ## Why proofs?
 
 An answer says that a goal succeeded. A proof records one successful route