Operators

Operators are functions that implement the various operators found in YADN. yadr is designed to avoid the need for someone using it to ever need to call these functions directly. They are intended to be invoked through the parsing of YADN. Their documentation here is just intended for maintenance purposes.

Qualifiers

yadr.operator.choice(boolean: bool, options: tuple[str, str]) → str

Make a choice.

YADN reference: x ? y

Parameters:

• boolean – The decision as a bool.

• options – The two options to pick from.

Returns:

The chosen option as a str.

Return type:

str

Usage:

>>> choice(False, ('spam', 'eggs'))
'eggs'

yadr.operator.choice_options(a: str, b: str) → tuple[str, str]

Create the options for a choice.

YADN reference: x : y (choice option)

Parameters:

• a – The qualifier for the true condition of a choice.

• b – The qualifier for the false condition of a choice.

Returns:

The qualifiers as a tuple.

Return type:

tuple

Usage:

>>> choice_options('success', 'failure')
('success', 'failure')

Dice Operators

yadr.operator.concat(num: int, size: int) → int

Concatenate the least significant digits.

YADN reference: x dc y (concat):

Parameters:

• num – The number of dice to roll.

• size – The highest number that can be rolled on a die.

Returns:

The concatenated least significant digits as an int.

Return type:

int

Usage:

>>> # This line is to ensure predictability for testing.
>>> # Do not use outside of test cases.
>>> _seed('spam')
>>>
>>> # Roll 2d10 as percentile dice. It's not quite right,
>>> # since 00 should be 100, but the physical dice have
>>> # that problem, too.
>>> concat(2, 10)
21

yadr.operator.die(num: int, size: int) → int

Roll a number of same-sized dice and return the result.

YADN reference: x d y (dice sum):

Parameters:

• num – The number of dice to roll.

• size – The highest number that can be rolled on a die.

Returns:

The sum of the result of each die as an int.

Return type:

int

Usage:

>>> # This line is to ensure predictability for testing.
>>> # Do not use outside of test cases.
>>> _seed('spam')
>>>
>>> # Roll 3d6.
>>> die(3, 6)
5

yadr.operator.exploding_die(num: int, size: int) → int

Roll a number of exploding same-sized dice.

YADN reference: x d! y (exploding dice):

Parameters:

• num – The number of dice to roll.

• size – The highest number that can be rolled on a die.

Returns:

The sum of the result of each die as an int.

Return type:

int

Usage:

>>> # This line is to ensure predictability for testing.
>>> # Do not use outside of test cases.
>>> _seed('spam')
>>>
>>> # Roll 5d!6.
>>> exploding_die(5, 6)
15

yadr.operator.keep_high_die(num: int, size: int) → int

Roll a number of dice and keep the highest.

YADN reference: x dh y (keep high die):

Parameters:

• num – The number of dice to roll.

• size – The highest number that can be rolled on a die.

Returns:

The highest value as an int.

Return type:

int

Usage:

>>> # This line is to ensure predictability for testing.
>>> # Do not use outside of test cases.
>>> _seed('spam')
>>>
>>> # Roll 5dh6.
>>> keep_high_die(5, 6)
5

yadr.operator.keep_low_die(num: int, size: int) → int

Roll a number of dice and keep the lowest.

YADN reference: x dl y (keep low die):

Parameters:

• num – The number of dice to roll.

• size – The highest number that can be rolled on a die.

Returns:

The lowest value as an int.

Return type:

int

Usage:

>>> # This line is to ensure predictability for testing.
>>> # Do not use outside of test cases.
>>> _seed('spam')
>>>
>>> # Roll 5dh6.
>>> keep_low_die(5, 6)
1

yadr.operator.wild_die(num: int, size: int) → int

Roll a number of same-sized dice and return the result, with one of the dice being the wild die.

YADN reference: x dw y (wild die):

Parameters:

• num – The number of dice to roll.

