games_dice 0.0.6 → 0.1.1

data/README.md

@@ -27,7 +27,7 @@ The main features of GamesDice are
 ## Special Note on Versions Prior to 1.0.0
 
 The author is using this code as an exercise in gem "best practice". As such, the gem
-will have a deliberately limited set of functionality prior to version 1.0.0, and there should be
+will have a limited set of functionality prior to version 1.0.0, and there should be
 many small release increments before then.
 
 ## Installation
@@ -60,7 +60,9 @@ dice rolls, explain the results or calculate probabilties as required.
 
 ### GamesDice factory methods
 
-#### GamesDice.create dice_description, prng
+#### GamesDice.create
+
+    dice = GamesDice.create dice_description, prng
 
 Converts a string such as '3d6+6' into a GamesDice::Dice object
 
@@ -73,14 +75,70 @@ Returns a GamesDice::Dice object.
 
 ### GamesDice::Dice instance methods
 
+Example results given for '3d6'. Unless noted, methods do not take any parameters.
+
 #### dice.roll
 
 Simulates rolling the dice as they were described in the constructor, and keeps a record of how the
 simulation result was achieved.
 
-Takes no parameters.
+    dice.roll        # => 12
+
+#### dice.result
+
+Returns the value from the last call to roll. This will be nil if no roll has been made yet.
+
+    dice.result      # => nil
+    dice.roll
+    dice.result      # => 12
+
+#### dice.max
+
+Returns the maximum possible value from a roll of the dice. Dice with the possibility of rolling
+progressively higher and higher values will return an arbitrary high value.
+
+    dice.max         # => 18
+
+#### dice.min
+
+Returns the minimum possible value from a roll of the dice. Dice with the possibility of rolling
+progressively lower and lower values will return an arbitrary low value.
+
+    dice.min         # => 3
+
+#### dice.minmax
+
+Convenience method, returns an array [ dice.min, dice.max ]
+
+    dice.minmax      # => [3,18]
+
+#### dice.probabilities
+
+Calculates probability distribution for the dice. Note that some distributions, involving keeping
+a number best or worst results, can take significant time to calculate.
+
+Returns a GamesDice::Probabilities object that describes the probability distribution.
+
+    probabilities = dice.probabilities
+
+### GamesDice::Probabilities instance methods
+
+#### probabilities.to_h
+
+Returns a hash representation of the probability distribution. Each keys is a possible result
+from rolling the dice (an Integer), and the associated value is the probability of a roll
+returning that value (a Float).
+
+#### probabilities.max
+
+Returns maximum value in the probability distribution. This may not be the theoretical maximum
+possible on the dice, if for example the dice can roll open-ended high results.
+
+#### probabilities.min
+
+Returns minimum value in the probability distribution. This may not be the theoretical minimum
+possible on the dice, if for example the dice can roll open-ended low results.
 
-Returns the integer result of the roll.
 
 ## String Dice Descriptions
 
@@ -101,6 +159,69 @@ That is the limit of combining dice and constants though, no multiplications, or
 like "(1d8)d8" - you can still use games_dice to help simulate these, but you will need to add your own
 code to do so.
 
