Command Functions

Below is the large list of command functions available for use in the dice parser, along with instructions on how to read the documentation. (Well, there will be, soon enough. :P)

Format

Functions are displayed as follows:

Sample Function Name

A brief description of the function will be displayed here.

Syntax:

Basic usage syntax will be in a bar like this

Operator Type: Operators can be infix, prefix, postfix, or functional. While the distinction should be obvious from the syntax, their type is listed here for clarity.

Precedence: Non-functional operators have a precedence, which dictates the order of operations for function resolution. Higher precedence operators are resolved first.

Operands:

  • The first operand’s function will be described here
    • Valid Types:
      • Valid input types will be listed in a sublist,
      • like this one. Sometime, additional restrictions will also be listed
  • Then we’ll move onto the second operand, and so on
    • Valid Types:
      • If a function is overloaded, some additional information
      • may be displayed in these sublists

Dice Functions

The following commands allow the creation or manipulation of dice.

Dice Creation ( d )

The d function creates new dice pools.

Syntax:

XdY

OR

dY

Operator Type: Prefix or Infix

Precedence: 12

Operands:

  • X: pool number. The resulting die pool will roll this many dice.

    • Valid Types:

      • Integers: Must be greater than zero
      • Dice: Will be evaluated, then, if the result is a positive integer, it will be used as in the above case.

  • Y: dice face. This represents the faces present on each die.

    • Valid Types:

      • Integers: Must be greater than zero. This will return dice with faces from one to Y.
      • Dice: Will be evaluated, then, if the result is a positive integer, it will be used as in the above case.
      • Vectors: Must contain only numbers. This will return dice whose faces are the elements of the vector.

Fudge Dice ( dF )

The dF function creates a Fudge dice pool

Syntax:

XdF

Operator Type: Postfix

Precedence: 11

Operands:

  • X: pool number. The resulting die pool will roll this many fudge dice.

    • Valid Types:

      • Integers: Must be greater than zero
      • Dice: Will be evaluated, then, if the result is a positive integer, it will be used as in the above case.

Keep/Drop Functions ( kh, kl, dh, dl)

The kh, kl, dh, and dl functions all serve similar functions; they modify an existing dice pool to (k)eep or (d)rop either (h)igh or (l)ow dice.

Syntax:

D{ kh | kl | dh | dl }N

Operator Type: Infix

Precedence: 10

  • D: The dice pool to modify.

    • Valid Types:

      • Dice

  • N: The number of high or low dice to keep or drop.

    • Valid Types:

      • Integers: Must be greater than zero
      • Dice: Will be evaluated, then, if the result is a positive integer, it will be used as in the above case.

Reroll Functions ( r and friends)

The r, r<, r<=, r>, r>=, rIn, and rOut functions all modify an existing dice pool, passed as a left argument, to reroll dice that meet a specific predicate:

  • r rerolls dice that are equal to its right-hand argument
  • r< rerolls dice that are less than its right-hand argument
  • r<= rerolls dice that are less than or equal to its right-hand argument
  • r> rerolls dice that are greater than its right-hand argument
  • r>= rerolls dice that are greater than or equal to its right-hand argument
  • rIn rerolls dice that are greater than or equal to the first element of its right hand argument AND less than or equal to the second element of its right-hand argument.
  • rOut rerolls dice that are less than or equal to the first element of its right hand argument OR less than or equal to the second element of its right-hand argument.

If a single dice pool is modified multiple times, rolls that meet the outer-most provided stipulation will be rerolled.

Syntax:

D{ r | r< | r<= | r> | r>= | rIn | rOut }N

Operator Type: Infix

Precedence: 10

  • D: The dice pool to modify.

    • Valid Types:

      • Dice

  • N: The number to test against.

    • Valid Types:

      • rIn and rOut

        • Vector: rIn and rOut both take a two-element vector of real numbers.

      • Remaining functions

        • Numbers: If the function is r, N may be any number. Otherwise, N must be a real number.
        • Dice: Will be evaluated, then, if the result is a valid number, it will be used as in the above case.

Exploding Functions ( ! and friends)

The !, !<, !<=, !>, and !>= functions all modify an existing dice pool, passed as a left argument, to have dice explode when they meet a specific predicate:

  • ! can either be an infix or a postfix operator. If it has a right argument, ! will cause dice to explode when equal to its right argument; otherwise, it will cause dice to explode when equal to the maximum possible face of the die.
  • !< causes dice whose results are less than its right-hand argument to explode.
  • !<= causes dice whose results are less than or equal to its right-hand argument to explode.
  • !> causes dice whose results are greater than its right-hand argument to explode.
  • !>= causes dice whose results are greater than or equal to its right-hand argument to explode.
  • !In causes dice whose results are greater than or equal to the first element of its right hand argument AND less than or equal to the second element of its right-hand argument to explode.
  • !Out causes dice whose results are less than or equal to the first element of its right hand argument OR less than or equal to the second element of its right-hand argument to explode.

