Lox Interpreter

A Java implementation of the Lox programming language from Robert Nystrom's book "Crafting Interpreters".

Overview

This project is a production-ready implementation of the Lox programming language, featuring:

• Variables and basic data types (numbers, strings, booleans, nil)
• Control flow (if statements, while loops, for loops)
• First-class functions with closures
• Classes with single inheritance
• Lexical scoping
• String escape sequences (\n, \t, \\, \")
• Recursion depth limits (prevents stack overflow)
• Division by zero error handling

Quick Start

Prerequisites

• Java 11 or higher
• Maven 3.6+

Build & Run

# Clone the repository
git clone https://github.com/yourusername/lox-interpreter.git
cd lox-interpreter

# Build the project
mvn package

# Run a Lox program
java -jar target/lox-interpreter-1.0.0.jar examples/hello.lox

# Start the REPL
java -jar target/lox-interpreter-1.0.0.jar

Using the Run Scripts

# On Unix/macOS
./lox examples/fibonacci.lox

# On Windows
lox.bat examples\fibonacci.lox

Usage

Running Programs

# Run a Lox script file
java -jar target/lox-interpreter-1.0.0.jar script.lox

# Or with Maven
mvn exec:java -Dexec.mainClass="com.lox.Lox" -Dexec.args="script.lox" -q

Interactive REPL

java -jar target/lox-interpreter-1.0.0.jar

Lox Interpreter v1.0
Type 'exit' to quit.

> print "Hello, World!";
Hello, World!
> var x = 42;
> print x * 2;
84
> exit

Language Syntax

Variables

var name = "Alice";
var age = 30;
var isActive = true;
var nothing = nil;

Control Flow

// If statement
if (age >= 18) {
    print "Adult";
} else {
    print "Minor";
}

// While loop
var i = 0;
while (i < 5) {
    print i;
    i = i + 1;
}

// For loop
for (var i = 0; i < 5; i = i + 1) {
    print i;
}

Functions

fun greet(name) {
    print "Hello, " + name + "!";
}

fun fibonacci(n) {
    if (n <= 1) return n;
    return fibonacci(n - 2) + fibonacci(n - 1);
}

greet("World");
print fibonacci(10);

Closures

fun makeCounter() {
    var count = 0;
    fun increment() {
        count = count + 1;
        return count;
    }
    return increment;
}

var counter = makeCounter();
print counter(); // 1
print counter(); // 2

Classes

class Animal {
    init(name) {
        this.name = name;
    }

    speak() {
        print this.name + " makes a sound.";
    }
}

class Dog < Animal {
    init(name, breed) {
        super.init(name);
        this.breed = breed;
    }

    speak() {
        print this.name + " barks!";
    }
}

var dog = Dog("Buddy", "Golden Retriever");
dog.speak(); // "Buddy barks!"

Built-in Functions

print clock(); // Returns current time in seconds

Project Structure

lox-interpreter/
├── src/
│   ├── main/java/com/lox/
│   │   ├── Lox.java              # Entry point
│   │   ├── ast/                  # AST nodes (Expr, Stmt)
│   │   ├── debug/                # AstPrinter
│   │   ├── error/                # Error handling
│   │   ├── interpreter/          # Interpreter, Environment
│   │   ├── parser/               # Parser
│   │   ├── resolver/             # Variable resolver
│   │   ├── runtime/              # Functions, classes, instances
│   │   ├── scanner/              # Lexer
│   │   └── token/                # Token types
│   └── test/java/com/lox/        # Unit tests
├── examples/                     # Example Lox programs
├── pom.xml                       # Maven configuration
└── README.md

Development

Build Commands

# Compile
mvn compile

# Run tests
mvn test

# Package JAR
mvn package

# Clean build
mvn clean install

Running Tests

mvn test

The test suite includes:

• Scanner tests (tokenization, escape sequences, error handling)
• Interpreter tests (expressions, statements, classes, closures)

Example Programs

See the examples/ directory:

• hello.lox - Hello World
• fibonacci.lox - Fibonacci sequence
• closures.lox - Closure demonstration
• classes.lox - Class inheritance example

Implementation Details

Pipeline

Source Code → Scanner → Tokens → Parser → AST → Resolver → Interpreter → Output

Key Features

• Visitor Pattern: Clean AST traversal for interpretation
• Environment Chaining: Proper lexical scoping
• Static Resolution: Variable binding at compile time
• Recursion Limits: Prevents stack overflow (max 1000 calls)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (mvn test)
5. Commit (git commit -m 'Add amazing feature')
6. Push (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Robert Nystrom for "Crafting Interpreters"
• The Lox language design