games_dice 0.3.9 → 0.4.0

data/lib/games_dice/die_result.rb

@@ -1,189 +1,193 @@
-# This class models the output of GamesDice::ComplexDie.
-#
-# An object of the class represents the results of a roll of a ComplexDie, including any re-rolls and
-# value mapping.
-#
-# @example Building up a result manually
-#  dr = GamesDice::DieResult.new
-#  dr.add_roll 5
-#  dr.add_roll 4, :reroll_replace
-#  dr.value # => 4
-#  dr.rolls # => [5, 4]
-#  dr.roll_reasons # => [:basic, :reroll_replace]
-#  # dr can behave as dr.value due to coercion and support for some operators
-#  dr + 6 # => 10
-#
-# @example Using a result from GamesDice::ComplexDie
-#  # An "exploding" six-sided die that needs a result of 8 to score "1 Success"
-#  d = GamesDice::ComplexDie.new( 6, :rerolls => [[6, :<=, :reroll_add]], :maps => [[8, :<=, 1, 'Success']] )
-#  # Generate result object by rolling the die
-#  dr = d.roll
-#  dr.rolls         # => [6, 3]
-#  dr.roll_reasons  # => [:basic, :reroll_add]
-#  dr.total         # => 9
-#  dr.value         # => 1
-#  dr.explain_value # => "[6+3] 9 Success"
-#
-
-class GamesDice::DieResult
-  include Comparable
-
-  # Creates new instance of GamesDice::DieResult. The object can be initialised "empty" or with a first result.
-  # @param [Integer,nil] first_roll_result Value for first roll of the die.
-  # @param [Symbol] first_roll_reason Reason for first roll of the die.
-  # @return [GamesDice::DieResult]
-  def initialize( first_roll_result=nil, first_roll_reason=:basic )
-    unless GamesDice::REROLL_TYPES.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
-
-  # The individual die rolls that combined to generate this result.
-  # @return [Array<Integer>] Un-processed values of each die roll used for this result.
-  attr_reader :rolls
-
-  # The individual reasons for each roll of the die. See GamesDice::RerollRule for allowed values.
-  # @return [Array<Symbol>] Reasons for each die roll, indexes match the #rolls Array.
-  attr_reader :roll_reasons
-
-  # Combined result of all rolls, *before* mapping.
-  # @return [Integer,nil]
-  attr_reader :total
-
-  # Combined result of all rolls, *after* mapping.
-  # @return [Integer,nil]
-  attr_reader :value
-
-  # Whether or not #value has been mapped from #total.
-  # @return [Boolean]
-  attr_reader :mapped
-
-  # Adds value from a new roll to the object. GamesDice::DieResult tracks reasons for the roll
-  # and makes the correct adjustment to the total so far. Any mapped value is cleared.
-  # @param [Integer] roll_result Value result from rolling the die.
-  # @param [Symbol] roll_reason Reason for rolling the die.
-  # @return [Integer] Total so far
-  def add_roll( roll_result, roll_reason=:basic )
-    unless GamesDice::REROLL_TYPES.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, and notes that the value has been mapped. Used by GamesDice::ComplexDie
-  # when there are one or more GamesDice::MapRule objects to process for a die.
-  # @param [Integer] to_value Replacement value.
-  # @param [String] description Description of what the mapped value represents e.g. "Success"
-  # @return [nil]
-  def apply_map( to_value, description = '' )
-    @mapped = true
-    @value = to_value
-    @map_description = description
-    return
-  end
-
-  # Generates a text description of how #value is determined. If #value has been mapped, includes the
-  # map description, but does not include the mapped value.
-  # @return [String] Explanation of #value.
-  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 + GamesDice::REROLL_TYPES[@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
-
-  # @!visibility private
-  # This is mis-named, it doesn't explain the total at all! It is used to generate summaries of keeper dice.
-  def explain_total
-    text = @total.to_s
-    text += ' ' + @map_description if @mapped && @map_description && @map_description.length > 0
-    return text
-  end
-
-  # @!visibility private
-  # all coercions simply use #value (i.e. nil or a Fixnum)
-  def coerce(thing)
-    @value.coerce(thing)
-  end
-
-  # @!visibility private
-  # addition uses #value
-  def +(thing)
-    @value + thing
-  end
-
-  # @!visibility private
-  # subtraction uses #value
-  def -(thing)
-    @value - thing
-  end
-
-  # @!visibility private
-  # multiplication uses #value
-  def *(thing)
-    @value * thing
-  end
-
-  # @!visibility private
-  # comparison <=> uses #value
-  def <=>(other)
-    self.value <=> other
-  end
-
-  # This is a deep clone, all attributes are cloned.
-  # @return [GamesDice::DieResult]
-  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
+# frozen_string_literal: true
+
+module GamesDice
+  # This class models the output of GamesDice::ComplexDie.
+  #
+  # An object of the class represents the results of a roll of a ComplexDie, including any re-rolls and
+  # value mapping.
+  #
+  # @example Building up a result manually
+  #  dr = GamesDice::DieResult.new
+  #  dr.add_roll 5
+  #  dr.add_roll 4, :reroll_replace
+  #  dr.value # => 4
+  #  dr.rolls # => [5, 4]
+  #  dr.roll_reasons # => [:basic, :reroll_replace]
+  #  # dr can behave as dr.value due to coercion and support for some operators
+  #  dr + 6 # => 10
+  #
+  # @example Using a result from GamesDice::ComplexDie
+  #  # An "exploding" six-sided die that needs a result of 8 to score "1 Success"
+  #  d = GamesDice::ComplexDie.new( 6, :rerolls => [[6, :<=, :reroll_add]], :maps => [[8, :<=, 1, 'Success']] )
+  #  # Generate result object by rolling the die
+  #  dr = d.roll
+  #  dr.rolls         # => [6, 3]
+  #  dr.roll_reasons  # => [:basic, :reroll_add]
+  #  dr.total         # => 9
+  #  dr.value         # => 1
+  #  dr.explain_value # => "[6+3] 9 Success"
+  #
+  class DieResult
+    include Comparable
+
+    # Creates new instance of GamesDice::DieResult. The object can be initialised "empty" or with a first result.
+    # @param [Integer,nil] first_roll_result Value for first roll of the die.
+    # @param [Symbol] first_roll_reason Reason for first roll of the die.
+    # @return [GamesDice::DieResult]
+    def initialize(first_roll_result = nil, first_roll_reason = :basic)
+      unless GamesDice::REROLL_TYPES.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
+
+    # The individual die rolls that combined to generate this result.
+    # @return [Array<Integer>] Un-processed values of each die roll used for this result.
+    attr_reader :rolls
+
+    # The individual reasons for each roll of the die. See GamesDice::RerollRule for allowed values.
+    # @return [Array<Symbol>] Reasons for each die roll, indexes match the #rolls Array.
+    attr_reader :roll_reasons
+
+    # Combined result of all rolls, *before* mapping.
+    # @return [Integer,nil]
+    attr_reader :total
+
+    # Combined result of all rolls, *after* mapping.
+    # @return [Integer,nil]
+    attr_reader :value
+
+    # Whether or not #value has been mapped from #total.
+    # @return [Boolean]
+    attr_reader :mapped
+
+    # Adds value from a new roll to the object. GamesDice::DieResult tracks reasons for the roll
+    # and makes the correct adjustment to the total so far. Any mapped value is cleared.
+    # @param [Integer] roll_result Value result from rolling the die.
+    # @param [Symbol] roll_reason Reason for rolling the die.
+    # @return [Integer] Total so far
+    def add_roll(roll_result, roll_reason = :basic)
+      unless GamesDice::REROLL_TYPES.key?(roll_reason)
+        raise ArgumentError, "Unrecognised reason for roll #{roll_reason}"
+      end
+
+      @rolls << Integer(roll_result)
+      @roll_reasons << roll_reason
+      @total = 0 if @rolls.length == 1
+
+      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, and notes that the value has been mapped. Used by GamesDice::ComplexDie
+    # when there are one or more GamesDice::MapRule objects to process for a die.
+    # @param [Integer] to_value Replacement value.
+    # @param [String] description Description of what the mapped value represents e.g. "Success"
+    # @return [nil]
+    def apply_map(to_value, description = '')
+      @mapped = true
+      @value = to_value
+      @map_description = description
+      nil
+    end
+
+    # Generates a text description of how #value is determined. If #value has been mapped, includes the
+    # map description, but does not include the mapped value.
+    # @return [String] Explanation of #value.
+    def explain_value
+      text = ''
+      if @rolls.length < 2
+        text = @total.to_s
+      else
+        text = "[#{@rolls[0]}"
+        text = (1..@rolls.length - 1).inject(text) do |so_far, i|
+          so_far + GamesDice::REROLL_TYPES[@roll_reasons[i]] + @rolls[i].to_s
+        end
+        text += "] #{@total}"
+      end
+      text += " #{@map_description}" if @mapped && @map_description && @map_description.length.positive?
+      text
+    end
+
+    # @!visibility private
+    # This is mis-named, it doesn't explain the total at all! It is used to generate summaries of keeper dice.
+    def explain_total
+      text = @total.to_s
+      text += " #{@map_description}" if @mapped && @map_description && @map_description.length.positive?
+      text
+    end
+
+    # @!visibility private
+    # all coercions simply use #value (i.e. nil or a Integer)
+    def coerce(thing)
+      @value.coerce(thing)
+    end
+
+    # @!visibility private
+    # addition uses #value
+    def +(other)
+      @value + other
+    end
+
+    # @!visibility private
+    # subtraction uses #value
+    def -(other)
+      @value - other
+    end
+
+    # @!visibility private
+    # multiplication uses #value
+    def *(other)
+      @value * other
+    end
+
+    # @!visibility private
+    # comparison <=> uses #value
+    def <=>(other)
+      value <=> other
+    end
+
+    # This is a deep clone, all attributes are cloned.
+    # @return [GamesDice::DieResult]
+    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
+end

data/lib/games_dice/map_rule.rb

@@ -1,70 +1,72 @@
-# 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
-
-  # 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 )
-      raise ArgumentError, "trigger_value #{trigger_value.inspect} cannot respond to trigger_op #{trigger_value.inspect}"
-    end
-
-    @trigger_value = trigger_value
-    @trigger_op = trigger_op
-    raise TypeError if ! mapped_value.is_a? Numeric
-    @mapped_value = Integer(mapped_value)
-    @mapped_name = mapped_name.to_s
-  end
-
-  # Trigger operation. How the rule is assessed against #trigger_value.
-  # @return [Symbol] Method name to be sent to #trigger_value
-  attr_reader :trigger_op
-
-  # 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
-
-  # Value that a die will use after the value has been mapped.
-  # @return [Integer]
-  attr_reader :mapped_value
-
-  # Name for mapped value, used in explanations.
-  # @return [String]
-  attr_reader :mapped_name
-
-  # 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
-    if op_result == true
-      return @mapped_value
-    end
-    return op_result
-  end
-end # class MapRule
+# frozen_string_literal: true
+
+module GamesDice
+  # 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 MapRule
+    # 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 = '')
+      unless trigger_value.respond_to?(trigger_op)
+        raise ArgumentError,
+              "trigger_value #{trigger_value.inspect} cannot respond to trigger_op #{trigger_value.inspect}"
+      end
+
+      @trigger_value = trigger_value
+      @trigger_op = trigger_op
+      raise TypeError unless mapped_value.is_a? Numeric
+
+      @mapped_value = Integer(mapped_value)
+      @mapped_name = mapped_name.to_s
+    end
+
+    # Trigger operation. How the rule is assessed against #trigger_value.
+    # @return [Symbol] Method name to be sent to #trigger_value
+    attr_reader :trigger_op
+
+    # 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
+
+    # Value that a die will use after the value has been mapped.
+    # @return [Integer]
+    attr_reader :mapped_value
+
+    # Name for mapped value, used in explanations.
+    # @return [String]
+    attr_reader :mapped_name
+
+    # 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
+      return @mapped_value if op_result == true
+
+      op_result
+    end
+  end
+end

data/lib/games_dice/marshal.rb

@@ -1,13 +1,18 @@
-class GamesDice::Probabilities
-  # @!visibility private
-  # Adds support for Marshal, via to_h and from_h methods
-  def _dump *ignored
-    Marshal.dump to_h
-  end
-
-  # @!visibility private
-  def self._load buf
-    h = Marshal.load buf
-    from_h h
-  end
-end
+# frozen_string_literal: true
+
+module GamesDice
+  # Probability calculations
+  class Probabilities
+    # @!visibility private
+    # Adds support for Marshal, via to_h and from_h methods
+    def _dump(*_ignored)
+      Marshal.dump to_h
+    end
+
+    # @!visibility private
+    def self._load(buf)
+      h = Marshal.load buf
+      from_h h
+    end
+  end
+end