# mshockwave/nacro architecture

> Architecture diagram of the GitHub repository mshockwave/nacro, 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/mshockwave/nacro
- Repository: https://github.com/mshockwave/nacro

## Overview

##### Main Components

a) Core Components (Central Focus):
- Nacro Parser (NacroParsers.h/cpp)
- Nacro Expander (NacroExpanders.h/cpp)
- Nacro Verifier (NacroVerifier.h/cpp)
- Nacro Rule Manager (NacroRule.h/cpp)
- Pragma Handler (NacroPragmaHandler.cpp)

b) External Dependencies:
- LLVM/Clang Infrastructure
- C/C++ Compiler Pipeline

##### Component Relationships

**[Source Code with #pragma nacro]**
- ↓
**[Clang Preprocessor]**
- ↓
**[Pragma Handler] → [Nacro Parser]**
- ↓
**[Nacro Rule Manager] ← → [Nacro Verifier]**
- ↓
**[Nacro Expander]**
- ↓
**[Generated C/C++ Code]**

##### Specific Details

a) Parser Section:
- Parsing of nacro rules
- Syntax validation
- Token processing

b) Rule Management:
- Rule storage and retrieval
- Rule validation flow

c) Expansion Section:
- Demonstrate macro expansion process
- Protection mechanisms (expression protection, capture detection)
- Loop handling

##### Additional Elements

- Unit Tests (unittest/)
- Integration Tests (test/)
- Playground (Playground/)

- A "Build System" section showing:
- CMake configuration
- LLVM/Clang integration
- Plugin compilation

##### Important Notes

- Plugin nature of the system by showing clear integration points with Clang
- Transformation pipeline from nacro syntax to expanded C/C++ code
- Safety features that differentiate it from traditional macros
- Validation and verification flows

##### Technical Details to Note

- LLVM/Clang version dependency (10.0.0)
- Platform support (Linux x86_64, partial MacOS)
- Build requirements and dependencies

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Input
        SRC["Source Code with #pragma nacro"]:::input
    end

    subgraph "Clang Infrastructure"
        CLANG["Clang Preprocessor"]:::external
    end

    subgraph "Core Components"
        PRAGMA["Pragma Handler"]:::core
        PARSER["Nacro Parser"]:::core
        RULE["Nacro Rule Manager"]:::core
        VERIFY["Nacro Verifier"]:::core
        EXPAND["Nacro Expander"]:::core
    end

    subgraph "Testing Infrastructure"
        UNIT["Unit Tests"]:::test
        INT["Integration Tests"]:::test
        PLAY["Playground"]:::test
    end

    subgraph "Build System"
        CMAKE["CMake Configuration"]:::build
        UTILS["Build Utils"]:::build
        SCRIPTS["Build Scripts"]:::build
    end

    subgraph Output
        GEN["Generated C/C++ Code"]:::output
    end

    %% Flow
    SRC --> CLANG
    CLANG --> PRAGMA
    PRAGMA --> PARSER
    PARSER --> RULE
    RULE <--> VERIFY
    RULE --> EXPAND
    EXPAND --> GEN

    %% Testing Connections
    PARSER -.-> UNIT
    EXPAND -.-> UNIT
    PARSER -.-> INT
    EXPAND -.-> INT
    PARSER -.-> PLAY
    EXPAND -.-> PLAY

    %% Build System Connections
    CMAKE --> CLANG
    UTILS --> CMAKE
    SCRIPTS --> CMAKE

    %% Styling
    classDef core fill:#a8d1f0,stroke:#333
    classDef external fill:#d3d3d3,stroke:#333
    classDef input fill:#90EE90,stroke:#333
    classDef output fill:#90EE90,stroke:#333
    classDef test fill:#FFB6C1,stroke:#333
    classDef build fill:#DDA0DD,stroke:#333

    %% Click Events
    click PRAGMA "https://github.com/mshockwave/nacro/blob/master/NacroPragmaHandler.cpp"
    click PARSER "https://github.com/mshockwave/nacro/blob/master/NacroParsers.h"
    click RULE "https://github.com/mshockwave/nacro/blob/master/NacroRule.h"
    click VERIFY "https://github.com/mshockwave/nacro/blob/master/NacroVerifier.h"
    click EXPAND "https://github.com/mshockwave/nacro/blob/master/NacroExpanders.h"
    click UNIT "https://github.com/mshockwave/nacro/tree/master//unittest"
    click INT "https://github.com/mshockwave/nacro/tree/master//test"
    click PLAY "https://github.com/mshockwave/nacro/tree/master//Playground"
    click CMAKE "https://github.com/mshockwave/nacro/blob/master/CMakeLists.txt"
    click UTILS "https://github.com/mshockwave/nacro/tree/master//cmake"
    click SCRIPTS "https://github.com/mshockwave/nacro/tree/master//utils"

    %% Legend
    subgraph Legend
        L1["Core Component"]:::core
        L2["External Component"]:::external
        L3["Input/Output"]:::input
        L4["Testing Component"]:::test
        L5["Build Component"]:::build
    end
```
