Summary
Forth primitives like +, -, *, /, and MOD produce a terse error
when the data stack doesn't have enough operands. For someone who just
typed their first definition wrong, the current message is not very
self-explanatory — they don't know whether they're missing one item or
three, or which word triggered the underflow.
This issue is to improve those messages so they read more like
"+ needs 2 items, stack had 1 (in word SQUARE)" — naming the word and
the shortfall.
Why it's a good first issue
The change is local to src/vm/ (likely the arithmetic primitives module
plus wherever the underflow error is constructed). No cross-module design
decisions, no protocol changes, no new dependencies. It's a great way to
get familiar with how the Forth VM dispatches primitives and how errors
flow back to the REPL.
It's also user-visible: anyone running cargo install unit and typing at
the REPL will benefit on day one.
Acceptance criteria
Where to look
src/vm/ — interpreter and primitive implementations
src/integration_tests.rs — pattern for stack/error tests
- Recent fix-pass commits for tone reference:
4696b6f, 92c2e30,
1855f24
Summary
Forth primitives like
+,-,*,/, andMODproduce a terse errorwhen the data stack doesn't have enough operands. For someone who just
typed their first definition wrong, the current message is not very
self-explanatory — they don't know whether they're missing one item or
three, or which word triggered the underflow.
This issue is to improve those messages so they read more like
"
+needs 2 items, stack had 1 (in wordSQUARE)" — naming the word andthe shortfall.
Why it's a good first issue
The change is local to
src/vm/(likely the arithmetic primitives moduleplus wherever the underflow error is constructed). No cross-module design
decisions, no protocol changes, no new dependencies. It's a great way to
get familiar with how the Forth VM dispatches primitives and how errors
flow back to the REPL.
It's also user-visible: anyone running
cargo install unitand typing atthe REPL will benefit on day one.
Acceptance criteria
+,-,*,/,MOD) andthe comparison words (
=,<,>) report a clearer underflowmessage that names the operand count and, when available, the
enclosing word.
src/vm/ortests/) so future regressions are caught.Where to look
src/vm/— interpreter and primitive implementationssrc/integration_tests.rs— pattern for stack/error tests4696b6f,92c2e30,1855f24