Function parse 

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

parse builds a generator from the given input string. If any of the string can be parsed a generator is returned. If no generator can be built then an error is returned with the input string.

• Examples

use rand::prelude::*;
let mut rng = rand::rng();
let g = dice_nom::parse("2d4! + 2d6! < 3d8!");
assert!(g.is_ok());
if let Ok(g) = g {
    let results = g.generate(&mut rng);
    assert!(!results.rhs.is_none());
}

let g = dice_nom::parse("attack badger");
assert!(!g.is_ok());
assert_eq!(g, Err("attack badger"));

Examples found in repository

examples/basic_usage.rs (line 35)

fn main() {
    let mut rng = rand::rng();

    println!("=== Basic Dice Rolling ===");

    // Simple dice rolls using the roller function
    let simple_d6 = roller(1, 6, None);
    let result = simple_d6.generate(&mut rng);
    println!("1d6: {}", result);

    let multiple_dice = roller(3, 6, None);
    let result = multiple_dice.generate(&mut rng);
    println!("3d6: {}", result);

    println!("\n=== Parsing Complex Expressions ===");

    // Parse and roll various dice expressions
    let expressions = vec![
        "3d6+4",   // Basic arithmetic
        "2d8-1",   // Subtraction
        "1d20+5",  // Common D&D roll
        "4d6^3",   // Keep highest 3 of 4 dice
        "2d20ADV", // Advantage (roll twice, keep higher)
        "2d20DIS", // Disadvantage (roll twice, keep lower)
    ];

    for expr in expressions {
        match parse(expr) {
            Ok(generator) => {
                let result = generator.generate(&mut rng);
                println!("{}: {}", expr, result);
            }
            Err(_) => println!("Failed to parse: {}", expr),
        }
    }

    println!("\n=== Exploding Dice ===");

    // Exploding dice examples
    let exploding_expressions = vec![
        "3d6!",   // Explode on max (reroll once if all dice are 6)
        "2d8!!",  // Explode until (keep rerolling while all dice are max)
        "4d6*",   // Explode each (reroll each die that's max)
        "3d10**", // Explode each until (keep rerolling each max die)
    ];

    for expr in exploding_expressions {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!("{}: {}", expr, result);
        }
    }

    println!("\n=== Target Numbers and Success Counting ===");

    // Target-based rolling
    let target_expressions = vec![
        "6d6[4]",     // Count dice >= 4 as successes
        "4d10(3)",    // Count dice <= 3 as successes
        "3d6{12}",    // Success if total >= 12
        "2d10{15,5}", // 1 success at 15, +1 for every 5 above
    ];

    for expr in target_expressions {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!("{}: {}", expr, result);
        }
    }

    println!("\n=== Pool Manipulation ===");

    // Pool operations
    let pool_expressions = vec![
        "5d6^3", // Keep highest 3
        "5d6`2", // Keep lowest 2
        "6d6~4", // Keep middle 4
        "5d6Y",  // Keep largest group of matching dice
    ];

    for expr in pool_expressions {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!("{}: {}", expr, result);
        }
    }

    println!("\n=== Comparisons ===");

    // Comparison operations
    let comparison_expressions = vec![
        "3d6 > 2d8",    // Left vs right comparison
        "1d20+5 >= 15", // Skill check vs DC
        "2d6 = 7",      // Exact match
        "3d6 <=> 3d6",  // Three-way comparison (-1, 0, or 1)
    ];

    for expr in comparison_expressions {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!(
                "{}: {} ({})",
                expr,
                result,
                if result.sum() == 1 {
                    "Success"
                } else if result.sum() == -1 {
                    "Failure"
                } else if result.sum() == 0 {
                    "Tie/False"
                } else {
                    "Unknown"
                }
            );
        }
    }

    println!("\n=== Multiple Rolls ===");

    // Demonstrate multiple rolls of the same expression
    if let Ok(generator) = parse("3d6") {
        println!("Rolling 3d6 five times:");
        for i in 1..=5 {
            let result = generator.generate(&mut rng);
            println!("Roll {}: {}", i, result);
        }
    }

    println!("\n=== Error Handling ===");

    // Show error handling for invalid expressions
    let invalid_expressions = vec!["attack the goblin", "3d6 + invalid", "d", ""];

    for expr in invalid_expressions {
        match parse(expr) {
            Ok(_) => println!("{}: Parsed successfully (unexpected!)", expr),
            Err(remaining) => println!("{}: Failed to parse, remaining: '{}'", expr, remaining),
        }
    }
}

examples/gaming_systems.rs (line 16)

