rouler/lib.rs
1// rouler - A container-based system for generating die rolls
2// Copyright (C) 2016 by John Berry
3//
4// This Source Code Form is subject to the terms of the Mozilla Public
5// License, v. 2.0. If a copy of the MPL was not distributed with this
6// file, You can obtain one at http://mozilla.org/MPL/2.0/.
7
8#![warn(missing_docs)]
9//! # rouler - A container-like system for generating dice rolls
10//!
11//! [](https://crates.io/crates/rouler)
12//!
13//! rouler is a library for handling repeatable dice rolls in a conveniently storable way.
14//! At the heart of rouler is the `Roller`, a simple struct that contains both the syntax for a specific
15//! dice roll, and the result of the most recent roll. This allows you to store a particular roll
16//! type in a variable, that can then be passed around (within the limits of mutable values), and
17//! repeated via method calls as needed. It is meant to be useful for CRPGs and tabletop game aids.
18//!
19//! ## Example usage
20//!
21//! ```
22//! use rouler::Roller;
23//!
24//! let mut stat = Roller::new("3d6");
25//!
26//! println!("STR: {}", stat.total());
27//! println!("DEX: {}", stat.reroll());
28//! ```
29//!
30//! ## The Die Roll Syntax
31//!
32//! rouler uses parsed strings to define die rolls, according to the following [pest](https://github.com/dragostis/pest/)
33//! grammar found in `rouler.pest`, with some additional rules checking:
34//!
35//! ```rust,ignore
36//! number = @{ "-"? ~ ("0" | '1'..'9' ~ '0'..'9'*) }
37//! op = _{ plus | minus | times | slash }
38//! plus = { "+" }
39//! minus = { "-" }
40//! times = { "*" }
41//! slash = { "/" }
42//!
43//! dice = _{ number ~ (roll ~ number) }
44//! roll = { "d" | "D" }
45//! custom_dice = { number ~ roll ~ sides }
46//! sides = _{ "[" ~ number ~ ("," ~ number )* ~ "]" }
47//!
48//! expr = { term ~ (op ~ term)* }
49//! term = _{ custom_dice | dice | number | "(" ~ expr ~ ")" }
50//!
51//! calc = _{ soi ~ expr ~ eoi }
52//!
53//! whitespace = _{ " " }
54//! ```
55//!
56//! Largely this should all be familiar basic mathematical notation, the key addition being the `d` operator,
57//! which operates according to the standard notation familiar from tabletop RPGs, ie.:
58//!
59//! `n[d|D]s`, where `n` = the number of dice to roll, and `s` = the number of sides on each die.
60//!
61//! There are additional constraints checked for in this operator alone as well: neither `n` or `s` can be zero,
62//! and `s` cannot be a negative number. `n` is allowed to be negative, but rather than rolling "negative dice",
63//! this merely negates the value of the entire roll, such that `-3d6` would generate a value between -3 and -18.
64//!
65//! Custom dice can also be specified, with arbitrary specific values, such as `1d[2,4,8,16,32,64]`, where the
66//! list after the `d` operator represents each face on the specified die (in this case, a backgammon doubling cube).
67//!
68//! ## Changelog
69//!
70//! ### 0.2.1
71//! * docs update
72//!
73//! ### 0.2.0
74//! * support for better error handling
75//! * updated to pest 1.0 grammar
76//! * arbitrary die sequences
77//!
78//! ### 0.1.3
79//! * Added Iterator support to Rollers
80//! * Better type inference for Roller::new()
81//!
82//! ### 0.1.2
83//! * Documentation fixes
84//!
85//! ### 0.1.1
86//! * Documentation fixes
87//!
88//! ### 0.1.0
89//! * Initial release
90//!
91#[macro_use]
92extern crate pest;
93#[macro_use]
94extern crate pest_derive;
95extern crate rand;
96#[macro_use]
97extern crate lazy_static;
98
99mod parse;
100mod random;
101mod roll;
102
103pub use roll::{Roller, roll_dice, roll_dice_or_fail, roller_or_fail};