+### Die Modifiers
+
+After the number of sides, you may add one or more modifiers, that affect all of the dice in that
+"NdX" group. A die modifier can be a single character, e.g.
+
+    1d10x
+
+A die modifier can also be a single letter plus an integer value, e.g.
+
+    1d6r1
+
+More complex die modifiers are possible, with parameters supplied in square brackets, and multiple
+modifiers should combine as expected e.g.
+
+    5d10r[10,add]k2
+
+#### Rerolls
+
+You can specify that dice rolling certain values should be re-rolled, and how that re-roll should be
+interpretted.
+
+The simple form specifies a low value that will automatically trigger a one-time replacement:
+
+    1d6r1
+
+When rolled, this die will score from 1 to 6. If it rolls a 1, it will roll again automatically
+and use that result instead.
+
+#### Maps
+
+You can specify that the value shown on each die is converted to some other set of values. If
+you add at least one map modifier, all unmapped values will map to 0 by default.
+
+The simple form specifies a value above which the result is considered to be 1, as in "one success":
+
+    3d10m6
+
+When rolled, this will score from 0 to 3 - the number of the ten-sided dice that scored 6 or higher.
+
+#### Keepers
+
+You can specify that only a sub-set of highest or lowest dice values will contribute to the final
+total.
+
+The simple form indicates the number of highest value dice to keep.
+
+    5d10k2
+
+When rolled, this will score from 2 to 20 - the sum of the two highest scoring ten-sided dice, out of
+five.
+
+#### Aliases
+
+Some combinations of modifiers crop up in well-known games, and have been allocated single-character
+short codes.
+
+This is an alias for "exploding" dice:
+
+    5d10x
+
+When rolled, this will score from 5 to theoretically any number, as results of 10 on any die mean that
+die rolls again and the result is added on.
+
 ## Contributing
 
 1. Fork it

data/lib/games_dice/complex_die.rb

@@ -19,10 +19,8 @@ class GamesDice::ComplexDie
   def initialize(sides, options_hash = {})
     @basic_die = GamesDice::Die.new(sides, options_hash[:prng])
 
-    @rerolls = options_hash[:rerolls]
-    validate_rerolls
-    @maps = options_hash[:maps]
-    validate_maps
+    @rerolls = construct_rerolls( options_hash[:rerolls] )
+    @maps = construct_maps( options_hash[:maps] )
 
     @total = nil
     @result = nil
@@ -149,6 +147,32 @@ class GamesDice::ComplexDie
 
   private
 
+  def construct_rerolls rerolls_input
+    return nil unless rerolls_input
+    raise TypeError, "rerolls should be an Array, instead got #{rerolls_input.inspect}" unless rerolls_input.is_a?(Array)
+    rerolls_input.map do |reroll_item|
+      case reroll_item
+      when Array then GamesDice::RerollRule.new( reroll_item[0], reroll_item[1], reroll_item[2], reroll_item[3] )
+      when GamesDice::RerollRule then reroll_item
+      else
+        raise TypeError, "items in rerolls should be GamesDice::RerollRule or Array, instead got #{reroll_item.inspect}"
+      end
+    end
+  end
+
+  def construct_maps maps_input
+    return nil unless maps_input
+    raise TypeError, "maps should be an Array, instead got #{maps_input.inspect}" unless maps_input.is_a?(Array)
+    maps_input.map do |map_item|
+      case map_item
+      when Array then GamesDice::MapRule.new( map_item[0], map_item[1], map_item[2], map_item[3] )
+      when GamesDice::MapRule then map_item
+      else
+        raise TypeError, "items in maps should be GamesDice::MapRule or Array, instead got #{map_item.inspect}"
+      end
+    end
+  end
+
   def calc_maps x
     y, n = 0, ''
     @maps.find do |rule|
@@ -162,22 +186,6 @@ class GamesDice::ComplexDie
     [y, n]
   end
 
-  def validate_rerolls
-    return unless @rerolls
-    raise TypeError, "rerolls should be an Array, instead got #{@rerolls.inspect}" unless @rerolls.is_a?(Array)
-    @rerolls.each do |rule|
-      raise TypeError, "items in rerolls should be GamesDice::RerollRule, instead got #{rule.inspect}" unless rule.is_a?(GamesDice::RerollRule)
-    end
-  end
-
-  def validate_maps
-    return unless @maps
-    raise TypeError, "maps should be an Array, instead got #{@maps.inspect}" unless @maps.is_a?(Array)
-    @maps.each do |rule|
-      raise TypeError, "items in maps should be GamesDice::MapRule, instead got #{rule.inspect}" unless rule.is_a?(GamesDice::MapRule)
-    end
-  end
-
   def minmax_mappings possible_values
     possible_values.map { |x| m, n = calc_maps( x ); m }.minmax
   end

