thag_common

Common types, macros, and utilities shared across thag_rs subcrates.

This is a foundation crate that provides the shared infrastructure used by thag_styling, thag_profiler, and the main thag_rs application. If you're using those crates, you're already benefiting from thag_common behind the scenes.

What's Inside

thag_common provides:

• Verbosity Controls - A unified system for controlling output detail levels across all thag tools

• Terminal Detection - Color capability and background detection for adaptive styling

• Auto Help System - Automatic extraction of help text from doc comments for command-line tools

• Configuration Management - Shared configuration utilities and error handling

• Common Types - Result types, error enums, and utility types used throughout the ecosystem

• Utility Macros - Helper macros for logging, debugging, number formatting, and common patterns

Who This Is For

Most users won't need to use this crate directly. It's primarily infrastructure for other thag_rs subcrates.

You might want to use thag_common if you're:

• Building tools that integrate with the thag ecosystem

• Creating extensions or plugins for thag

• Developing new subcrates that share thag's patterns

Usage

Add thag_common to your Cargo.toml:

[dependencies]
thag_common = "0.2"

Example: Verbosity Control

use thag_common::{set_verbosity_from_env, vprtln, V};

fn main() {
    // Set verbosity level from environment variable `THAG_VERBOSITY`.
    // Possible values are: qq, q, n (default), v or vv, OR 0 to 4
    set_verbosity_from_env();

    // Messages respect the verbosity setting
    vprtln!(V::Debug, "Debug message - only shown at debug level (vv/4)");
    vprtln!(V::Normal, "Normal message - shown at normal (n/2) and above");
    vprtln!(V::Quieter, "Essential message - shown even at quietest level (qq/0)");
}

Sample output when run with THAG_VERBOSITY=vv or THAG_VERBOSITY=4:

Debug message - only shown at debug level (vv/4)
Normal message - shown at normal (n/2) and above
Essential message - shown even at at quietest level (qq/0)

Sample output when run with THAG_VERBOSITY=qq or THAG_VERBOSITY=0:

Essential message - shown even at at quietest level (qq/0)

Example: Terminal Detection

use thag_common::terminal::detect_term_capabilities;

fn main() {
    // Detect terminal capabilities
    let (color_support, [r, g, b]) = detect_term_capabilities();
    println!("Terminal color support level is {color_support}. Background RGB detected is [{r}, {g}, {b}]");
}

Output:

Terminal color support level is true_color. Background RGB detected is [30, 30, 46]

Example: Auto Help System

thag_common provides an auto-help system that extracts help text from doc comments:

use thag_common::{auto_help, help_system::check_help_and_exit};

/// This program demonstrates the `thag_common` `auto_help` functionality.
/// Invoking it with `--help/-h` displays these doc comments as help.
//# Purpose: Demo of auto_help extracting help from source comments.
//# Categories: demo, testing
fn main() {
    // Check for help first - automatically extracts from source comments
    let help = auto_help!();
    check_help_and_exit(&help);

    println!("Hello, World!");
}

Output when run with --help:

test_program 0.0.1
Demo of auto_help extracting help from source comments.

This program demonstrates the `thag_common` `auto_help` functionality.
Invoking it with `--help/-h` displays these doc comments as help.

USAGE:
    test_program [OPTIONS]

OPTIONS:
    -h, --help       Print help

CATEGORIES: demo, testing

The auto_help system also works in conjunction with clap for more sophisticated command-line tools.

Example: Number Formatting

use thag_common::thousands;

fn main() {
    println!("thousands(12345678901234567890_u128)={}", thousands(12345678901234567890_u128));
}

Output:

thousands(12345678901234567890_u128)=12,345,678,901,234,567,890

Running These Examples with thag

These examples can be run directly with thag thanks to dependency inference. You can even use snippet wrapping to skip the fn main() boilerplate:

use thag_common::terminal::detect_term_capabilities;

// Detect terminal capabilities
let (color_support, [r, g, b]) = detect_term_capabilities();
println!("Terminal color support level is {color_support}. Background RGB detected is [{r}, {g}, {b}]");

Run with: thag -d <filename.rs> or pipe it in: thag -d

Features

Default Features

None - include only what you need.

Available Features

• config - Configuration management utilities

• color_detect - Terminal color support and background detection

• debug_logging - Enable debug logging at compile time

• document-features - Documentation for feature flags

Example with features:

[dependencies]
thag_common = { version = "0.2", features = ["color_detect"] }

Documentation

For detailed API documentation, see docs.rs/thag_common.

Part of the thag Ecosystem

thag_common is one component of the larger thag_rs toolkit:

• thag_rs - The main script runner and REPL

• thag_styling - Terminal styling with theme support

• thag_profiler - Lightweight code profiling

• thag_proc_macros - Procedural macros

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