## bin+lib ndice

A cli dice roller

### 2 releases(1 stable)

 1.0.0 May 10, 2023 Apr 28, 2023

#1 in #dice-roller

MIT license

15KB
299 lines

# ndice

Role a `n`ice `dice` (or `[n|d]ice`?)

# Table of Contents

## About

`ndice` is a cli dice roller and dice-rolling library.

Dices are writen in the format `\${number}\${exploding}d{\$sides}`, e.g. `1d6` means 1 six-sided dice. There's no limit to sides so a non-existing dice like `1d13` can be rolled.

• Each space-speparated argument is counted as one dice notation.
• Dices can be mixed, so `ndice 1d6 2d8 4d10` works.
• Invalid arguments are ignored.

## Installation

⬆️ Back to Top

### Binary

Download a pre-compiled binary from the release page

### Cargo

Install with cargo:

``````\$ cargo install ndice
``````

## Usage (CLI)

⬆️ Back to Top

``````\$ ndice [dice]
``````

Examples:

``````# Roll 1 six-sided dice
\$ ndice 1d6
Rolled: ["d6 => 1"]
Result: 1
# Roll 2 8 sided dice and 2 four sided dice
\$ ndice 2d8 2d4
Rolled: ["d8 => 6", "d8 => 3", "d4 => 1", "d4 => 1"]
Result: 11
``````

### Exploding dice

An exploding dice is a dice that is re-rolled when the highest possible value is rolled.

To roll a exploding dice use `ed` instead of `d` as argument.

• `1d6` -> normal d6
• `1ed6` -> exploding d6

### Modifier

A positive or negative modifier can be added to each dice.

• `1d6+2` -> add +2 to the result of rolling a d6
• `1d20-4` -> subtract 4 from the result of rolling a d20

## Usage (Library)

ndice can be used as library.

Add the library to Cargo.toml

``````[dependencies]
ndice = 1.0
``````

Optional JSON features can be enabled with a flag.

``````[dependencies]
ndice = { version = "1.0", features = ["json"] }
``````

And finally, call the two functions: `ndice::parse_dices` and `ndice::roll_dices`.

``````fn my_func() {
let args: Vec<String> = vec![String::from("1d6"), String::from("2d4"), String::from("1ed4")];
let dice_in_hand = ndice::parse_dices(args).unwrap();
let roll = ndice::roll_dices(dice_in_hand);
println!("{}", roll);
}
``````

See src/bin.rs for an example implementation.

## Contributing

⬆️ Back to Top

We love and welcome every form of contribution.

### Where to start?

Here are some good places to start:

### Tooling

• mktoc is used for table of content generation in the README.md (neat!)

### Install dev build

Sometimes it's nice to install a specific version of ndice, this can be done with the following command:

``````# install specific commit
cargo install --git https://github.com/KevinGimbel/ndice--force --rev \$COMMIT_ID
# install branch
cargo install --git https://github.com/KevinGimbel/ndice--force --branch \$BRANCH_NAME
``````

## License

⬆️ Back to Top

MIT, see LICENSE file.

~2.3–3.5MB
~62K SLoC