data/lib/games_dice/dice.rb

@@ -40,4 +40,30 @@ class GamesDice::Dice
     end
   end
 
+  def min
+    @min ||= @offset + @bunch_multipliers.zip(@bunches).inject(0) do |total,mb|
+      m,b = mb
+      total += m * b.min
+    end
+  end
+
+  def max
+    @max ||= @offset + @bunch_multipliers.zip(@bunches).inject(0) do |total,mb|
+      m,b = mb
+      total += m * b.max
+    end
+  end
+
+  def minmax
+    [min,max]
+  end
+
+  def probabilities
+    return @probabilities if @probabilities
+    probs = @bunch_multipliers.zip(@bunches).inject( GamesDice::Probabilities.new( { @offset => 1.0 } ) ) do |probs, mb|
+      m,b = mb
+      GamesDice::Probabilities.add_distributions_mult( 1, probs, m, b.probabilities )
+    end
+  end
+
 end # class Dice

data/lib/games_dice/parser.rb

@@ -4,27 +4,33 @@ require 'parslet'
 class GamesDice::Parser < Parslet::Parser
 
   # Descriptive language examples (capital letters stand in for integers)
-  #  NdX               -  a roll of N dice, with X sides each, values summed to total
-  #  NdX + C           -  a roll of N dice, with X sides each, values summed to total plus a constant C
-  #  NdX - C           -  a roll of N dice, with X sides each, values summed to total minus a constant C
-  #  NdX + MdY + C     -  any number of +C, -C, +NdX, -NdX etc sub-expressions can be combined
-  #  NdXkZ             -  a roll of N dice, sides X, keep best Z results and sum them
   #  NdXk[Z,worst]     -  a roll of N dice, sides X, keep worst Z results and sum them
-  #  NdXrZ             -  a roll of N dice, sides X, re-roll and replace Zs
   #  NdXr[Z,add]       -  a roll of N dice, sides X, re-roll and add on a result of Z
   #  NdXr[Y..Z,add]    -  a roll of N dice, sides X, re-roll and add on a result of Y..Z
-  #  NdXx              -  exploding dice, synonym for NdXr[X,add]
-  #  NdXmZ             -  mapped dice, values below Z score 0, values above Z score 1
   #  NdXm[>=Z,A]       -  mapped dice, values greater than or equal to Z score A (unmapped values score 0 by default)
 
   # These are the Parslet rules that define the dice grammar
   rule(:integer) { match('[0-9]').repeat(1) }
+  rule(:range) { integer.as(:range_start) >> str('..') >> integer.as(:range_end) }
   rule(:dlabel) { match('[d]') }
   rule(:bunch_start) { integer.as(:ndice) >> dlabel >> integer.as(:sides) }
+
+  rule(:reroll_label) { match(['r']).as(:reroll) }
+  rule(:keep_label) { match(['k']).as(:keep) }
+  rule(:map_label) { match(['m']).as(:map) }
+  rule(:alias_label) { match(['x']).as(:alias) }
+
+  rule(:single_modifier) { alias_label }
+  rule(:modifier_label) {  reroll_label | keep_label | map_label }
+  rule(:simple_modifier) { modifier_label >> integer.as(:simple_value) }
+  rule(:complex_modifier) { modifier_label >> str('[') >> str(']') } # TODO: param extraction
+
+  rule(:bunch_modifier) { single_modifier | simple_modifier }
+  rule(:bunch) { bunch_start >> bunch_modifier.repeat.as(:mods) }
   rule(:space) { match('\s').repeat(1) }
   rule(:space?) { space.maybe }
   rule(:operator) { match('[+-]').as(:op) >> space? }
-  rule(:add_bunch) { operator >> bunch_start >> space? }
+  rule(:add_bunch) { operator >> bunch >> space? }
   rule(:add_constant) { operator >> integer.as(:constant) >> space? }
   rule(:dice_expression) { add_bunch | add_constant }
   rule(:expressions) { dice_expression.repeat.as(:bunches) }
