games_dice 0.2.0 → 0.2.1

data/.travis.yml

@@ -3,8 +3,8 @@ rvm:
   - "1.8.7"
   - "1.9.3"
   - "2.0.0"
-  - jruby-18mode # JRuby in 1.8 mode
-  - jruby-19mode # JRuby in 1.9 mode
   - rbx-18mode
   - rbx-19mode
+  - ruby-head
+  - ree
 

data/Rakefile

@@ -1,5 +1,6 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "yard"
 
 task :default => [:test]
 
@@ -8,3 +9,7 @@ RSpec::Core::RakeTask.new(:test) do |t|
   t.pattern = "spec/*_spec.rb"
   t.verbose = false
 end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end

data/games_dice.gemspec

@@ -16,8 +16,10 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency "rspec", ">= 2.13.0"
   gem.add_development_dependency "rake", ">= 1.9.1"
+  gem.add_development_dependency "yard", ">= 0.8.6"
+  gem.add_development_dependency "redcarpet", ">=2.3.0"
 
-  gem.add_dependency "parslet", "~> 1.5.0"
+  gem.add_dependency "parslet", ">= 1.5.0"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

data/lib/games_dice.rb

@@ -11,6 +11,7 @@ require "games_dice/dice"
 require "games_dice/parser"
 
 module GamesDice
+  # @!visibility private
   @@parser = GamesDice::Parser.new
 
   def self.create dice_description, prng = nil

data/lib/games_dice/complex_die.rb

@@ -1,59 +1,82 @@
-# complex die that rolls 1..N, and may re-roll and adjust final value based on
-# parameters it is instantiated with
-#  d = GamesDice::DieExploding.new( 6, :explode_up => true ) # 'exploding' die
-#  d.roll # => GamesDice::DieResult of rolling die
-#  d.result # => same GamesDice::DieResult as returned by d.roll
+# This class models a die that is built up from a simpler unit by adding rules to re-roll
+# and interpret the value shown.
+#
+# An object of this class represents a single complex die. It rolls 1..#sides, with equal weighting
+# for each value. The value from a roll may be used to trigger yet more rolls that combine together.
+# After any re-rolls, the value can be interpretted ("mapped") as another integer, which is used as
+# the final result.
+#
+# @example An open-ended percentile die from a popular RPG
+#  d = GamesDice::ComplexDie.new( 100, :rerolls => [[96, :<=, :reroll_add],[5, :>=, :reroll_subtract]] )
+#  d.roll # => #<GamesDice::DieResult:0x007ff03a2415f8 @rolls=[4, 27], ...>
+#  d.result.value # => -23
+#  d.explain_result # => "[4-27] -23"
+#
+# @example An "exploding" six-sided die with a target number
+#  d = GamesDice::ComplexDie.new( 6, :rerolls => [[6, :<=, :reroll_add]], :maps => [[8, :<=, 1, 'Success']] )
+#  d.roll # => #<GamesDice::DieResult:0x007ff03a1e8e08 @rolls=[6, 5], ...>
+#  d.result.value # => 1
+#  d.explain_result # => "[6+5] 11 Success"
+#
+
 class GamesDice::ComplexDie
 
-  # arbitrary limit to simplify calculations and stay in Integer range for convenience. It should
-  # be much larger than anything seen in real-world tabletop games.
+  # @!visibility private
+  # arbitrary limit to speed up probability calculations. It should
+  # be larger than anything seen in real-world tabletop games.
   MAX_REROLLS = 1000
 
