# daftyon/easier-language architecture

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

- Interactive diagram: https://gitdiagram.com/daftyon/easier-language
- Repository: https://github.com/daftyon/easier-language

## Overview

##### Project Type & Purpose
- This is a domain-specific language implementation (a compiler/interpreter) named “EasierLang” (EL), complete with a CLI, build scripts, and packaging.
- Its goal is to take `.el` source files, perform lexical analysis, parsing, semantic analysis, and then either interpret them directly or package them into executables.

##### High-Level Components
A. CLI Frontend
– el_cli.py / main.py: Entry point for user commands (`el run`, `el build`, etc.)
– Dockerfile / quick_build.bat: Environment setup & containerized builds
B. Lexical Analyzer
– compiler/lexer.py: Tokenizes `.el` source into token stream (see tokens.py)
C. Parser & AST Builder
– compiler/parser.py: Parses tokens into an Abstract Syntax Tree (AST)
– utils/data_classes.py: Defines AST node data structures
D. Semantic Analyzer & Symbol Management
– compiler/semantic_analyzer.py: Enforces type rules, scoping
– compiler/symbol_table.py & compiler/scopes.py: Manage symbol tables and nested scopes
– utils/constants.py, utils/errors.py: Definitions & error handling support
E. Interpreter / Execution Engine
– compiler/interpreter.py: Walks the AST, executes statements, evaluates expressions, handles built-ins
– system/…: Built-in functions (system/builtin_functions), objects (system/objects)
F. Build & Packaging
– build_direct.py & build_executable.py: Scripts that bundle the interpreter and stdlib into a standalone package
– build/el/: Generated artifacts (pyz, toc, exe)
– setup.py / pyproject.toml: Python packaging & distribution
G. Examples & Tests
– examples/: Sample `.el` programs
– tests.py / src/test.el: Automated or manual tests

##### Component Interactions & Data Flow
– User invokes CLI → CLI parses flags → CLI calls the Compiler Driver (main.py)
– Driver loads source files from disk → passes text to Lexical Analyzer → produces token stream
– Token stream flows into Parser → builds AST
– AST flows into Semantic Analyzer → performs type checking and symbol resolution
– Either:
- Interpreter consumes checked AST → executes code and interacts with built-ins
- OR Build scripts consume the AST/bundled interpreter to produce standalone executables (EL packages)
– Errors at each phase bubble up to CLI → presented to user

