dice

一个用于解析和评估骰子表示的Python库和命令行工具。

我认为这个库“完成”了，并且不打算再添加任何功能。可能会发布错误和安全修复，特别是如果您在所有这些时间后仍然发现任何错误。如果您对这个空间的其他库感兴趣，dyce有一个非常好的比较表，列出了Python骰子滚动库。

快速入门

命令行

$ roll 3d6

以下为命令行参数

• -m --min 使所有掷骰子的结果都是可能的最小值
• -M --max 使所有掷骰子的结果都是可能的最大值
• -h --help 显示此帮助文本
• -v --verbose 显示更多输出
• -V --version 显示软件包版本

如果您的表达式以连字符（-）开头，则在其前面放置一个双连字符（--），以防止解析器尝试将其作为命令选项进行处理。例如：roll -- -10d6。或者，可以使用括号：roll (-10d6)。

Python API

从Python中调用

import dice
dice.roll('3d6')

这返回一个Element，它是掷骰子的结果，可以是list、int或其子类，具体取决于顶层运算符。

用法

安装

此库作为PyPI上的dice提供。使用您选择的Python包或依赖项管理器进行安装——如果您将其作为命令行工具安装，我建议使用pipx。

需要Python 3的最新版本（3.8或更高版本）。您可能可以运行它或轻松地将其适配到旧版本的Python，但我不支持任何已停止服务的Python版本。除此之外，唯一依赖项是pyparsing库。

符号

表达式类似于一个简单的方程式解析器，但有一些额外的运算符。

以下运算符按优先级顺序列出。可以使用括号强制改变求值顺序。

骰子运算符（[N]dS）接受数量（N）和面数（S），并返回一个包含N个介于1和S之间的随机数的列表。例如：4d6可能返回[6, 3, 2, 4]。使用%作为第二个操作数是掷d100的简写，使用f是±1模糊骰子的简写。

模糊骰子运算符（[N]uS）与骰子运算符可互换，但使得骰子范围从-S到S，而不是从1到S。这包括0。

特殊的野生骰子（[N]wS）掷骰子。这个集中的最后一个掷骰子称为“野生骰子”。如果这个骰子的掷骰结果是最大值，则将集中第二高的掷骰结果设置为最大值。如果它的掷骰结果是最小值，则将这个骰子和集中最高的掷骰结果都设置为0。然后再次掷骰子。如果这个掷骰结果再次是最小值，那么所有的骰子都设置为0。如果掷出一个单面野生骰子，则其行为类似于正常掷骰。

如果没有指定N，则假定您想要掷一个单骰子。d6等价于1d6。

可以使用x运算符将掷骰子爆炸，这将为超过给定阈值的每个掷骰结果添加额外的骰子。如果没有给出阈值，则默认为最大可能的掷骰结果。如果额外骰子超过此阈值，它们将“爆炸”！已采取措施防止解析器崩溃于无限爆炸。

您可以使用r和rr运算符让解析器重新掷低于某个阈值的骰子。单个r类型允许新的掷骰结果低于阈值，而双类型将掷骰结果的取值范围改变为具有最小值阈值的范围。阈值默认为最小掷骰结果。

可以使用（^或h）、（m或o）或（v或l）分别选择最高、中间或最低的掷骰结果或列表项。例如，6d6^3将保留最高的3个掷骰结果，而6d6v3将选择最低的3个掷骰结果。如果没有指定数字，则默认为保留最高和最低的除了一个，以及中间的除了两个。如果将这些运算符的任何操作数指定为负值，则此操作将从结果中删除相应数量的元素。例如，6d6^-2将删除集合中的两个最低值，留下4个最高值。0没有效果。

“爆炸”操作符的一个变体是 a（“再次”）操作符。该操作符不会重新投掷等于或大于阈值的值（或最大值），而是将等于提供的阈值（或最大值）的值加倍。当未指定右侧操作数时，左侧必须是一个骰子表达式。

有两种操作符可以用来计算一组骰子投掷或数字中等于或高于某个阈值的元素数量，即“成功”。这两个操作符都需要一个右侧操作数作为阈值。第一个操作符 e 只计算成功。第二个操作符 f 计算成功减去失败的数量，失败是指投掷的值为骰子元素的最小可能值，或列表的 1。

可以使用总（t）操作符将一个骰子投掷列表或集合转换为整数。6d1t 将返回 6，而不是 [1, 1, 1, 1, 1, 1]。将整数运算应用于投掷列表将自动将它们相加。

可以使用排序（s）操作符对一组骰子投掷进行排序。4d6s 不会更改返回值，但骰子将被从低到高排序。

+- 操作符是针对一组骰子投掷和列表的特殊前缀。它将列表中的奇数投掷取反。例如：[1, 2, 3] -> [-1, 2, -3]。还有一个取反（-）操作符，它作用于单个元素、集合或投掷，或列表。还有一个恒等（+）操作符。

可以使用逐点加（.+）和减（.-）操作符将值加到或从列表或投掷集合的每个元素中。例如：4d1 .+ 3 将返回 [4, 4, 4, 4]。

也提供了基本的整数运算：(16 / 8 * 4 - 2 + 1) % 4 -> 3。

最后，有两种操作符用于构建和扩展列表。要构建一个列表，使用逗号分隔元素。如果任何以逗号分隔的项目不是标量（例如，一个投掷），则通过取其总和将其展平。扩展操作符（|）用于将两个列表合并为一个，或将单个元素追加到列表的开始或结束位置。

Python API

上面的 dice.roll() 调用可以用 dice.roll_min() 或 dice.roll_max() 替换，以强制所有投掷都达到其最高或最低值。这可能有助于了解给定表达式的最小和最大可能值。请注意，这将使野骰子投掷表现得像普通投掷一样，并且作为爆炸进行的投掷不会被强制设置为高或低。

“roll”函数及其变体接受一个布尔参数 raw，这使得库返回元素而不是结果。请注意，evaluate_cached 方法在 roll 中作为部分调用，它填充了 element.result。调用 element.evaluate() 不会重置此值。

要显示元素树的详细分解，可以使用 dice.utilities.verbose_print(element) 函数。如果 element.result 尚未填充，则该函数首先调用 evaluate_cached()。如果您想使用自定义参数打印评估结果，请记住这一点。verbose_print() 返回一个 str。

大多数评估错误都会引发 DiceError 或 DiceFatalError，这两个都是 DiceBaseError 的子类。这些异常有一个名为 pretty_print 的方法，它将输出一个字符串，指示错误发生的位置：

>>> try:
...   dice.roll('1/0')
... except dice.DiceBaseException as e:
...   print(e.pretty_print())
...
1/0
  ^ Division by zero
>>>