If a single dice pool is modified multiple times, rolls that meet any of the provided stipulations will explode.

Syntax:

D{ ! | !< | !<= | !> | !>= | !In | !Out }N

Operator Type: Infix

Precedence: 10

  • D: The dice pool to modify.

    • Valid Types:

      • Dice

  • N: The number to test against.

    • Valid Types:

      • !In and !Out

        • Vector: !In and !Out both take a two-element vector of real numbers.

      • Remaining functions

        • Numbers: If the function is !, N may be any number. Otherwise, N must be a real number.
        • Dice: Will be evaluated, then, if the result is a valid number, it will be used as in the above case.

Success / Comparator Functions ( == and friends)

The ==, /=, <, <=, >, >=, In, and Out operators serve two functions:

  • If their left-hand argument is a die, it will be changed into a success-based pool: all dice that meet the function’s specific qualification will be counted as a success, and otherwise as a failure.
  • If their left-hand argument is not a die, the operator’s arguments will be compared based on the function, and turned into a boolean.

The operator’s qualifications are:

  • == tests the operands for equality.
  • /= tests the operands for inequality.
  • < takes a real number on the right. If the first operand is less than the second, it returns True; otherwise, it returns False.
  • <= takes a real number on the right. If the first operand is less than or equal to the second, it returns True; otherwise, it returns False.
  • > takes a real number on the right. If the first operand is greater than the second, it returns True; otherwise, it returns False.
  • >= takes a real number on the right. If the first operand is greater than or equal to the second, it returns True; otherwise, it returns False.
  • In takes a vector containing two real numbers on the right. If the first operand is within the inclusive range of the vector’s elements, it returns True; otherwise, it returns False.
  • Out takes a vector containing two real numbers on the right. If the first operand is not within the inclusive range of the vector’s elements, it returns True; otherwise, it returns False.

If a single dice pool is modified multiple times, rolls that meet any of the provided stipulations will explode.

Syntax:

X{ == | /= | < | <= | > | >= | In | Out }Y

Operator Type: Infix

Precedence: 1

  • X

    • Valid Types:

      • Dice: If a die is the left operand, its results will be deemed a success if they would return true under the relevant function.
      • Non-Dice: None-dice will simply be compared to the right operand, as per the above rules. == and /= can take any literal, while the other functions can only take real numbers.

  • Y: The number to test against.

    • Valid Types:

      • Dice: If a die is the right operand, it will be evaluated, and its result passed as the function’s right argument.
      • Non-Dice: None-dice will be used to judge the results of the die passed as the left operand, or simply compared to the left operand, as per the above rules. == and /= can take any literal, while the other functions can only take real numbers.

Logical Functions

The following commands are all logical operators, acting on their operands based on their Truthy-ness.

Forced Boolean ( bool)

The bool function transforms its argument to its logical equivalent: Truthy values will be converted to True, and Falsey values will be converted to False.

Syntax:

bool(X)

Operator Type: Functional

  • X: The value to transform to a boolean.

    • All types can be passed to bool. Dice will be evaluated prior to the operator being called.

Logical Negation ( ~, not)

The ~ and not functions transform their arguments to their logical opposites: Truthy values will be converted to False, and Falsey values will be converted to True.

Syntax:

~X

OR

not(X)

Operator Type: Prefix ( ~) or Functional ( not)

Precedence (for Prefix): 6

  • X: The value to logically negate.

    • All types can be passed to ~ and not. Dice will be evaluated prior to the operator being called.

Logical Conjunction ( &&, and)

The && and and functions take the logical conjunction of their arguments. In other words, if both of their operands are Truthy, they return True; otherwise, they return False

Syntax:

X&&Y

OR

X and Y

Operator Type: Infix

Precedence: 3

  • X and Y:

    • All types can be passed to && and and. Dice will be evaluated prior to the operator being called.

Logical Disjunction ( ||, or)

The || and or functions take the logical disjunction of their arguments. In other words, if both of their operands are Falsey, they return False; otherwise, they return True

Syntax:

X||Y

OR

X or Y

Operator Type: Infix

Precedence: 2

  • X and Y:

    • All types can be passed to || and or. Dice will be evaluated prior to the operator being called.

If Function ( if)

