# nathan4044/c-lisp-interpreter architecture

> Architecture diagram of the GitHub repository nathan4044/c-lisp-interpreter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nathan4044/c-lisp-interpreter
- Repository: https://github.com/nathan4044/c-lisp-interpreter

## Overview

Key Components to Include:

##### Scanner/Lexer Component (scanner.c/h)
- First stage of interpretation
- Converts source text into tokens
- Should be represented as the entry point

##### Compiler Component (compiler.c/h)
- Transforms tokens into bytecode
- Works with chunks of code
- Interfaces with memory management

##### Virtual Machine (vm.c/h)
- Core execution engine
- Interprets the bytecode
- Manages runtime environment

##### Memory Management System (memory.c/h)
- Handles allocation and garbage collection
- Supports both the compiler and VM

##### Object System (object.c/h)
- Represents Lisp data types
- Manages runtime objects

##### Value System (value.c/h)
- Handles different value types
- Works closely with the object system

##### Hash Table Implementation (table.c/h)
- Supports symbol tables and environment

##### Native Functions (nativeFns.c/h)
- Built-in function implementation
- Extends VM functionality

##### Supporting systems as parallel components
- Memory Manager (connected to all major components)
- Object System (connected to VM and Compiler)
- Hash Tables (connected to VM and Compiler)
- Native Functions (connected to VM)

- Blue: Core pipeline components (Scanner, Compiler, VM)
- Green: Memory management and storage (Memory Manager, Hash Tables)
- Yellow: Data representation (Object System, Value System)
- Purple: Runtime support (Native Functions)

Relationships to Show:
- Source text → Scanner → Tokens → Compiler → Bytecode → VM → Execution

- Memory Manager ↔ All Components
- Object System ↔ VM
- Object System ↔ Compiler
- Hash Tables ↔ VM
- Native Functions → VM

Additional Elements:
##### Debug System (debug.c/h)
- As a cross-cutting concern

##### Chunk System (chunk.c/h)
- As part of the compiler output
- Represents the bytecode container

##### Brief notes describing key interactions

Level of Detail:
- Keep component internals abstract
- Inter-component communication
- LISP-specific features
- Memory management interaction points

##### The relationship between objects and values

This design reflects a traditional interpreter architecture while highlighting the specific requirements of a Lisp implementation, such as symbol management and garbage collection.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Main Pipeline
    Source[Source Code]
    Scanner[Scanner/Lexer]:::core
    Compiler[Compiler]:::core
    VM[Virtual Machine]:::core
    Output[Program Output]
    
    %% Support Systems
    MemMgr[Memory Manager]:::memory
    ObjSys[Object System]:::data
    ValueSys[Value System]:::data
    HashTbl[Hash Tables]:::memory
    NativeFn[Native Functions]:::runtime
    Debug[Debug System]:::support
    Chunk[Chunk System]:::memory

    %% Main Flow
    Source --> Scanner
    Scanner --> |Tokens| Compiler
    Compiler --> |Bytecode| Chunk
    Chunk --> VM
    VM --> Output

    %% Memory Manager Connections
    MemMgr -.-> Scanner
    MemMgr -.-> Compiler
    MemMgr -.-> VM
    MemMgr -.-> ObjSys
    MemMgr -.-> HashTbl

    %% Object and Value System
    ObjSys <--> VM
    ObjSys <--> Compiler
    ValueSys <--> ObjSys
    ValueSys <--> VM

    %% Hash Tables and Native Functions
    HashTbl <--> VM
    HashTbl <--> Compiler
    NativeFn --> VM

    %% Debug System
    Debug -.- Scanner
    Debug -.- Compiler
    Debug -.- VM
    Debug -.- Chunk

    %% Styling
    classDef core fill:#a8d1f0,stroke:#333
    classDef memory fill:#90EE90,stroke:#333
    classDef data fill:#FFE5B4,stroke:#333
    classDef runtime fill:#DDA0DD,stroke:#333
    classDef support fill:#D3D3D3,stroke:#333

    %% Click Events
    click Scanner "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/scanner.c"
    click Compiler "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/compiler.c"
    click VM "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/vm.c"
    click MemMgr "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/memory.c"
    click ObjSys "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/object.c"
    click ValueSys "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/value.c"
    click HashTbl "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/table.c"
    click NativeFn "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/nativeFns.c"
    click Debug "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/debug.c"
    click Chunk "https://github.com/Nathan4044/c-lisp-interpreter/blob/main/chunk.c"

    %% Legend
    subgraph Legend
        CoreComp[Core Components]:::core
        MemComp[Memory Components]:::memory
        DataComp[Data Components]:::data
        RuntimeComp[Runtime Components]:::runtime
        SupportComp[Support Components]:::support
    end
```
