Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -699,3 +699,15 @@ number within the filtered subset, so --log-pin, --log-tag
and --log-note addressing is the same from any view. The
filtered export is chronological, like the lab record,
because an exported record is read forwards in time.

## 2026-11-07 — RPN / programmable mode (Free42 + Plus42 functionality)
SEAN asked for the functionality of Free42 and Plus42 and said
"proceed as you suggest". Chosen scope: (b) an HP-42S-compatible
RPN/programmable mode inside CalcDex first, then the Plus42
extras (equations, units, TVM, directories, plotting). Clean-room
implementation (Free42/Plus42 are GPLv2; CalcDex stays MIT): no
upstream source read or copied. Engine lives in a new `src/rpn/`
beside the registry, because the registry signature is stateless,
f64-only and scalar. Numbers: f64 first, 34-digit decimal in P2.
Own versioned state format; program listings import/export. No UI
code until the wireframe is approved. Plan: docs/RPN_PLAN.md.
5 changes: 5 additions & 0 deletions QUALITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,3 +126,8 @@ at release (2026-10-25, this machine).
- Windows cross-builds — x86_64-pc-windows-gnu (GCC 13): PE32+ GUI x86-64, `.rsrc` 14,792 B, exe 5,790,208 B, SHA-256 3764e29f92d1f6f3675a2f919abfbd9f631045385c237e32e0bdb6eda61e40d0; i686-pc-windows-gnu (GCC 13): PE32 GUI Intel 80386, `.rsrc` 14,792 B, exe 5,867,008 B, SHA-256 3d5f43b49f98654985f1323e717ca728b6240dad848b851439f2529840e2c9c5; aarch64-pc-windows-gnullvm (llvm-mingw clang): PE32+ GUI Aarch64, `.rsrc` 14,792 B, exe 5,194,240 B, SHA-256 757d6acf426033ff4375fcf3e952882d3a33057346ee054092376248eaeac259. Feature strings verified in all three binaries ("FOR ENGINEERS"). Toolchain notes: the VM had again lost the apt packages — gcc-mingw-w64-i686, gcc-mingw-w64-x86-64, nsis, msitools, llvm-18 and p7zip-full were reinstalled. The ARM64 build first linked without `.rsrc`: build.rs calls a bare `windres` for non-x86_64 targets, served by the per-arch shim in ~/calcdex-shims (i686 → GNU windres; aarch64 → llvm-mingw's wrapper), and the wrapper's llvm-windres needs clang on PATH for preprocessing — the first ARM64 build ran without llvm-mingw/bin on PATH, so build.rs quietly skipped the icon; adding ~/llvm-mingw/bin after the shim directory and touching build.rs fixed it (verified: .rsrc present at the same 14,792 B as the other targets).
- Assets (exact-name 7-asset set, in dist/ and copied to dist-archive/v0.8.0/): CalcDex-Setup-x86.exe 2,514,196 B 9d711860b2f4949ec22bac7ec7021457534fa4765950fb4096ef311bfb6c3e04; CalcDex-Setup-x64.exe 2,321,248 B 5ae67623b2b3ef600d8cf220541c5cce5b872c33005aa269e5e04cd636b7e0b2; CalcDex-Setup-ARM64.exe 2,115,849 B dc30e40f6d7c31aa39ce8c5356a8729f102ffba0cc316265579a416ed3f207ba; CalcDex-Setup-x86_64.msi 2,926,592 B e62818b2e4835735d862c924e93badc59feb022bcc633cffed0eb8c4657f3d27; CalcDex-Portable-x86.zip 2,976,329 B 8a440e012345dd39d664394c8763e538d680a61b2abe93909f81c11ba0658af3; CalcDex-Portable-x64.zip 2,781,315 B 24809750dc097e8b6857f598d67440e2cd5f0e7a1b6c74e9e1bf1520f1645af5; CalcDex-Portable-ARM64.zip 2,635,949 B 3883582295c225c179755397a1c397dfe07bb9c15c409a8429cfd2911a923b99. Every payload verified by extraction: all three NSIS installers and the MSI contain their architecture's exe (SHA-256 identical to the cross-builds above; MSI payload = x64), and each portable zip holds CalcDex.exe + LICENSE + PORTABLE.txt with the exe hash matching its cross-build and the PE machine correct (80386 / x86-64 / Aarch64). NSIS stubs are 32-bit launchers by design.
- On-Windows behaviour of the v0.8.0 GUI additions (MATERIALS view + USE E IN BEAM, the log view's search/filter/pin/export controls, the resistor colour text field): **Unverified** — a field run is the verdict.

## RPN P1 gate transcript (2026-11-07, Linux sandbox)
- `cargo fmt --check` clean. `cargo clippy --all-targets --locked -D warnings`: clean for the new code; one existing lint (`manual_range_contains`, src/lib.rs:390, Rust 1.97) is not from this change and was not touched.
- `cargo test --locked --no-fail-fast`: every test binary passes, including 13 new in tests/rpn_p1.rs, except `v090::first_run_copies_legacy_files_into_data_beside_the_exe`, which also fails on the unmodified base here (Windows-only migration path) — Partially verified until run on Windows.
- Behaviour matches the repo's own known answers only; not compared with a real HP-42S or Free42 (see RPN_PLAN.md limitations). On-Windows run of `CalcDex rpn` is Unverified.
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,19 @@ CalcDex --restore-log
CalcDex --check-update
```

RPN mode (v0.9.x, command line only for now; window comes later):

```
CalcDex rpn "2 3 + 4 *" prints 20.0000
CalcDex rpn "1 3 / ALL" prints 0.333333333333
CalcDex rpn "5 ENTER 3 -" --stack shows T/Z/Y/X
CalcDex rpn "12 STO A" --state work keep variables between runs
```

Tokens are separated by spaces: numbers (`1.5e-3`), operators,
and HP-42S names (ENTER, SIN, STO, RCL, FIX 4, ...). Errors name a
stable code such as `[RPN-103]`. See `docs/RPN_PLAN.md`.

Numbers go in the same order as the labelled boxes in the window.
For unit converters the two extra numbers pick the units from the
numbered list shown in that calculator's description.
Expand Down
14 changes: 14 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,20 @@

## Unreleased

### Added
- **RPN mode, phase P1 (command line).** `CalcDex rpn "2 3 + 4 *"`
runs HP-42S-style tokens on a 4-level stack with LASTX, stack
lift/ENTER, arithmetic, powers, roots, logs, trig (DEG/RAD/GRAD,
exact at quarter turns), hyperbolics, FACT/COMB/PERM, %, %CH,
MOD, named variables (STO/RCL and STO+ - * /, RCL+ - * /, CLV)
and FIX/SCI/ENG/ALL display. `--stack` shows T/Z/Y/X, `--json`
prints one JSON object, `--state NAME` keeps the stack and
variables between runs in `data/rpn-NAME.txt` (versioned,
atomic; a corrupt file is kept as `.bad`, a newer-version file
is never overwritten). `--clean`/`--uninstall` remove these
files. Numbers are f64 for now; 34-digit decimal is phase P2.
No window yet (phase P9). Plan: [RPN_PLAN.md](RPN_PLAN.md).

### Fixed
- Legacy storage migration stages and flushes the complete data set before
publication, preserving legacy storage on failure and existing foreign entries.
Expand Down
8 changes: 8 additions & 0 deletions docs/CREDITS.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,11 @@ problem-set tooling, the installers and these documents —
is part of this repository, MIT-licensed (see
[../LICENSE](../LICENSE)). Reference values in the
constants table are the CODATA 2018 recommended values.

## RPN mode

The RPN mode follows the behaviour of the HP-42S calculator as
described in HP's published owner's manual and in the public
documentation of Free42 / Plus42 by Thomas Okken (GPLv2). No code
from those projects is used (clean-room); the names and
conventions are theirs and HP's.
6 changes: 6 additions & 0 deletions docs/PARITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,3 +102,9 @@ result in outputs; full precision; scientific-notation inputs;
constants named; estimates labelled. Implemented in the registry
output text and README — Verified by CLI output; GUI presentation
of the v0.4.0, v0.5.0, v0.6.0 and v0.7.0 panels is Unverified until a fresh field run.

## RPN mode (P1)

| Capability | Window | Command line |
|---|---|---|
| RPN stack machine (P1) | Not yet (phase P9) | `CalcDex rpn "<tokens>"` — Verified by tests/rpn_p1.rs |
8 changes: 7 additions & 1 deletion docs/ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,10 @@
# Roadmap — what v0.1.1 does NOT do yet (honest list)
# Roadmap — what CalcDex does NOT do yet (honest list)

The RPN / programmable mode (Free42 + Plus42 functionality) is
planned in [RPN_PLAN.md](RPN_PLAN.md). The lists below date from
v0.1.1 and have not all been re-checked against v0.9.0; items
shipped since then (dates, log, engineering, units in expressions)
may still appear.

Done since v0.1 (removed from the gap list): merged MM/DD/YYYY date
fields with Today? buttons and end-date wording, CLI one-argument
Expand Down
148 changes: 148 additions & 0 deletions docs/RPN_PLAN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
# RPN / Programmable Mode — Architecture & UX Plan

Status: P1 done (RPN core + `rpn` CLI, f64 numbers). P2–P13 not
started. Progress: 1 of 13 phases (~8%, rough, phases differ a lot
in size). No ETA: P4–P6 and P10–P12 are the big ones.
Decision: scope (b) — an HP-42S-compatible RPN/programmable mode
inside CalcDex, then the Plus42-style extras. Recorded in DECISIONS.md.

## Goal
Offer the functionality of Free42 (HP-42S simulator) and Plus42
(Free42 + algebraic equations, units, directories, TVM, plotting)
as a new **RPN** mode of CalcDex, alongside the 316 registry
calculators. Targets: HP-42S program compatibility and Plus42
feature coverage, claimed only as far as tests prove.

## Clean-room rule
Free42/Plus42 are GPLv2. CalcDex is MIT. No Free42/Plus42 source is
read, copied or translated. Behaviour comes from the published
HP-42S Owner's Manual, HP-42S Programming Examples, the Free42 /
Plus42 public documentation pages, and black-box comparison of
program results. Test programs must be public-domain or written
here. Any contributor who has read Free42 source is asked to say so
in the PR.

## Why a new engine
The registry signature `Fn(&[f64]) -> Result<String,String>` is
stateless, scalar and f64-only. The RPN machine is stateful (stack,
registers, programs, flags) and typed (real, complex, string,
matrix, list, later unit/equation). It lives beside the registry:

```
src/rpn/
mod.rs public API: Session, Key/Op dispatch, text front end
num.rs Num (real) — f64-backed first, 34-digit decimal later
value.rs enum Value { Real, Complex, Str, Matrix, List, ... }
stack.rs 4-level stack + LASTX, optional growing "big stack"
ops/ one file per family: arith, trig, stats, base, time,
matrix, complex, string, list, flags, control
display.rs FIX/SCI/ENG/ALL, RDX./RDX, separators, base views
prog.rs program memory, labels, listing parse/print
run.rs interpreter: GTO/XEQ/RTN, flags, local vars, SST/BST
solve.rs SOLVE, integrator (programmable + equation based)
state.rs versioned state file, atomic save, import/export
eqn.rs (Plus42 phase) equation parser/evaluator
units.rs (Plus42 phase) attached units
```

`src/main.rs` stays shell-only. The registry is untouched except for
one new text entry point, `run_rpn(session, line)`, so the window
and CLI share one dispatch (AGENTS.md invariant).

## Invariants (inherit AGENTS.md)
- No `unwrap()`/`expect()` on user input or file content; every
error is a plain-words message with a stable code.
- State, programs and settings live under `data/`, versioned
(`schema_version`), written atomically, with a migration fixture
for every bump. Unparseable state is quarantined, never reset.
- Interpreter is bounded: step/time limit with a cancel check
(abort < 50 ms), recursion depth cap, memory cap.
- Offline, zero telemetry, idle RAM < 40 MB, UI thread < 16 ms
(long programs run on a worker thread).
- Every capability reachable from the CLI.

## CLI surface
```
CalcDex rpn "2 3 + 4 *" one-shot, prints X (and stack with --stack)
CalcDex rpn --state NAME ... use/save a named state
CalcDex rpn --run prog.txt load a listing and XEQ it
CalcDex rpn --listing prog.txt print/validate a listing
CalcDex rpn --json ... machine-readable result
```
Input tokens: numbers (incl. `1.5e-3`), HP-42S mnemonics (`ENTER`,
`STO 01`, `RCL "A"`, `XEQ "NAME"`), and `PRGM` lines.

## Numbers
- Phase 1: `Num` wraps f64 (Free42 "Binary" equivalent). Documented
difference: 0.1 inexact.
- Phase 2: `Num` becomes a 34-digit decimal (IEEE 754-2008
decimal128 semantics: 34 digits, exponent ±6144), pure Rust,
no C dependency. Transcendentals are implemented with guard
digits and verified against high-precision reference vectors.
A runtime/setting switch keeps both modes, as Free42 does.
- Risk: correct rounding of sin/exp/ln at 34 digits is the hardest
single item; if it slips, decimal mode ships with arithmetic,
sqrt and powers exact and transcendentals documented as
≤ 1 ulp-ish with measured error, never claimed correctly rounded.

## Phases (each = one PR, full gate green before merge)
| # | Scope | Done when |
|---|---|---|
| P1 | RPN core: stack, LASTX, entry, arithmetic and scientific functions, STO/RCL + named variables, FIX/SCI/ENG/ALL, `rpn` CLI | HP-42S manual chapter 2–3 examples pass |
| P2 | 34-digit decimal `Num`, Binary/Decimal switch | reference-vector suite; 0.1+0.2 exact |
| P3 | Complex (rect/polar), strings/ALPHA, lists | manual complex examples pass |
| P4 | Matrices: edit, inverse, det, transpose, row ops, linear solve, complex matrices | known-answer matrix suite |
| P5 | Programming: memory, labels, GTO/XEQ/RTN, tests, flags, loops (ISG/DSE), local vars (LSTO), SST/BST, listing import/export + clipboard | public-domain 42S programs run to expected output |
| P6 | Numerical SOLVE and integrator (programmable) | manual solver/integrator examples |
| P7 | Statistics (Σ+, regressions, forecasts), BASE (word size, bit ops), time/date functions | known-answer suites; dates 1582-10-15..4320-09-10 |
| P8 | State files, states manager, full copy/paste formats (scalars, matrices tab-delimited, programs) | round-trip + migration fixtures |
| P9 | GUI: keypad + display + program view + variables, as a mode on the mode rail | wireframe approved (below); screenshots from real run |
| P10 | Plus42: EQN parser/evaluator, direct+numeric solver, equation integration | equation suite |
| P11 | Plus42: attached units + catalog, TVM/amortization, directories | unit and TVM known answers |
| P12 | Plus42: XY plotting + plot viewer, big display options | plot export + visual check on Windows |
| P13 | Compatibility pass: corpus of 42S programs, verification matrix, docs | claims in README match tests |

Out of scope unless asked: HP-82240 printer emulation, skin files,
accelerometer/GPS/compass, Android/iOS builds (CalcDex is
windows-x64).

## UX
- New **RPN** mode on the mode rail (same Terminal theme, radius 0,
Cascadia Mono). Centre: display (stack levels, X highlighted,
annunciators: RAD/DEG, FIX/SCI, shift, PRGM, flags), keypad,
menu row (soft keys), optional program/variables panes. History
rail shows the tape.
- Keyboard first: physical keys map to RPN keys; Enter = ENTER;
Esc = cancel/abort program; Tab order logical; every key has a
tooltip (action + side effects).
- Window geometry and splitters persist (already supported).
- Accessibility: focus visuals, accessible names on every key,
contrast measured to WCAG AA, no colour-only annunciators.
- Wireframe sign-off is required before P9 (AGENTS.md gate); P1–P8
have no UI work.

## Testing / verification
- Known-answer vectors per op; property tests for stack invariants.
- Program corpus with expected outputs (written here or
public-domain).
- Failure drills: bad state file, truncated listing, runaway loop,
deep recursion, huge matrix, cancel mid-run.
- Evidence labels (Verified / Partially verified / Unverified) in
QUALITY.md; on-Windows GUI checks stay Unverified until run.

## Open questions
1. Wireframe approval (P9).
2. Decimal precision fallback acceptable per the risk note above?
3. Keep Free42-compatible `.f42` state files? Default: no — own
versioned format, with listing import/export for programs.

## Known limitations after P1 (Unverified against real HP-42S)
- SQRT of a negative real, LN of 0 or less, etc. give Invalid Data;
real hardware/Free42 may return complex results. Revisit in P3.
- `0 0 Y^X` returns 1 (IEEE); hardware behaviour not checked.
- `MOD` with divisor 0 is an error here; hardware not checked.
- ENG n shows n+1 significant digits and no trailing point
(`12E-3`); the HP-42S look may differ.
- No registers 00-99 limit, no SIZE, no complex/strings/matrices yet.
- Behaviour checked only by this repo's tests, not by running an
HP-42S or Free42.
1 change: 1 addition & 0 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ pub mod features;
pub mod meta;
pub mod paths;
pub mod rigour;
pub mod rpn;
pub mod settings;
pub mod students;
pub mod teachers;
Expand Down
Loading
Loading