A Swift library implementing a dice roller with various modifiers and mathematical operators.

The simplest way to roll dice is to use create a DiceRoller and call its parse(input:) method to obtain a tuple containing the parsed input, the roll results, and the final sum:

import DiceRoller

let roller = DiceRoller()
let (parsed, rolled, total) = try roller.parse(input: "2d8 + 2 + 1d4")
print("\(parsed): \(rolled) = \(total)")

The above code would output something like the following:

2d8+2+1d4: [7, 2]+2+[3] = 14

A more involved method of making the roll would be to call DiceRoller.decodeExpression(from:). This would return an Expression instance, the root of a tree of expressions.

Once you have an Expression, you can access a Lisp-style representation of the expression tree using Expression.debugDescription. Similarly Expression.description will yield the parsed version of the input---including any inferred values.

To roll the dice, you can call Expression.rolled() to obtain a new expression tree in which all dice groups have been rolled, and their outputs grouped in square braces ([]). Any modifiers will have been applied at this point; they will leave flags on any dice values they affected.

Lastly, the total of the roll can be obtained by calling Expression.computedValue. This will sum the dice rolled (or the number of successes, depending on the modifiers used), and will perform any mathematical operations included in the input to yield a final value.

To use the DiceRoller library in a SwiftPM project, add it to the dependencies for your package and your command-line executable target:

let package = Package(
    // name, platforms, products, etc.
    dependencies: [
        // other dependencies
        .package(url: "https://github.com/AlanQuatermain/DiceRoller", .branch("main")),
    ],
    targets: [
        .executableTarget(name: "<command-line-tool>", dependencies: [
            // other dependencies
            .product(name: "DiceRoller", package: "DiceRoller")
        ]),
        // other targets
    ]
)