Enum DiceExpr 

pub enum DiceExpr {
    Sum(Box<DiceExpr>, Box<DiceExpr>),
    Difference(Box<DiceExpr>, Box<DiceExpr>),
    Roll(RollSpec),
    Literal(i32),
}

A parsed dice expression that can be evaluated to produce a result.

This is the main type for working with dice expressions. It represents a tree structure of dice rolls, literals, and arithmetic operations.

Variants

• Sum: Addition of two sub-expressions (e.g., “2d6 + 3”)
• Difference: Subtraction of two sub-expressions (e.g., “1d20 - 2”)
• Roll: A dice roll specification (e.g., “2d6”)
• Literal: A constant integer value (e.g., “5”)

Examples

Parsing from a string

use dice_parser::DiceExpr;

let expr = DiceExpr::parse("2d6+3").unwrap();
let result = expr.roll().unwrap();
assert!(result.total >= 5 && result.total <= 15); // 2-12 from dice + 3

Manual construction

use dice_parser::{DiceExpr, RollSpec};

// Create "1d20 + 5"
let roll = DiceExpr::Roll(RollSpec::new(1, 20, None));
let modifier = DiceExpr::Literal(5);
let expr = DiceExpr::Sum(Box::new(roll), Box::new(modifier));

let result = expr.roll().unwrap();
assert!(result.total >= 6 && result.total <= 25);

Variants

Sum(Box<DiceExpr>, Box<DiceExpr>)

Addition of two dice expressions.

Difference(Box<DiceExpr>, Box<DiceExpr>)

Subtraction of two dice expressions.

Roll(RollSpec)

A dice roll specification.

Literal(i32)

A constant integer literal.

Implementations

impl DiceExpr

pub fn roll(&self) -> Result<ExprResult, DiceError>

Evaluate the dice expression using the default random number generator provided by the rand crate.

This method rolls all dice in the expression and computes the final result, including individual roll values and any modifiers.

Returns

• Ok(ExprResult): The result of evaluating the expression
• Err(DiceError): If the roll specification is invalid or an overflow occurs

Examples

use dice_parser::DiceExpr;

let expr = DiceExpr::parse("2d6+3").unwrap();
let result = expr.roll().unwrap();

// Result contains total, individual rolls, and modifier
assert!(result.total >= 5 && result.total <= 15);
assert_eq!(result.rolls.len(), 2); // Two d6 rolls
assert_eq!(result.modifier, 3);

Examples found in repository

examples/error_handling.rs (line 37)

fn main() {
    println!("=== Error Handling Examples ===\n");

    // Parse error - invalid syntax
    println!("1. Parse error (missing sides):");
    match DiceExpr::parse("2d") {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(e) => println!("  Error: {}", e),
    }
    println!();

    // Syntax error - negative dice count
    println!("2. Syntax error (negative dice count):");
    match DiceExpr::parse("-2d6") {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(e) => println!("  Error: {}", e),
    }
    println!();

    // Trailing input error
    println!("3. Trailing input error:");
    match DiceExpr::parse("2d6 extra") {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(e) => println!("  Error: {}", e),
    }
    println!();

    // Invalid spec error (keep more than rolled)
    println!("4. Invalid roll specification:");
    use dice_parser::{RollSpec, Keep};
    let spec = RollSpec::new(2, 6, Some(Keep::Highest(5))); // Try to keep 5 dice when only rolling 2
    let expr = DiceExpr::Roll(spec);
    match expr.roll() {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(e) => println!("  Error: {}", e),
    }
    println!();

    // Pattern matching on error types
    println!("5. Pattern matching on DiceError:");
    let result = DiceExpr::parse("abc");
    match result {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(DiceError::ParseError { kind, input, start, stop: _ }) => {
            println!("  Parse error at position {}: {:?}", start, kind);
            println!("  Input: {}", input);
        }
        Err(e) => println!("  Other error: {}", e),
    }
}

examples/basic_usage.rs (line 8)

