# clucompany/include_tt architecture

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

- Interactive diagram: https://gitdiagram.com/clucompany/include_tt
- Repository: https://github.com/clucompany/include_tt

## Overview

##### Project Type and Purpose
- This is a Rust library crate providing a compile‐time macro (`include_tt!`) that embeds external files (trees, strings, arrays) into Rust macro token streams.
- It integrates with the Rust compiler as a proc‐macro, performing file I/O and AST‐like transformations at compile time.

##### High‐Level Architecture Components
a. Consumer Code (Examples & Tests)
- `examples/` and `tests/` directories.
- Invoke `include_tt!` in user code or test harness.
b. Proc‐Macro Entry Point
- `src/macros/include.rs`
- Defines the `include_tt!` macro, accepted input tokens, and dispatch logic.
c. File Loader
- `src/trees/loader.rs`
- Reads the external `.tt` files using standard file I/O, produces raw text.
d. Parser & Expression Module
- `src/exprs/*` (e.g., `literal.rs`)
- Converts raw text into intermediate expression or literal representations.
e. Tree Abstractions & Transformers
- `src/trees/{group.rs, null.rs, replace.rs, result.rs, search.rs, sq_err.rs}`
- Macro “trees,” search/replace tokens, group subtrees, handle errors, and produce final token trees.
f. Rust Compiler (rustc) Integration
- Macro outputs a `TokenStream` back to `rustc`, which merges it into the compilation.

##### Relationships & Data Flow
1. User code ──calls──► `include_tt!` proc‐macro
2. Macro entry (`include_rs`) ──parses──► input tokens (paths, include directives)
3. Loader ──reads──► external file contents
4. Exprs module ──parses──► raw text → literal/array/string expressions
5. Tree transformers ──apply──► search & replace, grouping, error checking
6. Result module ──emits──► final `TokenStream`
7. Rust compiler ──compiles──► expanded code

##### Architectural Patterns & Principles
- Separation of Concerns: Distinct modules for file I/O (loader), parsing (exprs), transformation (trees), and macro interface.
- Pipeline Pattern: Data flows through a sequence of stages (load → parse → transform → generate).
- Error‐first Design: `sq_err.rs` handles macro expansion errors early, aborting with clear messages.

##### Technologies & Frameworks
- Rust Proc‐Macro API (`proc_macro` crate)
- Standard Library I/O for file reading
- Custom AST‐like “Tree” data structures
- Cargo build system and CI via GitHub Actions

##### Final Recommendations
- Every submodule as its own block to reflect how maintainers can swap or extend behavior.
- Proc‐macro integration point with the Rust compiler as a distinct component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Consumer Code"
        Examples["examples/"]:::external
        Tests["tests/"]:::external
    end

    Examples -->|"calls include_tt!"| Lib
    Tests -->|"calls include_tt!"| Lib

    Lib["src/lib.rs"]:::macro
    Include["src/macros/include.rs"]:::macro

    Lib --> Include
    Include -->|"parses input tokens"| Loader["src/trees/loader.rs"]:::loader

    Loader -->|"raw text"| ExprsDir["src/exprs/"]:::parser

    subgraph "Parser & Exprs"
        Literal["src/exprs/literal.rs"]:::parser
    end

    ExprsDir --> Literal
    Literal -->|"Expr AST"| Group["src/trees/group.rs"]:::transform

    subgraph "Trees Module"
        Null["src/trees/null.rs"]:::transform
        Search["src/trees/search.rs"]:::transform
        Replace["src/trees/replace.rs"]:::transform
        Err["src/trees/sq_err.rs"]:::transform
        Result["src/trees/result.rs"]:::transform
    end

    Group --> Search
    Search --> Replace
    Replace --> Err
    Err --> Result
    Result -->|"TokenStream"| Rustc["Rust Compiler (rustc)"]:::compiler

    click Examples "https://github.com/clucompany/include_tt/tree/main/examples/"
    click Tests "https://github.com/clucompany/include_tt/tree/main/tests/"
    click Lib "https://github.com/clucompany/include_tt/blob/main/src/lib.rs"
    click Include "https://github.com/clucompany/include_tt/blob/main/src/macros/include.rs"
    click Loader "https://github.com/clucompany/include_tt/blob/main/src/trees/loader.rs"
    click ExprsDir "https://github.com/clucompany/include_tt/tree/main/src/exprs/"
    click Literal "https://github.com/clucompany/include_tt/blob/main/src/exprs/literal.rs"
    click Group "https://github.com/clucompany/include_tt/blob/main/src/trees/group.rs"
    click Null "https://github.com/clucompany/include_tt/blob/main/src/trees/null.rs"
    click Search "https://github.com/clucompany/include_tt/blob/main/src/trees/search.rs"
    click Replace "https://github.com/clucompany/include_tt/blob/main/src/trees/replace.rs"
    click Err "https://github.com/clucompany/include_tt/blob/main/src/trees/sq_err.rs"
    click Result "https://github.com/clucompany/include_tt/blob/main/src/trees/result.rs"

    classDef external fill:#87ceeb,stroke:#333,stroke-width:1px
    classDef macro fill:#add8e6,stroke:#333,stroke-width:1px
    classDef loader fill:#98fb98,stroke:#333,stroke-width:1px
    classDef parser fill:#ffa500,stroke:#333,stroke-width:1px
    classDef transform fill:#ffff99,stroke:#333,stroke-width:1px
    classDef compiler fill:#dda0dd,stroke:#333,stroke-width:1px
```