• size – The highest number that can be rolled on a die.

Returns:

The sum of the values as an int.

Return type:

int

Usage:

>>> # This line is to ensure predictability for testing.
>>> # Do not use outside of test cases.
>>> _seed('spam')
>>>
>>> # Roll 5dw6.
>>> wild_die(5, 6)
0

Pool Generation Operators

yadr.operator.dice_pool(num: int, size: int) → Sequence[int]

Roll a dice pool.

YADN reference: x dp y (dice pool):

Parameters:

• num – The number of dice to roll.

• size – The highest number that can be rolled on a die.

Returns:

The the values as a tuple.

Return type:

tuple

Usage:

>>> # This line is to ensure predictability for testing.
>>> # Do not use outside of test cases.
>>> _seed('spam')
>>>
>>> # Roll 5g6.
>>> dice_pool(5, 6)
(1, 1, 3, 5, 5)

yadr.operator.exploding_pool(num: int, size: int) → Sequence[int]

Roll an exploding dice pool.

YADN reference: x g! y (exploding pool):

Parameters:

• num – The number of dice to roll.

• size – The highest number that can be rolled on a die.

Returns:

The the values as a tuple.

Return type:

tuple

Usage:

>>> # This line is to ensure predictability for testing.
>>> # Do not use outside of test cases.
>>> _seed('spam')
>>>
>>> # Roll 5g!6.
>>> exploding_pool(5, 6)
(1, 1, 3, 5, 5)

Pool Operators

yadr.operator.pool_cap(pool: Sequence[int], cap: int) → Sequence[int]

Cap the maximum value in a pool.

YADN reference: P pc y (pool cap):

Parameters:

• pool – A sequence of die values.

• cap – The maximum value of a die roll.

Returns:

The resulting values as a tuple.

Return type:

tuple

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]pc6.
>>> pool_cap([4, 10, 3, 5, 1, 9], 6)
(4, 6, 3, 5, 1, 6)

yadr.operator.pool_floor(pool: Sequence[int], floor: int) → Sequence[int]

Floor the minimum value in a pool.

YADN reference: P pc y (pool floor):

Parameters:

• pool – A sequence of die values.

• floor – The minimum value of a die roll.

Returns:

The resulting values as a tuple.

Return type:

tuple

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]pf6.
>>> pool_floor([4, 10, 3, 5, 1, 9], 6)
(6, 10, 6, 6, 6, 9)

yadr.operator.pool_keep_above(pool: Sequence[int], floor: int) → Sequence[int]

Discard all values in a pool below a given value.

YADN reference: P pa y (pool keep above):

Parameters:

• pool – A sequence of die values.

• floor – The minimum value to keep.

Returns:

The resulting values as a tuple.

Return type:

tuple

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]pa6.
>>> pool_keep_above([4, 10, 3, 5, 1, 9], 6)
(10, 9)

yadr.operator.pool_keep_below(pool: Sequence[int], ceiling: int) → Sequence[int]

Discard all values in a pool above a given value.

YADN reference: P pb y (pool keep below):

Parameters:

• pool – A sequence of die values.

• ceiling – The maximum value to keep.

Returns:

The resulting values as a tuple.

Return type:

tuple

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]pb6.
>>> pool_keep_below([4, 10, 3, 5, 1, 9], 6)
(4, 3, 5, 1)

yadr.operator.pool_keep_high(pool: Sequence[int], keep: int) → Sequence[int]

Keep a number of the highest dice.

YADN reference: P ph y (pool keep high):

Parameters:

• pool – A sequence of die values.

• keep – The maximum value to keep.

Returns:

The resulting values as a tuple.

Return type:

tuple

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]ph3.
>>> pool_keep_high([4, 10, 3, 5, 1, 9], 3)
(10, 5, 9)

yadr.operator.pool_keep_low(pool: Sequence[int], keep: int) → Sequence[int]

Keep a number of the lowest dice.

