# masoom-wahid/drlang architecture

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

- Interactive diagram: https://gitdiagram.com/masoom-wahid/drlang
- Repository: https://github.com/masoom-wahid/drlang

## Overview

##### Main Components
- Input Source Code: Represent the source code files (as seen in the examples folder) that the language will process.
- Scanner (Lexical Analyzer): Use the “scanner.h/c” files as the module that tokenizes the input code.
- Compiler (Parser and Bytecode Generator): Based on “compiler.h/c”, it takes tokenized inputs and produces a “chunk” of bytecode (see also “chunk.h/c” that describes the bytecode data structure).
- Bytecode Chunk: Represents the in-memory representation where the code is stored post-compilation.
- Virtual Machine (VM): The “vm.h/c” files implement the runtime engine that reads and executes the bytecode.
- Memory Management & Object System: Modules under “memory.c”, “object.c”, and “table.c” provide the infrastructure for managing values, dynamic objects, and hash table operations for variable storage or interned strings.
- Debugging Tools: The “debug.h/c” files give you support for logging or debugging the bytecode execution.

##### Relationships and Interactions
- The system starts with the main entry point (“main.c”), which reads a source file.
- It passes the raw text to the Scanner, which tokenizes the input.
- The Compiler then converts these tokens into a Chunk (a container for bytecode instructions).
- The Virtual Machine (VM) interprets the Chunk, making calls to the memory and object management modules during execution.
- The Debug module can optionally tap into both compilation and execution phases to provide useful logs.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project cleanly separates lexing, parsing/compilation, and runtime execution.
- Layered Architecture: There is a clear input → processing (scanner/compiler) → execution (vm) pipeline.
- Modularity: Independent modules (scanner, compiler, vm, memory, debugging) make the system easier to maintain and extend. This is crucial as the language is still in active development.
- Data Encapsulation: The “chunk” represents compiled bytecode with well-defined boundaries between compilation and execution layers.

##### Relevant Technologies, Frameworks, and Libraries
- Language: C (with GCC as required by the README).
- Build System: A makefile is used to compile the project.
- Standard C libraries for memory management, I/O, etc.

- Start at the top left with the “Source Code (Examples)”.
- From the Compiler, output flows into a “Chunk” container.
- The “Chunk” then feeds into the “Virtual Machine” which is the execution engine.
- Optionally, add a side branch from both the Compiler and VM to a “Debug” module, indicating cross-cutting tracing/logging functionality.
- Finally, indicate that the final output (if any) is sent through I/O (i.e., the “parto” or print statements in the language).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Main["Main Entry Point"]:::misc
    Input["Source Code (Examples)"]:::input

    subgraph "Compile-Time"
        Scanner["Scanner (Lexical Analyzer)"]:::compile
        Compiler["Compiler (Parser & Bytecode Generator)"]:::compile
        Chunk["Bytecode Chunk"]:::compile
    end

    subgraph "Run-Time"
        VM["Virtual Machine (VM)"]:::runtime
        Memory["Memory Management"]:::runtime
        Objects["Object System & Table Management"]:::runtime
        Debug["Debugging Tools"]:::runtime
    end

    Main -->|"Reads_source"| Input
    Input -->|"Tokenizes"| Scanner
    Scanner -->|"SendsTokens"| Compiler
    Compiler -->|"Generates_Bytecode"| Chunk
    Chunk -->|"Feeds_to_VM"| VM
    VM -->|"Uses_Memory"| Memory
    VM -->|"Handles_Objects"| Objects
    VM -->|"Logs_via_Debug"| Debug
    Compiler -->|"Emits_Debug_Info"| Debug

    click Input "https://github.com/masoom-wahid/drlang/tree/main/examples/"
    click Scanner "https://github.com/masoom-wahid/drlang/blob/main/include/scanner.h"
    click Scanner "https://github.com/masoom-wahid/drlang/blob/main/src/scanner.c"
    click Compiler "https://github.com/masoom-wahid/drlang/blob/main/include/compiler.h"
    click Compiler "https://github.com/masoom-wahid/drlang/blob/main/src/compiler.c"
    click Chunk "https://github.com/masoom-wahid/drlang/blob/main/include/chunk.h"
    click Chunk "https://github.com/masoom-wahid/drlang/blob/main/src/chunk.c"
    click VM "https://github.com/masoom-wahid/drlang/blob/main/include/vm.h"
    click VM "https://github.com/masoom-wahid/drlang/blob/main/src/vm.c"
    click Memory "https://github.com/masoom-wahid/drlang/blob/main/include/memory.h"
    click Memory "https://github.com/masoom-wahid/drlang/blob/main/src/memory.c"
    click Objects "https://github.com/masoom-wahid/drlang/blob/main/include/object.h"
    click Objects "https://github.com/masoom-wahid/drlang/blob/main/src/object.c"
    click Objects "https://github.com/masoom-wahid/drlang/blob/main/include/table.h"
    click Objects "https://github.com/masoom-wahid/drlang/blob/main/src/table.c"
    click Debug "https://github.com/masoom-wahid/drlang/blob/main/include/debug.h"
    click Debug "https://github.com/masoom-wahid/drlang/blob/main/src/debug.c"
    click Main "https://github.com/masoom-wahid/drlang/blob/main/src/main.c"

    classDef input fill:#F0F8FF,stroke:#1E90FF,stroke-width:2px;
    classDef compile fill:#E6FFE6,stroke:#32CD32,stroke-width:2px;
    classDef runtime fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
    classDef misc fill:#E0FFFF,stroke:#008B8B,stroke-width:2px;
```
