Lox Interpreter (Java)

A complete Java implementation of the Lox programming language, built by following Crafting Interpreters and implemented as part of the CodeCrafters Interpreter Challenge.

This project implements lexing, parsing, static resolution, and execution for the full Lox language, including functions, closures, classes, inheritance, and native functions.

---

Features

Language Support

• Data types: numbers, strings, booleans, nil

• Expressions: arithmetic, comparison, equality, logical operators

• Variables: lexical scoping, assignment, shadowing

• Control flow: if, else, while, for

• Functions: first-class functions, closures, recursion

• Classes and object-oriented programming:

  • Constructors (init)
  • Instance methods and properties
  • Single inheritance using super
  • this binding

• Native functions: clock()

Interpreter Internals

• Tree-walk interpreter
• Recursive-descent parser
• Static scope resolution (two-pass execution)
• Visitor pattern for AST traversal
• Runtime error handling with defined exit codes

---

Tech Stack

• Language: Java 11+
• Build tool: Maven
• Architecture: AST with Visitor pattern
• Platform: CodeCrafters

---

Project Structure

codecrafters-interpreter-java/
├── pom.xml
├── codecrafters.yml
├── your_program.sh
└── src/main/java/nox/
    ├── Main.java
    ├── parser/
    │   ├── Token.java
    │   ├── Parser.java
    │   ├── Expr.java
    │   ├── Stmt.java
    │   ├── LiteralParser.java
    │   ├── StatementParser.java
    │   └── AstPrinter.java
    └── interpreter/
        ├── Interpreter.java
        ├── Resolver.java
        ├── Environment.java
        ├── LoxCallable.java
        ├── LoxFunction.java
        ├── LoxClass.java
        ├── LoxInstance.java
        ├── ClockFunction.java
        ├── RuntimeError.java
        └── ResolverError.java

---

Running the Interpreter

Prerequisites

• Java 11 or newer
• Maven

Build

mvn clean package

Commands

Tokenize (Lexer)

./your_program.sh tokenize file.lox

Parse (AST)

./your_program.sh parse file.lox

Evaluate Expression

./your_program.sh evaluate file.lox

Run Full Program

./your_program.sh run file.lox

---

Example

Lox Program

class Counter {
  init() {
    this.value = 0;
  }

  inc() {
    this.value = this.value + 1;
    return this.value;
  }
}

var c = Counter();
print c.inc();
print c.inc();

Output

1
2

---

Interpreter Design

Execution Pipeline

1. Lexing: source code to tokens
2. Parsing: tokens to AST
3. Resolution: static scope binding
4. Interpretation: AST execution

Two-Pass Design

• Ensures correct lexical scoping
• Enables constant-time variable lookup
• Detects invalid use of return, this, and super before execution

---

Error Handling

Error Type	Exit Code
Syntax and resolution errors	65
Runtime errors	70

Handled cases include:

• Undefined variables
• Invalid inheritance
• Incorrect function arity
• Type mismatches
• Invalid property access

---

Grammar (EBNF)

program        → declaration* EOF ;
declaration    → classDecl | funDecl | varDecl | statement ;
classDecl      → "class" IDENTIFIER ( "<" IDENTIFIER )? "{" function* "}" ;
funDecl        → "fun" function ;
function       → IDENTIFIER "(" parameters? ")" block ;
statement      → exprStmt | ifStmt | whileStmt | forStmt | printStmt | returnStmt | block ;
expression     → assignment ;
assignment     → IDENTIFIER "=" assignment | logic_or ;

---

References

• Crafting Interpreters — Robert Nystrom
• CodeCrafters Interpreter Challenge https://app.codecrafters.io/courses/interpreter/overview

---

License

Educational project created for learning language design and interpreter implementation.