games_dice 0.0.1 → 0.0.2

data/lib/games_dice.rb

@@ -1,5 +1,6 @@
 require "games_dice/version"
 require "games_dice/die"
+require "games_dice/die_result"
 
 module GamesDice
   # TODO: Factory methods for various dice schemes

data/lib/games_dice/die_result.rb

@@ -0,0 +1,162 @@
+# returned by any complex die roll (i.e. one that may be subject to re-rolls or adjustments to each die)
+#  dr = GamesDice::DieResult.new
+#  dr.add_roll(5)
+#  dr.add_roll(4,:reroll_add)
+#  dr.value # => 9
+#  dr.rolls # => [5,4]
+#  dr.roll_reasons # => [:basic,:reroll_add]
+#  dr + 5 # => 14
+# As the last example implies, GamesDice::DieResult objects coerce to the #value attribute
+class GamesDice::DieResult
+  include Comparable
+
+  # allowed reasons for making a roll, and symbol to use before number in #explain
+  REASONS = {
+    :basic => ',',
+    :reroll_add => '+',
+    :reroll_new_die => '*', # TODO: This needs to be flagged *before* value, and maybe linked to cause
+    :reroll_new_keeper => '*',
+    :reroll_subtract => '-',
+    :reroll_replace => '|',
+    :reroll_use_best => '/',
+    :reroll_use_worst => '\\',
+  }
+
+  # first_roll_result is optional value of first roll of the die
+  def initialize( first_roll_result=nil, first_roll_reason=:basic )
+    unless REASONS.has_key?(first_roll_reason)
+      raise ArgumentError, "Unrecognised reason for roll #{first_roll_reason}"
+    end
+
+    if (first_roll_result)
+      @rolls = [Integer(first_roll_result)]
+      @roll_reasons = [first_roll_reason]
+      @total = @rolls[0]
+    else
+      @rolls = []
+      @roll_reasons = []
+      @total = nil
+    end
+    @mapped = false
+    @value = @total
+  end
+
+  public
+
+  # array of integers
+  attr_reader :rolls
+
+  # array of symbol reasons for making roll
+  attr_reader :roll_reasons
+
+  # combined numeric value of all rolls, nil if nothing calculated yet. Often the same number as
+  # #result, but may be different if there has been a call to #apply_map
+  attr_reader :total
+
+  # overall result of applying all rolls, nil if nothing calculated yet
+  attr_reader :value
+
+  # true if #apply_map has been called, and no more roll results added since
+  attr_reader :mapped
+
+  # stores the value of a simple die roll. roll_result should be an Integer,
+  # roll_reason is an optional symbol description of why the roll was made
+  # #total and #value are calculated based on roll_reason
+  def add_roll( roll_result, roll_reason=:basic )
+    unless REASONS.has_key?(roll_reason)
+      raise ArgumentError, "Unrecognised reason for roll #{roll_reason}"
+    end
+    @rolls << Integer(roll_result)
+    @roll_reasons << roll_reason
+    if @rolls.length == 1
+      @total = 0
+    end
+
+    case roll_reason
+    when :basic
+      @total = roll_result
+    when :reroll_add
+      @total += roll_result
+    when :reroll_subtract
+      @total -= roll_result
+    when :reroll_new_die
+      @total = roll_result
+    when :reroll_new_keeper
+      @total = roll_result
+    when :reroll_replace
+      @total = roll_result
+    when :reroll_use_best
+      @total = [@value,roll_result].max
+    when :reroll_use_worst
+      @total = [@value,roll_result].min
+    end
+
+    @mapped = false
+    @value = @total
+  end
+
+  # sets #value arbitrarily intended for use by GamesDice::MapRule objects
+  def apply_map( to_value, description = '' )
+    @mapped = true
+    @value = to_value
+    @map_description = description
+  end
+
+  # returns a string summary of how #value was obtained, showing all contributing rolls
+  def explain_value
+    text = ''
+    if @rolls.length < 2
+      text = @total.to_s
+    else
+      text = '[' + @rolls[0].to_s
+      text = (1..@rolls.length-1).inject( text ) { |so_far,i| so_far + REASONS[@roll_reasons[i]] + @rolls[i].to_s }
+      text += '] ' + @total.to_s
+    end
+    text += ' ' + @map_description if @mapped && @map_description && @map_description.length > 0
+    return text
+  end
+
+  # returns a string summary of the #total, including effect of any maps that been applied
+  def explain_total
+    text = @total.to_s
+    text += ' ' + @map_description if @mapped && @map_description && @map_description.length > 0
+    return text
+  end
+
+  # all coercions simply use #value (i.e. nil or a Fixnum)
+  def coerce(thing)
+    @value.coerce(thing)
+  end
+
+  # addition uses #value
+  def +(thing)
+    @value + thing
+  end
+
+  # subtraction uses #value
+  def -(thing)
+    @value - thing
+  end
+
+  # multiplication uses #value
+  def *(thing)
+    @value * thing
+  end
+
+  # comparison <=> uses #value
+  def <=>(other)
+    self.value <=> other
+  end
+
+  # implements a deep clone (used for recursive probability calculations)
+  def clone
+    cloned = GamesDice::DieResult.new()
+    cloned.instance_variable_set('@rolls', @rolls.clone)
+    cloned.instance_variable_set('@roll_reasons', @roll_reasons.clone)
+    cloned.instance_variable_set('@total', @total)
+    cloned.instance_variable_set('@value', @value)
+    cloned.instance_variable_set('@mapped', @mapped)
+    cloned.instance_variable_set('@map_description', @map_description)
+    cloned
+  end
+end

