# hari4742/pylox architecture

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

- Interactive diagram: https://gitdiagram.com/hari4742/pylox
- Repository: https://github.com/hari4742/pylox

## Overview

##### Project Identification and Purpose
- Pylox is a Python-based frontend for a Lox interpreter inspired by “Crafting Interpreters.” The primary purpose is to read Lox source code and process it through tokenization (lexical analysis), parsing (AST generation), and evaluation (interpreting expressions and statements).
- It handles error reporting and variable scoping and supports features like an AST printer and command-line interfaces (CLI) for different operations (tokenize, parse, evaluate).

##### Analysis of the File Structure
- Directories:
- The “lox/” directory holds the core interpreter modules. Notable files include:
- scanner.py – Responsible for tokenizing Lox source code.
- parser.py – Implements the recursive descent parser to build an AST.
- expr.py & stmt.py – Define AST node structures.
- interpreter.py – Contains the evaluation logic of the AST.
- ast_printer.py – For visual representation of the AST.
- environment.py – Manages variable scoping.
- Additional modules for error and function handling (error.py, return_error.py, lox_callable.py, lox_function.py).
- The “app/” directory (e.g., main.py) likely contains higher-level logic or could be targeting a graphical/alternative interface.
- “examples/” holds Lox scripts (like script.lox) for testing and demo purposes.
- “tool/” contains helper scripts such as generate_ast.py for generating AST node definitions.
- Top-level files like pylox.py and pylox-cli.py are entry points for running the interpreter and command executions respectively.
- Build/configuration scripts (e.g., Pipfile, requirements.txt) clarify dependency management.

##### Main Architectural Components
- Frontend CLI:
- pylox-cli.py: Provides a command-based interface to tokenize, parse, or evaluate Lox scripts.
- pylox.py: Acts as the main entrypoint for running Lox programs.
- Core Interpreter (located in “lox/”):
- Scanner Component: Scans raw source code into tokens.
- Parser Component: Processes tokens and constructs the AST using grammar defined in the README.
- AST and Node Management: Modules like expr.py, stmt.py, and ast_printer.py define and/or display the abstract syntax tree.
- Interpreter/Evaluation Component: Interpreter logic executes the AST, applies variable scoping (environment.py), and handles runtime evaluation.
- Error Handling: error.py and return_error.py are used to report syntax and runtime exceptions.
- Functionality for Lox callable entities: lox_callable.py and lox_function.py manage function definitions and calls.
- Utilities & Build Tools:
- The “tool/” directory’s generate_ast.py script aids in generating AST classes based on specific grammar inputs.

##### Relationships and Data Flow
- The CLI (pylox-cli.py/pylox.py) acts as the user entry point that receives a Lox script.
- The script is first processed by the Scanner to generate a token stream.
- The Parser takes these tokens and builds the AST (with potential visualization via ast_printer.py).
- The Interpreter then traverses the AST to evaluate expressions and execute statements.
- Supporting components like the Environment keep track of scopes, and error modules ensure robustness.
- Data flows from the source input to tokenization, then to parsing (AST generation), and finally to evaluation, with clear error-handling pathways at each stage.

##### Architectural Patterns & Design Principles
- Modular Separation: The project cleanly separates the lexical analysis, parsing, and evaluation phases.
- Layered Architecture: Each processing stage (scanning, parsing, interpretation) is encapsulated in its own module, which simplifies debugging and extension.
- Command Pattern (via CLI): Different CLI commands (tokenize, parse, evaluate) trigger different functionalities while leveraging the same core components.
- Utilization of the visitor pattern or similar (implied by AST printer and interpreter traversals) to handle nodes uniformly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer Subgraph
    subgraph "CLI Layer"
        cli1["pylox-cli.py"]:::cli
        cli2["pylox.py"]:::cli
    end

    %% Test Scripts Subgraph
    subgraph "Test Scripts"
        ex["Lox Script Samples"]:::input
    end

    %% Core Interpreter Subgraph
    subgraph "Core Interpreter"
        scn["Scanner"]:::core
        subgraph "AST Builder"
            prs["Parser"]:::core
            exp["Expressions (AST)"]:::core
            stm["Statements (AST)"]:::core
            astp["AST Printer"]:::core
        end
        intp["Interpreter"]:::core
        env["Environment"]:::core
        callbl["Callable Interface"]:::core
        lfunc["Function Handler"]:::core
        err["Error Manager"]:::error
        rerr["Return/Error Handler"]:::error
    end

    %% Utilities Subgraph
    subgraph "Utilities"
        gen["AST Generator"]:::util
    end

    %% Data Flow Connections
    ex -->|"provides"| cli1
    ex -->|"provides"| cli2

    cli1 -->|"reads script"| scn
    cli2 -->|"reads script"| scn

    scn -->|"tokenizes"| prs
    scn -->|"error"| err

    prs -->|"builds AST"| intp
    prs -->|"defines"| exp
    prs -->|"defines"| stm
    prs -->|"visualizes"| astp
    prs -->|"error"| err

    gen ---|"generates"| exp
    gen ---|"generates"| stm
    gen ---|"generates"| astp

    intp -->|"evaluates"| env
    intp -->|"reports"| err
    intp -->|"handles"| rerr
    intp -->|"calls"| callbl

    callbl -->|"manages"| lfunc

    %% Styles
    classDef cli fill:#a7d8de,stroke:#333,stroke-width:2px;
    classDef core fill:#f4d03f,stroke:#333,stroke-width:2px;
    classDef util fill:#82e0aa,stroke:#333,stroke-width:2px;
    classDef input fill:#fad7a0,stroke:#333,stroke-width:2px;
    classDef error fill:#f1948a,stroke:#333,stroke-width:2px;

    %% Click Events
    click cli1 "https://github.com/hari4742/pylox/blob/master/pylox-cli.py"
    click cli2 "https://github.com/hari4742/pylox/blob/master/pylox.py"
    click scn "https://github.com/hari4742/pylox/blob/master/lox/scanner.py"
    click prs "https://github.com/hari4742/pylox/blob/master/lox/parser.py"
    click exp "https://github.com/hari4742/pylox/blob/master/lox/expr.py"
    click stm "https://github.com/hari4742/pylox/blob/master/lox/stmt.py"
    click astp "https://github.com/hari4742/pylox/blob/master/lox/ast_printer.py"
    click intp "https://github.com/hari4742/pylox/blob/master/lox/interpreter.py"
    click env "https://github.com/hari4742/pylox/blob/master/lox/environment.py"
    click err "https://github.com/hari4742/pylox/blob/master/lox/error.py"
    click rerr "https://github.com/hari4742/pylox/blob/master/lox/return_error.py"
    click callbl "https://github.com/hari4742/pylox/blob/master/lox/lox_callable.py"
    click lfunc "https://github.com/hari4742/pylox/blob/master/lox/lox_function.py"
    click gen "https://github.com/hari4742/pylox/blob/master/tool/generate_ast.py"
    click ex "https://github.com/hari4742/pylox/tree/master/examples/"
```
