Rollex is an elixir application that lets you evaluate dice rolls with simple arithmetic operators. The API attempts to follow common, de facto standards found in other dice rolling applications (e.g. VTTs) and libraries as much as possible for familiarity and ease of use.

• The operators supported are +, -, /, *.
• Grouping is via parentheses
• Polyhedral dice are designated using the <quantity>d<sides> format (Ex. 20d8 or D100). The following operations are supported to filter such rolls:
  • <: consider rolls less than the target number to be successes (3d10<4)
  • >: consider rolls greater than the target number to be successes (3d10>4)
  • =: consider rolls equal to the target number to be successes (1d6=6)
  • =[low..high]: consider rolls between low and high to be successes (1d6=[1..2])
  • =[x,y,..]: consider rolls in the list of numbers to be successes (1d6=[1,3,5] would succeed on odd numbers only)
  • o: only odd numbers are considered succcesses
  • e: only even numbers are considered succcesses
  • k and kh: keeps the highest N dice in the pool (4d6k3 or 4d6kh3)
  • kl: keeps the lowest N dice in the pool (4d6kl2)
  • dh: drops the highest N dice in the pool (4d6dh2)
  • d and dl: drops the lower N dice in the pool (4d6d1 or 4d6dl1)
  • r<, r>, and r= reroll dice that are less than, greater then, or equal to a number (or a range in the case of equality)
• Fudge dice are designated using '<quantity>df', The starting state may optionally be provided with a one-letter code for: (t)errible, (p)oor, (m)ediocre, (f)air, (g)ood, g(r)eat, (s)superb If no starting state is defined, it assumed to start at the neutral "fair" state.

When a roll is evaluated, Rollex returns a tagged success tuple ({:ok | :error, term}). On success, the term is a map that contains a tokens and a totals field. The totals field contains information such as the sum total (arithmetic) and the number of successes, while the tokens field contains each token and their respect results.

Tokens with the is_dice: true field represent "rollable" dice. This can be used to, for example, filter the results for dice that were rolled and show the user a representation of those dice being rolled.

Example:

iex> Rollex.roll("1d6+1d4")
{:ok,
  %{
    tokens: [
      %Rollex.Tokens.RegularDice{
        arithmetic: 3,
        is_dice: true,
        operation: nil,
        quantity: 1,
        regex: ~r/A(*)[dD](+)/,
        rejected_rolls: [],
        sides: 6,
        valid_rolls: [3]
      },
      %Rollex.Tokens.Addition{regex: ~r/A+/},
      %Rollex.Tokens.RegularDice{
        arithmetic: 1,
        is_dice: true,
        operation: nil,
        quantity: 1,
        regex: ~r/A(*)[dD](+)/,
        rejected_rolls: [],
        sides: 4,
        valid_rolls: [1]
      },
      %Rollex.Tokens.End{regex: ~r/Az/}
    ],
    totals: %{arithmetic: 4, successes: 2}
  }
}

Dice expressions may also be precompiled using compile/2. The resulting struct can then be passed to evaluate/1 as many times as desired. These are therefore all equivalent:

Rollex.roll("1d6")
Rollex.compile("1d6") |> Rollex.evaluate()

dice = Rollex.compile("1d6")
Rollex.evaluate(dice)
Rollex.evaluate(dice)

A map containing the odds for all possible results of a given dice roll can be generated by passing a compiled roll to histogram/1:

iex> Rollex.compile("2d6") |> Rollex.histogram()
{:ok,
  %{
    2 => 2.778,
    3 => 5.556,
    4 => 8.333,
    5 => 11.111,
    6 => 13.889,
    7 => 16.667,
    8 => 13.889,
    9 => 11.111,
    10 => 8.333,
    11 => 5.556,
    12 => 2.778
  }
}