@@ -59,6 +65,25 @@ class GamesDice::Parser < Parslet::Parser
           when '-' then -1
         end
       end
+
+      # Modifiers
+      if in_hash[:mods]
+        in_hash[:mods].each do |mod|
+          case
+          when mod[:alias]
+            collect_alias_modifier mod, out_hash
+          when mod[:keep]
+            collect_keeper_rule mod, out_hash
+          when mod[:map]
+            out_hash[:maps] ||= []
+            collect_map_rule mod, out_hash
+          when mod[:reroll]
+            out_hash[:rerolls] ||= []
+            collect_reroll_rule mod, out_hash
+          end
+        end
+      end
+
       out_hash
     end
   end
@@ -76,4 +101,43 @@ class GamesDice::Parser < Parslet::Parser
     end
   end
 
+  # Called when we have a single letter convenient alias for common dice adjustments
+  def collect_alias_modifier alias_mod, out_hash
+    alias_name = alias_mod[:alias].to_s
+    case alias_name
+    when 'x' # Exploding re-roll
+      out_hash[:rerolls] ||= []
+      out_hash[:rerolls] << [ out_hash[:sides], :==, :reroll_add ]
+    end
+  end
+
+  # Called for any parsed reroll rule
+  def collect_reroll_rule reroll_mod, out_hash
+    out_hash[:rerolls] ||= []
+    if reroll_mod[:simple_value]
+      out_hash[:rerolls] << [ reroll_mod[:simple_value].to_i, :>=, :reroll_replace, 1 ]
+    end
+    # TODO: Handle complex descriptions
+  end
+
+  # Called for any parsed keeper mode
+  def collect_keeper_rule keeper_mod, out_hash
+    if keeper_mod[:simple_value]
+      out_hash[:keep_mode] = :keep_best
+      out_hash[:keep_number] = keeper_mod[:simple_value].to_i
+      return
+    end
+    # TODO: Handle complex descriptions
+  end
+
+  # Called for any parsed map mode
+  def collect_map_rule map_mod, out_hash
+    out_hash[:maps] ||= []
+    if map_mod[:simple_value]
+      out_hash[:maps] << [ map_mod[:simple_value].to_i, :<=, 1 ]
+      return
+    end
+    # TODO: Handle complex descriptions
+  end
+
 end # class Parser

data/lib/games_dice/probabilities.rb

@@ -94,4 +94,18 @@ class GamesDice::Probabilities
     GamesDice::Probabilities.new( h )
   end
 
+  # adding two probability distributions calculates a new distribution, representing what would
+  # happen if you created a random number using the sum of numbers from both distributions
+  def self.add_distributions_mult m_a, pd_a, m_b, pd_b
+    h = {}
+    pd_a.ph.each do |ka,pa|
+      pd_b.ph.each do |kb,pb|
+        kc = m_a * ka + m_b * kb
+        pc = pa * pb
+        h[kc] = h[kc] ? h[kc] + pc : pc
+      end
+    end
+    GamesDice::Probabilities.new( h )
+  end
+
 end # class Dice

data/lib/games_dice/reroll_rule.rb

@@ -31,7 +31,7 @@ class GamesDice::RerollRule
   #   :reroll_add - add result of reroll to running total, and ignore :reroll_subtract for this die
   #   :reroll_subtract - subtract result of reroll from running total, and reverse sense of any further :reroll_add results
   #   :reroll_replace - use the new value in place of existing value for the die
-  #   :reroll_use_best - use the new value if it is higher than the erxisting value
+  #   :reroll_use_best - use the new value if it is higher than the existing value
   #   :reroll_use_worst - use the new value if it is higher than the existing value
   attr_reader :type
 

data/lib/games_dice/version.rb

@@ -1,3 +1,3 @@
 module GamesDice
-  VERSION = "0.0.6"
+  VERSION = "0.1.1"
 end

data/spec/complex_die_spec.rb

