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:

[dependencies]
thag_proc_macros = "0.2"

Example: Profiling Macros

The profiling macros are the most commonly used. They're typically imported through thag_profiler:

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 for comprehensive profiling examples.

Example: Safe Print Macros

Thread-safe printing for concurrent environments:

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:

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:

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:

[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.

For profiling usage, see the thag_profiler documentation.

Part of the thag Ecosystem

thag_proc_macros is one component of the larger thag_rs toolkit:

• thag_rs - The main script runner and REPL

• thag_profiler - Lightweight code profiling (main user of these macros)

• thag_styling - Terminal styling with theme support

• thag_common - Shared types and utilities

• thag_demo - Interactive demos

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (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.