fn main() {
    let mut rng = rand::rng();

    println!("=== D&D 5th Edition Examples ===");

    // Character creation - roll stats
    println!("Rolling ability scores (4d6, drop lowest):");
    for ability in ["STR", "DEX", "CON", "INT", "WIS", "CHA"] {
        if let Ok(generator) = parse("4d6^3") {
            let result = generator.generate(&mut rng);
            println!("{}: {}", ability, result);
        }
    }

    // Combat rolls
    println!("\nCombat examples:");
    let combat_rolls = vec![
        ("Attack roll (d20+5)", "1d20+5"),
        ("Damage (longsword)", "1d8+3"),
        ("Sneak attack", "1d8+3+3d6"),
        ("Fireball damage", "8d6"),
        ("Healing potion", "2d4+2"),
    ];

    for (description, expr) in combat_rolls {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!("{}: {}", description, result);
        }
    }

    // Advantage/Disadvantage
    println!("\nAdvantage and Disadvantage:");
    let adv_dis_rolls = vec![
        ("Attack with Advantage", "1d20ADV+5"),
        ("Stealth with Disadvantage", "1d20DIS+2"),
    ];

    for (description, expr) in adv_dis_rolls {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!("{}: {}", description, result);
        }
    }

    println!("\n=== Call of Cthulhu  ===");

    // Character creation - roll stats
    println!("Generate statistics:");
    let character_stats = vec![
        ("STR (Strength)", "3d6x5"),
        ("CON (Constitution)", "3d6x5"),
        ("SIZ (Size)", "2d6+6x5"),
        ("DEX (Dexterity)", "3d6x5"),
        ("APP (Appearance)", "3d6x5"),
        ("INT (Intelligence)", "2d6+6x5"),
        ("POW (Power)", "3d6x5"),
        ("EDU (Education)", "2d6+6x5"),
        ("Luck", "3d6x5"),
    ];

    for (description, expr) in character_stats {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!("{}: {}", description, result);
        }
    }

    println!("\n=== World of Darkness Examples ===");

    // Success counting system
    let wod_rolls = vec![
        ("Dexterity + Athletics (6 dice)", "6d10[6]"),
        ("Manipulation + Subterfuge (4 dice)", "4d10[6]"),
        ("Intelligence + Academics (7 dice)", "7d10[6]"),
    ];

    for (description, expr) in wod_rolls {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!("{}: {} successes", description, result.lhs.hits());
        }
    }

    println!("\n=== Shadowrun Examples ===");

    // Edge cases and exploding dice
    let shadowrun_rolls = vec![
        ("Firearms skill test", "8d6[5]"),
        ("Edge-enhanced roll", "8d6**[5]"),
        ("Damage resistance", "6d6[5]"),
    ];

    for (description, expr) in shadowrun_rolls {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            println!("{}: {} hits", description, result.lhs.hits());
        }
    }

    println!("\n=== GURPS Examples ===");

    // 3d6 roll-under system
    let gurps_rolls = vec![
        ("Skill check vs 12", "3d6 <= 12"),
        ("Attribute check vs 14", "3d6 <= 14"),
        ("Hard skill check vs 10", "3d6 <= 10"),
    ];

    for (description, expr) in gurps_rolls {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            let success = result.sum() == 1;
            println!(
                "{}: {} ({})",
                description,
                result.lhs.sum(),
                if success { "Success" } else { "Failure" }
            );
        }
    }

    println!("\n=== Fate/Fudge Examples ===");

    // Fudge dice simulation using d3 (1=-, 2=blank, 3=+)
    println!("Fate dice (simulated with d3s where 1=-, 2=0, 3=+):");
    for i in 1..=3 {
        if let Ok(generator) = parse("4d3--2") {
            let result = generator.generate(&mut rng);
            let fate_result = result.sum();
            println!(
                "Roll {}: {} ({})",
                i,
                result,
                match fate_result {
                    -4..=-3 => "Terrible",
                    -2..=-1 => "Poor",
                    0 => "Mediocre",
                    1..=2 => "Good",
                    3..=4 => "Great",
                    _ => "Exceptional",
                }
            );
        }
    }

    println!("\n=== Savage Worlds Examples ===");

    // Exploding dice and Aces
    let savage_worlds_rolls = vec![
        ("Fighting with d8", "1d8!"),
        ("Shooting with d10", "1d10!"),
        ("Wild die + trait", "1d6! + 1d8!"),
        ("Damage with d6+2", "1d6!+2"),
    ];

    for (description, expr) in savage_worlds_rolls {
        if let Ok(generator) = parse(expr) {
            let result = generator.generate(&mut rng);
            let total = result.sum();
            println!(
                "{}: {} ({})",
                description,
                result,
                if total >= 4 { "Success" } else { "Failure" }
            );
        }
    }
}