@@ -45,6 +45,8 @@ describe GamesDice::ComplexDie do
     GamesDice::ComplexDie.new( 10, :rerolls => [] )
     GamesDice::ComplexDie.new( 10, :rerolls => [GamesDice::RerollRule.new(6, :<=, :reroll_add)] )
     GamesDice::ComplexDie.new( 10, :rerolls => [GamesDice::RerollRule.new(6, :<=, :reroll_add),GamesDice::RerollRule.new(1, :>=, :reroll_subtract)] )
+    GamesDice::ComplexDie.new( 10, :rerolls => [[6, :<=, :reroll_add]] )
+    GamesDice::ComplexDie.new( 10, :rerolls => [[6, :<=, :reroll_add],[1, :>=, :reroll_subtract]] )
 
     lambda do
       GamesDice::ComplexDie.new( 10, :rerolls => 7 )
@@ -57,23 +59,46 @@ describe GamesDice::ComplexDie do
     lambda do
       GamesDice::ComplexDie.new( 10, :rerolls =>  [GamesDice::RerollRule.new(6, :<=, :reroll_add), :reroll_add] )
     end.should raise_error( TypeError )
+
+    lambda do
+      GamesDice::ComplexDie.new( 10, :rerolls => [7] )
+    end.should raise_error( TypeError )
+
+    lambda do
+      GamesDice::ComplexDie.new( 10, :rerolls => [['hello']] )
+    end.should raise_error( TypeError )
+
+    lambda do
+      GamesDice::ComplexDie.new( 10, :rerolls =>  [ [6, :<=, :reroll_add ], :reroll_add] )
+    end.should raise_error( TypeError )
+
   end
 
   it "should optionally accept a maps param" do
     GamesDice::ComplexDie.new( 10, :maps => [] )
     GamesDice::ComplexDie.new( 10, :maps => [GamesDice::MapRule.new(7, :<=, 1)] )
     GamesDice::ComplexDie.new( 10, :maps => [GamesDice::MapRule.new(7, :<=, 1), GamesDice::MapRule.new(1, :>, -1) ] )
+    GamesDice::ComplexDie.new( 10, :maps => [ [7, :<=, 1] ] )
+    GamesDice::ComplexDie.new( 10, :maps => [ [7, :<=, 1], [1, :>, -1] ] )
 
     lambda do
       GamesDice::ComplexDie.new( 10, :maps => 7 )
     end.should raise_error( TypeError )
 
+    lambda do
+      GamesDice::ComplexDie.new( 10, :maps => [7] )
+    end.should raise_error( TypeError )
+
+    lambda do
+      GamesDice::ComplexDie.new( 10, :maps => [ [7] ] )
+    end.should raise_error( TypeError )
+
     lambda do
       GamesDice::ComplexDie.new( 10, :maps => ['hello'] )
     end.should raise_error( TypeError )
 
     lambda do
-      GamesDice::ComplexDie.new( 10, :maps =>  [GamesDice::MapRule.new(7, :<=, 1),GamesDice::RerollRule.new(6, :<=, :reroll_add)] )
+      GamesDice::ComplexDie.new( 10, :maps => [GamesDice::MapRule.new(7, :<=, 1),GamesDice::RerollRule.new(6, :<=, :reroll_add)] )
     end.should raise_error( TypeError )
   end
 
@@ -83,7 +108,7 @@ describe GamesDice::ComplexDie do
       die.min.should == 1
       die.max.should == 40
 
-      die = GamesDice::ComplexDie.new( 10, :rerolls => [GamesDice::RerollRule.new(1, :>=, :reroll_subtract)] )
+      die = GamesDice::ComplexDie.new( 10, :rerolls => [[1, :>=, :reroll_subtract]] )
       die.min.should == -9
       die.max.should == 10
 
@@ -93,7 +118,7 @@ describe GamesDice::ComplexDie do
     end
 
     it "should simulate a d10 that rerolls and adds on a result of 10" do