fn main() {
    println!("=== Basic Parsing and Rolling ===");
    let expr = DiceExpr::parse("2d6+3").unwrap();
    let result = expr.roll().unwrap();
    println!("Expression: 2d6+3");
    println!("Total: {}", result.total);
    println!("Rolls: {:?}", result.rolls);
    println!("Modifier: {}", result.modifier);
    println!();

    println!("=== Manual Construction ===");
    let roll_spec = RollSpec::new(4, 6, Some(Keep::Highest(3)));
    let expr = DiceExpr::Roll(roll_spec);
    let result = expr.roll().unwrap();
    println!("Expression: 4d6 keep highest 3");
    println!("Total: {}", result.total);
    println!("All rolls: {:?}", result.rolls);
    println!();

    println!("=== Complex Expression ===");
    let d2d6 = DiceExpr::Roll(RollSpec::new(2, 6, None));
    let d1d4 = DiceExpr::Roll(RollSpec::new(1, 4, None));
    let modifier = DiceExpr::Literal(2);
    let sum = DiceExpr::Sum(Box::new(d2d6), Box::new(d1d4));
    let expr = DiceExpr::Difference(Box::new(sum), Box::new(modifier));
    let result = expr.roll().unwrap();
    println!("Expression: (2d6 + 1d4) - 2");
    println!("Total: {}", result.total);
    println!();

    println!("=== D&D 5e Advantage ===");
    let advantage = DiceExpr::Roll(RollSpec::new(2, 20, Some(Keep::Highest(1))));
    let result = advantage.roll().unwrap();
    println!("Expression: 2d20 keep highest 1 (advantage)");
    println!("Rolls: {:?}", result.rolls);
    println!("Result: {}", result.total);
    println!();

    println!("=== D&D 5e Disadvantage ===");
    let disadvantage = DiceExpr::Roll(RollSpec::new(2, 20, Some(Keep::Lowest(1))));
    let result = disadvantage.roll().unwrap();
    println!("Expression: 2d20 keep lowest 1 (disadvantage)");
    println!("Rolls: {:?}", result.rolls);
    println!("Result: {}", result.total);
    println!();

    println!("=== Character Ability Scores ===");
    println!("Rolling 4d6 drop lowest for 6 abilities:");
    let ability_roll = DiceExpr::Roll(RollSpec::new(4, 6, Some(Keep::Highest(3))));
    for i in 0..6 {
        let result = ability_roll.roll().unwrap();
        println!("  Ability {}: {} (rolls: {:?})", i + 1, result.total, result.rolls);
    }
}

examples/complete_api.rs (line 38)

