polyhedra 0.3.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ruby-1.9.3@polyhedra --create

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "guard"
+  gem "guard-rspec"
+  gem "listen"
+  gem "rb-fsevent"
+  gem "rspec"
+end
+

data/Guardfile

@@ -0,0 +1,47 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{^lib/polyhedra/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # Capybara request specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # Capybara request specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+

data/README.md

@@ -0,0 +1,209 @@
+# Overview
+
+Polyhedra is a tool to help you write programs that manage dice using
+the kinds of expressions most RPG rulebooks use. Some examples of dice
+expressions that can be handled:
+
+* d20
+* 3d6
+* 6d6
+* 1d4-1
+* 2d6x10
+* 2d6*10
+* 4d6t3     # roll 4d6, take highest 3
+* 3d6r2     # roll 3d6, re-rolling 1's or 2's
+* 2d6-1x10  # note that +/- modifiers happen before multipliers; that's just how dice math works. 2d6-1x10 == 1-11x10 == 10-110
+* 1d6 fire  # you can assign units to the dice as well
+
+Polyhedra understands dice math:
+
+* 3d6 + 2d6 => 5d6
+* 2d6 + 1d4 => 2d6 + 1d4 # dissimilar bases can't be added
+* 1d6 fire + 1d4 fire + 1d6 earth => 1d6 + 1d4 fire + 1d6 earth # similar units are grouped before bases
+
+Note that adding two dissimilar dice results in a "DiceSet", which is
+a collection of Dice objects. You can still "roll" a DiceSet just like
+you would a Dice object, but #sides won't work and #units will return
+an array.
+
+Polyhedra also understands units, and knows to avoid adding dice of
+different units:
+
+* 3d6 fire + 2d6 physical
+* 1d4 frost + 2
+
+# Dice Notation
+
+The simplest RPG Dice notation is given as numbers and letters of the
+form _NdS_, where N is the number of dice to roll and S is the number
+of sides per die. When you roll all the dice in a Yahtzee cup, you are
+rolling 5d6, or five dice, each with six sides. If you are rolling a
+single die, you can omit the 1 and represent the notation as e.g d6.
+
+Role-playing games make allowances for other alterations to the roll:
+you can add or subtract (2d6+3, 1d4-1), multiply or divide (1d4x10,
+1d6/2). (Note that most game systems round down, so 1d6/2 actually
+yields a number between 0 and 3.)
+
+Mathematically, none of the following are equivalent: 1d3, 1d4-1,
+1d6/2. The first one cannot roll 0's, and although the second two have
+the same min/max range, 1d4-1 has an even distribution--exactly a 25%
+chance of rolling each number--while 1d6/2 has an uneven distribution
+(a 17% chance of rolling a 0, 33% chance of rolling a 1, etc).
+
+## Notational Affixes
+
+* rR - Reroll any dice equal or below R. R must be < S. 3d6r3 will
+  roll 12-18 as each die must be 4 or higher to be kept.
+  Mathematically 3d6r3 is identical to 3d3+9 but the semantics are
+  considered to be different so the extra notation is allowed.
+
+* RR - Reroll any dice equal or above R. R must be > 1 and <= S.
+
+* kM - Keep highest M dice. 1 < M < N. 4d6k3 means roll 4d6, but only
+  count the highest 3 dice in the final tally.
+
+* KM - Keep lowest M dice. 1 < M < N.
+
+
+
+# Order of Operations
+
+Rerolls are considered first, then keeps. Next--and this is the
+reverse of typical algebraic precedence--addition or subtraction
+happens and finally multiplication or division. Thus
+
+  4d6r1k3+1x10
+
+Would roll dice until 4 dice showed 2 or higher, then the top 3 dice
+would be kept. The range at this point would be 6-18. 1 would be added
+to this bumping the range to 7-19. Finally the roll is mulitplied by
+10 to yield a range of 70-190. Note that because multiplication is
+performed last the final value will be in steps of the multiplier;
+e.g. the above dice expression could roll a 70, 80, 90, etc., but
+could not roll a 75 or an 81.
+
+# Monkeypatch! Woo! (Fixnum shorthand)
+
+Polyhedra will add .d* methods to Fixnum and to Kernel (d20 is the same
+as 1.d20 is the same as Dice.new "1d20"). Since this is a monkeypatch,
+it's optional. Require polyhedra/shorthand instead of polyhedra to get
+these methods.
+
+
+    require 'polyhedra/shorthand'
+    dice = 3.d6
+    # => <#Dice: 3d6>
+
+    fire1 = 1.d6("fire")
+    fire2 = 2.d8("fire")
+    fire3 = 3.d6(:fire) # symbols and strings are okay
+    frost = 2.d6("frost")
+
+    fire1 + fire2 + fire3 + frost
+    # => <DiceSet: <Dice: 4d6, fire>, <Dice: 2d8, fire>, <Dice: 2d6 frost>]
+
+Note that while the shorthand allows for modifiers like -1 or x10, it
+looks kind of lame.
+
+    1.d6("r1-1")
+    # => <Dice: 1d6r1-1>
+    2.d10("+3x10")
+    # => <Dice: 2d10+3x10>
+    d20
+    # => <Dice: 1d20>
+
+I am open to changing the interface to cascade like so:
+
+4.d6.r1.k3("+1x10") but honestly this still looks unnecessarily
+complicated. Better to just use Dice.new() at this point.
+
+Then again, since we have to catch method_missing to allow for
+arbitrary digits, maybe we could steal a page from the Rails playbook
+and allow longer methods names that encode the entire sequence, such
+as:
+
+    4.d6r1t3
+    # => <Dice: 4d6r1t3
+
+The only gotcha is that we can't capture +/- in its proper place
+(immediately after the dX sequence). Legal ruby would be `4.d6r1t3+3`
+but proper dice notation would `4.d6+3r1t3` which won't work.
+
+Hrm, if a Dice.new() or Fixnum#dXX statement returns a Dice object,
+maybe we should define +,-,*,/ etc to return new Dice objects?
+
+    d6
+    # => <Dice: 1d6>
+    d6 + 1
+    # => <Dice: 1d6+1>
+
+
+## Complex Notation
+
+A set of Dice can be collected into a DiceSet and rolled as a unit:
+
+    bag = DiceSet.new
+    bag << Dice.new('3d6')
+    bag << '2d4'  # bag#<< accepts Dice or string
+    bag
+    # => <DiceSet: <Dice: 3d6>, <Dice: 2d4>>
+    bag.roll
+    # => 19
+    bag.max
+    # => 26
+    bag.min
+    # => 5
+
+## Units
+
+Each Dice object can have its own units, and units are treated as a
+higher-order grouping than number of sides. Note that #min, #max and
+#roll will return an array of pairs containing the amount and unit for
+each type of dice.
+
+    bag = DiceSet.new
+    bag << 1.d6("fire")
+    bag << 1.d6("fire")
+    bag << 1.d4("frost")
+    bag.min
+    # => [[2, :fire], [1, :frost]]
+    bag.min_without_units
+    # => 3
+    bag.max
+    # => [[12, :fire], [4, :frost]]
+    bag.max_without_units
+    # => 16
+    bag.roll
+    # => [[7, :fire], [2, :frost]]
+    bag.roll_without_units
+    # => 11
+
+You can also pass a specific unit to #min, #max and #roll to isolate
+part of the roll:
+
+    bag.max(:fire)
+    # => 12
+    bag.min(:frost)
+    # => 1
+    bag.roll(:fire)
+    # => 3
+
+
+# Contributing
+
+1. Pull requests are welcome!
+2. Fork the repo
+3. Write _good_ specs for your change: specs that fully cover and
+  clearly document the intent of your change
+4. Send a pull request
+
+*Note:* If you want to make a wild and crazy change (and have it
+  merged into the gem), I'm open to that--but please get in touch with
+  me and let's chat about the direction you want to go so you don't
+  waste your time (unless you're okay with your changes staying in
+  your fork forever)
+
+
+
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/polyhedra.rb

@@ -0,0 +1,3 @@
+require "polyhedra/version"
+require "polyhedra/dice"
+

data/lib/polyhedra/dice.rb

@@ -0,0 +1,112 @@
+module Polyhedra
+  class Dice
+    include Comparable
+
+    attr_accessor :number, :sides, :offset, :multiplier, :divisor, :reroll_under, :take_top
+    attr_writer :rng
+
+    def initialize(dice_expression)
+      dice_expression = dice_expression.gsub(/s+/, '')
+
+      @offset = @reroll_under = 0
+      @multiplier = @divisor = 1
+
+      @take_top = @number = [1, dice_expression.to_i].max
+      dice_expression.sub!(/^\d+/, '')
+
+      while dice_expression.length > 0
+        action, amount, dice_expression = pop_expression(dice_expression)
+        amount = amount.to_i
+        case action
+        when 'd'
+          self.sides = amount
+        when '+'
+          self.offset = amount
+        when '-'
+          self.offset = -amount
+        when '*', 'x'
+          self.multiplier = amount
+        when '/'
+          self.divisor = amount
+        when 'r'
+          self.reroll_under = amount
+        when 't'
+          self.take_top = amount
+        end
+      end
+    end
+
+    def to_s
+      str = ""
+      str << "%dd%d" % [number, sides]
+      str << "%+d" % offset unless offset.zero?
+      str << "x%d" % multiplier unless multiplier == 1
+      str << "/%d" % divisor unless divisor == 1
+      str << "r%d" % reroll_under unless reroll_under.zero?
+      str << "t%d" % take_top unless take_top == number
+      str
+    end
+
+    def roll
+      rolled_dice = []
+
+      while rolled_dice.size < number
+        roll=rand(sides)+1
+        rolled_dice << roll if roll > reroll_under
+      end
+
+      rolled_dice = rolled_dice.sort.reverse.take take_top
+
+      rolled_dice.inject {|a,b| a+b}
+    end
+
+    def min
+      ((take_top + offset + (reroll_under*take_top)) * multiplier) / divisor
+    end
+
+    def max
+      ((take_top * sides + offset) * multiplier) / divisor
+    end
+
+    def pop_expression(string)
+      %r|^([dr+-x\*/])(\d+)(.*)$|.match(string).to_a.dup.tap(&:shift)
+    end
+
+    # def dice_matrix
+    #   # TODO: make this work with take_top--probably a sort/take in the each_slice?
+    #   # TODO: make this work with reroll--probably change the 1..sides to reroll+1..sides ?
+    #   Array.new(number) { (1..sides).to_a }.inject(:product).flatten.each_slice(number).map {|ray| ray.sort.take take_top }
+    # end
+
+    def rand(num)
+      rng.rand(num)
+    end
+
+    def inverted_divisor
+      1.0 / divisor
+    end
+
+    def <=>(other)
+      a,b = [:sides, :number, :multiplier, :inverted_divisor, :offset].map {|sym| [send(sym), other.send(sym)] }.detect {|a,b| (a <=> b) != 0 }
+      a <=> b
+      # if sides != other.sides
+      #   sides <=> other.sides
+      # else
+      #   if number != other.number
+      #     number <=> other.number
+      #   else
+      #     if multiplier != other.multiplier
+      #       multiplier <=> other.multiplier
+      #     else
+      #       -divisor <=> -other.divisor
+      #     end
+      #   end
+      # end
+    end
+
+    private
+    def rng
+      @rng ||= Random.new
+    end
+  end
+end

data/lib/polyhedra/version.rb

@@ -0,0 +1,3 @@
+module Polyhedra
+  VERSION = "0.3.0"
+end

data/polyhedra.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "polyhedra/version"
+
+Gem::Specification.new do |s|
+  s.name        = "polyhedra"
+  s.version     = Polyhedra::VERSION
+  s.authors     = ["David Brady"]
+  s.email       = ["github@shinybit.com"]
+  s.homepage    = ""
+  s.summary     = %q{Dice manipulation and rolling gem capable of handling complex dice expressions}
+  s.description = %q{Dice manipulation and rolling gem capable of handling complex RPG dice expressions, from a simple "d6" up to "4d6r1k3-2x10 frost" and "3d6", etc.}
+
+  s.rubyforge_project = "polyhedra"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+
+#  s.add_runtime_dependency "treetop"
+end

data/spec/lib/dice_spec.rb

@@ -0,0 +1,137 @@
+require 'spec_helper'
+require 'polyhedra/dice'
+
+# I roll twenties! rand(n) always returns max possible value
+class LuckyRng < Random
+  def rand(num)
+    num-1
+  end
+end
+
+# Returns 0, 1, 2, ..., n-1 in order.
+class GaussianRng < Random
+  def rand(num)
+    @sequence ||= (0..num).cycle
+    @sequence.next
+  end
+end
+
+# Returns... whatever... you tell... it to...
+class JediMindTrickRng < Random
+  def initialize(sequence)
+    @sequence = sequence.cycle
+    super(0)
+  end
+
+  def rand(num)
+    @sequence.next
+  end
+end
+
+module Polyhedra
+  describe Dice do
+    context "simple dice expression" do
+      let(:dice) { Dice.new("3d6") }
+
+      it { dice.offset.should == 0 }
+      it { dice.sides.should == 6 }
+      it { dice.number.should == 3 }
+      it { dice.roll.should >= 3 }
+      it { dice.roll.should <= 18 }
+      it { dice.min.should == 3 }
+      it { dice.max.should == 18 }
+    end
+
+    context "with offset" do
+      it { Dice.new("3d6+2").min.should == 5 }
+      it { Dice.new("3d6+2").max.should == 20 }
+      it { Dice.new("3d6-2").min.should == 1 }
+      it { Dice.new("3d6-2").max.should == 16 }
+    end
+
+    context "with scalar" do
+      it { Dice.new("3d6x10").min.should == 30 }
+      it { Dice.new("3d6x10").max.should == 180 }
+      it { Dice.new("3d6*10").min.should == 30 }
+      it { Dice.new("3d6*10").max.should == 180 }
+      it { Dice.new("1d6/2").min.should == 0 }
+      it { Dice.new("1d6/2").max.should == 3 }
+    end
+
+    context "with reroll_under" do
+      let(:dice) { Dice.new("3d6r1") }
+      before(:each) do
+        dice.rng = JediMindTrickRng.new [0, 1, 0, 2, 0, 3]
+      end
+      it { dice.reroll_under.should == 1 }
+      it { dice.min.should == 6 }
+      it { dice.max.should == 18 }
+
+      it { dice.roll.should == 9 }
+    end
+
+    context "with take_top" do
+      let(:dice) { Dice.new("4d6t3") }
+      it { dice.take_top.should == 3 }
+      it { dice.max.should == 18 }
+      it { dice.min.should == 3 }
+      context "with loaded dice" do
+        before :each do
+          dice.rng = JediMindTrickRng.new [2,0,4,5]
+        end
+        it { dice.roll.should == 14 }
+      end
+    end
+
+    context "when I roll twenties" do
+      let(:dice) { Dice.new("4d6") }
+      before :each do
+        dice.rng = LuckyRng.new
+      end
+      it { dice.roll.should == 24 }
+    end
+
+    describe "#pop_expression" do
+      describe "returns subexpression, rest_of_string"  do
+        it { Dice.new("1d6").pop_expression("r3string").should == ["r", "3", "string"] }
+      end
+    end
+
+    describe "#to_s" do
+      it { Dice.new("d20").to_s.should == "1d20" }
+      it { Dice.new("1d4*10").to_s.should =="1d4x10" }
+
+      # These expressions should all parse and to_s as themselves
+      [ "3d6",
+        "1d4+1",
+        "3d6r1",
+        "4d6t3",
+        "6d6+3r2t4",
+        "1d10x10",
+        "1d4+2x10",
+        "1d6/2",
+        "9d8+2x5r2t6"
+      ].each do |str|
+        it "correctly parses '#{str}'" do
+          Dice.new(str).to_s.should eq str
+        end
+      end
+    end
+
+    describe "comparison" do
+      it { Dice.new("3d6").should == Dice.new("3d6") }
+      it("favors bases first") { Dice.new("10d4").should < Dice.new("1d5") }
+      it("favors number second") { Dice.new("3d6").should > Dice.new("2d6") }
+      it("favors multipliers third") { Dice.new("3d6x10").should > Dice.new("3d6x8") }
+      it("favors divisors third") { Dice.new("3d6/10").should < Dice.new("3d6/8") }
+      it("favors offset fourth") { Dice.new("3d6+3").should > Dice.new("3d6") }
+    end
+
+    describe "dice math" do
+      describe "addition" do
+        it { Dice.new("3d6")}
+      end
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+# spec helper
+
+
+# ;-) -- happy little no-op for now

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: polyhedra
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+  prerelease: 
+platform: ruby
+authors:
+- David Brady
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-17 00:00:00.000000000 Z
+dependencies: []
+description: Dice manipulation and rolling gem capable of handling complex RPG dice
+  expressions, from a simple "d6" up to "4d6r1k3-2x10 frost" and "3d6", etc.
+email:
+- github@shinybit.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .rvmrc
+- Gemfile
+- Guardfile
+- README.md
+- Rakefile
+- lib/polyhedra.rb
+- lib/polyhedra/dice.rb
+- lib/polyhedra/version.rb
+- polyhedra.gemspec
+- spec/lib/dice_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: polyhedra
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Dice manipulation and rolling gem capable of handling complex dice expressions
+test_files:
+- spec/lib/dice_spec.rb
+- spec/spec_helper.rb