🦆 waddling-errors-macros

Procedural macros for waddling-errors.

Installation

[dependencies]
waddling-errors = "0.7"
waddling-errors-macros = "0.7"

Quick Start

setup! must be called once at crate root before using diag!. Module names (components, primaries, sequences) are conventions—use whatever structure fits your project.

// src/lib.rs
use waddling_errors_macros::{setup, component, primary, sequence, diag};

setup! {
    components = crate::components,
    primaries = crate::primaries,
    sequences = crate::sequences,
}

pub mod components {
    use waddling_errors_macros::component;
    component! { Auth { docs: "Authentication" } }
}

pub mod primaries {
    use waddling_errors_macros::primary;
    primary! { Token { docs: "Token errors" } }
}

pub mod sequences {
    use waddling_errors_macros::sequence;
    sequence! {
        EXPIRED(17) { description: "Resource expired" },
    }
}

diag! {
    E.Auth.Token.EXPIRED: {
        message: "Token expired at {{timestamp}}",
        fields: [timestamp],
        
        'Pub description: "Session expired. Please log in again.",
        'Dev description: "Token TTL exceeded. Check refresh logic.",
        'Int description: "Check auth_tokens table.",
    },
}

// Use it
let error = E_AUTH_TOKEN_EXPIRED;
println!("{}", error.runtime.code);  // E.Auth.Token.017

Macros

setup! - Configure paths (required at crate root)

setup! {
    components = crate::components,
    primaries = crate::primaries,
    sequences = crate::sequences,
}

component! - Define components

component! {
    Auth { docs: "Authentication system" },
    Database { docs: "Database operations" },
}

primary! - Define primary categories

primary! {
    Token { docs: "Token-related errors" },
    Connection { docs: "Connection errors" },
}

sequence! - Define sequences

sequence! {
    MISSING(1) { description: "Required item missing" },
    EXPIRED(17) { description: "Resource expired" },
}

diag! - Define diagnostics

diag! {
    E.Auth.Token.EXPIRED: {
        message: "Token expired at {{timestamp}}",
        fields: [timestamp],
        pii: [user_email],  // PII fields use {{pii/field}}
        
        // Role-based descriptions
        'Pub description: "Session expired.",
        'Dev description: "Token TTL exceeded.",
        'Int description: "Check auth_tokens table.",
        
        role: "Public",
        tags: ["auth"],
    },
}

Visibility Markers

Role-Based Documentation

diag! {
    E.Auth.Token.EXPIRED: {
        message: "Token expired",
        
        'Pub description: "Session expired.",           // End users
        'Dev description: "Token TTL exceeded.",        // Developers
        'Int description: "Redis key: auth:token:*",    // Internal
        
        role: "Public",
    },
}

Generate separate docs per role:

cargo run --bin doc-gen --features doc-gen

Feature Flags

Documentation

• Macro Guide - Complete syntax reference
• Validation Guide - Compile-time validation
• API Reference

License

MIT or Apache-2.0.