.. RPDiscordRewrite documentation master file, created by sphinx-quickstart on Mon May 28 13:33:53 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. .. _command_syntax: Command Syntax ============================================ -------------------------------------------- The command-based dice roller is designed to be easy to use, but powerful. The basic syntax of the parser is outlined below; the functions that compose most of the usefulness of the parser are listed under the :ref:`command_functions` section. .. _terminology: Terminology ============================================ Potentially unfamiliar terms that are used throughout the command documentation are defined here. .. _overloaded: Overloaded -------------------------------------------- An *overloaded* operator is an operator that does different things on different operands. For example, the `d` function: *When given a number `X` on the left and a number `Y` on the right, the `d` function will create a new dice pool with `X` `Y`-sided dice. *When the `d` function is given a die `D` on the left and a number `Z` on the right, it will instead modify `D` to drop the `Z` lowest results from the dice pool. .. _truthy_falsey: Truthy and Falsey Values -------------------------------------------- Certain functions which usually would expect boolean values, such as ``if``, will instead coerce unexpected values to ``True`` or ``False``: * There are two values will be converted to False: ``0`` and the empty vector ``()``. These, along with ``False`` itself, are called "Falsey" values. * Unrolled dice will be evaluated prior to being coerced into being ``True`` or ``False``. * All other values will be converted to ``True``, and are thus called "Truthy"". .. _exploding_dice: Exploding Dice -------------------------------------------- Dice pools can *explode* on certain values. If a dice pool *explodes* on a value ``N``, for each die whose result is ``N``, one rolls an additional die, which could, in turn explode, and so on. For example, say we roll ``10d6!``, a pool of ten six-sided dice that explode on a result of 6, and get: :: 5, 4, 1, 4, 6, 2, 4, 3, 6, 6 We rolled three sixes in this pool. Since these dice explode on the six, we roll an additional ``3d6!`` :: 6, 2, 5 We managed another six, so we get to roll another ``1d6!`` :: 5 No more sixes there, so we're done rolling; now we add up the results and get our end total: :: (5+4+1+4+6+2+4+3+6+6)+(6+2+5)+(5) = 59 .. _constants: Constants ============================================ The following sections cover various constant values: literals, rational numbers, and complex numbers. .. _literals: Literals -------------------------------------------- A `literal` is a constant term in a dice expression. The dice parser supports three fundamental types of literal: integers, floats, and booleans. * Integers are your typical 'whole numbers', along with their negatives; `1, 21, 0,` and `-5` are all integers. * Floats are your typical floating point numbers, more commonly known as decimals. `0.0, 6.0, 3.5`, and `-19.32132132` are all floats. * There are only two boolean values: `True` and `False`. They can be used in statements like `if` or `not`, or generated by comparison operators like `<=` or `!=` .. _rational_numbers: Rational Numbers -------------------------------------------- The dice parser also supports rational numbers. If two integer values are divided with `/`, the result will be internally turned into a rational number, rather than a float. All basic arithmetic involving only rationals or integers will be carried out exactly, rather than using a floating-point approximation. While exact, this is a bit slower than floating-point arithmetic, so if a calculation involving division seems to be rather slow, consider turning one of the integers involved into a float, which should speed up the processing. .. _complex_numbers: Complex Numbers -------------------------------------------- The dice parser can even work with imaginary and complex numbers. In keeping with python convention, the imaginary unit, written as `i` in most mathematics, is instead represented with a `j`. The real and imaginary parts of complex numbers can be composed of reals, floats, or rationals, and, where possible, calculations are done exactly. .. _grouping: Grouping ============================================ The following sections cover the two grouping mechanisms: parentheses and brackets. .. _parentheses:: Parentheses -------------------------------------------- As-is typical, the dice parser uses parentheses `()` for grouping expressions. If a parenthetical expression contains no non-nested commas, the parentheses simply say to perform a given operation first, ignoring any normal order of operations. However, if a parenthetical expression contains commas, the result will instead be a :ref:`vector`, whose elements are the parts of the expression that are separated by commas. .. _brackets:: Brackets -------------------------------------------- It may seem as though brackets should behave identically to parentheses. However, besides the standard grouping functionality of parentheses, brackets serve an additional, important role; any statement within brackets will be forced to evaluate fully to a number before being used in calculations outside of the brackets. This allows certain overloaded functions, such as `d` or `>=`, to safely be used on the results of dice, rather than the dice themselves. .. _vectors: Vectors ============================================ The term 'vector' is used rather loosely when it comes to the dice parser. Fundamentally, they are simply lists of values, which could potentially include other vectors. However, they also have some additional arithmetic operations available; one can, for example, add two vectors of numbers together in the natural way, or multiply a vector of numbers by a scalar.