# thag_common
[](https://crates.io/crates/thag_common)
[](https://docs.rs/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`:
```toml
[dependencies]
thag_common = "0.2"
```
### Example: Verbosity Control
```rust
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
```rust
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:
```rust
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
```rust
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:
```rust
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:
```toml
[dependencies]
thag_common = { version = "0.2", features = ["color_detect"] }
```
## Documentation
For detailed API documentation, see [docs.rs/thag_common](https://docs.rs/thag_common).
## Part of the thag Ecosystem
`thag_common` is one component of the larger `thag_rs` toolkit:
- **[thag_rs](https://crates.io/crates/thag_rs)** - The main script runner and REPL
- **[thag_styling](https://crates.io/crates/thag_styling)** - Terminal styling with theme support
- **[thag_profiler](https://crates.io/crates/thag_profiler)** - Lightweight code profiling
- **[thag_proc_macros](https://crates.io/crates/thag_proc_macros)** - Procedural macros
- **[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.