# sheunl/phloxlang architecture

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

- Interactive diagram: https://gitdiagram.com/sheunl/phloxlang
- Repository: https://github.com/sheunl/phloxlang

## Overview

Based on your file tree and README, this repository is a “learning playground” for building simple compilers and interpreters, following ideas from the “Crafting Interpreters” book. In fact, you have two distinct implementations: one in PHP (named “phlox”) and another in Rust (named “rlox”). The PHP version appears to be a complete interpreter with components for scanning, parsing, building an abstract syntax tree (AST) through expression and statement classes, and handling runtime concerns (such as environments, errors, and function/class representation). Meanwhile, the Rust version is a more compact implementation dealing with chunks, memory, debugging, and the overall flow (as seen in main.rs).

- Overall Project – “Basic Compilers” or “Interpreters”
- PHP-based implementation (“phlox”)
- Rust-based implementation (“rlox”)

##### For the PHP implementation (phlox), highlight the following components
a. Lexical Analysis & Scanning:
– Module: Scanner (phlox/src/Phlox/Scanner.php)
– Role: Tokenizing the source code
b. Parsing & AST Construction:
– Modules: Parser (phlox/src/Phlox/Parser.php), and AST nodes under Expr (e.g., Binary, Literal, Grouping, etc.) and Stmt directories (e.g., Expression, If_.php, While_.php, etc.)
– Role: Converting tokens into an AST representation
c. Semantic Analysis:
– Module: Resolver (phlox/src/Phlox/Resolver.php)
– Role: Managing scope rules and resolving variable references
d. Interpreter Runtime:
– Modules: Interpreter (phlox/src/Phlox/Interpreter.php) and Environment (phlox/src/Phlox/Environment.php)
– Role: Executing the AST and managing runtime environments
e. Object Model & Data Structures:
– Core Types: LoxCallable, LoxClass, LoxFunction, LoxInstance, ClassType, FunctionType
– Data Structures: Custom implementations of Map and Stack (phlox/src/Phlox/DS)
f. Error Handling & Support:
– RuntimeError and Return_ modules to manage exceptions and returns from functions
g. Tooling & Testing:
– Tools directory for code generation or packaging (GenerateAst.php, PharBuilder.php)
– Extensive tests (unit, feature, and performance tests) under phlox/test

##### For the Rust implementation (rlox), include
a. Core Entry Point and Management:
– Main module (rlox/src/main.rs) as the central entry point
b. Code execution and memory:
– Chunk management (rlox/src/chunk.rs) representing instructions or bytecode sequences
– Memory management (rlox/src/memory.rs) to handle runtime allocations or garbage collection aspects
c. Debugging:
– Debug functionalities (rlox/src/debug.rs)
– Emphasize the separation of concerns, where the entry point orchestrates the lower-level processing modules

– Scanner → Parser → Resolver → Interpreter (depicting execution order in phlox)
– Main → Chunk/Memory/Debug in rlox flows.
- Dependencies like the Parser’s reliance on tokens from the Scanner, and the Interpreter’s dependency on the AST produced by the Parser.
- How testing modules interact with these core components, ensuring correctness and performance verification.

##### Architectural Patterns and Design Principles
- That the PHP implementation follows an interpreter pattern with clearly separated phases (lexing, parsing, semantic analysis, interpretation) and adheres to an AST visitor design pattern (seen in the Expr/Visitor.php and Stmt/Visitor.php).
- The modular design in both implementations reflects separation of concerns and makes it easier to extend or replace modules (for instance, swapping out the Scanner or adding new types of AST nodes).

## Diagram (Mermaid)