fn main() {
    // ========================================
    // 1. DiceExpr - The main expression type
    // ========================================

    // 1.1 Parsing from string
    println!("1. Parsing and expressions");
    let parsed = DiceExpr::parse("2d6+3").unwrap();
    println!("  1.1 Parsing e.g. \"2d6+3\" yields:");
    println!("    {:?}", parsed);

    // 1.2 DiceExpr variants - all publicly accessible
    let literal = DiceExpr::Literal(5);
    println!("  1.2 A literal expression \"5\": ");
    println!("    {:?}", literal);

    let roll = DiceExpr::Roll(RollSpec::new(2, 6, None));
    println!("  1.3 A single roll expression corresponding to 2d6:",);
    println!("    {:?}", roll);

    let sum = DiceExpr::Sum(Box::new(roll.clone()), Box::new(literal.clone()));
    println!("  1.4 A sum of two expression, e.g. \"2d6+5\":");
    println!("    {:?}", sum);

    let _diff = DiceExpr::Difference(Box::new(roll.clone()), Box::new(DiceExpr::Literal(1)));
    println!("  1.5 A difference of two expressions, e.g. \"2d6-1\":",);
    println!("    {:?}", _diff);

    // 1.3 Rolling methods
    println!("\n  1.6 DiceExpr::roll() - Rolling expressions");
    let result1 = parsed.roll().unwrap();
    println!("    An expression, 2d6+3: {}", result1.total);
    let result2 = literal.roll().unwrap();
    println!("    A literal 5: {}", result2.total);
    let result3 = roll.roll().unwrap();
    println!("    A single roll 2d6: {}", result3.total);
    let result4 = sum.roll().unwrap();
    println!("    A manual sum, 2d6+5: {}", result4.total);
    let result5 = _diff.roll().unwrap();
    println!("    A manual diff, 2d6-1: {}", result5.total);

    println!("\n   1.7 DiceExpr::roll_with_rng() - Roll with custom RNG");
    let rng = StdRng::seed_from_u64(42);
    let result6 = DiceExpr::parse("1d20").unwrap().roll_with_rng(rng).unwrap();
    println!("       Rolling 1d20: {}", result6.total);

    // ========================================
    // 2. RollSpec - Dice roll specification
    // ========================================
    println!("\n2. RollSpec Usage:");
    println!("   Struct with public fields and constructor\n");

    let spec = RollSpec::new(4, 6, Some(Keep::Highest(3)));
    println!("   RollSpec::new(4, 6, Some(Keep::Highest(3)))");
    println!("   - count: {}", spec.count);
    println!("   - sides: {}", spec.sides);
    println!("   - keep: {:?}", spec.keep);

    // ========================================
    // 3. Keep - Keep modifier enum
    // ========================================
    println!("\n3. Keep Usage:");
    println!("   Enum with public variants\n");

    let _keep_high = Keep::Highest(3);
    println!("   {:?} - Keep 3 highest dice", _keep_high);

    let _keep_low = Keep::Lowest(1);
    println!("   {:?} - Keep 1 lowest die", _keep_high);

    // Use in RollSpec
    let _advantage = RollSpec::new(2, 20, Some(Keep::Highest(1)));
    let _disadvantage = RollSpec::new(2, 20, Some(Keep::Lowest(1)));
    println!("\n  Example with Advantage:");
    println!(
        "    {:?}, result: {}",
        _advantage,
        DiceExpr::Roll(_advantage.clone()).roll().unwrap().total
    );
    println!("\n  Example with Disadvantage:");
    println!(
        "    {:?}, result: {}",
        _disadvantage,
        DiceExpr::Roll(_disadvantage.clone()).roll().unwrap().total
    );

    // ========================================
    // 4. ExprResult - Roll result
    // ========================================
    println!("\n4. ExprResult Usage:");
    println!("   Struct with public fields\n");

    let expr = DiceExpr::parse("2d6+3").unwrap();
    let result: ExprResult = expr.roll().unwrap();

    println!("   ExprResult from rolling 2d6+3:");
    println!("   - total: {} (final result)", result.total);
    println!("   - rolls: {:?} (individual dice)", result.rolls);
    println!("   - modifier: {} (constant modifiers)", result.modifier);

    // ========================================
    // 5. DiceError - Error handling
    // ========================================
    println!("\n5. DiceError Usage:");
    println!("   Enum with public variants for error handling\n");

    // ParseError variant
    if let Err(DiceError::ParseError {
        kind,
        input,
        start,
        stop: _,
    }) = DiceExpr::parse("invalid")
    {
        println!("   DiceError::ParseError:");
        println!("   - kind: {:?}", kind);
        println!("   - input: {}", input);
        println!("   - start: {}", start);
    }

    // SyntaxError variant
    if let Err(DiceError::SyntaxError { expected, .. }) = DiceExpr::parse("-2d6") {
        println!("\n   DiceError::SyntaxError:");
        if let Some(exp) = expected {
            println!("   - expected: {}", exp);
        }
    }

    // TrailingInput variant
    if let Err(DiceError::TrailingInput { pos, .. }) = DiceExpr::parse("2d6 extra") {
        println!("\n   DiceError::TrailingInput:");
        println!("   - pos: {}", pos);
    }

    // InvalidSpec variant
    let bad_spec = RollSpec::new(2, 6, Some(Keep::Highest(5)));
    if let Err(DiceError::InvalidSpec(spec, msg)) = DiceExpr::Roll(bad_spec).roll() {
        println!("\n   DiceError::InvalidSpec:");
        println!("   - spec: {:?}", spec);
        println!("   - message: {}", msg);
    }

    // ========================================
    // 6. Complete Example
    // ========================================
    println!("\n6. Complete Example:");
    println!("   Building a complex expression with all features\n");

    // Character creation: 6 abilities, each 4d6 keep highest 3
    println!("   Rolling D&D ability scores (4d6 drop lowest):");
    let ability_roll = DiceExpr::Roll(RollSpec::new(4, 6, Some(Keep::Highest(3))));

    for i in 1..=6 {
        if let Ok(result) = ability_roll.roll() {
            println!(
                "   Ability {}: {} (rolls: {:?})",
                i, result.total, result.rolls
            );
        }
    }
}

pub fn roll_with_rng<T: Rng>(&self, r: T) -> Result<ExprResult, DiceError>

Evaluate the dice expression using a custom random number generator.

