MoosicBox Assert

A conditional assertion library providing enhanced assertion macros with colorized output and stack traces, controlled by environment variables.

Features

• Conditional Assertions: Enable/disable assertions via environment variable
• Colorized Output: Red background with white text for assertion failures
• Stack Traces: Automatic backtrace capture on assertion failures
• Multiple Assert Types: Different assertion behaviors (exit, error, panic, unimplemented)
• Flexible Error Handling: Convert assertions to errors, warnings, or panics
• Environment Control: Runtime control over assertion behavior

Installation

Add this to your Cargo.toml:

[dependencies]
moosicbox_assert = "0.1.4"
log = "0.4.29" # Required by exported macros from this crate (for example assert!/die!/assert_or_error!/die_or_error!/die_or_warn!)

Usage

Basic Assertions

use moosicbox_assert::{assert, die};

fn main() {
    // Set environment variable to enable assertions
    unsafe { std::env::set_var("ENABLE_ASSERT", "1"); }

    let value = 42;

    // Basic assertion - exits process on failure
    assert!(value > 0);
    assert!(value == 42, "Expected 42, got {}", value);

    // Unconditional death (only when assertions enabled)
    if value < 0 {
        die!("Value cannot be negative: {}", value);
    }
}

Assert with Error Return

use moosicbox_assert::assert_or_err;

#[derive(Debug)]
enum MyError {
    InvalidValue,
    OutOfRange,
}

fn validate_input(value: i32) -> Result<(), MyError> {
    // Convert assertion failure to error return
    assert_or_err!(value >= 0, MyError::InvalidValue);
    assert_or_err!(value <= 100, MyError::OutOfRange, "Value {} is out of range", value);

    Ok(())
}

fn main() {
    unsafe { std::env::set_var("ENABLE_ASSERT", "1"); }

    match validate_input(-5) {
        Ok(()) => println!("Input is valid"),
        Err(e) => println!("Validation error: {:?}", e),
    }
}

Assert with Logging

use moosicbox_assert::assert_or_error;

fn process_data(data: &[u8]) {
    // Log error instead of exiting when assertions disabled
    assert_or_error!(!data.is_empty(), "Cannot process empty data");
    assert_or_error!(data.len() < 1024, "Data too large: {} bytes", data.len());

    // Process data...
}

fn main() {
    env_logger::init();

    // With ENABLE_ASSERT=1: exits on failure
    // With ENABLE_ASSERT=0: logs error and continues
    unsafe { std::env::set_var("ENABLE_ASSERT", "0"); }

    process_data(&[]);  // Will log error but not exit
}

Assert with Panic

use moosicbox_assert::assert_or_panic;

fn critical_operation(input: Option<i32>) {
    // Panic with colorized output on failure
    let value = input.expect("Input required");
    assert_or_panic!(value > 0, "Value must be positive, got {}", value);

    println!("Processing value: {}", value);
}

fn main() {
    unsafe { std::env::set_var("ENABLE_ASSERT", "1"); }

    critical_operation(Some(42));  // OK
    critical_operation(Some(-1));  // Panics with colored output
}

Assert with Unimplemented

use moosicbox_assert::assert_or_unimplemented;

fn experimental_feature(enabled: bool) {
    // Mark unimplemented code paths
    assert_or_unimplemented!(enabled, "Feature not yet implemented");

    println!("Running experimental feature");
}

fn main() {
    unsafe { std::env::set_var("ENABLE_ASSERT", "1"); }

    experimental_feature(true);   // OK
    experimental_feature(false);  // Calls unimplemented!() with colors
}

Environment Control

use moosicbox_assert::assert;

fn debug_mode_example() {
    let data = vec![1, 2, 3];

    // Only checked when ENABLE_ASSERT=1
    assert!(!data.is_empty());
    assert!(data.len() == 3, "Expected 3 elements");
}

fn main() {
    // Disable assertions for production
    unsafe { std::env::set_var("ENABLE_ASSERT", "0"); }
    debug_mode_example();  // Assertions are no-ops

    // Enable for debugging
    unsafe { std::env::set_var("ENABLE_ASSERT", "1"); }
    debug_mode_example();  // Assertions are active
}

Assertion Types

assert!(condition [, message])

Exits the process with colored output when condition fails and assertions are enabled.

assert_or_err!(condition, error [, message])

Returns the error when condition fails, or exits with assertion if ENABLE_ASSERT=1.

assert_or_error!(condition, message)

Logs an error when condition fails, or exits with assertion if ENABLE_ASSERT=1.

assert_or_panic!(condition [, message])

Panics with colored output when condition fails, or exits with assertion if ENABLE_ASSERT=1.

assert_or_unimplemented!(condition [, message])

Calls unimplemented!() when condition fails, or exits with assertion if ENABLE_ASSERT=1.

die!([message])

Unconditionally exits with colored output when assertions are enabled.

Additional Macros

The library also provides additional utility macros for specialized use cases:

• die_or_warn!(message): Exits with colored output if ENABLE_ASSERT=1, otherwise logs a warning
• die_or_err!(error, message): Exits if ENABLE_ASSERT=1, otherwise returns the error
• die_or_error!(message): Exits if ENABLE_ASSERT=1, otherwise logs an error
• die_or_propagate!(result [, message]): Exits if ENABLE_ASSERT=1 and result is error, otherwise propagates error with ?
• die_or_panic!(message): Exits if ENABLE_ASSERT=1, otherwise panics
• die_or_unimplemented!(message): Exits if ENABLE_ASSERT=1, otherwise calls unimplemented!()

Environment Variables

• ENABLE_ASSERT: Set to "1" to enable assertions, any other value disables them

Output Format

When assertions fail, the output includes:

• Red background with white text for visibility
• Bold and underlined formatting
• Full stack trace showing the failure location
• Custom messages with formatting support

Dependencies

• colored: For colorized terminal output
• moosicbox_env_utils: For environment variable handling
• Standard library backtrace support

Use Cases

• Development: Enable detailed assertion checking
• Testing: Verify preconditions and postconditions
• Production: Disable assertions for performance
• Debugging: Get detailed failure information with stack traces