openscad-cpp-evaluator 0.8.1__tar.gz → 0.9.1__tar.gz

{openscad_cpp_evaluator-0.8.1 → openscad_cpp_evaluator-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_cpp_evaluator
-Version: 0.8.1
+Version: 0.9.1
 Summary: C++ OpenSCAD evaluator with Python bindings
 Author: NeuSCAD Contributors
 License-Expression: MIT

{openscad_cpp_evaluator-0.8.1 → openscad_cpp_evaluator-0.9.1}/include/openscad_cpp_evaluator/bytecode.hpp

@@ -131,16 +131,33 @@ enum class Op {
     // chunk actually running Op::MakeClosure), and constructs
     // Closure{node, capturedTrail} -- reusing Closure::capturedLet (value.hpp)
     // and callCtxFor's existing capturedLet-rooting (user_calls.cpp)
-    // UNCHANGED: invoking this closure later (always via the interpreter,
-    // see ClosureSite's own doc comment for why its body is never itself
-    // compiled) works exactly like any interpreter-created escaping closure
-    // always has, no new invocation-side code needed at all. Replaces
+    // UNCHANGED: invoking this closure later works through the exact same
+    // machinery any interpreter-created escaping closure always has, no new
+    // invocation-side code needed at all (its own body may itself run
+    // compiled too now, see Evaluator::lookupCompiledLiteralChunk). Replaces
     // Op::PushConst's frozen `Closure{&n, nullptr}` specifically for a
     // literal whose (transitively merged) capture set is non-empty; a
     // literal that closes over nothing at all -- even transitively -- still
     // takes the cheaper PushConst path, unchanged.
     MakeClosure,
 
+    // Letrec support for TWO OR MORE sibling `let`-bound closures that
+    // reference each other by name (fnliterals.scad-style mutual
+    // recursion, e.g. isEven/isOdd each calling the other) -- see the
+    // LetOp compile case's own doc comment (bytecode_compiler.cpp) for why
+    // a forward reference (an EARLIER closure referencing a LATER sibling
+    // that doesn't exist yet at the point the earlier one is constructed)
+    // can't be resolved by Op::MakeClosure itself the way a self-reference
+    // is: there's nothing to read OR self-patch into, since the later
+    // sibling hasn't even been created yet. a = consumer's own local slot
+    // (already holds a MakeClosure-created closure, via a preceding
+    // Op::StoreLocal), b = name pool index (the captured name, inside the
+    // consumer's own capturedTrail, that's finally ready), c = the local
+    // slot the just-constructed sibling was JUST stored into (also via a
+    // preceding Op::StoreLocal) -- patches slots[a]'s own capturedTrail
+    // with slots[c], keyed by name b.
+    PatchClosureCapture,
+
     // A call whose callee isn't statically resolvable to a builtin or a
     // named FunctionDeclaration (see CallFn) -- the callee expression is
     // compiled to push its own Value first, THEN each argument (so at

{openscad_cpp_evaluator-0.8.1 → openscad_cpp_evaluator-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "openscad_cpp_evaluator"
-version = "0.8.1"
+version = "0.9.1"
 description = "C++ OpenSCAD evaluator with Python bindings"
 readme = "README.md"
 requires-python = ">=3.12"

{openscad_cpp_evaluator-0.8.1 → openscad_cpp_evaluator-0.9.1}/src/bytecode_compiler.cpp

@@ -10,6 +10,7 @@
 
 #include <functional>
 #include <unordered_map>
+#include <unordered_set>
 
 namespace oscadeval {
 
@@ -68,27 +69,31 @@ void bubbleEscapingCaptures(const CompiledChunk::ClosureSite& site, const oscad:
 // True if any instruction in `chunk`'s own body/defaults is Op::LoadFree --
 // i.e. an identifier that resolved to neither a local, a statically-known
 // enclosing upvalue, nor a dyn ($-prefixed) name at compile time (see
-// compileExpr's own Identifier case). The direct `let(a = function(...)
-// ... a(...) ...)` self-reference (reduce()/accumulate()/while()'s own
-// idiom) no longer hits this -- see the LetOp case's own letrec pre-declare,
-// below -- but anything the pre-declare doesn't cover still does: `a`
-// wrapped in a ternary/let/anything other than a bare FunctionLiteral RHS
-// (`let(a = cond ? function(...) ...a(...)... : function(...) ...)`),
-// mutual recursion between two sibling let-bound closures (each references
-// the OTHER, which isn't declared yet when compiling the first), or any
-// other free variable this phase simply can't resolve statically. For any
-// of those, Evaluator::evalIdentifier's own ctx.scope->lookupVariable()
-// fallback re-evaluates the let-binding's RHS FRESH on every single call,
-// producing a new Closure whose capturedLet is THIS invocation's own
-// ctx.let_ (see expr_eval.cpp's FunctionLiteral case) rather than a stable
-// snapshot -- registering such a chunk for compiled invocation would still
-// be functionally correct, but each recursive call's own
-// capturedLet->openChild() then nests ONE level deeper than the last
-// (confirmed empirically: an O(n) list reduce() degrading to O(n^2) once
-// compiled, before the letrec pre-declare existed), since nothing about
-// that repeated fresh-derivation ever re-roots the trail. Excluding a
-// LoadFree-containing chunk from registration leaves it running
-// interpreted exactly as before -- correct, if not optimized.
+// compileExpr's own Identifier case). A `let(a = function(...) ...
+// a(...) ...)` self-reference, mutual recursion between two-or-more
+// sibling `let`-bound closures (fnliterals.scad-style isEven/isOdd, each
+// calling the other), and either of those wrapped in a ternary (`let(a =
+// cond ? function(...) ...a(...)... : function(...) ...)`, every reachable
+// branch unambiguously a closure) no longer hit this -- see the LetOp
+// case's own letrec pre-declare, below, and collectLetrecCandidateLiterals'
+// own doc comment for exactly which RHS shapes qualify. Anything the
+// pre-declare doesn't cover still does: a reference buried in something
+// other than a direct-or-ternary closure RHS (`let(a = some_call() ?
+// function(...) ...a(...)... : function(...) ...)`, a non-ternary
+// conditional shape, etc.), or any other free variable this phase simply
+// can't resolve statically. For any of those, Evaluator::evalIdentifier's
+// own ctx.scope->lookupVariable() fallback re-evaluates the let-binding's
+// RHS FRESH on every single call, producing a new Closure whose
+// capturedLet is THIS invocation's own ctx.let_ (see expr_eval.cpp's
+// FunctionLiteral case) rather than a stable snapshot -- registering such
+// a chunk for compiled invocation would still be functionally correct,
+// but each recursive call's own capturedLet->openChild() then nests ONE
+// level deeper than the last (confirmed empirically: an O(n) list
+// reduce() degrading to O(n^2) once compiled, before the letrec pre-
+// declare existed), since nothing about that repeated fresh-derivation
+// ever re-roots the trail. Excluding a LoadFree-containing chunk from
+// registration leaves it running interpreted exactly as before --
+// correct, if not optimized.
 bool containsLoadFree(const std::vector<Instruction>& code) {
     for (const Instruction& ins : code) {
         if (ins.op == Op::LoadFree) return true;
@@ -104,6 +109,38 @@ bool containsLoadFree(const CompiledChunk& chunk) {
     return false;
 }
 
+// Recursively collects every FunctionLiteral `expr` could actually
+// evaluate to at runtime -- a bare literal, or a ternary (or nested
+// ternaries) whose branches ALL recursively qualify, e.g. `cond ?
+// function(...) ...a(...)... : function(...) ...` (the ternary-wrapped
+// self/mutual-reference case the direct-RHS-only letrec pre-declare,
+// below, doesn't reach on its own). Returns std::nullopt -- not just an
+// empty vector -- the moment ANY reachable branch ISN'T reliably a
+// closure (a plain value, a call, anything else): letrec pre-declaration
+// only makes sense when EVERY runtime path through `expr` really does
+// produce a fresh closure that might reference the let-binding's own
+// name, never a mix. A CommentedExpr wrapper is transparent, matching
+// compileExpr's own handling of it everywhere else.
+std::optional<std::vector<const oscad::FunctionLiteral*>> collectLetrecCandidateLiterals(const oscad::ASTNode& expr) {
+    using oscad::NodeKind;
+    if (expr.kind() == NodeKind::CommentedExpr) {
+        return collectLetrecCandidateLiterals(*static_cast<const oscad::CommentedExpr&>(expr).expr);
+    }
+    if (expr.kind() == NodeKind::FunctionLiteral) {
+        return std::vector<const oscad::FunctionLiteral*>{static_cast<const oscad::FunctionLiteral*>(&expr)};
+    }
+    if (expr.kind() == NodeKind::TernaryOp) {
+        auto& t = static_cast<const oscad::TernaryOp&>(expr);
+        auto trueLits = collectLetrecCandidateLiterals(*t.trueExpr);
+        if (!trueLits) return std::nullopt;
+        auto falseLits = collectLetrecCandidateLiterals(*t.falseExpr);
+        if (!falseLits) return std::nullopt;
+        trueLits->insert(trueLits->end(), falseLits->begin(), falseLits->end());
+        return trueLits;
+    }
+    return std::nullopt;
+}
+
 // Compile-time name -> slot resolution, mirroring the LetOp/nested-scope
 // shadowing rules callCtx()/letChildCtx() apply at runtime: one frame per
 // LetOp (pushed/popped around its own assignments+body), innermost frame
@@ -566,35 +603,96 @@ public:
                 size_t placeholderIdx = out.size();
                 out.push_back({Op::OpenLocalScope, 0, 0, nullptr});
                 int slotStart = nextSlot_;
-                for (const auto& assign : n.assignments) {
+                // Letrec pre-pass: every assignment whose RHS is GUARANTEED
+                // to evaluate to a closure -- a direct `name =
+                // function(...) ...`, or `name = cond ? function(...) ... :
+                // function(...) ...` (or nested ternaries of the same
+                // shape) -- gets its own slot declared up front, before ANY
+                // of them are compiled -- not just so a closure can
+                // reference itself (see the self-reference handling
+                // below), but so an EARLIER one can also reference a LATER
+                // sibling (mutual recursion, e.g. fnliterals.scad-style
+                // isEven/isOdd calling each other). `letrecSlot[i]` stays
+                // -1 for anything else, which keeps the existing after-the-
+                // fact declareLocal path below completely unchanged
+                // (`let(x = x + 1)` must still see the OUTER x, not a
+                // fresh, not-yet-assigned local shadowing it -- only an
+                // RHS that's UNAMBIGUOUSLY always a closure has "see
+                // myself/a sibling" as a sensible reading at all; see
+                // collectLetrecCandidateLiterals' own doc comment, above,
+                // for why a mixed/uncertain RHS shape doesn't qualify).
+                // `letrecCandidates[i]` is every FunctionLiteral node `i`'s
+                // own RHS could actually construct at runtime -- more than
+                // one for a ternary -- each independently checked for a
+                // self/sibling reference below, since either one might be
+                // the value `name` ends up holding.
+                std::vector<int> letrecSlot(n.assignments.size(), -1);
+                std::vector<std::vector<const oscad::FunctionLiteral*>> letrecCandidates(n.assignments.size());
+                std::unordered_set<int> pendingLetrecSlots;
+                for (size_t i = 0; i < n.assignments.size(); ++i) {
+                    const auto& assign = n.assignments[i];
+                    const std::string& name = assign->name->name;
+                    if (name.empty() || name[0] == '$') continue;
+                    if (auto candidates = collectLetrecCandidateLiterals(*assign->expr)) {
+                        letrecSlot[i] = declareLocal(scope, name);
+                        letrecCandidates[i] = std::move(*candidates);
+                        pendingLetrecSlots.insert(letrecSlot[i]);
+                    }
+                }
+                // consumerSlot/name pairs an EARLIER closure's own
+                // Op::MakeClosure left unresolved because they targeted a
+                // sibling that didn't exist yet at that point -- resolved
+                // (an Op::PatchClosureCapture emitted) the moment that
+                // sibling's own StoreLocal runs, below.
+                std::unordered_map<int, std::vector<std::pair<int, std::string>>> pendingWaiters;
+                for (size_t i = 0; i < n.assignments.size(); ++i) {
+                    const auto& assign = n.assignments[i];
                     const std::string& name = assign->name->name;
-                    // A DIRECT `name = function(...) ...` RHS -- the
-                    // reduce()/accumulate()/while() idiom, and count_to()-
-                    // style helpers generally -- gets its own slot declared
-                    // BEFORE compiling that RHS (letrec-style), so a
-                    // self-reference inside the closure's own body resolves
-                    // as a genuine upvalue (Op::LoadUpvalue) instead of
-                    // falling through to Op::LoadFree. Every other RHS shape
-                    // keeps the existing after-the-fact declareLocal below
-                    // unchanged (`let(x = x + 1)` must still see the OUTER
-                    // x, not a fresh, not-yet-assigned local shadowing it --
-                    // only a function-literal RHS has "see myself" as a
-                    // sensible reading at all). See Op::MakeClosure's own
-                    // runtime handler (bytecode_vm.cpp) for how the
-                    // resulting self-capture is actually resolved -- the
-                    // closure being created doesn't exist yet at the moment
-                    // its own captures are normally snapshotted, so this
-                    // one is deferred and patched in after construction
-                    // instead of read eagerly like every other capture.
-                    const bool selfBinding = !name.empty() && name[0] != '$' &&
-                                              assign->expr->kind() == oscad::NodeKind::FunctionLiteral;
-                    int preDeclaredSlot = -1;
-                    if (selfBinding) preDeclaredSlot = declareLocal(scope, name);
+                    const int preDeclaredSlot = letrecSlot[i];
+                    const bool selfBinding = preDeclaredSlot >= 0;
                     compileExpr(*assign->expr, out, scope); // RHS is never tail
-                    if (selfBinding && out.back().op == Op::MakeClosure) {
-                        CompiledChunk::ClosureSite& site = chunk_.closureSites[static_cast<size_t>(out.back().a)];
-                        for (auto& cap : site.captures) {
-                            if (cap.targetDecl == selfDecl_ && cap.slot == preDeclaredSlot) cap.isSelfReference = true;
+                    for (const oscad::FunctionLiteral* candidate : letrecCandidates[i]) {
+                        CompiledChunk::ClosureSite* site = nullptr;
+                        for (auto& s : chunk_.closureSites) {
+                            if (s.node == candidate) {
+                                site = &s;
+                                break;
+                            }
+                        }
+                        // No entry at all means this particular candidate
+                        // (e.g. one branch of a ternary) never referenced
+                        // itself/a sibling/anything else -- zero captures,
+                        // still the cheaper Op::PushConst path, nothing
+                        // here to patch.
+                        if (!site) continue;
+                        auto& captures = site->captures;
+                        for (auto it = captures.begin(); it != captures.end();) {
+                            if (it->targetDecl != selfDecl_ || !pendingLetrecSlots.count(it->slot)) {
+                                ++it;
+                                continue;
+                            }
+                            if (it->slot == preDeclaredSlot) {
+                                // See Op::MakeClosure's own runtime handler
+                                // (bytecode_vm.cpp): the closure being
+                                // created doesn't exist yet at the moment
+                                // its own captures are normally snapshotted,
+                                // so this one is deferred and patched in
+                                // right after construction instead of read
+                                // eagerly like every other capture.
+                                it->isSelfReference = true;
+                                ++it;
+                            } else {
+                                // Forward reference to a sibling that hasn't
+                                // been constructed AT ALL yet -- unlike the
+                                // self-reference case above, there's nothing
+                                // to read OR self-patch into here. Left out
+                                // of `captures` entirely (nothing for
+                                // Op::MakeClosure to even attempt) and
+                                // deferred to a real Op::PatchClosureCapture
+                                // once that sibling's own StoreLocal runs.
+                                pendingWaiters[it->slot].emplace_back(preDeclaredSlot, it->name);
+                                it = captures.erase(it);
+                            }
                         }
                     }
                     if (!name.empty() && name[0] == '$') {
@@ -602,6 +700,17 @@ public:
                     } else {
                         int slot = selfBinding ? preDeclaredSlot : declareLocal(scope, name);
                         out.push_back({Op::StoreLocal, slot, 0, &assign->position()});
+                        if (selfBinding) {
+                            pendingLetrecSlots.erase(slot);
+                            auto waitersIt = pendingWaiters.find(slot);
+                            if (waitersIt != pendingWaiters.end()) {
+                                for (const auto& [consumerSlot, capName] : waitersIt->second) {
+                                    out.push_back({Op::PatchClosureCapture, consumerSlot, internName(capName),
+                                                    &assign->position(), nullptr, slot});
+                                }
+                                pendingWaiters.erase(waitersIt);
+                            }
+                        }
                     }
                 }
                 out[placeholderIdx].a = slotStart;

{openscad_cpp_evaluator-0.8.1 → openscad_cpp_evaluator-0.9.1}/src/bytecode_vm.cpp

@@ -203,6 +203,29 @@ Value runChunk(Evaluator& ev, const CompiledChunk& chunk, const std::vector<Inst
                 ++pc;
                 break;
             }
+            case Op::PatchClosureCapture: {
+                // Mutual-recursion support (see the LetOp compile case's
+                // own doc comment, bytecode_compiler.cpp): `slots[ins.a]`
+                // (the consumer, e.g. isEven) already holds a real
+                // MakeClosure-created closure whose own capturedTrail is
+                // missing this ONE entry -- it was left out entirely at
+                // compile time because the sibling it names (e.g. isOdd)
+                // hadn't been constructed yet. `slots[ins.c]` (that
+                // sibling's own slot) does now, since this instruction only
+                // ever runs immediately after that sibling's own
+                // Op::StoreLocal. Mutates the SAME shared TrailView the
+                // consumer's own capturedLet already points at -- visible
+                // to it exactly like every other capture, no different
+                // from Op::MakeClosure's own self-reference patch, above.
+                const Value& consumerVal = slots[static_cast<size_t>(ins.a)];
+                if (const auto* closurePtr = std::get_if<ClosurePtr>(&consumerVal); closurePtr && *closurePtr) {
+                    if (auto trail = capturedLetTrail(**closurePtr)) {
+                        trail->set(chunk.names[static_cast<size_t>(ins.b)], slots[static_cast<size_t>(ins.c)]);
+                    }
+                }
+                ++pc;
+                break;
+            }
             case Op::Range: {
                 Value step = std::move(stack.back());
                 stack.pop_back();

{openscad_cpp_evaluator-0.8.1 → openscad_cpp_evaluator-0.9.1}/tests/test_bytecode_compiler.cpp

@@ -659,6 +659,82 @@ TEST(BytecodeCompiler, PlainLetSelfReferenceStillSeesTheOuterBindingNotItself) {
     EXPECT_EQ(runCapturingEcho("x = 100;\nfunction f() = let(x = x + 1) x;\necho(f());"), "ECHO: 101");
 }
 
+TEST(BytecodeCompiler, MutualRecursionBetweenSiblingLetBoundClosuresResolvesCorrectly) {
+    ScopedVm vm(true);
+    // fnliterals.scad-style isEven()/isOdd(): TWO sibling closures in the
+    // SAME let(), each calling the OTHER by name. `isEven` (compiled
+    // FIRST) references `isOdd`, which doesn't exist at all yet at that
+    // point -- unlike a self-reference, there's nothing to read OR self-
+    // patch into (see Op::PatchClosureCapture's own doc comment,
+    // bytecode.hpp): resolved instead by a real patch instruction emitted
+    // right after `isOdd`'s own StoreLocal, once it actually exists.
+    // 3 stops, not one per logical call (isEvenTest's own entry, plus one
+    // per level of isEven(6)->isOdd(5)->isEven(4)->...->isEven(0)):
+    // isEven<->isOdd calling each other in tail position is exactly what
+    // the tail-call trampoline collapses into ONE evalUserFunctionCore
+    // invocation for the WHOLE chain (see runCompiledFunctionTrampoline,
+    // bytecode_vm.cpp) -- its own unconditional body-entry checkDebug()
+    // fires once for that entire loop, not once per hop. isEvenTest's own
+    // entry (1) + that one trampoline loop (1) + the top-level echo()
+    // statement's own stop (module code is never compiled) = 3.
+    const int stops = countDebugHookStops(
+        "function isEvenTest(n) = let(isEven = function(k) k==0 ? true : isOdd(k-1), isOdd = function(k) "
+        "k==0 ? false : isEven(k-1)) isEven(n);\n"
+        "echo(isEvenTest(6));",
+        std::unordered_map<std::string, std::set<int>>{});
+    EXPECT_EQ(stops, 3);
+    EXPECT_EQ(runCapturingEcho("function isEvenTest(n) = let(isEven = function(k) k==0 ? true : isOdd(k-1), "
+                                "isOdd = function(k) k==0 ? false : isEven(k-1)) isEven(n);\n"
+                                "echo(isEvenTest(6));\necho(isEvenTest(7));"),
+              "ECHO: true\nECHO: false");
+}
+
+TEST(BytecodeCompiler, ThreeWaySiblingMutualRecursionResolvesCorrectly) {
+    ScopedVm vm(true);
+    // The patch mechanism isn't hardcoded to pairs -- a THIRD sibling
+    // (f3, itself forward-referencing f1, the FIRST one compiled) proves
+    // pendingWaiters/Op::PatchClosureCapture generalizes to an arbitrary
+    // cycle length, not just mutual (2-closure) recursion specifically.
+    EXPECT_EQ(runCapturingEcho("function test(n) = let(f1 = function(k) k==0 ? \"f1\" : f2(k-1), f2 = "
+                                "function(k) k==0 ? \"f2\" : f3(k-1), f3 = function(k) k==0 ? \"f3\" : "
+                                "f1(k-1)) f1(n);\n"
+                                "echo(test(9));\necho(test(10));\necho(test(11));"),
+              "ECHO: \"f1\"\nECHO: \"f2\"\nECHO: \"f3\"");
+}
+
+TEST(BytecodeCompiler, TernaryWrappedSelfReferenceResolvesAsUpvalue) {
+    ScopedVm vm(true);
+    // The letrec pre-declare's own eligibility check isn't limited to a
+    // bare `name = function(...) ...` RHS -- `cond ? function(...) ... :
+    // function(...) ...` (EVERY reachable branch is unambiguously a
+    // closure, see collectLetrecCandidateLiterals' own doc comment,
+    // bytecode_compiler.cpp) also pre-declares, and BOTH branches'
+    // FunctionLiteral nodes are independently found and marked afterward
+    // (a ternary can produce two structurally distinct closures, not just
+    // one). Deep, genuinely TAIL-recursive (`acc` accumulates on the way
+    // down, not after the recursive call returns -- see this file's own
+    // DeepSelfTailRecursionUnderVmDoesNotOverflowTheNativeStack, above, for
+    // why that distinction matters at this depth) to prove it actually
+    // runs compiled, not just correctly-but-slowly interpreted.
+    const std::string script =
+        "function make(n) = let(a = n > 0 ? function(k, acc) k<=0 ? acc : a(k-1, acc+n) : function(k, acc) acc) "
+        "a(200000, 0);\necho(make(1));";
+    EXPECT_EQ(runCapturingEcho(script), "ECHO: 200000");
+}
+
+TEST(BytecodeCompiler, TernaryWrappedMutualRecursionResolvesCorrectly) {
+    ScopedVm vm(true);
+    // Same ternary-wrapped-RHS eligibility as the self-reference case
+    // above, but for TWO siblings that reference each other -- both
+    // Op::PatchClosureCapture's forward-reference deferral and the
+    // ternary's own multi-candidate handling apply simultaneously.
+    const std::string script =
+        "function test(n) = let(isEven = n >= 0 ? function(k) k==0 ? true : isOdd(k-1) : function(k) undef, "
+        "isOdd = n >= 0 ? function(k) k==0 ? false : isEven(k-1) : function(k) undef) isEven(n);\n"
+        "echo(test(10));\necho(test(7));";
+    EXPECT_EQ(runCapturingEcho(script), "ECHO: true\nECHO: false");
+}
+
 TEST(BytecodeCompiler, ClosureWithDollarParameterStillBailsContainer) {
     ScopedVm vm(true);
     // Residual, deliberate limitation: a FunctionLiteral with its OWN