I wanted an interactive calculator that does real work: variables, user-defined functions with recursion, ternaries, and reuse of the last result. The harder constraint was pedagogical. The interpreter had to stay small enough that each stage reads and reasons end to end, so the code itself works as an explanation of how an expression language is built.

That ruled out reaching for a parser generator or a big expression library. A generated parser would hide the part I most wanted to be legible: the grammar, and how precedence falls out of it.

The shape is a textbook three-stage interpreter. A hand-written lexer emits a typed token stream. A recursive-descent parser turns tokens into a std::variant AST owned by unique_ptr. A tree-walking evaluator folds the AST to a double against a mutable state. Errors are typed exceptions caught at the REPL loop, so one bad line never kills the session.

1. i

   Tokenizer.

   A hand-written scanner. It tracks a single decimal point, supports leading-dot numbers like .25, and does two-char operator lookahead for ==, !=, <=, >= with a helpful diagnostic on a lone !.

   src/token.cpp
2. ii

   Parser.

   Recursive descent with precedence climbing. One higher-order helper, abstract_parse, derives the whole precedence ladder from a sub-parser, an operator set, and an associativity flag. It is the cleanest part of the codebase.

   src/expression.cpp:170
3. iii

   Evaluator.

   A tree-walk over the variant AST. Built-ins resolve before user functions, arity is checked, and each call gets a fresh local scope, so recursion works for free against shared state.

   src/evaluator.cpp:87

Three decisions trade something away, and all three stay in the repo as written rather than papered over.