More Forth words: +LOOP/J/LEAVE, DOES>, RECURSE, PICK/ROLL/?DUP/MIN/MAX/<=/>=/<>

[softwarewrighter]

Problem

Follow-up to #2 (DO/LOOP family and friends). That issue added DO/LOOP/?DO/I/UNLOOP and CONSTANT/VARIABLE and BEGIN-style WHILE/REPEAT/AGAIN. The remaining words from #2's body are still missing — most are small one-liners once the loop and defining-word machinery is in place, but a few (DOES>, LEAVE) need additional kernel support.

Scope: both kernels (forth-in-forth and forth-on-forthish), unless otherwise noted. Preserve byte-identical output across the two where possible.

Words to add

1. DO-loop extensions (build on #2)

• +LOOP — like LOOP but increments the index by TOS instead of 1. Handles negative increments (down-counting) and the "cross the boundary" exit condition (standard Forth semantics: exit when the boundary is crossed in the direction of increment).
  • Needs a new (+LOOP) primitive in kernel.s. IMMEDIATE +LOOP parallels LOOP's compile-time behavior.
• J — push the outer loop's index (for nested DO/LOOP). With our RS layout [index limit caller-IP], J reads 9(r1) (index of the outer loop, below caller's IP). One new primitive.
• LEAVE — exit the current loop early. Requires compile-time bookkeeping: ?DO-style forward branches chained through LOOP so each LEAVE can be patched to the loop exit. Meaningful refactor of the IMMEDIATE DO/LOOP compiler.

2. DOES>

• DOES> — splice runtime behavior onto the most recent CREATE. Requires the inner interpreter to support re-entering a colon-def at a patched address. Classic approach: CREATE builds a word whose CFA is a trampoline that pushes the data-field address and jumps to DOCOL at a patched location.
• Would let CONSTANT/VARIABLE be expressed more elegantly: : CONSTANT CREATE , DOES> @ ; instead of the current ,DOCOL + ['] LIT templating.
• Non-trivial. Likely wants a small kernel primitive ((DOES>)) plus rework of CREATE's CFA format.

3. RECURSE

• RECURSE — IMMEDIATE; compiles a call to the currently-compiling definition. Needed because the new entry is SMUDGE/HIDDEN during its own compilation, so FIND won't see it. With LATEST pointing at the in-progress entry, implementation is a few lines: : RECURSE LATEST @ >CFA , ; IMMEDIATE (requires >CFA or equivalent).

4. Stack / comparison ergonomics (pure Forth, no new primitives)

• ?DUP — DUP if non-zero. : ?DUP DUP IF DUP THEN ;
• PICK — n PICK copies the n-th stack element to top. One-liner using SP@ (we have it): : PICK 1 + 3 * SP@ + @ ; — cell-size aware.
• ROLL — n ROLL rotates the n-th element to top. Trickier; needs a helper loop.
• MIN / MAX — : MIN 2DUP < IF DROP ELSE NIP THEN ; etc.
• <= / >= / <> — : <= > 0= ;, : >= < 0= ;, : <> = 0= ;
• 0<> — non-zero test. : 0<> 0= 0= ;

Expected location: core/lowlevel.fth for simple ones; core/midlevel.fth or a new core/ergo.fth tier for PICK/ROLL if they grow.

Non-goals

• Changes to the asm forth.s root kernel (separate users, separate compatibility concerns — same scope rule as forth-in-forth: add DO/LOOP, ?DO, WHILE/REPEAT, AGAIN, CONSTANT, VARIABLE #2).
• Double-cell (2@, 2!, D+) arithmetic.
• Floating point, strings, files.

Motivation

With the words from #2 in place, the core language feels almost complete, but a handful of idioms — especially LEAVE, ?DUP, MIN/MAX, <=/>=/<> — still require awkward workarounds in demos. DOES> is the big one: it unlocks a whole family of defining words (arrays, enumerations, records) that are currently inexpressible.

Split from #2 so that issue can stay closed; pick any subset of these off at a time.

Testing

Each new word gets a demo in examples/ and stack-leak coverage (DEPTH before/after). Match byte-identical behavior between forth-in-forth and forth-on-forthish kernels where applicable.

[softwarewrighter]

Partial progress in 1de7b28 — landed the easy half across the layered kernels (forth-in-forth, forth-on-forthish, forth-from-forth):

• ?DUP > <= >= <> MIN MAX (and PICK lifted to forth-in-forth for symmetry)
• All one-line Forth defs in core/lowlevel.fth, no asm changes
• New reg-rs test tf24a_fof_more_words covers all of them
• 69 tf24a tests pass

Note: <> is defined as = 0= rather than the more idiomatic = INVERT because forth-in-forth doesn't have INVERT (it requires NAND from phase 3). 0= works equivalently on boolean inputs and is available in all kernels' minimal.fth.

Still TODO (need asm-level work):

• +LOOP — increment-by-N runtime alongside the existing (LOOP) +1.
• J — outer-loop index when DO is nested.
• LEAVE — early-exit from DO/LOOP.
• DOES> — runtime extension of CREATE.
• RECURSE — IMMEDIATE word that compiles a self-reference (needed because runtime.fth's Forth : HIDDEN-bits the in-progress def).
• ROLL — needs RECURSE.

Keeping this issue open until those land in a future step.

[softwarewrighter]

Further progress in 52e8236:

Done across all three layered kernels (one-line Forth defs in lowlevel.fth, no asm needed):

• ✅ RECURSE (IMMEDIATE) — compiles a self-reference via LATEST @ + 4 + namelen.
• ✅ ROLL — standard ?DUP IF SWAP >R 1 - RECURSE R> SWAP THEN.

Verified 0/1/2/4 ROLL against 1 2 3 [4 5] N ROLL . . . [. .]:

• 0 ROLL → no-op
• 1 ROLL = SWAP
• 2 ROLL = ROT
• 4 ROLL pulls the 4-deep item to top

New reg-rs test tf24a_fof_recurse_roll. 70 tests pass.

Cumulative GH #3 status:

• Done: ?DUP > <= >= <> MIN MAX RECURSE ROLL (and PICK lifted to forth-in-forth)
• TODO (asm work): +LOOP J LEAVE DOES>

Keeping open until those four land.

[softwarewrighter]

More progress in d6f66b7: J (outer-loop index) added across all 3 layered kernels as a 1-line Forth def : J RP@ 9 + @ ;. Lifted RP@ as asm primitive into forth-in-forth (phase-3 subsets 14A added it to the more-evolved kernels; forth-in-forth didn't have it).

Also fixed a flakiness in tf24a_fff_selftest under parallel test runs — cor24-run's default 10s wall-clock limit was getting hit when many tests shared CPU. Bumped to -t 60 in build-kernel.sh and test-kernel.sh.

GH #3 status:

• ✅ Done: ?DUP > <= >= <> MIN MAX RECURSE ROLL J + PICK lift
• TODO: +LOOP, LEAVE, DOES> — each needs a real asm primitive (or asm-level scheme).

71 tf24a tests pass.