This method is useful for deterministic testing or when you want to control the randomness source.

Parameters

• r: Any type implementing the rand::Rng trait

Returns

• Ok(ExprResult): The result of evaluating the expression
• Err(DiceError): If the roll specification is invalid or an overflow occurs

Examples

use dice_parser::DiceExpr;
use rand::{SeedableRng, rngs::StdRng};

let expr = DiceExpr::parse("1d20").unwrap();

// Use a seeded RNG for deterministic results
let rng = StdRng::seed_from_u64(42);
let result = expr.roll_with_rng(rng).unwrap();
assert!(result.total >= 1 && result.total <= 20);

Examples found in repository

examples/custom_rng.rs (line 15)

fn main() {
    println!("=== Deterministic Rolling with Custom RNG ===\n");

    let expr = DiceExpr::parse("2d6+3").unwrap();

    println!("Rolling the same expression with the same seed produces identical results:\n");

    // First roll with seed 42
    let rng1 = StdRng::seed_from_u64(42);
    let result1 = expr.roll_with_rng(rng1).unwrap();
    println!("First roll (seed 42):");
    println!("  Total: {}", result1.total);
    println!("  Rolls: {:?}", result1.rolls);

    // Second roll with the same seed should give the same result
    let rng2 = StdRng::seed_from_u64(42);
    let result2 = expr.roll_with_rng(rng2).unwrap();
    println!("\nSecond roll (seed 42):");
    println!("  Total: {}", result2.total);
    println!("  Rolls: {:?}", result2.rolls);

    assert_eq!(result1.total, result2.total);
    assert_eq!(result1.rolls, result2.rolls);
    println!("\n✓ Results match as expected!");

    // Different seed produces different results
    let rng3 = StdRng::seed_from_u64(123);
    let result3 = expr.roll_with_rng(rng3).unwrap();
    println!("\nThird roll (seed 123):");
    println!("  Total: {}", result3.total);
    println!("  Rolls: {:?}", result3.rolls);
    println!("\n✓ Different seed produces different results (usually)");
}

examples/complete_api.rs (line 51)

