# amanxgiri/lox architecture

> Architecture diagram of the GitHub repository amanxgiri/lox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amanxgiri/lox
- Repository: https://github.com/amanxgiri/lox

## Overview

##### Project type and purpose
- This is an interpreter project implementing the “Lox” language in two variants:
a. A bytecode‐based VM in C (clox)
b. A tree‐walking interpreter in Java (jlox)
- There is also a small code‐generation tool (tool/GenerateAst.java) that scaffolds AST classes.
- Purpose: demonstrate language implementation techniques (lexing, parsing, AST, resolver, interpreter or VM, memory management).

##### File structure
- Top‐level directories:
- clox/ – C implementation
- jlox/ – Java implementation
- tool/ – AST generator utility
- clox modules (chunk, vm, memory, value, debug) reveal a bytecode compiler + VM + manual memory management layer
- jlox classes (Scanner, Parser, Expr, Stmt, Interpreter, Resolver, Environment, LoxFunction/Class, etc.) reveal a front‐end + semantic analysis + tree‐walking interpreter
- tool/GenerateAst.java generates the Java AST classes under jlox/Expr.java and jlox/Stmt.java

##### README for additional insights
- README.md is placeholder; rely on file names and project conventions from “Crafting Interpreters.”

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Code Generation (Tool)"
    Gen["GenerateAst Tool"]:::tool
  end

  subgraph "C Implementation (clox)"
    InputC["REPL/Script Runner"]:::c
    Common["common.h"]:::c
    Chunk["Parser & Chunk Builder"]:::c
    VM["VM Core"]:::c
    Memory["Memory Manager"]:::c
    Value["Value System"]:::c
    Debug["Debug/Error Reporting"]:::c
  end

  subgraph "Java Implementation (jlox)"
    InputJ["Lox.java (REPL/Runner)"]:::java
    Scanner["Scanner"]:::java
    Parser["Parser"]:::java
    Token["Token/TokenType"]:::java
    ASTNodes["Expr/Stmt AST Nodes"]:::java
    AstPrinter["AstPrinter"]:::java
    Resolver["Resolver"]:::java
    Interpreter["Interpreter"]:::java
    Env["Environment"]:::java
    LoxCallable["LoxCallable"]:::java
    LoxFunction["LoxFunction"]:::java
    LoxClass["LoxClass"]:::java
    LoxInstance["LoxInstance"]:::java
    Return["Return Control Flow"]:::java
    RuntimeError["RuntimeError"]:::java
  end

  Gen -->|"generates AST classes"| ASTNodes

  InputC -->|source code| Common
  InputC -->|source code| Chunk
  Common --> Chunk
  Chunk -->|bytecode chunks| VM
  VM -->|alloc/free| Memory
  VM -->|manages| Value
  VM -->|logs/errors| Debug

  InputJ --> Scanner
  Scanner -->|tokens| Token
  Scanner -->|tokens| Parser
  Token --> Parser
  Parser -->|AST| ASTNodes
  ASTNodes --> AstPrinter
  ASTNodes --> Resolver
  Resolver -->|annotated AST| Interpreter
  Interpreter -->|executes AST| ASTNodes
  Interpreter --> Env
  Env -.->|stores variables| Interpreter
  Interpreter --> RuntimeError
  Interpreter --> Return
  Interpreter --> LoxCallable
  LoxCallable --> LoxFunction
  LoxCallable --> LoxClass
  LoxClass --> LoxInstance

  click InputC "https://github.com/amanxgiri/lox/blob/master/clox/main.c"
  click Common "https://github.com/amanxgiri/lox/blob/master/clox/common.h"
  click Chunk "https://github.com/amanxgiri/lox/blob/master/clox/chunk.c"
  click Chunk "https://github.com/amanxgiri/lox/blob/master/clox/chunk.h"
  click VM "https://github.com/amanxgiri/lox/blob/master/clox/vm.c"
  click VM "https://github.com/amanxgiri/lox/blob/master/clox/vm.h"
  click Memory "https://github.com/amanxgiri/lox/blob/master/clox/memory.c"
  click Memory "https://github.com/amanxgiri/lox/blob/master/clox/memory.h"
  click Value "https://github.com/amanxgiri/lox/blob/master/clox/value.c"
  click Value "https://github.com/amanxgiri/lox/blob/master/clox/value.h"
  click Debug "https://github.com/amanxgiri/lox/blob/master/clox/debug.c"
  click Debug "https://github.com/amanxgiri/lox/blob/master/clox/debug.h"

  click InputJ "https://github.com/amanxgiri/lox/blob/master/jlox/Lox.java"
  click Scanner "https://github.com/amanxgiri/lox/blob/master/jlox/Scanner.java"
  click Parser "https://github.com/amanxgiri/lox/blob/master/jlox/Parser.java"
  click Token "https://github.com/amanxgiri/lox/blob/master/jlox/Token.java"
  click Token "https://github.com/amanxgiri/lox/blob/master/jlox/TokenType.java"
  click ASTNodes "https://github.com/amanxgiri/lox/blob/master/jlox/Expr.java"
  click ASTNodes "https://github.com/amanxgiri/lox/blob/master/jlox/Stmt.java"
  click AstPrinter "https://github.com/amanxgiri/lox/blob/master/jlox/AstPrinter.java"
  click Resolver "https://github.com/amanxgiri/lox/blob/master/jlox/Resolver.java"
  click Interpreter "https://github.com/amanxgiri/lox/blob/master/jlox/Interpreter.java"
  click Env "https://github.com/amanxgiri/lox/blob/master/jlox/Environment.java"
  click LoxCallable "https://github.com/amanxgiri/lox/blob/master/jlox/LoxCallable.java"
  click LoxFunction "https://github.com/amanxgiri/lox/blob/master/jlox/LoxFunction.java"
  click LoxClass "https://github.com/amanxgiri/lox/blob/master/jlox/LoxClass.java"
  click LoxInstance "https://github.com/amanxgiri/lox/blob/master/jlox/LoxInstance.java"
  click Return "https://github.com/amanxgiri/lox/blob/master/jlox/Return.java"
  click RuntimeError "https://github.com/amanxgiri/lox/blob/master/jlox/RuntimeError.java"

  click Gen "https://github.com/amanxgiri/lox/blob/master/tool/GenerateAst.java"

  classDef c fill:#AEDFF7,stroke:#0000FF
  classDef java fill:#C2F0C2,stroke:#006400
  classDef tool fill:#D3D3D3,stroke:#808080
```
