1
.TH dicelab 1 "February 2007" "dicelab v0.2" "Dicelab - examine and roll dice"
3
dicelab \- roll and examine dice rolling schemes
11
.BR \-h ", "\-\-help ", "\-?
14
.BR \-\-version ", "\-v
15
display version number
17
.BR \-\-print\-tree ", "\-p
18
print the parse tree (for debugging purposes)
21
roll the dice as specified. This will also be used if no other action is
25
reroll many times and sum up the results to get a statistical distribution of
29
specify the number of rerolls for --eval, default it 10000
32
read the scheme description from file instead from stdin
35
Dicelab reads a description of a dice rolling scheme from a file or from stdin
36
if no file is specified and then rolls or examines this scheme.
39
Single die rolls may be made using the 'd' operator, followed by the number of
40
faces on the die to be rolled. E.g., d6 will roll a single six-sided die, and
41
d2 will flip a coin. Expressions may be modified by the standard arithmetic
42
operators. d10-1 will yield a value between 0 and 9, inclusive. In order to
43
roll multiple dice of the same type, use the repetition operator '#'. 2#d6
44
will roll two six-sided dice; this is not the same as 2*d6, which rolls only
45
a single die but multipies the result by two, or 2d6 which will cause a syntax
46
error. In order to get the sum of two six-sided dice, do sum(2#d6).
73
| <scalar> .. <scalar>
78
| (drop|keep)? low <scalar> <expr>
79
| (drop|keep)? high <scalar> <expr>
80
| (drop|keep)? first <scalar> <expr>
81
| (drop|keep)? last <scalar> <expr>
82
| (drop|keep)? == <scalar> <expr>
83
| (drop|keep)? != <scalar> <expr>
84
| (drop|keep)? < <scalar> <expr>
85
| (drop|keep)? > <scalar> <expr>
86
| (drop|keep)? <= <scalar> <expr>
87
| (drop|keep)? >= <scalar> <expr>
88
| if <expr> then <expr> else <expr>
89
| let <variable> = <expr> in <expr>
90
| while <variable> = <expr> do <expr>
91
| foreach <variable> in <expr> do <expr>
100
Comments may be inserted by using double slashed (//) as in C.
103
.BR + " "- " "* " "/ " "^
105
These are the familiar binary arithmetic operators for addition,
106
subtraction, multiplication, division, and exponentiation. Division
107
rounds toward zero. Examples: 5+7, d6-1, 2^10
111
This is the unary minus operator. Examples: -1
115
This is the modulus operator. x % y gives the remainder of x divided by y.
120
This is the scalar concatenation operator. x . y gives xy, the
121
concatenation of x and y. Examples: -10.9, d6.d6
125
This is the die roll operator. dn gives the value of a single roll of an
126
n-sided die. Examples: d6, 2#d6
130
These are the extended sum and product operators. If e is an expression,
131
sum e and prod e give the sum of the members of e and the product of the
132
members of e, respectively. Examples: sum(1..100), prod(3#d6)
136
This is the list size operator. If e is an expression, then count e gives
137
the number of members of e. Examples: count(1,2,3), count(== 6 10#d6)
141
This is the list repetition operator. If n is a nonnegative scalar and e is
142
an expression, then n#e is a list containing the results of n evaluations
143
of e. Examples: 10#8, 3#d10
147
This is the range operator. If x and y are scalars, then x..y is a list
148
consisting of the interval [x,y]. If x>y, then the resulting list is empty.
149
Examples: 1..10, 4..d10
153
This is the list concatenation operator. v,u gives the list consisting of
154
all of the members of v, followed by all of the members of u. Examples:
159
This is the list sorting operator. sort e sorts the list e in ascending
160
order. Examples: sort(10#d6)
164
This is the list permutation operator. sort e results in a random
165
permutation of the list e. Use perm to shuffle a list.
166
Examples: perm(1..52)
170
This is the list reversal operator. rev e results in a list with the same
171
members as the list e, but in reverse order. Examples: rev(1..10), rev
176
These operators act as filters by finding the least and greatest values in
177
lists. If n is a nonnegative scalar and e is an expression, then low n e
178
gives the n least members of e, and high n e gives the n greatest members
179
of e. Examples: high 3 5#d6
183
These operators act as filters by finding initial and final segments of
184
lists. If n is a nonnegtive scalar and e is an expression, then first n e
185
gives the first n members of e, and last n e gives the last n members of e.
186
Examples: first 3 (1..10)
188
.BR == " "!= " "< " "> " "<= " ">=
190
These operators act as filters by finding values in lists which meet given
191
conditions. If x is a scalar and e is an expression, then == x e gives the
192
list of members of e equal to x; != x e gives the list of members of e not
193
equal to x; < x e gives the list of members of e less than x; > x e gives
194
the list of members of e greater than x; <= x e gives the list of members
195
of e less than or equal to x; >= x e gives the list of members of e greater
196
than or equal to x. Examples: >= 3 5#d6
200
These operators modify filters on lists. If fop is a filter operation on an
201
expression e, then keep fop e has the same result as fop e and drop fop e
202
evaluates to e less keep fop e. In other words, drop negates filter
203
conditions, and keep affirms them. keep is never necessary and exists only
204
for symmetry. Examples: sum(drop low 1 4#d6)
208
This is the variable assignment and substitution operator. If x is a
209
variable and e and f are an expressions, then let x = e in f gives the list
210
which results from evaluating f with the value of e substituted for every
211
occurance of x in f. Evaluation of e is done prior to substitution.
212
Examples: let x = d6 in x*x
216
This is the bounded iteration operator. If x is a variable and e and f are
217
expressions, then foreach x in e do f gives the list which results from
218
assigning to x each of the members of e and evaluating f. Examples: foreach
223
This is the unbounded iteration operator. If x is a variable and e and f
224
are expressions, then while x = e do f is the list v0,v1,...,vn, where v0
225
is the result of evaluating e and vi+1 is the result of assigning vi to x
226
and evaluating f, stopping at the first vi which is empty.
227
Examples: while x=d6 do ((count <6 x)#d6)
231
This is the branching operator. If e, f, and g are expressions, then if e
232
then f else g gives f if e is nonempty, and g otherwise. Examples: if
233
count(>4 2#d6) then 1 else 0
236
Count the number of dice greater than 7:
243
Count the number of dice greater than 7 minus the number of dice equal to 1:
246
let c=5#d10 in (count >7 c)-(count ==1 c)
250
Count the number of rolls until a 6 is rolled:
253
count (while x=d6 do ((count <6 x)#d6))
257
Count the number of rolls until a 6 is rolled, more efficiently:
260
count (while x=(d6/6) do ((count <1 x)#(d6/6)))
264
Roll attributes for a new D&D character:
267
6#sum(drop low 1 4#d6)
271
Roll on the 11..66 morale check table in The Gamers' Civil War Brigade
279
Find the median of 3 d20s:
286
3d6 with rerolls on 6s:
289
sum(while x=3#d6 do ((count ==6 x)#d6))
293
Roll 7 d10 and find the largest sum of identical dice:
296
let x = 7#d10 in high 1 (foreach y in 1..10 do sum (==y x))
300
The Fibonacci sequence is defined by Fn = Fn-1 + Fn-2, with F1 = F2 = 1.
301
Calculate the first twenty Fibonacci numbers:
307
let f = (f,sum(high 2 f)) in
308
if ==n i then f else ()
312
Risk has battles where the attacker rolls 3d6 and the defender rolls 2d6.
313
The highest attacker die is matched with the highest defender die and the
314
second highest attacker die to the second highest defender die. For both
315
matches, the highest wins, with ties going to the defender. The number of
321
count( (<(high 1 a) high 1 b),
322
(<(high 1 low 2 a) low 1 b))
326
Storyteller die roll with target number 8 and botches indicated at -1:
330
let succs = count >7 c in
331
let ones = count ==1 c in
332
if >0 succs then high 1 (0,succs-ones)
333
else if >0 ones then -1 else 0
337
Combat in Silent Death is rather complex. Three dice are rolled. If their
338
sum is above a target, the roll is a hit. To calculate damage, the same dice
339
are sorted. If all three are equal, all are summed to yield the damage. If
340
the least two are equal, but the third is higher, the high die is the damage.
341
If the two highest are equal, but the third is lower, the two high dice are
342
summed to yield the damage. If all three dice are different, the middle die
343
is the damage. This example assumes that the dice are two d8s and a d10, with
344
a target number of 15:
349
let a = low 1 x in // low die
350
let b = high 1 low 2 x in // middle die
351
let c = high 1 x in // high die
352
if ==a ==b c then a+b+c // all equal
353
else if ==a <c b then c // two low equal
354
else if >a ==c b then b+c // two high equal
355
else b // all different
359
Dicelab is based on the excellent work "roll" by Torben Mogensen (http://www.diku.dk/~torbenm/Dice.zip). Without his work and comments, this would hardly ever have happened.
361
The current language specification and the extensions to the original language
362
are derived from the work of Joel Uckelman (http://dice.nomic.net/bones.html),
363
most of the documentation is stolen from him as well.
365
This code was written by Robert Lemmen <robertle@semistable.com> who would be glad to hear your questions and remarks.
added
removed
dicelab.1
