# verse-lang/verse architecture

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

- Interactive diagram: https://gitdiagram.com/verse-lang/verse
- Repository: https://github.com/verse-lang/verse

## Overview

##### Project type and purpose
- This is a compiler project (“The Verse Programming Language”) split into several sub-areas:
- A C++-based compiler implementation (in cpp-compiler/)
- Verse standard library modules (in std/)
- Example Verse programs (in examples/)
- An editor integration/grammar definition (in language-verse/)
- Purpose: take .vrs source code, lex/parse it, perform semantic analysis, emit LLVM IR, run it through LLVM optimizer, and produce a native executable.

##### File structure
- Top-level directories:
- cpp-compiler/: all compiler source (.hpp, main.cpp, lex.hpp, parse.hpp, test.cpp)
- std/: prewritten Verse standard modules (.vrs files)
- examples/: sample Verse programs
- language-verse/: grammar (verse.cson), editor settings, styles, package.json
- The compiler directory clearly follows a traditional compiler pipeline: lexing (Token.hpp, lex.hpp), parsing (Expression.hpp, parse.hpp), symbol management (Scope.hpp, NamedValue.hpp, IDGenerator.hpp), intermediate structure (StringTree.hpp, Match.hpp), and I/O (File.hpp, Stream.hpp).
- No build scripts at top level; README instructs manual g++ compile inside cpp-compiler/.

##### README for additional insights
- Confirms design: compile to LLVM IR and run optimizer for best performance.
- States current stage: pre-alpha, self-hosting is a future milestone.
- Build step is simply “g++ main.cpp” inside cpp-compiler/.

##### Elements
- From “Examples & User Code” and “std/ modules” into “Lexer”.
- From “Lexer” to “Parser”, then to “Semantic Analyzer”, then to “Code Generator”, then to “LLVM Optimizer/Backend”, then to “Executable Output”.
- Another for I/O/loader components (e.g., green) like std loader and examples.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Compiler Pipeline"
        CLI["CLI Frontend"]:::compilerPhase
        Lex["Lexical Analyzer"]:::compilerPhase
        Parser["Parser"]:::compilerPhase
        Semantic["Semantic Analyzer"]:::compilerPhase
        IR["Intermediate Representation (AST/IR)"]:::compilerPhase
        CodeGen["Code Generator"]:::compilerPhase
        LLVM["LLVM Optimizer/Backend"]:::compilerPhase
        Exec["Executable Output"]:::compilerPhase
    end

    subgraph "I/O & Library"
        Examples["Examples & User Code"]:::loader
        Std["Standard Library Loader"]:::loader
    end

    subgraph "Utilities"
        File["File.hpp"]:::util
        Stream["Stream.hpp"]:::util
        String["String.hpp"]:::util
        Typedefs["typedefs.hpp"]:::util
    end

    subgraph "Editor Support"
        Grammar["Grammar (verse.cson)"]:::editor
        Editor["Editor Integration"]:::editor
    end

    Examples -->|reads source| CLI
    CLI -->|invokes lexer| Lex
    Std -->|load modules| Semantic
    Lex -->|Token Stream| Parser
    Parser -->|AST| Semantic
    Semantic -->|Annotated AST| IR
    IR -->|walk IR| CodeGen
    CodeGen -->|LLVM IR| LLVM
    LLVM -->|native executable| Exec
    Grammar -->|provides syntax| Editor

    File --> CLI
    File --> Lex
    File --> Parser
    File --> Semantic
    File --> CodeGen

    Stream --> CLI
    String --> CLI
    Typedefs --> CLI

    classDef compilerPhase fill:#ADD8E6,stroke:#000
    classDef loader fill:#90EE90,stroke:#000
    classDef util fill:#D3D3D3,stroke:#000
    classDef editor fill:#FFA500,stroke:#000

    click CLI "https://github.com/verse-lang/verse/blob/master/cpp-compiler/main.cpp"
    click Lex "https://github.com/verse-lang/verse/blob/master/cpp-compiler/lex.hpp"
    click Lex "https://github.com/verse-lang/verse/blob/master/cpp-compiler/Token.hpp"
    click Parser "https://github.com/verse-lang/verse/blob/master/cpp-compiler/parse.hpp"
    click Parser "https://github.com/verse-lang/verse/blob/master/cpp-compiler/Expression.hpp"
    click Semantic "https://github.com/verse-lang/verse/blob/master/cpp-compiler/Scope.hpp"
    click Semantic "https://github.com/verse-lang/verse/blob/master/cpp-compiler/NamedValue.hpp"
    click Semantic "https://github.com/verse-lang/verse/blob/master/cpp-compiler/IDGenerator.hpp"
    click Semantic "https://github.com/verse-lang/verse/blob/master/cpp-compiler/HashTable.hpp"
    click IR "https://github.com/verse-lang/verse/blob/master/cpp-compiler/StringTree.hpp"
    click IR "https://github.com/verse-lang/verse/blob/master/cpp-compiler/Match.hpp"
    click IR "https://github.com/verse-lang/verse/blob/master/cpp-compiler/Class.hpp"
    click CodeGen "https://github.com/verse-lang/verse/blob/master/cpp-compiler/main.cpp"
    click Std "https://github.com/verse-lang/verse/blob/master/cpp-compiler/loadFile.hpp"
    click Std "https://github.com/verse-lang/verse/tree/master/std/"
    click Examples "https://github.com/verse-lang/verse/tree/master/examples/"
    click Grammar "https://github.com/verse-lang/verse/blob/master/language-verse/grammars/verse.cson"
    click Editor "https://github.com/verse-lang/verse/blob/master/language-verse/settings/language-verse.cson"
    click Editor "https://github.com/verse-lang/verse/blob/master/language-verse/styles/base.less"
    click Editor "https://github.com/verse-lang/verse/blob/master/language-verse/package.json"
    click File "https://github.com/verse-lang/verse/blob/master/cpp-compiler/File.hpp"
    click Stream "https://github.com/verse-lang/verse/blob/master/cpp-compiler/Stream.hpp"
    click String "https://github.com/verse-lang/verse/blob/master/cpp-compiler/String.hpp"
    click Typedefs "https://github.com/verse-lang/verse/blob/master/cpp-compiler/typedefs.hpp"
```