##### Architectural Patterns & Principles
- Classic compiler pipeline: Lexing → Parsing → Semantic Analysis → Interpretation/Code Generation
- Clear separation of concerns:
– `compiler/` for all language processors
– `system/` for runtime library & built-ins
– `utils/` for shared data structures & error handling
- Packaging layer sits orthogonal to language pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontend
    subgraph "CLI Frontend"
        direction TB
        El_CLI["el_cli.py / main.py"]:::frontend
        Docker["Dockerfile / quick_build.bat"]:::frontend
    end

    %% Source Code Artifact
    Source_Code["Source Code (.el)"]:::artifact

    %% Compiler Core
    subgraph "Compiler Core"
        direction TB
        Lexer["Lexer\n(compiler/lexer.py)"]:::core
        Parser["Parser\n(compiler/parser.py)"]:::core
        AST["AST\n(utils/data_classes.py)"]:::artifact
        subgraph "Semantic Analyzer & Symbol Management"
            direction TB
            Semi["Semantic Analyzer\n(compiler/semantic_analyzer.py)"]:::core
            SymTable["Symbol Table\n(compiler/symbol_table.py)"]:::core
            Scopes["Scopes\n(compiler/scopes.py)"]:::core
            Consts["Constants\n(utils/constants.py)"]:::core
            Errs["Errors\n(utils/errors.py)"]:::core
        end
        Interpreter["Interpreter\n(compiler/interpreter.py)"]:::core
    end

    %% Runtime Library
    subgraph "Runtime Library"
        direction TB
        Builtins["Built-in Functions\n(system/builtin_functions/main.py)"]:::runtime
        Objects["Objects\n(system/objects/main.py)"]:::runtime
        Reserved["Reserved Names\n(system/reserved.py)"]:::runtime
    end

    %% Packaging Layer
    subgraph "Build & Packaging"
        direction TB
        BuildDirect["build_direct.py"]:::packaging
        BuildExe["build_executable.py"]:::packaging
        Artifacts["Artifacts (build/el/)"]:::artifact
        Config["Packaging Config\n(setup.py, pyproject.toml)"]:::packaging
    end

    %% Examples & Tests
    subgraph "Examples & Tests"
        direction TB
        Examples["examples/"]:::external
        TestScript["tests.py"]:::external
        TestSrc["src/test.el"]:::external
    end

    %% Connections
    El_CLI -->|"runs"| Source_Code
    Source_Code -->|"text input"| Lexer
    Lexer -->|"tokens"| Parser
    Parser -->|"AST"| AST
    AST -->|"untyped AST"| Semi
    Semi -->|"checked AST"| Interpreter
    Interpreter -->|"calls"| Builtins
    Interpreter -->|"uses"| Objects
    Interpreter -->|"refers"| Reserved
    AST -->|"AST for packaging"| BuildDirect
    Interpreter -->|"embed interpreter"| BuildExe
    BuildDirect -->|"generates"| Artifacts
    BuildExe -->|"generates"| Artifacts
    Config --> Artifacts
    El_CLI -->|"executes tests"| TestScript
    TestScript -->|"runs example"| TestSrc
    TestSrc --> Source_Code
    Examples --> Source_Code

    %% Click Events
    click El_CLI "https://github.com/daftyon/easier-language/blob/main/el_cli.py"
    click Docker "https://github.com/daftyon/easier-language/tree/main/Dockerfile"
    click Lexer "https://github.com/daftyon/easier-language/blob/main/compiler/lexer.py"
    click Parser "https://github.com/daftyon/easier-language/blob/main/compiler/parser.py"
    click AST "https://github.com/daftyon/easier-language/blob/main/utils/data_classes.py"
    click Semi "https://github.com/daftyon/easier-language/blob/main/compiler/semantic_analyzer.py"
    click SymTable "https://github.com/daftyon/easier-language/blob/main/compiler/symbol_table.py"
    click Scopes "https://github.com/daftyon/easier-language/blob/main/compiler/scopes.py"
    click Consts "https://github.com/daftyon/easier-language/blob/main/utils/constants.py"
    click Errs "https://github.com/daftyon/easier-language/blob/main/utils/errors.py"
    click Interpreter "https://github.com/daftyon/easier-language/blob/main/compiler/interpreter.py"
    click Builtins "https://github.com/daftyon/easier-language/blob/main/system/builtin_functions/main.py"
    click Objects "https://github.com/daftyon/easier-language/blob/main/system/objects/main.py"
    click Reserved "https://github.com/daftyon/easier-language/blob/main/system/reserved.py"
    click BuildDirect "https://github.com/daftyon/easier-language/blob/main/build_direct.py"
    click BuildExe "https://github.com/daftyon/easier-language/blob/main/build_executable.py"
    click Artifacts "https://github.com/daftyon/easier-language/tree/main/build/el/"
    click Config "https://github.com/daftyon/easier-language/blob/main/setup.py"
    click Examples "https://github.com/daftyon/easier-language/tree/main/examples/"
    click TestScript "https://github.com/daftyon/easier-language/blob/main/tests.py"
    click TestSrc "https://github.com/daftyon/easier-language/blob/main/src/test.el"

    %% Styles
    classDef frontend fill:#CFE2F3,stroke:#333,stroke-width:1px
    classDef core fill:#D9EAD3,stroke:#333,stroke-width:1px
    classDef packaging fill:#F9CB9C,stroke:#333,stroke-width:1px
    classDef runtime fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef artifact fill:#EAD1DC,stroke:#333,stroke-width:1px
    classDef external fill:#F4CCCC,stroke:#333,stroke-width:1px
```
