# thag_proc_macros
[](https://crates.io/crates/thag_proc_macros)
[](https://docs.rs/thag_proc_macros)
Procedural macros for `thag_rs` and `thag_profiler`.
This is a proc macro crate that provides the macros used by `thag_profiler` for code profiling, along with utility macros used internally by other `thag_rs` subcrates. If you're using `thag_profiler` or `thag_rs`, you're already benefiting from these macros.
## What's Inside
`thag_proc_macros` provides:
- **Profiling Macros** - `#[profiled]`, `#[enable_profiling]`, `profile!`, and `end!` for performance profiling
- **Safe Print Macros** - Thread-safe printing macros for concurrent output
- **File Navigation** - `file_navigator!` macro for interactive directory traversal with `inquire`
- **Styling Macros** - Theme generation, palette methods, ANSI styling support, and compile-time theme loading
- **Category System** - `category_enum!` for organizing demo scripts
- **Internal Utilities** - Build-time code generation and utility macros
## Who This Is For
**Most users won't import this crate directly.** If you're using `thag_profiler`, you're already using these macros through that crate. If you're using `thag_rs`, the macros you need are re-exported.
You might want to use `thag_proc_macros` directly if you're:
- Performing directory navigation with `inquire`
- Building custom profiling integrations
- Developing new `thag_rs` subcrates that need the macro infrastructure
- Contributing to the thag ecosystem
## Usage
Add `thag_proc_macros` to your `Cargo.toml`:
```toml
[dependencies]
thag_proc_macros = "0.2"
```
### Example: Profiling Macros
The profiling macros are the most commonly used. They're typically imported through `thag_profiler`:
```rust
use thag_proc_macros::{enable_profiling, profiled, profile, end};
#[enable_profiling(time)]
fn main() {
expensive_calculation();
profile!(section_name);
// Critical section to profile
end!(section_name);
}
#[profiled]
fn expensive_calculation() -> u64 {
// Function is automatically profiled
42
}
```
See the [thag_profiler documentation](https://docs.rs/thag_profiler) for comprehensive profiling examples.
### Example: Safe Print Macros
Thread-safe printing for concurrent environments:
```rust
use thag_proc_macros::{safe_println, safe_eprintln};
fn main() {
// Safe for concurrent use
safe_println!("This prints safely from multiple threads");
safe_eprintln!("Errors also print safely");
}
```
### Example: Category Enum
Generate enums from configuration files:
```rust
use thag_proc_macros::category_enum;
// Generates Category enum from config file
category_enum!("path/to/categories.toml");
```
### Example: File Navigator
The `file_navigator!` macro generates an interactive file browser that works with `inquire`. It's used extensively by thag's own tools for navigating directories to select files or save-locations:
```rust
use inquire;
use thag_proc_macros::file_navigator;
fn main() {
// Generate the FileNavigator struct and implementation
file_navigator!();
// Navigate to select a .rs file
let result = select_file(
&mut FileNavigator::new(),
Some("rs"), // File extension filter
false, // Don't show hidden files
);
match result {
Ok(path) => println!("Selected: {}", path.display()),
Err(e) => eprintln!("\nError: {}", e),
}
}
```
Output shows an interactive menu with the current directory structure, for example:
```
> *TYPE PATH TO NAVIGATE*
..
📁 assets
📁 bank
📁 benches
📁 built_in
v 📁 claude
[Press Enter to navigate, select a file to load]
```
Navigate with arrow keys, select with Enter. The macro handles the entire navigation UI.
## Features
### Default Features
None - include only what you need.
### Available Features
- **`time_profiling`** - Enable time-based profiling macros
- **`full_profiling`** - Enable comprehensive profiling (time + memory)
- **`debug_logging`** - Enable debug logging in profiling code
- **`tui`** - Enable TUI-related macros
- **`internal_docs`** - Show internal API documentation
Example with profiling features:
```toml
[dependencies]
thag_proc_macros = { version = "0.2", features = ["full_profiling"] }
```
## How It Works
As a proc macro crate, `thag_proc_macros` operates at compile time. The macros analyze and transform your code during compilation, generating optimized implementations that have zero runtime overhead when profiling features are turned off.
**Key Design Principles**:
- **Zero-cost abstractions** - No overhead when features are turned off
- **Compile-time safety** - Errors caught during compilation, not at runtime
- **Feature-gated** - Include only what you need
## Documentation
For detailed API documentation, see [docs.rs/thag_proc_macros](https://docs.rs/thag_proc_macros).
For profiling usage, see the [thag_profiler documentation](https://docs.rs/thag_profiler).
## Part of the thag Ecosystem
`thag_proc_macros` is one component of the larger `thag_rs` toolkit:
- **[thag_rs](https://crates.io/crates/thag_rs)** - The main script runner and REPL
- **[thag_profiler](https://crates.io/crates/thag_profiler)** - Lightweight code profiling (main user of these macros)
- **[thag_styling](https://crates.io/crates/thag_styling)** - Terminal styling with theme support
- **[thag_common](https://crates.io/crates/thag_common)** - Shared types and utilities
- **[thag_demo](https://crates.io/crates/thag_demo)** - Interactive demos
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## Contributing
Contributions will be considered (under MIT/Apache 2 license) if they align with the aims of the project.
Rust code should pass clippy::pedantic checks.