fn main() {
    // ========================================
    // 1. DiceExpr - The main expression type
    // ========================================

    // 1.1 Parsing from string
    println!("1. Parsing and expressions");
    let parsed = DiceExpr::parse("2d6+3").unwrap();
    println!("  1.1 Parsing e.g. \"2d6+3\" yields:");
    println!("    {:?}", parsed);

    // 1.2 DiceExpr variants - all publicly accessible
    let literal = DiceExpr::Literal(5);
    println!("  1.2 A literal expression \"5\": ");
    println!("    {:?}", literal);

    let roll = DiceExpr::Roll(RollSpec::new(2, 6, None));
    println!("  1.3 A single roll expression corresponding to 2d6:",);
    println!("    {:?}", roll);

    let sum = DiceExpr::Sum(Box::new(roll.clone()), Box::new(literal.clone()));
    println!("  1.4 A sum of two expression, e.g. \"2d6+5\":");
    println!("    {:?}", sum);

    let _diff = DiceExpr::Difference(Box::new(roll.clone()), Box::new(DiceExpr::Literal(1)));
    println!("  1.5 A difference of two expressions, e.g. \"2d6-1\":",);
    println!("    {:?}", _diff);

    // 1.3 Rolling methods
    println!("\n  1.6 DiceExpr::roll() - Rolling expressions");
    let result1 = parsed.roll().unwrap();
    println!("    An expression, 2d6+3: {}", result1.total);
    let result2 = literal.roll().unwrap();
    println!("    A literal 5: {}", result2.total);
    let result3 = roll.roll().unwrap();
    println!("    A single roll 2d6: {}", result3.total);
    let result4 = sum.roll().unwrap();
    println!("    A manual sum, 2d6+5: {}", result4.total);
    let result5 = _diff.roll().unwrap();
    println!("    A manual diff, 2d6-1: {}", result5.total);

    println!("\n   1.7 DiceExpr::roll_with_rng() - Roll with custom RNG");
    let rng = StdRng::seed_from_u64(42);
    let result6 = DiceExpr::parse("1d20").unwrap().roll_with_rng(rng).unwrap();
    println!("       Rolling 1d20: {}", result6.total);

    // ========================================
    // 2. RollSpec - Dice roll specification
    // ========================================
    println!("\n2. RollSpec Usage:");
    println!("   Struct with public fields and constructor\n");

    let spec = RollSpec::new(4, 6, Some(Keep::Highest(3)));
    println!("   RollSpec::new(4, 6, Some(Keep::Highest(3)))");
    println!("   - count: {}", spec.count);
    println!("   - sides: {}", spec.sides);
    println!("   - keep: {:?}", spec.keep);

    // ========================================
    // 3. Keep - Keep modifier enum
    // ========================================
    println!("\n3. Keep Usage:");
    println!("   Enum with public variants\n");

    let _keep_high = Keep::Highest(3);
    println!("   {:?} - Keep 3 highest dice", _keep_high);

    let _keep_low = Keep::Lowest(1);
    println!("   {:?} - Keep 1 lowest die", _keep_high);

    // Use in RollSpec
    let _advantage = RollSpec::new(2, 20, Some(Keep::Highest(1)));
    let _disadvantage = RollSpec::new(2, 20, Some(Keep::Lowest(1)));
    println!("\n  Example with Advantage:");
    println!(
        "    {:?}, result: {}",
        _advantage,
        DiceExpr::Roll(_advantage.clone()).roll().unwrap().total
    );
    println!("\n  Example with Disadvantage:");
    println!(
        "    {:?}, result: {}",
        _disadvantage,
        DiceExpr::Roll(_disadvantage.clone()).roll().unwrap().total
    );

    // ========================================
    // 4. ExprResult - Roll result
    // ========================================
    println!("\n4. ExprResult Usage:");
    println!("   Struct with public fields\n");

    let expr = DiceExpr::parse("2d6+3").unwrap();
    let result: ExprResult = expr.roll().unwrap();

    println!("   ExprResult from rolling 2d6+3:");
    println!("   - total: {} (final result)", result.total);
    println!("   - rolls: {:?} (individual dice)", result.rolls);
    println!("   - modifier: {} (constant modifiers)", result.modifier);

    // ========================================
    // 5. DiceError - Error handling
    // ========================================
    println!("\n5. DiceError Usage:");
    println!("   Enum with public variants for error handling\n");

    // ParseError variant
    if let Err(DiceError::ParseError {
        kind,
        input,
        start,
        stop: _,
    }) = DiceExpr::parse("invalid")
    {
        println!("   DiceError::ParseError:");
        println!("   - kind: {:?}", kind);
        println!("   - input: {}", input);
        println!("   - start: {}", start);
    }

    // SyntaxError variant
    if let Err(DiceError::SyntaxError { expected, .. }) = DiceExpr::parse("-2d6") {
        println!("\n   DiceError::SyntaxError:");
        if let Some(exp) = expected {
            println!("   - expected: {}", exp);
        }
    }

    // TrailingInput variant
    if let Err(DiceError::TrailingInput { pos, .. }) = DiceExpr::parse("2d6 extra") {
        println!("\n   DiceError::TrailingInput:");
        println!("   - pos: {}", pos);
    }

    // InvalidSpec variant
    let bad_spec = RollSpec::new(2, 6, Some(Keep::Highest(5)));
    if let Err(DiceError::InvalidSpec(spec, msg)) = DiceExpr::Roll(bad_spec).roll() {
        println!("\n   DiceError::InvalidSpec:");
        println!("   - spec: {:?}", spec);
        println!("   - message: {}", msg);
    }

    // ========================================
    // 6. Complete Example
    // ========================================
    println!("\n6. Complete Example:");
    println!("   Building a complex expression with all features\n");

    // Character creation: 6 abilities, each 4d6 keep highest 3
    println!("   Rolling D&D ability scores (4d6 drop lowest):");
    let ability_roll = DiceExpr::Roll(RollSpec::new(4, 6, Some(Keep::Highest(3))));

    for i in 1..=6 {
        if let Ok(result) = ability_roll.roll() {
            println!(
                "   Ability {}: {} (rolls: {:?})",
                i, result.total, result.rolls
            );
        }
    }
}

pub fn parse(input: &str) -> Result<DiceExpr, DiceError>

Parse a dice expression from a string.

This is the prefred way to create a DiceExpr. This is especially useful when parsin user input. The parser supports a subset standard dice notation with addition and subtraction.

Supported Syntax

