Expand description
rouler - A container-like system for generating dice rolls
rouler is a library for handling repeatable dice rolls in a conveniently storable way.
At the heart of rouler is the Roller
, a simple struct that contains both the syntax for a specific
dice roll, and the result of the most recent roll. This allows you to store a particular roll
type in a variable, that can then be passed around (within the limits of mutable values), and
repeated via method calls as needed. It is meant to be useful for CRPGs and tabletop game aids.
Example usage
use rouler::Roller;
let mut stat = Roller::new("3d6");
println!("STR: {}", stat.total());
println!("DEX: {}", stat.reroll());
The Die Roll Syntax
rouler uses parsed strings to define die rolls, according to the following pest
grammar found in rouler.pest
, with some additional rules checking:
number = @{ "-"? ~ ("0" | '1'..'9' ~ '0'..'9'*) }
op = _{ plus | minus | times | slash }
plus = { "+" }
minus = { "-" }
times = { "*" }
slash = { "/" }
dice = _{ number ~ (roll ~ number) }
roll = { "d" | "D" }
custom_dice = { number ~ roll ~ sides }
sides = _{ "[" ~ number ~ ("," ~ number )* ~ "]" }
expr = { term ~ (op ~ term)* }
term = _{ custom_dice | dice | number | "(" ~ expr ~ ")" }
calc = _{ soi ~ expr ~ eoi }
whitespace = _{ " " }
Largely this should all be familiar basic mathematical notation, the key addition being the d
operator,
which operates according to the standard notation familiar from tabletop RPGs, ie.:
n[d|D]s
, where n
= the number of dice to roll, and s
= the number of sides on each die.
There are additional constraints checked for in this operator alone as well: neither n
or s
can be zero,
and s
cannot be a negative number. n
is allowed to be negative, but rather than rolling “negative dice”,
this merely negates the value of the entire roll, such that -3d6
would generate a value between -3 and -18.
Custom dice can also be specified, with arbitrary specific values, such as 1d[2,4,8,16,32,64]
, where the
list after the d
operator represents each face on the specified die (in this case, a backgammon doubling cube).
Changelog
0.2.1
- docs update
0.2.0
- support for better error handling
- updated to pest 1.0 grammar
- arbitrary die sequences
0.1.3
- Added Iterator support to Rollers
- Better type inference for Roller::new()
0.1.2
- Documentation fixes
0.1.1
- Documentation fixes
0.1.0
- Initial release
Structs
The Roller
is the core struct of the library. The basic principle is to provide a reusable
container that provides a specific kind of die roll, so that it can be quickly and easily repeated
whenever called for. Each container contains the syntax of the roll type it represents, and the
value of the last roll it made. Containers are thus self-mutating, but self-contained.
Functions
A simple function for throwaway die rolls that do not need to be saved as a
Roller
. Provided for convenience.
A function for throwaway die rolls that do not need to be saved as a
Roller
. Provided for convenience.
A function for safely creating a new Roller
without panicking.