dice_parser/lib.rs
1//! # dice-parser
2//!
3//! A parser and roller for standard RPG dice notation.
4//!
5//! This crate provides a simple way to parse and evaluate dice expressions
6//! commonly used in tabletop role-playing games. It supports basic arithmetic operations
7//! (addition and subtraction) and dice rolling with various modifiers.
8//!
9//! ## Features
10//!
11//! - Parse standard dice notation (e.g., "2d6", "1d20+5", "3d8-2")
12//! - Support for keep highest/lowest mechanics (currently via manual construction only; parsing support planned for future release)
13//! - Detailed roll results including individual die rolls and modifiers
14//! - Custom RNG support for deterministic testing
15//! - Comprehensive error handling
16//!
17//! ## Quick Start
18//!
19//! ### Parsing and Rolling
20//!
21//! ```
22//! use dice_parser::DiceExpr;
23//!
24//! // Parse a dice expression from a string
25//! let expr = DiceExpr::parse("2d6+3").unwrap();
26//!
27//! // Roll the dice
28//! let result = expr.roll().unwrap();
29//! println!("Total: {}", result.total);
30//! println!("Rolls: {:?}", result.rolls);
31//! println!("Modifier: {}", result.modifier);
32//! ```
33//!
34//! ### Manual Construction
35//!
36//! ```
37//! use dice_parser::{DiceExpr, RollSpec, Keep};
38//!
39//! // Manually construct a dice expression: 4d6 keep highest 3
40//! let roll_spec = RollSpec::new(4, 6, Some(Keep::Highest(3)));
41//! let expr = DiceExpr::Roll(roll_spec);
42//!
43//! let result = expr.roll().unwrap();
44//! println!("Total: {}", result.total);
45//! ```
46//!
47//! ### Using Custom RNG
48//!
49//! ```
50//! use dice_parser::DiceExpr;
51//! use rand::{SeedableRng, rngs::StdRng};
52//!
53//! let expr = DiceExpr::parse("1d20").unwrap();
54//! let rng = StdRng::seed_from_u64(42);
55//! let result = expr.roll_with_rng(rng).unwrap();
56//! ```
57
58mod ast;
59mod error;
60mod parser;
61mod roller;
62
63pub use crate::ast::{DiceExpr, Keep, RollSpec};
64pub use crate::error::DiceError;
65pub use crate::roller::ExprResult;