Liking cljdoc? Tell your friends :D

Big Jule

"I had the spots taken off for luck. But I remember where the spots formerly were."
  • Big Jule - Guys and Dolls

Big Jule is an extensible and comprehensive Dice Roller for Clojure/Script. It allows for expressing dice rolls in a traditional, natural format, and can build reusable dice-rolling functions.

Dependencies are minimal, but meant to be Clojure 1.9 ready. The presence of spec is assumed.


Big Jule is available in Clojars. Add this :dependency to your Leiningen project.clj:

[bigjule "0.1.0"]

The library should has a minimal API and should be fairly easy to use. These examples should work in a repl.

Pull it in for use as such:

  (require '[bigjule.core :as bjd])

A bare number supplied as a dice/roll specification will be treated as the number of sides. This should look like this:

 (bjd/roll [6])
 #_=> 4

Be a little more explicit with your roll request:

 (bjd/roll [:d 6])
 #_=> 5

Roll more dice and total the result:

 (bjd/roll [3 :d 6])
 #_=> 12

By default in these scenarios, we return the total of the roll. identity as a dice modifier will return a col of individual dice rolls:

  (bjd/roll [3 :d 6 identity])

  #_=> (4 2 1)

To allow modifiers to be passed as pure data, modifier functions can be supplied as keywords too:

  (bjd/roll [3 :d 6 :identity])
  #_=> (4 5 2)

Other common dice modifiers are built into the library:

  (bjd/roll [3 :d 6 + 5]

  #_=> 18

Try a different, improbable, number of sides:

  (bjd/roll [2 :d 7])
  #_=> 5

...and with another common modifier:

  (bjd/roll [2 :d 7 - 1])
  #_=> 3

Dice specifications can consume other dice specifications, allowing us to roll random sided dice and dice counts:

  (bjd/roll [[1 :d 4] :d [2 :d 4]])
  #_=> 6

Arguments to modifiers can be dice specifications, too:

  (bjd/roll [1 :d 6 - [1 :d 6]])
  #_ => -1

A dice-roller can be produced as a function with:

  (bjd/prepare-roll [4 :d 6])
  #_ => 15

A convenience macro is provided, too:

  (bjd/defroll r2d6 [2 :d 6])
  #_=> 5

The modifier position should be a function. Except for a few obvious special cases, it should be an fn of two arguments - a list of roll results and a list of arguments.

The roll-die multimethod can be extended to provide different dice-rolling conventions.

That should about cover it. Enjoy.


This mostly does what I need right now, but I suspect that might be a few interesting changes in the future.

I'm likely to overhaul the modifiers system to allow for multiple modifiers. Not 100% sure how I want to treat presidency rules between modifier functions, so I may leave well enough alone for a while.

It might be interesting to provide configurable random seeds and saved state for save games.

Suggestions and PRs welcome.


Copyright © 2017 Damon Kropf-Untucht Distributed under the Eclipse Public License version 1.0

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close