YADN reference: P pl y (pool keep low):

Parameters:

• pool – A sequence of die values.

• keep – The maximum value to keep.

Returns:

The resulting values as a tuple.

Return type:

tuple

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]pl3.
>>> pool_keep_low([4, 10, 3, 5, 1, 9], 3)
(4, 3, 1)

yadr.operator.pool_modulo(pool: Sequence[int], divisor: int) → Sequence[int]

Perform a modulo operation of each member.

YADN reference: P p% y (pool modulo):

Parameters:

• pool – A sequence of die values.

• divisor – The maximum value to keep.

Returns:

The resulting values as a tuple.

Return type:

tuple

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]p%3.
>>> pool_modulo([4, 10, 3, 5, 1, 9], 3)
(1, 1, 0, 2, 1, 0)

yadr.operator.pool_remove(pool: Sequence[int], cut: int) → Sequence[int]

Remove members of a pool of the given value.

YADN reference: P pr y (pool remove):

Parameters:

• pool – A sequence of die values.

• cut – The maximum value to keep.

Returns:

The resulting values as a tuple.

Return type:

tuple

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]pr5.
>>> pool_remove([4, 10, 3, 5, 1, 9], 5)
(4, 10, 3, 1, 9)

Pool Degeneration Operators

yadr.operator.pool_concatenate(pool: Sequence[int]) → int

Concatenate the dice in the pool.

YADN reference: C P (pool concatenate):

Parameters:

pool – A sequence of die values.

Returns:

The resulting value as an int.

Return type:

int

Usage:

>>> # Roll C[4, 10, 3, 5, 1, 9].
>>> pool_concatenate([4, 10, 3, 5, 1, 9])
4103519

yadr.operator.pool_count(pool: Sequence[int]) → int

Count the dice in the pool.

YADN reference: N P (pool count):

Parameters:

pool – A sequence of die values.

Returns:

The resulting value as an int.

Return type:

int

Usage:

>>> # Roll N[4, 10, 3, 5, 1, 9].
>>> pool_count([4, 10, 3, 5, 1, 9])
6

yadr.operator.pool_sum(pool: Sequence[int]) → int

Sum the dice in the pool.

YADN reference: S P (pool sum):

Parameters:

pool – A sequence of die values.

Returns:

The resulting value as an int.

Return type:

int

Usage:

>>> # Roll S[4, 10, 3, 5, 1, 9].
>>> pool_sum([4, 10, 3, 5, 1, 9])
32

yadr.operator.count_successes(pool: Sequence[int], target: int) → int

Count the number of successes in the pool.

YADN reference: P ns y (count successes):

Parameters:

• pool – A sequence of die values.

• target – The target number for success.

Returns:

The resulting value as an int.

Return type:

int

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]ns6.
>>> count_successes([4, 10, 3, 5, 1, 9], 6)
2

yadr.operator.count_successes_with_botch(pool: Sequence[int], target: int) → int

Count the number of successes in the pool. Then remove a success for each botch.

YADN reference: P nb y (count successes and botches):

Parameters:

• pool – A sequence of die values.

• target – The target number for success.

Returns:

The resulting value as an int.

Return type:

int

Usage:

>>> # Roll [4, 10, 3, 5, 1, 9]nb6.
>>> count_successes_with_botch([4, 10, 3, 5, 1, 9], 6)
1

The Random Number Generator

The random number generator (RNG) used to generate the die rolls is set by the current value of yadr.operator.roll(). The value of yadr.operator.roll() is a function that uses an RNG to perform the die roll and return the result. There are currently two options available for use as this rolling function:

• yadr.operations._roll_random() (uses random.randint())

• yadr.operations._roll_secrets() (uses secrets.randbelow())

The default rolling function is yadr.operations._roll_random().

Warning

While you can change the value of yadr.operations.roll() to change the RNG, doing so may not be thread safe. This probably doesn’t matter in most situations but caution is still recommended.