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.
Operator | Associativity |
---|---|
d | left-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
Helper function that calls ExDiceRoller.Tokenizer.tokenize/1
Processes a given string as a dice roll and returns the final result. Note that the final result is a rounded integer
Helper function that calls ExDiceRoller.Tokenizer.tokenize/1
Link to this section Functions
calculate(ExDiceRoller.Parser.expression(), Keyword.t()) :: number()
Takes a given expression from parse and calculates the result.
compile(String.t() | ExDiceRoller.Parser.expression()) :: {:ok, ExDiceRoller.Compiler.compiled_function()} | {:error, any()}
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
Executes a function built by compile/1
.
parse(ExDiceRoller.Tokenizer.tokens()) :: {:ok, ExDiceRoller.Parser.expression()}
Helper function that calls ExDiceRoller.Tokenizer.tokenize/1
.
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
tokenize(String.t()) :: {:ok, ExDiceRoller.Tokenizer.tokens()}
Helper function that calls ExDiceRoller.Tokenizer.tokenize/1
.