• Dice rolls: NdS where N is the number of dice and S is the number of sides
• Literals: Any integer (positive or negative)
• Addition: expr + expr
• Subtraction: expr - expr
• Whitespace is ignored

Note: Keep mechanics (e.g., “2d20kh” for keep highest, “6d6kl3” for keep lowest 3) are planned for a future release. Currently, use manual construction with RollSpec and Keep for keep functionality.

Parameters

• input: A string slice containing the dice expression

Returns

• Ok(DiceExpr): The parsed expression
• Err(DiceError): If the input is malformed or contains syntax errors

Examples

use dice_parser::DiceExpr;

// Simple dice roll
let expr = DiceExpr::parse("2d6").unwrap();

// With addition
let expr = DiceExpr::parse("1d20 + 5").unwrap();

// Complex expression
let expr = DiceExpr::parse("2d6 + 1d4 - 2").unwrap();

// Negative dice count is not allowed
assert!(DiceExpr::parse("-2d6").is_err());

Examples found in repository

examples/custom_rng.rs (line 9)

fn main() {
    println!("=== Deterministic Rolling with Custom RNG ===\n");

    let expr = DiceExpr::parse("2d6+3").unwrap();

    println!("Rolling the same expression with the same seed produces identical results:\n");

    // First roll with seed 42
    let rng1 = StdRng::seed_from_u64(42);
    let result1 = expr.roll_with_rng(rng1).unwrap();
    println!("First roll (seed 42):");
    println!("  Total: {}", result1.total);
    println!("  Rolls: {:?}", result1.rolls);

    // Second roll with the same seed should give the same result
    let rng2 = StdRng::seed_from_u64(42);
    let result2 = expr.roll_with_rng(rng2).unwrap();
    println!("\nSecond roll (seed 42):");
    println!("  Total: {}", result2.total);
    println!("  Rolls: {:?}", result2.rolls);

    assert_eq!(result1.total, result2.total);
    assert_eq!(result1.rolls, result2.rolls);
    println!("\n✓ Results match as expected!");

    // Different seed produces different results
    let rng3 = StdRng::seed_from_u64(123);
    let result3 = expr.roll_with_rng(rng3).unwrap();
    println!("\nThird roll (seed 123):");
    println!("  Total: {}", result3.total);
    println!("  Rolls: {:?}", result3.rolls);
    println!("\n✓ Different seed produces different results (usually)");
}

examples/error_handling.rs (line 10)

fn main() {
    println!("=== Error Handling Examples ===\n");

    // Parse error - invalid syntax
    println!("1. Parse error (missing sides):");
    match DiceExpr::parse("2d") {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(e) => println!("  Error: {}", e),
    }
    println!();

    // Syntax error - negative dice count
    println!("2. Syntax error (negative dice count):");
    match DiceExpr::parse("-2d6") {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(e) => println!("  Error: {}", e),
    }
    println!();

    // Trailing input error
    println!("3. Trailing input error:");
    match DiceExpr::parse("2d6 extra") {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(e) => println!("  Error: {}", e),
    }
    println!();

    // Invalid spec error (keep more than rolled)
    println!("4. Invalid roll specification:");
    use dice_parser::{RollSpec, Keep};
    let spec = RollSpec::new(2, 6, Some(Keep::Highest(5))); // Try to keep 5 dice when only rolling 2
    let expr = DiceExpr::Roll(spec);
    match expr.roll() {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(e) => println!("  Error: {}", e),
    }
    println!();

    // Pattern matching on error types
    println!("5. Pattern matching on DiceError:");
    let result = DiceExpr::parse("abc");
    match result {
        Ok(_) => println!("  Unexpectedly succeeded!"),
        Err(DiceError::ParseError { kind, input, start, stop: _ }) => {
            println!("  Parse error at position {}: {:?}", start, kind);
            println!("  Input: {}", input);
        }
        Err(e) => println!("  Other error: {}", e),
    }
}

examples/basic_usage.rs (line 7)