-      die = GamesDice::ComplexDie.new(10, :rerolls => [GamesDice::RerollRule.new(10, :<=, :reroll_add)] )
+      die = GamesDice::ComplexDie.new(10, :rerolls => [[10, :<=, :reroll_add]] )
       [5,4,14,7,8,1,9].each do |expected|
         die.roll.should == expected
         die.result.should == expected
@@ -101,7 +126,7 @@ describe GamesDice::ComplexDie do
     end
 
     it "should explain how it got results outside range 1 to 10 on a d10" do
-      die = GamesDice::ComplexDie.new(10, :rerolls => [GamesDice::RerollRule.new(10, :<=, :reroll_add),GamesDice::RerollRule.new(1, :>=, :reroll_subtract)] )
+      die = GamesDice::ComplexDie.new(10, :rerolls => [[10, :<=, :reroll_add],[1, :>=, :reroll_subtract]] )
       ["5","4","[10+4] 14","7","8","[1-9] -8"].each do |expected|
         die.roll
         die.explain_result.should == expected
@@ -109,7 +134,7 @@ describe GamesDice::ComplexDie do
     end
 
     it "should calculate an expected result" do
-      die = GamesDice::ComplexDie.new(10, :rerolls => [GamesDice::RerollRule.new(10, :<=, :reroll_add),GamesDice::RerollRule.new(1, :>=, :reroll_subtract)] )
+      die = GamesDice::ComplexDie.new(10, :rerolls => [[10, :<=, :reroll_add],[1, :>=, :reroll_subtract]] )
       die.probabilities.expected.should be_within(1e-10).of 5.5
 
       die = GamesDice::ComplexDie.new(10, :rerolls => [GamesDice::RerollRule.new(1, :<=, :reroll_use_best, 1)] )
@@ -179,7 +204,7 @@ describe GamesDice::ComplexDie do
     end
 
     it "should simulate a d10 that scores 1 for success on a value of 7 or more" do
-      die = GamesDice::ComplexDie.new( 10, :maps => [GamesDice::MapRule.new(7, :<=, 1, 'S')] )
+      die = GamesDice::ComplexDie.new( 10, :maps => [ [ 7, :<=, 1, 'S' ] ] )
       [0,0,1,0,1,1,0,1].each do |expected|
         die.roll.should == expected
         die.result.should == expected
@@ -187,7 +212,7 @@ describe GamesDice::ComplexDie do
     end
 
     it "should label the mappings applied with the provided names" do
-      die = GamesDice::ComplexDie.new( 10, :maps => [GamesDice::MapRule.new(7, :<=, 1, 'S'),GamesDice::MapRule.new(1, :>=, -1, 'F')] )
+      die = GamesDice::ComplexDie.new( 10, :maps => [ [7, :<=, 1, 'S'], [1, :>=, -1, 'F'] ] )
       ["5", "4", "10 S", "4", "7 S", "8 S", "1 F", "9 S"].each do |expected|
         die.roll
         die.explain_result.should == expected
@@ -229,10 +254,10 @@ describe GamesDice::ComplexDie do
     end
   end
 
-  describe "with rerolls and maps" do
+  describe "with rerolls and maps together" do
     before do
       @die = GamesDice::ComplexDie.new( 6,
-        :rerolls => [GamesDice::RerollRule.new(6, :<=, :reroll_add)],
+        :rerolls => [[6, :<=, :reroll_add]],
         :maps => [GamesDice::MapRule.new(9, :<=, 1, 'Success')]
         )
     end

data/spec/parser_spec.rb

@@ -5,7 +5,7 @@ describe GamesDice::Parser do
   describe "#parse" do
     let(:parser) { GamesDice::Parser.new }
 
