# arithy/packcc architecture

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

- Interactive diagram: https://gitdiagram.com/arithy/packcc
- Repository: https://github.com/arithy/packcc

## Overview

##### Project type and purpose
- This is PackCC, an open-source **command-line parser generator tool** written in C.
- You feed it a grammar in PEG format, and it spits out a C parser (a .c and .h file) that uses packrat parsing with left-recursion support.

##### File structure
- **src/packcc.c**: the single core source file implementing CLI, parsing the PEG, building an AST, and emitting C code.
- **import/**: reusable grammar fragments (e.g., Unicode rules, AST support).
- **examples/**: sample grammars and driver programs (calculator, tiny-C compiler).
- **tests/**: Bats scripts and helper files to verify correct parser behavior.
- **benchmark/**: scripts and sample inputs to measure performance.
- **CMakeLists.txt** and **.github/workflows/**: build system and CI.

##### README for insights
- Confirms the pipeline:
1. Read PEG grammar (+ `%import` files)
2. Parse grammar definitions with packrat algorithm
3. Build an AST of grammar rules
4. Generate C source and header files
- Build and test flow powered by CMake, Bats, and Uncrustify.

- **CLI Front-End** (packcc executable)
- **Import Manager** (handles `%import` directives and search paths)
- **Grammar Parser Module** (packrat parser engine, left-recursion support)
- **Grammar AST** (in-memory representation of rules and actions)
- **Code Generator** (walks the AST, emits .c & .h code, applies `%header`/`%source` sections)
- **File I/O** (reading .peg, writing output files)
- **Build System & CI** (CMake, GitHub Actions)
- **Test Harness** (Bats scripts, test inputs)
- **Benchmark Suite** (benchmark scripts & sample grammars)

- User invokes **CLI Front-End** → **File I/O** reads grammar file & `%import` files → hands text to **Import Manager** → combined grammar goes to **Grammar Parser Module** → produces **Grammar AST** → flows into **Code Generator** → uses **File I/O** to write .c/.h → exit.
- **Build System** orchestrates compilation of src/packcc.c into executable, runs **Test Harness** and **Benchmark Suite**.

c. Architectural patterns and principles
- **Single-pass pipeline**: text → import resolution → parsing → AST → code generation.
- **Packrat parsing** with **memoization** for linear-time grammar parsing.
- **Modular import** system for grammar reuse.
- **Test-driven** via Bats; **CI automation** via GitHub Actions.

d. Key technologies
- Language: **C** (single source file).
- Build: **CMake**, **Make**/Visual Studio.
- Tests: **Bats-core** + shell helper scripts, **Uncrustify** for code style.
- CI: **GitHub Actions** (.github/workflows/testing.yml).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Input & CLI
    subgraph "User Input & CLI"
        CLI["CLI Front-End\n(packcc executable)"]:::frontend
        FileIO["File I/O\n(read .peg & write .c/.h)"]:::frontend
    end

    %% Import & Parsing
    subgraph "Import & Parsing"
        ImportMgr["Import Manager\n(%import handling)"]:::core
        Parser["Grammar Parser Module\n(packrat engine)"]:::core
        AST["Grammar AST\n(in-memory)"]:::core
    end

    %% Code Generation
    subgraph "Code Generation"
        CodeGen["Code Generator\n(emits C .c/.h)"]:::core
    end

    %% Infrastructure
    subgraph "Infrastructure"
        subgraph "Build & CI"
            Build["Build Orchestration\n(CMake)"]:::infra
            CI["CI Pipeline\n(GitHub Actions)"]:::infra
        end
        Test["Test Harness\n(Bats scripts)"]:::infra
        Bench["Benchmark Suite"]:::infra
        Ex["Examples\n(sample grammars)"]:::infra
    end

    %% Data Flow
    CLI --> FileIO
    FileIO --> ImportMgr
    ImportMgr --> Parser
    Parser --> AST
    AST --> CodeGen
    CodeGen --> FileIO

    %% Infrastructure Relations
    Build --> CLI
    CI --> Test
    CI --> Bench
    Test --> CLI
    Bench --> CLI
    Ex --> CLI

    %% Click Events
    click CLI "https://github.com/arithy/packcc/blob/main/src/packcc.c"
    click FileIO "https://github.com/arithy/packcc/blob/main/src/packcc.c"
    click ImportMgr "https://github.com/arithy/packcc/tree/main/import/"
    click Parser "https://github.com/arithy/packcc/blob/main/src/packcc.c"
    click AST "https://github.com/arithy/packcc/blob/main/import/code/pcc_ast.peg"
    click CodeGen "https://github.com/arithy/packcc/blob/main/src/packcc.c"
    click Build "https://github.com/arithy/packcc/blob/main/CMakeLists.txt"
    click CI "https://github.com/arithy/packcc/blob/main/.github/workflows/testing.yml"
    click Test "https://github.com/arithy/packcc/tree/main/tests/"
    click Bench "https://github.com/arithy/packcc/tree/main/benchmark/"
    click Ex "https://github.com/arithy/packcc/tree/main/examples/"

    %% Styles
    classDef frontend fill:#cdeac0,stroke:#2f6627,color:#000;
    classDef core fill:#c0d6e4,stroke:#1f4667,color:#000;
    classDef infra fill:#ffe3b3,stroke:#b37400,color:#000;
```