```mermaid
flowchart TD
    P["Basic Compilers/Interpreters"]:::project
    PHP_D["PHP Implementation (phlox)"]:::php
    RUST_D["Rust Implementation (rlox)"]:::rust

    P --> PHP_D
    P --> RUST_D

    %% PHP Components
    subgraph "PHP Components"
        direction TB
        %% Lexical Analysis & Parsing
        subgraph "Lexical Analysis & Parsing"
            direction TB
            SC("Scanner"):::lex
            PS("Parser"):::parse
            SC -->|"tokenizes"| PS
        end
        %% AST & Semantic Analysis
        subgraph "AST & Semantic Analysis"
            direction TB
            EX("Expression AST"):::ast
            ST("Statement AST"):::ast
            RS("Resolver"):::semantic
            PS -->|"buildsAST"| EX
            PS -->|"buildsAST"| ST
            EX --> RS
            ST --> RS
        end
        %% Interpreter Runtime
        subgraph "Interpreter Runtime"
            direction TB
            IT("Interpreter"):::runtime
            ENV("Environment"):::runtime
            RS --> IT
            IT --> ENV
        end
        %% Object Model & Data Structures
        subgraph "Object Model & Data Structures"
            direction TB
            LC("LoxCallable"):::model
            LCL("LoxClass"):::model
            LF("LoxFunction"):::model
            LI("LoxInstance"):::model
            CT("ClassType"):::model
            FT("FunctionType"):::model
            MP("Map"):::ds
            STK("Stack"):::ds
            IT --> LC
            IT --> LCL
            IT --> LF
            IT --> LI
            IT --> CT
            IT --> FT
            IT --> MP
            IT --> STK
        end
        %% Error Handling
        subgraph "Error Handling"
            direction TB
            RE("RuntimeError"):::error
            RT("Return_"):::error
            IT --> RE
            IT --> RT
        end
        %% Tooling & Testing
        subgraph "Tooling & Testing"
            direction TB
            GA("GenerateAst"):::tool
            PB("PharBuilder"):::tool
            TS("Tests"):::test
            SC --> GA
            GA --> PB
            PB --> TS
        end
    end

    %% Rust Components
    subgraph "Rust Components"
        direction TB
        MA("Main"):::rust
        CH("Chunk"):::rust
        MEM("Memory"):::rust
        DB("Debug"):::rust
        MA -->|"calls"| CH
        MA -->|"calls"| MEM
        MA -->|"calls"| DB
    end

    %% Connecting implementation headers to their components
    PHP_D --> SC
    RUST_D --> MA

    %% Styles
    classDef project fill:#F0B27A,stroke:#7D6608,stroke-width:2px;
    classDef php fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef lex fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px;
    classDef parse fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px;
    classDef ast fill:#FCF3CF,stroke:#B7950B,stroke-width:1px;
    classDef semantic fill:#FAD7A0,stroke:#AF601A,stroke-width:1px;
    classDef runtime fill:#D5F5E3,stroke:#196F3D,stroke-width:1px;
    classDef model fill:#F9E79F,stroke:#B7950B,stroke-width:1px;
    classDef ds fill:#FDEDEC,stroke:#922B21,stroke-width:1px;
    classDef error fill:#F5B7B1,stroke:#943126,stroke-width:1px;
    classDef tool fill:#D2B4DE,stroke:#6C3483,stroke-width:1px;
    classDef test fill:#FADBD8,stroke:#C0392B,stroke-width:1px;
    classDef rust fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;

    %% Click Events
    click P "https://github.com/sheunl/phloxlang/tree/main/root"
    click PHP_D "https://github.com/sheunl/phloxlang/tree/main/phlox/"
    click SC "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/Scanner.php"
    click PS "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/Parser.php"
    click EX "https://github.com/sheunl/phloxlang/tree/main/phlox/src/Phlox/Expr/"
    click ST "https://github.com/sheunl/phloxlang/tree/main/phlox/src/Phlox/Stmt/"
    click RS "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/Resolver.php"
    click IT "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/Interpreter.php"
    click ENV "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/Environment.php"
    click LC "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/LoxCallable.php"
    click LCL "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/LoxClass.php"
    click LF "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/LoxFunction.php"
    click LI "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/LoxInstance.php"
    click CT "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/ClassType.php"
    click FT "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/FunctionType.php"
    click MP "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/DS/Map.php"
    click STK "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/DS/Stack.php"
    click RE "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/RuntimeError.php"
    click RT "https://github.com/sheunl/phloxlang/blob/main/phlox/src/Phlox/Return_.php"
    click GA "https://github.com/sheunl/phloxlang/blob/main/phlox/tools/GenerateAst.php"
    click PB "https://github.com/sheunl/phloxlang/blob/main/phlox/tools/PharBuilder.php"
    click TS "https://github.com/sheunl/phloxlang/tree/main/phlox/test/"

    click RUST_D "https://github.com/sheunl/phloxlang/tree/main/rlox/"
    click MA "https://github.com/sheunl/phloxlang/blob/main/rlox/src/main.rs"
    click CH "https://github.com/sheunl/phloxlang/blob/main/rlox/src/chunk.rs"
    click MEM "https://github.com/sheunl/phloxlang/blob/main/rlox/src/memory.rs"
    click DB "https://github.com/sheunl/phloxlang/blob/main/rlox/src/debug.rs"
```