-    it "should convert descriptive strings to data usable in the GamesDice::Dice constructor" do
+    it "should parse simple dice sums" do
       variations = {
         '1d6' => { :bunches => [{:ndice=>1, :sides=>6, :multiplier=>1}], :offset => 0 },
         '2d8-1d4' => { :bunches => [{:ndice=>2, :sides=>8, :multiplier=>1},{:ndice=>1, :sides=>4, :multiplier=>-1}], :offset => 0 },
@@ -22,5 +22,61 @@ describe GamesDice::Parser do
       end
     end
 
+    it "should parse 'NdXrY' as 'roll N times X-sided dice, re-roll and replace a Y or less (once)'" do
+      variations = {
+        '1d6r1' => { :bunches => [{:ndice=>1, :sides=>6, :multiplier=>1, :rerolls=>[ [1,:>=,:reroll_replace,1] ]}], :offset => 0 },
+        '2d20r7' => { :bunches => [{:ndice=>2, :sides=>20, :multiplier=>1, :rerolls=>[ [7,:>=,:reroll_replace,1] ]}], :offset => 0 },
+        '1d8r2' => { :bunches => [{:ndice=>1, :sides=>8, :multiplier=>1, :rerolls=>[ [2,:>=,:reroll_replace,1] ]}], :offset => 0 },
+      }
+
+      variations.each do |input,expected_output|
+        parser.parse( input ).should ==  expected_output
+      end
+    end
+
+    it "should parse 'NdXmZ' as 'roll N times X-sided dice, a value of Z or more equals 1 (success)'" do
+      variations = {
+        '5d6m6' => { :bunches => [{:ndice=>5, :sides=>6, :multiplier=>1, :maps=>[ [6,:<=,1] ]}], :offset => 0 },
+        '2d10m7' => { :bunches => [{:ndice=>2, :sides=>10, :multiplier=>1, :maps=>[ [7,:<=,1] ]}], :offset => 0 },
+      }
+
+      variations.each do |input,expected_output|
+        parser.parse( input ).should ==  expected_output
+      end
+    end
+
+    it "should parse 'NdXkC' as 'roll N times X-sided dice, add together the best C'" do
+      variations = {
+        '5d10k3' => { :bunches => [{:ndice=>5, :sides=>10, :multiplier=>1, :keep_mode=>:keep_best, :keep_number=>3}], :offset => 0 },
+      }
+
+      variations.each do |input,expected_output|
+        parser.parse( input ).should ==  expected_output
+      end
+    end
+
+    it "should parse 'NdXx' as 'roll N times X-sided *exploding* dice'" do
+      variations = {
+        '5d10x' => { :bunches => [{:ndice=>5, :sides=>10, :multiplier=>1, :rerolls=>[ [10,:==,:reroll_add] ]}], :offset => 0 },
+        '3d6x' => { :bunches => [{:ndice=>3, :sides=>6, :multiplier=>1, :rerolls=>[ [6,:==,:reroll_add] ]}], :offset => 0 },
+      }
+
+      variations.each do |input,expected_output|
+        parser.parse( input ).should ==  expected_output
+      end
+    end
+
+    it "should successfully parse combinations of modifiers in any valid order" do
+      variations = {
+        '5d10r1x' => { :bunches => [{:ndice=>5, :sides=>10, :multiplier=>1, :rerolls=>[ [1,:>=,:reroll_replace,1], [10,:==,:reroll_add] ]}], :offset => 0 },
+        '3d6xk2' => { :bunches => [{:ndice=>3, :sides=>6, :multiplier=>1, :rerolls=>[ [6,:==,:reroll_add] ], :keep_mode=>:keep_best, :keep_number=>2 }], :offset => 0 },
+        '4d6m8x' => { :bunches => [{:ndice=>4, :sides=>6, :multiplier=>1, :maps=>[ [8,:<=,1] ], :rerolls=>[ [6,:==,:reroll_add] ] }], :offset => 0 },
+      }
+
+      variations.each do |input,expected_output|
+        parser.parse( input ).should ==  expected_output
+      end
+    end
+
   end # describe "#parse"
 end

data/spec/probability_spec.rb

@@ -35,7 +35,7 @@ RSpec::Matchers.define :be_valid_distribution do
   end
 
   description do |given|
-    "a hash describing a complete discrete probability distribution of integers"
+    "a hash describing a complete probability distribution of integer results"
   end
 end
 

data/spec/readme_spec.rb

@@ -0,0 +1,96 @@
+require 'games_dice'
+# This spec demonstrates that documentation from the README.md works as intended
+
+# Test helper class, a stub of a PRNG
+class TestPRNG
+  def initialize
+    @numbers = [0.123,0.234,0.345,0.999,0.876,0.765,0.543,0.111,0.333,0.777]
+  end
+  def rand(n)
+    Integer( n * @numbers.pop )
+  end
+end
+
+describe GamesDice do
+
+  describe '#create' do
+    it "converts a string such as '3d6+6' into a GamesDice::Dice object" do
+      d = GamesDice.create '3d6+6'
+      d.is_a?( GamesDice::Dice ).should be_true
+    end
+
+    it "takes a parameter 'dice_description', which is a string such as '3d6' or '2d4-1'" do
+      d = GamesDice.create '3d6'
+      d.is_a?( GamesDice::Dice ).should be_true
+      d = GamesDice.create '2d4-1'
+      d.is_a?( GamesDice::Dice ).should be_true
+    end
+
+    it "takes an optional parameter 'prng', which if provided it should be an object that has a method 'rand( integer )'" do
+      prng = TestPRNG.new
+      d = GamesDice.create '3d6', prng
+      d.is_a?( GamesDice::Dice ).should be_true
+    end
+  end # describe '#create'
+
+end # describe GamesDice
+
+describe GamesDice::Dice do
+
+  before :each do
+    srand(67809)
+  end
+
+  let(:dice) { GamesDice.create '3d6'}
+
+  describe "#roll" do
+    it "simulates rolling the dice as they were described in the constructor" do
+      expected_results = [11,15,11,12,12,9]
+      expected_results.each do |expected|
+        dice.roll.should == expected
+      end
+    end
+  end
+
+  describe "#result" do
+    it "returns the value from the last call to roll" do
+      expected_results = [11,15,11,12,12,9]
+      expected_results.each do |expected|
+        dice.roll
+        dice.result.should == expected
+      end
+    end
+
+    it "will be nil if no roll has been made yet" do
+      dice.result.should be_nil
+    end
+  end
+
+  describe "#max" do
+    it "returns the maximum possible value from a roll of the dice" do
+      dice.max.should == 18
+    end
+  end
+
+  describe "#min" do
+    it "returns the minimum possible value from a roll of the dice" do
+      dice.min.should == 3
+    end
+  end
+
+  describe "#minmax" do
+    it "returns an array [ dice.min, dice.max ]" do
+      dice.minmax.should == [3,18]
+    end
+  end
+
+  describe "#probabilities" do
+    it "calculates probability distribution for the dice" do
+      pd = dice.probabilities
+      pd.is_a?( GamesDice::Probabilities ).should be_true
+      pd.p_eql( 3).should be_within(1e-10).of 1.0/216
+      pd.p_eql( 11 ).should be_within(1e-10).of 27.0/216
+    end
+  end
+
+end # describe GamesDice::Dice

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: games_dice
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-13 00:00:00.000000000 Z
+date: 2013-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -94,6 +94,7 @@ files:
 - spec/map_rule_spec.rb
 - spec/parser_spec.rb
 - spec/probability_spec.rb
+- spec/readme_spec.rb
 - spec/reroll_rule_spec.rb
 - travis.yml
 homepage: https://github.com/neilslater/games_dice
@@ -110,7 +111,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 384639309274746311
+      hash: 514639472622102988
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -119,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 384639309274746311
+      hash: 514639472622102988
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -135,4 +136,5 @@ test_files:
 - spec/map_rule_spec.rb
 - spec/parser_spec.rb
 - spec/probability_spec.rb
+- spec/readme_spec.rb
 - spec/reroll_rule_spec.rb