-  # sides is e.g. 6 for traditional cubic die, or 20 for icosahedron.
-  # It can take non-traditional values, such as 7, but must be at least 1.
-  #
-  # options_hash may contain keys setting following attributes
-  #  :rerolls => an array of rules that cause the die to roll again, see #rerolls
-  #  :maps => an array of rules to convert a value into a final result for the die, see #maps
-  #  :prng => any object that has a rand(x) method, which will be used instead of internal rand()
-  def initialize(sides, options_hash = {})
-    @basic_die = GamesDice::Die.new(sides, options_hash[:prng])
+  # Creates new instance of GamesDice::ComplexDie
+  # @param [Integer] sides Number of sides on a single die, passed to GamesDice::Die's constructor
+  # @param [Hash] options
+  # @option options [Array<GamesDice::RerollRule,Array>] :rerolls The rules that cause the die to roll again
+  # @option options [Array<GamesDice::MapRule,Array>] :maps The rules to convert a value into a final result for the die
+  # @option options [#rand] :prng An alternative source of randomness to Ruby's built-in #rand, passed to GamesDice::Die's constructor
+  # @return [GamesDice::ComplexDie]
+  def initialize( sides, options = {} )
+    @basic_die = GamesDice::Die.new(sides, options[:prng])
 
-    @rerolls = construct_rerolls( options_hash[:rerolls] )
-    @maps = construct_maps( options_hash[:maps] )
+    @rerolls = construct_rerolls( options[:rerolls] )
+    @maps = construct_maps( options[:maps] )
 
     @total = nil
     @result = nil
   end
 
-  # underlying GamesDice::Die object, used to generate all individual rolls
+  # The simple component used by this complex one
+  # @return [GamesDice::Die] Object used to make individual dice rolls for the complex die
   attr_reader :basic_die
 
-  # may be nil, in which case no re-rolls are triggered, or an array of GamesDice::RerollRule objects
+  # @return [Array<GamesDice::RerollRule>, nil] Sequence of re-roll rules, or nil if re-rolls are not required.
   attr_reader :rerolls
 
-  # may be nil, in which case no mappings apply, or an array of GamesDice::MapRule objects
+  # @return [Array<GamesDice::MapRule>, nil] Sequence of map rules, or nil if mapping is not required.
   attr_reader :maps
 
-  # result of last call to #roll, nil if no call made yet
+  # @return [GamesDice::DieResult, nil] Result of last call to #roll, nil if no call made yet
   attr_reader :result
 
-  # true if probability calculation did not hit any limitations, so has covered all possible scenarios
-  # false if calculation was cut short and probabilities are an approximation
-  # nil if probabilities have not been calculated yet
+  # Whether or not #probabilities includes all possible outcomes.
+  # True if all possible results are represented and assigned a probability. Dice with open-ended re-rolls
+  # may have calculations cut short, and will result in a false value of this attribute. Even when this
+  # attribute is false, probabilities should still be accurate to nearest 1e-9.
+  # @return [Boolean, nil] Depending on completeness when generating #probabilites
   attr_reader :probabilities_complete
 
-  # number of sides, same as #basic_die.sides
+  # @!attribute [r] sides
+  # @return [Integer] Number of sides.
   def sides
     @basic_die.sides
   end
 
-  # string explanation of roll, including any re-rolls etc, same as #result.explain_value
+  # @!attribute [r] explain_result
+  # @return [String,nil] Explanation of result, or nil if no call to #roll yet.
   def explain_result
     @result.explain_value
   end
 
-  # minimum possible value
+  # @!attribute [r] min
+  # @return [Integer] Minimum possible result from a call to #roll
   def min
     return @min_result if @min_result
     @min_result, @max_result = [probabilities.min, probabilities.max]
@@ -63,8 +86,8 @@ class GamesDice::ComplexDie
     @min_result
   end
 
-  # maximum possible value. A ComplexDie with open-ended additive re-rolls will calculate roughly 1001 times the
-  # maximum of #basic_die.max (although the true value is infinite)
+  # @!attribute [r] max
+  # @return [Integer] Maximum possible result from a call to #roll
   def max
     return @max_result if @max_result
     @min_result, @max_result = [probabilities.min, probabilities.max]
@@ -74,9 +97,10 @@ class GamesDice::ComplexDie
     @max_result
   end
 
