Skip to content

README.md

Latest commit

 

History

History
83 lines (59 loc) · 3.53 KB

README.md

File metadata and controls

83 lines (59 loc) · 3.53 KB

progress-banner

Build Your Own Interpreter in Python — a Lox tree-walk interpreter from scratch

A working interpreter for Lox (the language from Robert Nystrom's Crafting Interpreters) implemented in pure Python. Scanner, recursive-descent parser, pretty-printer, and tree-walk evaluator — all in one readable file. Real Lox programs run: variables, control flow, first-class functions, closures, recursion.

Built in under 48 hours with Claude Code while reaching CodeCrafters Python leaderboard rank #13.

If you searched for "Crafting Interpreters in Python", "Lox interpreter from scratch", "tree-walk interpreter tutorial", or "recursive descent parser Python" — this repo is a compact, end-to-end reference.

What works

$ cat hello.lox
fun fib(n) {
  if (n < 2) return n;
  return fib(n - 2) + fib(n - 1);
}
for (var i = 0; i < 8; i = i + 1) print fib(i);

$ ./your_program.sh run hello.lox
0
1
1
2
3
5
8
13

Four commands

Command What it does
./your_program.sh tokenize Scan source → print tokens (TYPE lexeme literal)
./your_program.sh parse Parse one expression → print Lisp-style AST (+ 1.0 2.0)
./your_program.sh evaluate Parse + evaluate one expression → print the value
./your_program.sh run Execute a full Lox program (statements, functions, scope…)

Language features implemented

  • Scanner: all Lox tokens — single/double char operators, string literals (multiline), number literals (with .0 literal formatting), identifiers, keywords, // comments
  • Parser: full Lox grammar — expressions (precedence-correct), statements (var, print, block, if/else, while, for, function declarations, return), with proper error recovery / panic-mode synchronization
  • Evaluator:
    • Environments with lexical scoping
    • Truthiness & Lox equality semantics
    • Short-circuit and/or
    • Function declarations, calls, closures over their enclosing env
    • return implemented as a control-flow exception
    • Runtime errors with [line N] reporting (exit 70)
    • Parse errors → exit 65 (CodeCrafters-compatible)
  • Native function: clock() returns wall time, used for benchmarks

Architecture

  • Single file (app/main.py, ~700 lines): scanner → AST dataclasses → parser → AST printer → interpreter → CLI dispatcher
  • Recursive-descent parser mirrors the grammar one-to-one with the book
  • Tree-walk interpreter uses isinstance dispatch for readability instead of the visitor pattern

Run it

./your_program.sh run path/to/program.lox

Requires uv and Python 3.14.

Why this repo is worth reading

Most Lox implementations you find online are Java (the book's language) or C (Part III). This is Python, single-file, and covers the complete Part II interpreter through functions and closures — a good companion if you're working through Crafting Interpreters in a different language.

Credits

Part of the CodeCrafters "Build Your Own Interpreter" challenge. Language and grammar by Robert Nystrom.