How clucompany/include_tt works
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.