roll
====

roll is a program to roll dices specified in a simple and intuitive way.

see INSTALL on how to compile and install roll and the man page for
instructions

Synopsis
--------

    roll [-hpsv] [--version] expression

Description
-----------

Rolls a user-defined dice sequence. The dices to roll are defined using
dN where N is the number of sides. Dices can be rolled multiple times by
prepending the number of repetitions (e.g., 3d6) and used in simple
mathematical expressions (e.g., 2d8+4).

Options
-------

    --help, -h
           help

    --positive, -p
           allow only positive results

    --sum-series, -s
           show the sum of roll series

    --verbose, -v
           verbose (displays the result for each roll)

    --version
           prints the version of the program

Expressions
-----------

Expressions are in dice notation (also known as dice algebra, common
dice notation or RPG dice notation).

Die rolls are expressed in the form NdX or NDX where N is the number of
dices (1 if omitted) and X the number of dice faces.

roll also accepts W (German) or T (Swedish) to specify a dice (D in
English)

If the final number is omitted, it is assumed to be a six.

To this basic notation, an additive modifier can be appended, yielding
expressions of the form, NdX+C. The plus can be replaced by a minus sign
("-") for subtraction. C is a number to be added subtracted from the
final total.

See: http://en.wikipedia.org/wiki/Dice_notation

Percentile dice (d%)

Often, the variable X in the above notation will be "%". Although a
100-sided die does exist, it is both more common and more uniformly
random to use a combination of two ten-sided dice known as percentile
dice, where one die represents tens and the other units. A roll of two
zeroes means 100.

If you want to roll a single 100-sided die use the "d100" notation.

d10x

d10x is equivalent to d10 x d10 and gives a non-linear distribution.

Fudge dice (dF or df)

The Fudge role-playing game system uses customized "Fudge dice" which
have an equal number of plus, minus and blank sides.

Multipliers

In some games, the above notation is expanded to allow for a multiplier,
as in NdXxC or CxNdX, where "x" or "*" denotes multiplication (can be
replaced by "/" for division) and C is a natural number.

Results are rounded up.

Reroll filters

It is possible to specify restrictions on dice rolls telling which
values to keep and which values to discard by putting a filter after the
dice. If a value is to be discarded the dice is re-rolled until the
result is valid value. You can specify to keep only values bigger (>),
bigger or equal (>=), smaller (<), smaller or equal (<=) or different
(!=) from a given number. The comparator is specified right after the
the die specification (e.g., 1D6>2).

Selective results

It is possible to keep only the M highest or lowest dices with the
following notation:

-   NdXhM: roll N dices with X sides and keep the highest M results (M
    must be less or equal N)
-   NdXkM: K for keep is equivalent to H for highest
-   NdXlM: roll N dices with X sides and keep the lowest M results (M
    must be less or equal N)

Or using the abbreviated notation NdX-L to drop the lowest and NdX-H to
drop the highest result.

Series and repetitions

It is possible to concatenate top-level expressions with a comma
("expression, expression") and to repeat the execution of an expression
or a set of expressions by using a counter and curly brackets
("N{ expression}")

Examples

    3d6        rolls 3 6-sided dices and sums the results
               (can be abbreviated with "3d")
    1d8 + 3    rolls 1 8-sided die and adds 3
                      (can be abbreviated by "d8+3")
    d%         rolls 2 10-sided dices: one represents the tens and
               the other units
    1d6x5      rolls 1 6-sided dice and multiplies the result by 5
    1d6 / 2    rolls 1 6-sided dice and divides the result by 2 (1d3)
    4d6h3      rolls 4 6-sided dices and keeps the 3 highest results
               (discarding the lowest)
    4d6-L      rolls 4 6-sided dices and discards the lowest
    "6{3d6}"   rolls 3d6 6 times (expression
               is quoted to avoid the > being interpreted as
               redirection by the shell)
    "1d6>2"    rolls 1d6 until the result is bigger than 2 (expression
               is quoted to avoid the > being interpreted as
               redirection by the shell)
    4DF        rolls 4 Fudge dices
    10dx       rolls 2 ten-sided dices and multiply the results

Grammar (EBNF)

    expression   := term { "+" term | "-" term } .
    term         := number | factor [ ("*"|"/") number |
                    number ("*"|"/") factor | "(" expression ")" .
    factor       := number FilteredDice [ ("h"|"H"|"l"|"L"|"k"|"K") number ] | number FilteredDice "-" [ ("h"|"H"|"l"|"L") | FilteredDice .
    FilteredDice := dice | dice (">"|">="|"<"|"<="|"!=") number .
    dice         := "d" | "D" | "w" | "W" | "t" | "T" [ number | "%" | "F" | "f" | "x" | "X" ]
