# peshala-prabhapoorna/jlox architecture

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

- Interactive diagram: https://gitdiagram.com/peshala-prabhapoorna/jlox
- Repository: https://github.com/peshala-prabhapoorna/jlox

## Overview

##### Project type and purpose
- This is a language‐interpreter/compiler‐style project (“jlox”) written in Java, implementing the Lox language from the Crafting Interpreters book.
- Its core purpose is to take Lox source code, run it through the standard compilation pipeline (scanning, parsing, semantic analysis/resolution) and then either interpret it directly or run it in a REPL.

##### File structure
- Top‐level:
- pom.xml – Maven build, dependency and packaging configuration
- jlox (executable wrapper/script)
- LICENSE, .gitignore, README.md
- src/tool/GenerateAst.java – code‐generation utility for AST classes (one‐time or build‐time tool).
- src/lox/ – contains all interpreter source code:
- Scanner.java – lexical analysis component
- Parser.java – syntax analysis, builds AST (Expr, Stmt hierarchies)
- AstPrinter.java – utility to pretty‐print the AST
- Resolver.java – semantic analysis (scope resolution, binding)
- Interpreter.java – evaluation of AST nodes (implements Visitor pattern)
- Environment.java – runtime storage for variable bindings and scopes
- Classes for runtime values: LoxFunction, LoxClass, LoxInstance, LoxCallable
- Token, TokenType, RuntimeError, Return, etc.
- Lox.java – entry point (sets up REPL or runs script file)
- test/ – folder of .lox files exercising language features (control flow, classes, functions, etc.)

##### README for additional insights
- Clarifies dependencies (JDK, Maven) and expected usage (REPL vs script mode).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI / Entry Point
    subgraph "CLI / Entry"
        direction TB
        LoxCLI["Lox.java"]:::cli
        JloxScript["jlox (script)"]:::cli
    end

    %% Frontend: Lexing & Parsing
    subgraph "Frontend (Lexing & Parsing)" 
        direction TB
        Scanner["Scanner.java"]:::frontend
        Token["Token.java"]:::frontend
        TokenType["TokenType.java"]:::frontend
        Parser["Parser.java"]:::frontend
        Expr["Expr.java"]:::frontend
        Stmt["Stmt.java"]:::frontend
        AstPrinter["AstPrinter.java"]:::frontend
    end

    %% Semantic Analysis
    subgraph "Semantic Analysis" 
        direction TB
        Resolver["Resolver.java"]:::semantic
    end

    %% Runtime Components
    subgraph "Runtime" 
        direction TB
        Interpreter["Interpreter.java"]:::runtime
        Environment["Environment.java"]:::runtime
        LoxCallable["LoxCallable.java"]:::runtime
        LoxFunction["LoxFunction.java"]:::runtime
        LoxClass["LoxClass.java"]:::runtime
        LoxInstance["LoxInstance.java"]:::runtime
        RuntimeError["RuntimeError.java"]:::runtime
        Return["Return.java"]:::runtime
    end

    %% Tooling
    subgraph "Tooling" 
        direction TB
        GenerateAst["GenerateAst.java"]:::tooling
    end

    %% Build / Packaging
    subgraph "Build"
        direction TB
        Maven["pom.xml"]:::infra
    end

    %% Tests
    subgraph "Tests"
        direction TB
        Tests["test/"]:::infra
    end

    %% Data Flow
    JloxScript -->|"invokes"| LoxCLI
    LoxCLI -->|"reads source code"| Scanner
    Scanner -->|"Tokens"| Parser
    Parser -->|"AST (Expr/Stmt)"| Resolver
    Resolver -->|"Scoped AST"| Interpreter
    Interpreter -->|"executes AST"| Environment
    Environment -->|"variable lookup/define"| Interpreter
    Interpreter -->|"creates & calls"| LoxFunction
    Interpreter -->|"creates & calls"| LoxClass
    Interpreter -->|"creates & calls"| LoxInstance
    Interpreter -->|"implements call"| LoxCallable
    Interpreter -->|"throws errors"| RuntimeError
    Interpreter -->|"handles return"| Return

    GenerateAst -->|"generates AST classes"| Expr
    GenerateAst -->|"generates AST classes"| Stmt
    Maven -->|"runs at build time"| GenerateAst
    Maven -->|"compiles source"| Scanner
    Tests -->|"run via CLI"| LoxCLI

    %% Click Events
    click Scanner "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Scanner.java"
    click Token "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Token.java"
    click TokenType "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/TokenType.java"
    click Parser "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Parser.java"
    click Expr "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Expr.java"
    click Stmt "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Stmt.java"
    click AstPrinter "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/AstPrinter.java"
    click Resolver "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Resolver.java"
    click Interpreter "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Interpreter.java"
    click Environment "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Environment.java"
    click LoxCallable "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/LoxCallable.java"
    click LoxFunction "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/LoxFunction.java"
    click LoxClass "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/LoxClass.java"
    click LoxInstance "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/LoxInstance.java"
    click RuntimeError "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/RuntimeError.java"
    click Return "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Return.java"
    click LoxCLI "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/lox/Lox.java"
    click JloxScript "https://github.com/peshala-prabhapoorna/jlox/tree/main/jlox"
    click GenerateAst "https://github.com/peshala-prabhapoorna/jlox/blob/main/src/tool/GenerateAst.java"
    click Maven "https://github.com/peshala-prabhapoorna/jlox/blob/main/pom.xml"
    click Tests "https://github.com/peshala-prabhapoorna/jlox/tree/main/test/"

    %% Styles
    classDef frontend fill:#E0F0FF,stroke:#0000FF
    classDef semantic fill:#E0FFE0,stroke:#00AA00
    classDef runtime fill:#FFE0B2,stroke:#FF9900
    classDef tooling fill:#F0F0F0,stroke:#AAAAAA
    classDef cli fill:#F8F8F8,stroke:#888888
    classDef infra fill:#EFEFEF,stroke:#666666
```