The if function is the primary use for booleans. It takes three arguments: A boolean (or argument to be interpreted as a boolean), followed by two statements. If the first argument is Truthy, if returns the second argument; otherwise, it returns the third argument.

Syntax:

if(X,Y,Z)

Operator Type: Functional

  • X:

    • All types can be passed to X, to be read as Truthy or Falsey. Dice will be evaluated prior to the operator being called.

  • Y and Z:

    • All types can be passed to Y and Z.

Numeric Functions

The following commands all perform standard operations on numeric values.

Exponentiation ( ^, **)

The ^ / ** function performs exponentiation, as follows:

  • If both arguments are numbers, the left will be raised to the power of the right. If the left is a float, or the right a non-integer, floating point arithmetic will be used; otherwise, values will be exactly calculated.
  • If the left argument is a number, and the right a numeric vector, the result will be a numeric vector, containing the results of raising the left argument to each element of the right accordingly.
  • If the left argument is a numeric vector, and the right a number, the result will be a numeric vector, containing the results of raising each element of the left argument to the power of the right.
  • If both arguments are numeric vectors of the same length, corresponding elements will be exponentiated.

Syntax:

X^Y

OR

X**Y

Operator Type: Infix

Precedence: 4

  • X and Y.

    • Numbers
    • Numeric Vectors: If both arguments are vectors, they must be of the same length.

Multiplication ( *)

The * function performs multiplication, as follows:

  • If both arguments are numbers, they will be multiplied. If either is a float, floating point arithmetic will be used; otherwise, values will be exactly calculated.
  • If one argument is a number and the other is a numeric vector, each element in the vector will be multiplied by the single element.
  • If both arguments are numeric vectors of the same length, corresponding elements will be multiplied.

Syntax:

X*Y

Operator Type: Infix

Precedence: 3

  • X and Y.

    • Numbers
    • Numeric Vectors: If both arguments are vectors, they must be of the same length.

Divison ( /)

The / function performs divison on numbers.

Syntax:

X/Y

Operator Type: Infix

Precedence: 3

  • X and Y.

    • Numbers: Y must be non-zero.

Modulus ( %)

The % function returns the remainder of its left argument when divided by its right argument.

Syntax:

X%Y

Operator Type: Infix

Precedence: 3

  • X and Y.

    • Integers: Y must be non-zero.

Addition ( +)

The + function performs addition. It can add pairs of numbers or pairs of vectors; vectors will be added componentwse.

Syntax:

X+Y

Operator Type: Infix

Precedence: 2

  • X and Y.

    • Both can be numbers
    • Both can be numeric vectors

Subtraction ( -)

The - function performs subtraction and negation:

  • It can subtract pairs of numbers or pairs of vectors; vectors will be subtract componentwse.
  • If there’s nothing to be subtracted from, - will negate its number or vector operand.

Syntax:

X-Y

OR

::
-X

Operator Type: Infix or Prefix

Precedence: 2 (Infix) or 6 (Prefix)

  • X and (Possibly) Y.

    • Both can be numbers
    • Both can be numeric vectors

Sum ( sum)

The sum function takes an indefinite number of numbers, and adds them.

Syntax:

sum(A,B,...,Z)

Operator Type: Functional

  • A, B, …, Z

    • Numbers

Product ( prod)

The prod function takes an indefinite number of numbers, and multiplies them.

Syntax:

prod(A,B,...,Z)

Operator Type: Functional

  • A, B, …, Z

    • Numbers

Ceiling ( ceil)

The ceil function gets the ceiling of a real number. The ceiling of a real number is the smallest integer greater than or equal to said real number; in other words, ceil rounds a number up.

Syntax:

ceil(X)

Operator Type: Functional

  • X

    • Real Numbers

Floor ( floor)

The floor function gets the floor of a real number. The floor of a real number is the largest integer less than or equal to said real number; in other words, floor rounds a number down.

Syntax:

floor(X)

Operator Type: Functional

  • X

    • Real Numbers

Round ( round)

The round function rounds a real number in the traditional way; if a number’s fractional part is less than 0.5, round down; otherwise, round up.

Syntax:

round(X)

Operator Type: Functional

  • X

    • Real Numbers

Maximum ( max)

The max function takes an indefinite number of real numbers, and returns the largest one.

Syntax:

max(A,B,...,Z)

Operator Type: Functional

  • A, B, …, Z

    • Real Numbers

Minimum ( min)

The min function takes an indefinite number of real numbers, and returns the smallest one.

Syntax:

min(A,B,...,Z)

Operator Type: Functional

  • A, B, …, Z

    • Real Numbers