fn main() {
    println!("=== Basic Parsing and Rolling ===");
    let expr = DiceExpr::parse("2d6+3").unwrap();
    let result = expr.roll().unwrap();
    println!("Expression: 2d6+3");
    println!("Total: {}", result.total);
    println!("Rolls: {:?}", result.rolls);
    println!("Modifier: {}", result.modifier);
    println!();

    println!("=== Manual Construction ===");
    let roll_spec = RollSpec::new(4, 6, Some(Keep::Highest(3)));
    let expr = DiceExpr::Roll(roll_spec);
    let result = expr.roll().unwrap();
    println!("Expression: 4d6 keep highest 3");
    println!("Total: {}", result.total);
    println!("All rolls: {:?}", result.rolls);
    println!();

    println!("=== Complex Expression ===");
    let d2d6 = DiceExpr::Roll(RollSpec::new(2, 6, None));
    let d1d4 = DiceExpr::Roll(RollSpec::new(1, 4, None));
    let modifier = DiceExpr::Literal(2);
    let sum = DiceExpr::Sum(Box::new(d2d6), Box::new(d1d4));
    let expr = DiceExpr::Difference(Box::new(sum), Box::new(modifier));
    let result = expr.roll().unwrap();
    println!("Expression: (2d6 + 1d4) - 2");
    println!("Total: {}", result.total);
    println!();

    println!("=== D&D 5e Advantage ===");
    let advantage = DiceExpr::Roll(RollSpec::new(2, 20, Some(Keep::Highest(1))));
    let result = advantage.roll().unwrap();
    println!("Expression: 2d20 keep highest 1 (advantage)");
    println!("Rolls: {:?}", result.rolls);
    println!("Result: {}", result.total);
    println!();

    println!("=== D&D 5e Disadvantage ===");
    let disadvantage = DiceExpr::Roll(RollSpec::new(2, 20, Some(Keep::Lowest(1))));
    let result = disadvantage.roll().unwrap();
    println!("Expression: 2d20 keep lowest 1 (disadvantage)");
    println!("Rolls: {:?}", result.rolls);
    println!("Result: {}", result.total);
    println!();

    println!("=== Character Ability Scores ===");
    println!("Rolling 4d6 drop lowest for 6 abilities:");
    let ability_roll = DiceExpr::Roll(RollSpec::new(4, 6, Some(Keep::Highest(3))));
    for i in 0..6 {
        let result = ability_roll.roll().unwrap();
        println!("  Ability {}: {} (rolls: {:?})", i + 1, result.total, result.rolls);
    }
}

examples/complete_api.rs (line 15)