-  # returns a hash of value (Integer) => probability (Float) pairs. For efficiency with re-rolls, the calculation may cut
-  # short based on depth of recursion or closeness to total 1.0 probability. Therefore low probabilities
-  # (less than one in a billion) in open-ended re-rolls are not always represented in the hash.
+  # Calculates the probability distribution for the die. For open-ended re-roll rules, there are some
+  # arbitrary limits imposed to prevent large amounts of recursion. Probabilities should be to nearest
+  # 1e-9 at worst.
+  # @return [GamesDice::Probabilities] Probability distribution of die.
   def probabilities
     return @probabilities if @probabilities
     @probabilities_complete = true
@@ -106,8 +130,9 @@ class GamesDice::ComplexDie
     @probabilities = GamesDice::Probabilities.new( prob_hash )
   end
 
-  # generates Integer between #min and #max, using rand()
-  # first roll reason can be over-ridden, required for re-roll types that spawn new dice
+  # Simulates rolling the die
+  # @param [Symbol] reason Assign a reason for rolling the first die.
+  # @return [GamesDice::DieResult] Detailed results from rolling the die, including resolution of rules.
   def roll( reason = :basic )
     # Important bit - actually roll the die
     @result = GamesDice::DieResult.new( @basic_die.roll, reason )

data/lib/games_dice/die.rb

@@ -1,12 +1,28 @@
-# basic die that rolls 1..N, typically with equal weighting for each value
-#  d = Die.new(6)
+# This class models the simplest, most-familiar kind of die.
+#
+# An object of the class represents a basic die that rolls 1..#sides, with equal weighting for each value.
+#
+# @example Create a 6-sided die, and roll it
+#  d = GamesDice::Die.new( 6 )
 #  d.roll # => Integer in range 1..6
-#  d.result # => same Integer value as returned by d.roll
+#  d.result # => same Integer value as just returned by d.roll
+#
+# @example Create a 10-sided die, that rolls using a monkey-patch to SecureRandom
+#  module SecureRandom
+#    def self.rand n
+#      random_number( n )
+#    end
+#  end
+#  d = GamesDice::Die.new( 10, SecureRandom )
+#  d.roll # => (secure) Integer in range 1..10
+#  d.result # => same Integer value as just returned by d.roll
+
 class GamesDice::Die
-  # sides is e.g. 6 for traditional cubic die, or 20 for icosahedron.
-  # It can take non-traditional values, such as 7, but must be at least 1.
-  # prng is an object that has a rand(x) method. If provided, it will be called as
-  # prng.rand(sides), and is expected to return an integer in range 0...sides
+
+  # Creates new instance of GamesDice::Die
+  # @param [Integer] sides the number of sides
+  # @param [#rand] prng random number generator, GamesDice::Die will use Ruby's built-in #rand() by default
+  # @return [GamesDice::Die]
   def initialize( sides, prng=nil )
     @sides = Integer(sides)
     raise ArgumentError, "sides value #{sides} is too low, it must be 1 or greater" if @sides < 1
@@ -15,29 +31,36 @@ class GamesDice::Die
     @result = nil
   end
 
-  # number of sides as set by #new
+  # @return [Integer] number of sides on simulated die
   attr_reader :sides
 
-  # integer result of last call to #roll, nil if no call made yet
+  # @return [Integer] result of last call to #roll, nil if no call made yet
   attr_reader :result
 
-  # minimum possible value
+  # @return [Object] random number generator as supplied to constructor, may be nil
+  attr_reader :prng
+
+  # @!attribute [r] min
+  # @return [Integer] minimum possible result from a call to #roll
   def min
     1
   end
 
-  # maximum possible value
+  # @!attribute [r] max
+  # @return [Integer] maximum possible result from a call to #roll
   def max
     @sides
   end
 
-  # returns a GamesDice::Probabilities object that models distribution of the die
+  # Calculates probability distribution for this die.
+  # @return [GamesDice::Probabilities] probability distribution of the die
   def probabilities
     return @probabilities if @probabilities
     @probabilities = GamesDice::Probabilities.for_fair_die( @sides )
   end
 
