# jpoirier/picoc architecture

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

- Interactive diagram: https://gitdiagram.com/jpoirier/picoc
- Repository: https://github.com/jpoirier/picoc

## Overview

##### Main Components (Core Architecture)

a) Lexical Analysis & Parsing Layer

b) Type System & Variable Management
- Create components for:
- Type System (type.c)
- Variable Handler (variable.c)
- Symbol Table (table.c)
- Heap Management (heap.c)
- Relationships between these components

c) Platform Abstraction Layer
- Platform-specific I/O (platform_unix.c, platform_msvc.c)
- Library implementations (library_unix.c, library_msvc.c)

d) Standard Library Implementation
- Core library functions (clibrary.c)
- Individual library modules (cstdlib/*.c files)
- Connection to the interpreter core

##### Data Flow

- Input source code → Lexer → Parser → Interpreter
- Symbol Table ↔ Variable Handler
- Platform Interface ↔ Core Components
- Standard Library ↔ Interpreter Core

##### Important Elements

a) Input/Output:
- Source code input
- Command-line interface
- Interactive mode
- Script execution mode

b) Memory Management:
- Heap allocation system
- Stack management
- Variable storage

c) Platform Abstraction:
- How platform-specific code is isolated
- Cross-platform compatibility

##### Additional Details

- Component types
- Version information

##### Implementation Notes

Annotations for:
- Stack size configuration
- Platform porting points
- Library extension mechanisms
- Supported data types

##### Testing Framework

How the extensive test suite (tests/ directory) interfaces with the system, but keep it separate from the main execution flow.

- The interpreter's compact nature (~3500 lines core)
- Platform independence
- Scripting capabilities
- Standard C library support
- Clear separation between core interpreter and platform-specific code

Remember to indicate the system's unique features:
- Interactive mode capabilities
- Script execution mode
- Variable deletion functionality
- Native C function integration
- Platform abstraction layer

This will create a comprehensive yet clear visualization of PicoC's architecture that highlights both its simplicity and functionality.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Input
        SRC[Source Code]
    end

    subgraph "Core Interpreter"
        direction TB
        LEX[Lexer]:::core
        PAR[Parser]:::core
        EXP[Expression Handler]:::core
        
        LEX --> PAR
        PAR --> EXP
    end

    subgraph "Type & Memory Management"
        direction TB
        TYP[Type System]:::core
        VAR[Variable Handler]:::core
        SYM[Symbol Table]:::core
        HEP[Heap Management]:::core
        
        TYP <--> VAR
        VAR <--> SYM
        HEP <--> VAR
    end

    subgraph "Platform Layer"
        direction TB
        subgraph "Platform Interface"
            PFU["Unix Platform"]:::platform
            PFM["MSVC Platform"]:::platform
        end
        
        subgraph "Platform Library"
            LBU["Unix Library"]:::platform
            LBM["MSVC Library"]:::platform
        end
    end

    subgraph "Standard Library"
        direction TB
        CLB[Core Library]:::stdlib
        subgraph "C Standard Modules"
            MATH["Math"]:::stdlib
            STR["String"]:::stdlib
            STDIO["Standard I/O"]:::stdlib
            STDLIB["Standard Lib"]:::stdlib
        end
    end

    subgraph "Testing & Debug"
        TST[Test Framework]:::test
        DBG[Debug Infrastructure]:::test
    end

    %% Main Flow
    SRC --> LEX
    EXP --> VAR
    
    %% Platform Connections
    PFU & PFM --> EXP
    LBU & LBM --> CLB
    
    %% Library Connections
    CLB --> |Uses| VAR
    MATH & STR & STDIO & STDLIB --> CLB

    %% Testing Connections
    TST --> LEX
    TST --> PAR
    DBG --> EXP

    %% Styling
    classDef core fill:#a8d1f0,stroke:#333
    classDef platform fill:#90EE90,stroke:#333
    classDef stdlib fill:#FFB347,stroke:#333
    classDef test fill:#D3D3D3,stroke:#333

    %% Click Events
    click LEX "https://github.com/jpoirier/picoc/blob/master/lex.c"
    click PAR "https://github.com/jpoirier/picoc/blob/master/parse.c"
    click EXP "https://github.com/jpoirier/picoc/blob/master/expression.c"
    click TYP "https://github.com/jpoirier/picoc/blob/master/type.c"
    click VAR "https://github.com/jpoirier/picoc/blob/master/variable.c"
    click SYM "https://github.com/jpoirier/picoc/blob/master/table.c"
    click HEP "https://github.com/jpoirier/picoc/blob/master/heap.c"
    click PFU "https://github.com/jpoirier/picoc/blob/master/platform/platform_unix.c"
    click PFM "https://github.com/jpoirier/picoc/blob/master/platform/platform_msvc.c"
    click LBU "https://github.com/jpoirier/picoc/blob/master/platform/library_unix.c"
    click LBM "https://github.com/jpoirier/picoc/blob/master/platform/library_msvc.c"
    click CLB "https://github.com/jpoirier/picoc/blob/master/clibrary.c"
    click MATH "https://github.com/jpoirier/picoc/blob/master/cstdlib/math.c"
    click STR "https://github.com/jpoirier/picoc/blob/master/cstdlib/string.c"
    click STDIO "https://github.com/jpoirier/picoc/blob/master/cstdlib/stdio.c"
    click STDLIB "https://github.com/jpoirier/picoc/blob/master/cstdlib/stdlib.c"
    click TST "https://github.com/jpoirier/picoc/tree/master/tests/"
    click DBG "https://github.com/jpoirier/picoc/blob/master/debug.c"
```