fn main() {
    // ========================================
    // 1. DiceExpr - The main expression type
    // ========================================

    // 1.1 Parsing from string
    println!("1. Parsing and expressions");
    let parsed = DiceExpr::parse("2d6+3").unwrap();
    println!("  1.1 Parsing e.g. \"2d6+3\" yields:");
    println!("    {:?}", parsed);

    // 1.2 DiceExpr variants - all publicly accessible
    let literal = DiceExpr::Literal(5);
    println!("  1.2 A literal expression \"5\": ");
    println!("    {:?}", literal);

    let roll = DiceExpr::Roll(RollSpec::new(2, 6, None));
    println!("  1.3 A single roll expression corresponding to 2d6:",);
    println!("    {:?}", roll);

    let sum = DiceExpr::Sum(Box::new(roll.clone()), Box::new(literal.clone()));
    println!("  1.4 A sum of two expression, e.g. \"2d6+5\":");
    println!("    {:?}", sum);

    let _diff = DiceExpr::Difference(Box::new(roll.clone()), Box::new(DiceExpr::Literal(1)));
    println!("  1.5 A difference of two expressions, e.g. \"2d6-1\":",);
    println!("    {:?}", _diff);

    // 1.3 Rolling methods
    println!("\n  1.6 DiceExpr::roll() - Rolling expressions");
    let result1 = parsed.roll().unwrap();
    println!("    An expression, 2d6+3: {}", result1.total);
    let result2 = literal.roll().unwrap();
    println!("    A literal 5: {}", result2.total);
    let result3 = roll.roll().unwrap();
    println!("    A single roll 2d6: {}", result3.total);
    let result4 = sum.roll().unwrap();
    println!("    A manual sum, 2d6+5: {}", result4.total);
    let result5 = _diff.roll().unwrap();
    println!("    A manual diff, 2d6-1: {}", result5.total);

    println!("\n   1.7 DiceExpr::roll_with_rng() - Roll with custom RNG");
    let rng = StdRng::seed_from_u64(42);
    let result6 = DiceExpr::parse("1d20").unwrap().roll_with_rng(rng).unwrap();
    println!("       Rolling 1d20: {}", result6.total);

    // ========================================
    // 2. RollSpec - Dice roll specification
    // ========================================
    println!("\n2. RollSpec Usage:");
    println!("   Struct with public fields and constructor\n");

    let spec = RollSpec::new(4, 6, Some(Keep::Highest(3)));
    println!("   RollSpec::new(4, 6, Some(Keep::Highest(3)))");
    println!("   - count: {}", spec.count);
    println!("   - sides: {}", spec.sides);
    println!("   - keep: {:?}", spec.keep);

    // ========================================
    // 3. Keep - Keep modifier enum
    // ========================================
    println!("\n3. Keep Usage:");
    println!("   Enum with public variants\n");

    let _keep_high = Keep::Highest(3);
    println!("   {:?} - Keep 3 highest dice", _keep_high);

    let _keep_low = Keep::Lowest(1);
    println!("   {:?} - Keep 1 lowest die", _keep_high);

    // Use in RollSpec
    let _advantage = RollSpec::new(2, 20, Some(Keep::Highest(1)));
    let _disadvantage = RollSpec::new(2, 20, Some(Keep::Lowest(1)));
    println!("\n  Example with Advantage:");
    println!(
        "    {:?}, result: {}",
        _advantage,
        DiceExpr::Roll(_advantage.clone()).roll().unwrap().total
    );
    println!("\n  Example with Disadvantage:");
    println!(
        "    {:?}, result: {}",
        _disadvantage,
        DiceExpr::Roll(_disadvantage.clone()).roll().unwrap().total
    );

    // ========================================
    // 4. ExprResult - Roll result
    // ========================================
    println!("\n4. ExprResult Usage:");
    println!("   Struct with public fields\n");

    let expr = DiceExpr::parse("2d6+3").unwrap();
    let result: ExprResult = expr.roll().unwrap();

    println!("   ExprResult from rolling 2d6+3:");
    println!("   - total: {} (final result)", result.total);
    println!("   - rolls: {:?} (individual dice)", result.rolls);
    println!("   - modifier: {} (constant modifiers)", result.modifier);

    // ========================================
    // 5. DiceError - Error handling
    // ========================================
    println!("\n5. DiceError Usage:");
    println!("   Enum with public variants for error handling\n");

    // ParseError variant
    if let Err(DiceError::ParseError {
        kind,
        input,
        start,
        stop: _,
    }) = DiceExpr::parse("invalid")
    {
        println!("   DiceError::ParseError:");
        println!("   - kind: {:?}", kind);
        println!("   - input: {}", input);
        println!("   - start: {}", start);
    }

    // SyntaxError variant
    if let Err(DiceError::SyntaxError { expected, .. }) = DiceExpr::parse("-2d6") {
        println!("\n   DiceError::SyntaxError:");
        if let Some(exp) = expected {
            println!("   - expected: {}", exp);
        }
    }

    // TrailingInput variant
    if let Err(DiceError::TrailingInput { pos, .. }) = DiceExpr::parse("2d6 extra") {
        println!("\n   DiceError::TrailingInput:");
        println!("   - pos: {}", pos);
    }

    // InvalidSpec variant
    let bad_spec = RollSpec::new(2, 6, Some(Keep::Highest(5)));
    if let Err(DiceError::InvalidSpec(spec, msg)) = DiceExpr::Roll(bad_spec).roll() {
        println!("\n   DiceError::InvalidSpec:");
        println!("   - spec: {:?}", spec);
        println!("   - message: {}", msg);
    }

    // ========================================
    // 6. Complete Example
    // ========================================
    println!("\n6. Complete Example:");
    println!("   Building a complex expression with all features\n");

    // Character creation: 6 abilities, each 4d6 keep highest 3
    println!("   Rolling D&D ability scores (4d6 drop lowest):");
    let ability_roll = DiceExpr::Roll(RollSpec::new(4, 6, Some(Keep::Highest(3))));

    for i in 1..=6 {
        if let Ok(result) = ability_roll.roll() {
            println!(
                "   Ability {}: {} (rolls: {:?})",
                i, result.total, result.rolls
            );
        }
    }
}

Trait Implementations

impl Clone for DiceExpr

fn clone(&self) -> DiceExpr

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DiceExpr

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for DiceExpr

type Err = DiceError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.