-  # generates Integer between #min and #max, using rand()
+  # Simulates rolling the die
+  # @return [Integer] selected value between 1 and #sides inclusive
   def roll
     if @prng
       @result = @prng.rand(@sides) + 1
@@ -46,13 +69,17 @@ class GamesDice::Die
     end
   end
 
-  # always nil, available for compatibility with ComplexDie
+  # @!attribute [r] rerolls
+  # Rules for when to re-roll this die.
+  # @return [nil] always nil, available for interface equivalence with GamesDice::ComplexDie
   def rerolls
     nil
   end
 
-  # always nil, available for compatibility with ComplexDie
+  # @!attribute [r] maps
+  # Rules for when to map return value of this die.
+  # @return [nil] always nil, available for interface equivalence with GamesDice::ComplexDie
   def maps
     nil
   end
-end # class Die
+end # class GamesDice::Die

data/lib/games_dice/version.rb

@@ -1,3 +1,3 @@
 module GamesDice
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/spec/die_spec.rb

@@ -46,8 +46,10 @@ describe GamesDice::Die do
   describe "#probabilities" do
     it "should return the die's probability distribution as a GamesDice::Probabilities object" do
       die = GamesDice::Die.new(6)
-      die.probabilities.is_a?( GamesDice::Probabilities ).should be_true
       probs = die.probabilities
+      probs.is_a?( GamesDice::Probabilities ).should be_true
+
+      probs.to_h.should be_valid_distribution
 
       probs.p_eql(1).should be_within(1e-10).of 1/6.0
       probs.p_eql(2).should be_within(1e-10).of 1/6.0
@@ -55,23 +57,6 @@ describe GamesDice::Die do
       probs.p_eql(4).should be_within(1e-10).of 1/6.0
       probs.p_eql(5).should be_within(1e-10).of 1/6.0
       probs.p_eql(6).should be_within(1e-10).of 1/6.0
-      probs.to_h.values.inject(:+).should be_within(1e-9).of 1.0
-
-      probs.p_gt(6).should == 0.0
-      probs.p_gt(-20).should == 1.0
-      probs.p_gt(4).should be_within(1e-10).of 2/6.0
-
-      probs.p_ge(20).should == 0.0
-      probs.p_ge(1).should == 1.0
-      probs.p_ge(4).should be_within(1e-10).of 0.5
-
-      probs.p_le(6).should == 1.0
-      probs.p_le(-3).should == 0.0
-      probs.p_le(5).should be_within(1e-10).of 5/6.0
-
-      probs.p_lt(7).should == 1.0
-      probs.p_lt(1).should == 0.0
-      probs.p_lt(3).should be_within(1e-10).of 2/6.0
 
       probs.expected.should be_within(1e-10).of 3.5
     end

data/spec/helpers.rb

@@ -1,5 +1,6 @@
 # games_dice/spec/helpers.rb
 
+# TestPRNG tests short predictable series
 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]
@@ -9,6 +10,20 @@ class TestPRNG
   end
 end
 
+# TestPRNGMax checks behaviour of re-rolls
+class TestPRNGMax
+  def rand(n)
+    Integer( n ) - 1
+  end
+end
+
+# TestPRNGMax checks behaviour of re-rolls
+class TestPRNGMin
+  def rand(n)
+    1
+  end
+end
+
 # A valid distribution is:
 #  A hash
 #  Keys are all Integers

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: games_dice
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-30 00:00:00.000000000 Z
+date: 2013-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -43,12 +43,44 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 1.9.1
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.3.0
 - !ruby/object:Gem::Dependency
   name: parslet
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 1.5.0
   type: :runtime
@@ -56,7 +88,7 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 1.5.0
 description: ! "A simulated-dice library, with flexible rules that allow dice systems
@@ -112,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4046591063539756555
+      hash: -3596350699515982404
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -121,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4046591063539756555
+      hash: -3596350699515982404
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -141,3 +173,4 @@ test_files:
 - spec/probability_spec.rb
 - spec/readme_spec.rb
 - spec/reroll_rule_spec.rb
+has_rdoc: