ExDiceRoller v0.3.0-alpha ExDiceRoller

Converts strings into dice rolls and returns expected results. Ignores any spaces, including tabs and newlines, in the provided string.

Examples

iex> ExDiceRoller.roll("1")
1

iex> ExDiceRoller.roll("1d8")
1

iex> ExDiceRoller.roll("2d20 + 5")
34

iex> ExDiceRoller.roll("2d8 + -5")
0

iex> ExDiceRoller.roll("(1d4)d(6*5) - (2/3+1)")
18

iex> ExDiceRoller.roll("1+2-3*4+5/6*7+8-9")
-4

iex> ExDiceRoller.roll("1+  2*3d 4")
15

iex> ExDiceRoller.roll("1dx+6", x: 10)
15

Order of Precedence

The following table shows order of precendence, from highest to lowest, of the operators available to ExDiceRoller.

OperatorAssociativity
dleft-to-right
+, -unary
*, /left-to-right
+, -left-to-right

Effects of Parentheses

As in math, parentheses can be used to create sub-expressions.

iex> ExDiceRoller.tokenize("1+3d4*1-2/-3") |> elem(1) |> ExDiceRoller.parse()
{:ok,
{{:operator, '-'},
  {{:operator, '+'}, {:digit, '1'},
  {{:operator, '*'}, {:roll, {:digit, '3'}, {:digit, '4'}}, {:digit, '1'}}},
  {{:operator, '/'}, {:digit, '2'}, {:digit, '-3'}}}}

iex> ExDiceRoller.tokenize("(1+3)d4*1-2/-3") |> elem(1) |> ExDiceRoller.parse()
{:ok,
{{:operator, '-'},
  {{:operator, '*'},
  {:roll, {{:operator, '+'}, {:digit, '1'}, {:digit, '3'}}, {:digit, '4'}},
  {:digit, '1'}}, {{:operator, '/'}, {:digit, '2'}, {:digit, '-3'}}}}

iex> ExDiceRoller.tokenize("1+3d(4*1)-2/-3") |> elem(1) |> ExDiceRoller.parse()
{:ok,
{{:operator, '-'},
  {{:operator, '+'}, {:digit, '1'},
  {:roll, {:digit, '3'}, {{:operator, '*'}, {:digit, '4'}, {:digit, '1'}}}},
  {{:operator, '/'}, {:digit, '2'}, {:digit, '-3'}}}}

iex> ExDiceRoller.tokenize("1+3d4*(1-2)/-3") |> elem(1) |> ExDiceRoller.parse()
{:ok,
{{:operator, '+'}, {:digit, '1'},
  {{:operator, '/'},
  {{:operator, '*'}, {:roll, {:digit, '3'}, {:digit, '4'}},
    {{:operator, '-'}, {:digit, '1'}, {:digit, '2'}}}, {:digit, '-3'}}}}

Compiled Rolls

Some systems utilize complex dice rolling equations. Repeatedly tokenizing, parsing, and interpreting complicated dice rolls strings can lead to a performance hit on an application. To ease the burden, developers can compile a dice roll string into an anonymous function. This anonymous function can be cached and reused repeatedly without having to re-parse the string, nor re-interpret the parsed expression.

iex> {:ok, roll_fun} = ExDiceRoller.compile("2d6+3")
iex> ExDiceRoller.execute(roll_fun)
8
iex> ExDiceRoller.execute(roll_fun)
13
iex> ExDiceRoller.execute(roll_fun)
10
iex> ExDiceRoller.execute(roll_fun)
11

Link to this section Summary

Functions

Takes a given expression from parse and calculates the result

Compiles a string or t:expression/0 into an anonymous function

Executes a function built by compile/1

Processes a given string as a dice roll and returns the final result. Note that the final result is a rounded integer

Link to this section Functions

Link to this function calculate(expression, args \\ [])

Takes a given expression from parse and calculates the result.

Compiles a string or t:expression/0 into an anonymous function.

iex> {:ok, roll_fun} = ExDiceRoller.compile("1d8+2d(5d3+4)/3")
iex> ExDiceRoller.execute(roll_fun)
5.0
Link to this function execute(compiled, args \\ [])
execute(function(), Keyword.t()) :: number()

Executes a function built by compile/1.

Link to this function roll(roll_string, args \\ [])
roll(String.t(), Keyword.t()) :: integer()

Processes a given string as a dice roll and returns the final result. Note that the final result is a rounded integer.

iex> ExDiceRoller.roll("1d6+15")
18
Link to this function tokenize(roll_string)
tokenize(String.t()) :: {:ok, ExDiceRoller.Tokenizer.tokens()}

Helper function that calls ExDiceRoller.Tokenizer.tokenize/1.