data/lib/games_dice/version.rb

@@ -1,3 +1,3 @@
 module GamesDice
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/die_result_spec.rb

@@ -0,0 +1,261 @@
+require 'games_dice'
+
+describe GamesDice::DieResult do
+
+  describe ".new" do
+
+    it "should work without parameters to represent 'no results yet'" do
+      die_result = GamesDice::DieResult.new()
+      die_result.value.should == nil
+      die_result.rolls.should == []
+      die_result.roll_reasons.should == []
+    end
+
+    it "should work with a single Integer param to represent an initial result" do
+      die_result = GamesDice::DieResult.new(8)
+      die_result.value.should == 8
+      die_result.rolls.should == [8]
+      die_result.roll_reasons.should == [:basic]
+    end
+
+    it "should not accept a param that cannot be coerced to Integer" do
+      lambda { GamesDice::DieResult.new([]) }.should raise_error( TypeError )
+      lambda { GamesDice::DieResult.new('N') }.should raise_error( ArgumentError )
+    end
+
+    it "should not accept unknown reasons for making a roll" do
+      lambda { GamesDice::DieResult.new(8,'wooo') }.should raise_error( ArgumentError )
+      lambda { GamesDice::DieResult.new(8,:frabulous) }.should raise_error( ArgumentError )
+    end
+
+  end
+
+  describe "#add_roll" do
+
+    context "starting from 'no results yet'" do
+      let(:die_result) { GamesDice::DieResult.new() }
+
+      it "should create an initial result" do
+        die_result.add_roll(5)
+        die_result.value.should == 5
+        die_result.rolls.should == [5]
+        die_result.roll_reasons.should == [:basic]
+      end
+
+      it "should accept non-basic reasons for the first roll" do
+        die_result.add_roll(4,:reroll_subtract)
+        die_result.value.should == -4
+        die_result.rolls.should == [4]
+        die_result.roll_reasons.should == [:reroll_subtract]
+      end
+
+      it "should not accept a first param that cannot be coerced to Integer" do
+        lambda { die_result.add_roll([]) }.should raise_error( TypeError )
+        lambda { die_result.add_roll('N') }.should raise_error( ArgumentError )
+      end
+
+      it "should not accept an unsupported second param" do
+        lambda { die_result.add_roll(5,[]) }.should raise_error( ArgumentError )
+        lambda { die_result.add_roll(15,:bam) }.should raise_error( ArgumentError )
+      end
+
+    end
+
+    context "starting with an initial result" do
+      let(:die_result) { GamesDice::DieResult.new(7) }
+
+      it "should not accept a first param that cannot be coerced to Integer" do
+        lambda { die_result.add_roll([]) }.should raise_error( TypeError )
+        lambda { die_result.add_roll('N') }.should raise_error( ArgumentError )
+      end
+
+      it "should not accept an unsupported second param" do
+        lambda { die_result.add_roll(5,[]) }.should raise_error( ArgumentError )
+        lambda { die_result.add_roll(15,:bam) }.should raise_error( ArgumentError )
+      end
+
+      context "add another basic roll" do
+        it "should replace an initial result, as if the die were re-rolled" do
+          die_result.add_roll(5)
+          die_result.value.should == 5
+          die_result.rolls.should == [7,5]
+          die_result.roll_reasons.should == [:basic, :basic]
+        end
+      end
+
+      context "exploding dice" do
+        it "should add to value when exploding up" do
+          die_result.add_roll( 6, :reroll_add )
+          die_result.value.should == 13
+          die_result.rolls.should == [7,6]
+          die_result.roll_reasons.should == [:basic, :reroll_add]
+        end
+
+        it "should subtract from value when exploding down" do
+          die_result.add_roll( 4, :reroll_subtract )
+          die_result.value.should == 3
+          die_result.rolls.should == [7,4]
+          die_result.roll_reasons.should == [:basic, :reroll_subtract]
+        end
+      end
+
+      context "re-roll dice" do
+        it "should optionally replace roll unconditionally" do
+          die_result.add_roll( 2, :reroll_replace )
+          die_result.value.should == 2
+          die_result.rolls.should == [7,2]
+          die_result.roll_reasons.should == [:basic, :reroll_replace]
+
+          die_result.add_roll( 5, :reroll_replace )
+          die_result.value.should == 5
+          die_result.rolls.should == [7,2,5]
+          die_result.roll_reasons.should == [:basic, :reroll_replace, :reroll_replace]
+        end
+
+        it "should optionally use best roll" do
+          die_result.add_roll( 2, :reroll_use_best )
+          die_result.value.should == 7
+          die_result.rolls.should == [7,2]
+          die_result.roll_reasons.should == [:basic, :reroll_use_best]
+
+          die_result.add_roll( 9, :reroll_use_best )
+          die_result.value.should == 9
+          die_result.rolls.should == [7,2,9]
+          die_result.roll_reasons.should == [:basic, :reroll_use_best, :reroll_use_best]
+        end
+
+        it "should optionally use worst roll" do
+          die_result.add_roll( 4, :reroll_use_worst )
+          die_result.value.should == 4
+          die_result.rolls.should == [7,4]
+          die_result.roll_reasons.should == [:basic, :reroll_use_worst]
+
+          die_result.add_roll( 5, :reroll_use_worst )
+          die_result.value.should == 4
+          die_result.rolls.should == [7,4,5]
+          die_result.roll_reasons.should == [:basic, :reroll_use_worst, :reroll_use_worst]
+        end
+      end
+
+      context "combinations of reroll reasons" do
+        it "should correctly handle valid reasons for extra rolls in combination" do
+          die_result.add_roll( 10, :reroll_add )
+          die_result.add_roll( 3, :reroll_subtract)
+          die_result.value.should == 14
+          die_result.rolls.should == [7,10,3]
+          die_result.roll_reasons.should == [:basic, :reroll_add, :reroll_subtract]
+
+          die_result.add_roll( 12, :reroll_replace )
+          die_result.value.should == 12
+          die_result.rolls.should == [7,10,3,12]
+          die_result.roll_reasons.should == [:basic, :reroll_add, :reroll_subtract, :reroll_replace]
+
+          die_result.add_roll( 9, :reroll_use_best )
+          die_result.value.should == 12
+          die_result.rolls.should == [7,10,3,12,9]
+          die_result.roll_reasons.should == [:basic, :reroll_add, :reroll_subtract, :reroll_replace, :reroll_use_best]
+
+          die_result.add_roll( 15, :reroll_add)
+          die_result.value.should == 27
+          die_result.rolls.should == [7,10,3,12,9,15]
+          die_result.roll_reasons.should == [:basic, :reroll_add, :reroll_subtract, :reroll_replace, :reroll_use_best, :reroll_add]
+        end
+      end
+
+    end
+
+  end
+
+  describe "#explain_value" do
+    let(:die_result) { GamesDice::DieResult.new() }
+
+    it "should be empty string for 'no results yet'" do
+      die_result.explain_value.should == ''
+    end
+
+    it "should be a simple stringified number when there is one die roll" do
+      die_result.add_roll(3)
+      die_result.explain_value.should == '3'
+    end
+
+    it "should describe all single rolls made and how they combine" do
+      die_result.add_roll(6)
+      die_result.explain_value.should == '6'
+
+      die_result.add_roll(5,:reroll_add)
+      die_result.explain_value.should == '[6+5] 11'
+
+      die_result.add_roll(2,:reroll_replace)
+      die_result.explain_value.should == '[6+5|2] 2'
+
+      die_result.add_roll(7,:reroll_subtract)
+      die_result.explain_value.should == '[6+5|2-7] -5'
+
+      die_result.add_roll(4,:reroll_use_worst)
+      die_result.explain_value.should == '[6+5|2-7\\4] -5'
+
+      die_result.add_roll(3,:reroll_use_best)
+      die_result.explain_value.should == '[6+5|2-7\\4/3] 3'
+
+    end
+
+  end
+
+  it "should combine via +,- and * intuitively based on #value" do
+    die_result = GamesDice::DieResult.new(7)
+    (die_result + 3).should == 10
+    (4 + die_result).should == 11
+    (die_result - 2).should == 5
+    (9 - die_result).should == 2
+
+    (die_result + 7.7).should == 14.7
+    (4.1 + die_result).should == 11.1
+
+    (die_result * 2).should == 14
+    (1 * die_result).should == 7
+
+    other_die_result = GamesDice::DieResult.new(6)
+    other_die_result.add_roll(6,:reroll_add)
+    (die_result + other_die_result).should == 19
+    (other_die_result - die_result).should == 5
+  end
+
+  it "should support comparison with >,<,>=,<= as if it were an integer, based on #value" do
+    die_result = GamesDice::DieResult.new(7)
+
+    (die_result > 3).should be_true
+    (14 > die_result).should be_true
+    (die_result >= 7).should be_true
+    (9.5 >= die_result).should be_true
+    (die_result < 3).should be_false
+    (14 < die_result).should be_false
+    (die_result <= 8).should be_true
+    (14 <= die_result).should be_false
+
+    other_die_result = GamesDice::DieResult.new(6)
+    other_die_result.add_roll(6,:reroll_add)
+    (die_result > other_die_result).should be_false
+    (other_die_result > die_result).should be_true
+    (die_result >= other_die_result).should be_false
+    (other_die_result >= die_result).should be_true
+    (die_result < other_die_result).should be_true
+    (other_die_result < die_result).should be_false
+    (die_result <= other_die_result).should be_true
+    (other_die_result <= die_result).should be_false
+
+  end
+
+  it "should sort, based on #value" do
+    die_results = [
+      GamesDice::DieResult.new(7), GamesDice::DieResult.new(5), GamesDice::DieResult.new(8), GamesDice::DieResult.new(3)
+    ]
+
+    die_results.sort!
+
+    die_results[0].value.should == 3
+    die_results[1].value.should == 5
+    die_results[2].value.should == 7
+    die_results[3].value.should == 8
+  end
+
+end

data/spec/die_spec.rb

@@ -1,4 +1,4 @@
-require 'games_dice/die'
+require 'games_dice'
 
 # Test helper class, a stub of a PRNG
 class TestPRNG

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: games_dice
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-08 00:00:00.000000000 Z
+date: 2013-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -44,7 +44,9 @@ files:
 - games_dice.gemspec
 - lib/games_dice.rb
 - lib/games_dice/die.rb
+- lib/games_dice/die_result.rb
 - lib/games_dice/version.rb
+- spec/die_result_spec.rb
 - spec/die_spec.rb
 homepage: ''
 licenses: []
@@ -71,5 +73,6 @@ signing_key:
 specification_version: 3
 summary: Simulates and explains dice rolls from a variety of game systems.
 test_files:
+- spec/die_result_spec.rb
 - spec/die_spec.rb
 has_rdoc: