games_dice 0.2.1 → 0.2.2

data/lib/games_dice.rb

@@ -14,6 +14,11 @@ module GamesDice
   # @!visibility private
   @@parser = GamesDice::Parser.new
 
+  # Creates an instance of GamesDice::Dice from a string description.
+  # @param [String] dice_description Uses a variation of common game notation, examples: '1d6', '3d8+1d4+7', '5d10k2'
+  # @param [#rand] prng Optional random number generator, default is to use Ruby's built-in #rand()
+  # @return [GamesDice::Dice] A new dice object.
+  #
   def self.create dice_description, prng = nil
     parsed = @@parser.parse( dice_description )
     GamesDice::Dice.new( parsed[:bunches], parsed[:offset], prng )

data/lib/games_dice/constants.rb

@@ -1,6 +1,6 @@
 module GamesDice
 
-  # reasons for making a reroll, and text explanation symbols for them
+  # Reasons for making a reroll, and text explanation symbols for them
   REROLL_TYPES = {
     :basic => ',',
     :reroll_add => '+',

data/lib/games_dice/map_rule.rb

@@ -1,8 +1,32 @@
-# helps model complex dice systems such as "count number of dice showing X or more"
+# This class models rules that convert numbers shown on a die to values used in a game. A
+# common use for this is to count "successes" - dice that score a certain number or higher.
+#
+# An object of the class represents a single rule, such as "count a die result of 5 or more as 1
+# _success_".
+#
+# @example A rule for counting successes
+#  rule = GamesDice::MapRule.new( 6, :<=, 1, 'Success' )
+#  # Test how the rule applies . . .
+#  rule.map_from 4   # => nil
+#  rule.map_from 6   # => 1
+#
+# @example A rule for counting "fumbles" which reduce total successes
+#  rule = GamesDice::MapRule.new( 1, :==, -1, 'Fumble' )
+#  # Test how the rule applies . . .
+#  rule.map_from 7   # => nil
+#  rule.map_from 1   # => -1
+#
+
 class GamesDice::MapRule
 
-  # trigger_op, trigger_value, mapped_value and mapped_name set the attributes of the same name
-  #  rule = RPGMapRule.new( 6, :<=, 1, 'Success' ) # score 1 for a result of 6 or more
+  # Creates new instance of GamesDice::MapRule. The rule will be assessed as
+  #   trigger_value.send( trigger_op, x )
+  # where x is the Integer value shown on a die.
+  # @param [Integer,Range<Integer>,Object] trigger_value Any object is allowed, but typically an Integer
+  # @param [Symbol] trigger_op A method of trigger_value that takes an Integer param and returns Boolean
+  # @param [Integer] mapped_value The value to use in place of the trigger value
+  # @param [String] mapped_name Name of mapped value, for use in descriptions
+  # @return [GamesDice::MapRule]
   def initialize trigger_value, trigger_op, mapped_value=0, mapped_name=''
 
     if ! trigger_value.respond_to?( trigger_op )
@@ -16,23 +40,25 @@ class GamesDice::MapRule
     @mapped_name = mapped_name.to_s
   end
 
-  # an Integer value or Range that will be mapped to a single value. #trigger_op is called against it
-  attr_reader :trigger_value
-
-  # a valid symbol for a method, which will be called against #trigger_value with the current
-  # die result as a param. If the operator returns true for a specific die result, then the
-  # mapped_value will be used in its stead. If the operator returns nil or false, the map is not
-  # triggered. All other values will be returned as the result of the map (allowing you to
-  # specify any method that takes an integer as input and returns something else as the end result)
+  # Trigger operation. How the rule is assessed against #trigger_value.
+  # @return [Symbol] Method name to be sent to #trigger_value
   attr_reader :trigger_op
 
-  # an integer value
+  # Trigger value. An object that will use #trigger_op to assess a die result for a reroll.
+  # @return [Integer,Range,Object] Object that receives (#trigger_op, die_result)
+  attr_reader :trigger_value
+
+  # Mapped value.
+  # @return [Integer]
   attr_reader :mapped_value
 
-  # a string description of the mapping, e.g. 'S' for a success
+  # Name for mapped value.
+  # @return [String]
   attr_reader :mapped_name
 
-  # runs the rule against test_value, returning either a new value, or nil if the rule does not apply
+  # Assesses the rule against a die result value.
+  # @param [Integer] test_value Value that is result of rolling a single die.
+  # @return [Integer,nil] Replacement value, or nil if this rule doesn't apply
   def map_from test_value
     op_result = @trigger_value.send( @trigger_op, test_value )
     return nil unless op_result

data/lib/games_dice/reroll_rule.rb

@@ -1,9 +1,34 @@
-# specifies when and how a ComplexDie should be re-rolled
+# This class models a variety of game rules that cause dice to be re-rolled.
+#
+# An object of the class represents a single rule, such as "re-roll a result of 1
+# and use the new value".
+#
+# @example A rule for "exploding" dice
+#  rule = GamesDice::RerollRule.new( 6, :<=, :reroll_add )
+#  # Test whether the rule applies . . .
+#  rule.applies? 4   # => false
+#  rule.applies? 6   # => true
+#  rule.type         # => :reroll_add
+#
+# @example A rule for re-rolling and taking best value if first attempt is lower than a threshold
+#  rule = GamesDice::RerollRule.new( 11, :>, :reroll_use_best, 1 )
+#  # Test whether the rule applies . . .
+#  rule.applies? 4   # => true
+#  rule.applies? 14  # => false
+#  rule.type         # => :reroll_use_best
+#
+
 class GamesDice::RerollRule
 
-  # trigger_op, trigger_value, type and limit set the attributes of the same name
-  #  rule = GamesDice::RerollRule.new( 10, :<=, :reroll_add ) # an 'exploding' die
-  def initialize trigger_value, trigger_op, type, limit=nil
+  # Creates new instance of GamesDice::RerollRule. The rule will be assessed as
+  #   trigger_value.send( trigger_op, x )
+  # where x is the Integer value shown on a die.
+  # @param [Integer,Range<Integer>,Object] trigger_value Any object is allowed, but typically an Integer
+  # @param [Symbol] trigger_op A method of trigger_value that takes an Integer param and returns Boolean
+  # @param [Symbol] type The type of reroll
+  # @param [Integer] limit Maximum number of times this rule can be applied to a single die
+  # @return [GamesDice::RerollRule]
+  def initialize trigger_value, trigger_op, type, limit = 1000
 
     if ! trigger_value.respond_to?( trigger_op )
       raise ArgumentError, "trigger_value #{trigger_value.inspect} cannot respond to trigger_op #{trigger_value.inspect}"
@@ -16,30 +41,35 @@ class GamesDice::RerollRule
     @trigger_value = trigger_value
     @trigger_op = trigger_op
     @type = type
-    @limit = limit ? Integer(limit) : 1000
+    @limit = limit ? Integer( limit ) : 1000
     @limit = 1 if @type == :reroll_subtract
   end
 
-  # a valid symbol for a method, which will be called against #trigger_value with the current
-  # die result as a param. It should return true or false
+  # Trigger operation. How the rule is assessed against #trigger_value.
+  # @return [Symbol] Method name to be sent to #trigger_value
   attr_reader :trigger_op
 
-  # an Integer value or Range that will cause the reroll to occur. #trigger_op is called against it
+  # Trigger value. An object that will use #trigger_op to assess a die result for a reroll.
+  # @return [Integer,Range,Object] Object that receives (#trigger_op, die_result)
   attr_reader :trigger_value
 
-  # a symbol, should be one of the following:
-  #   :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 existing value
-  #   :reroll_use_worst - use the new value if it is higher than the existing value
+  # The reroll behaviour that this rule triggers.
+  # @return [Symbol] A category for the re-roll, declares how it should be processed
+  # The following values are supported:
+  # +: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 existing value
+  # +:reroll_use_worst+:: use the new value if it is higher than the existing value
   attr_reader :type
 
-  # maximum number of times this rule should be applied to a single die. If type is:reroll_subtract,
-  # this value is always 1. A default value of 100 is used if not set in the constructor
+  # Maximum to number of times that this rule can be applied to a single die.
+  # @return [Integer] A number of rolls.
   attr_reader :limit
 
-  # runs the rule against a test value, returning truth value from calling the trigger_op method
+  # Assesses the rule against a die result value.
+  # @param [Integer] test_value Value that is result of rolling a single die.
+  # @return [Boolean] Whether the rule applies.
   def applies? test_value
     @trigger_value.send( @trigger_op, test_value ) ? true : false
   end

data/lib/games_dice/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: games_dice
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-05 00:00:00.000000000 Z
+date: 2013-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -144,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3596350699515982404
+      hash: -2482711703426352461
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -153,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3596350699515982404
+      hash: -2482711703426352461
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24