games_dice 0.4.0 → 0.5.0

data/lib/games_dice/bunch_helpers.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module GamesDice
+  class Bunch
+    # @!visibility private
+    # Private extension methods for GamesDice::Bunch keep rules
+    module KeepHelpers
+      private
+
+      def keep_mode_from_hash(options)
+        @keep_mode = options[:keep_mode]
+        case @keep_mode
+        when nil
+          @keep_mode = nil
+        when :keep_best, :keep_worst
+          @keep_number = Integer(options[:keep_number] || 1)
+        else
+          raise ArgumentError, ":keep_mode can be nil, :keep_best or :keep_worst. Got #{options[:keep_mode].inspect}"
+        end
+      end
+
+      def find_used_dice_due_to_keep_mode(used_dice, unused_dice = [])
+        full_dice = result_details.sort_by(&:total)
+        case @keep_mode
+        when :keep_best
+          used_dice = full_dice[-@keep_number..]
+          unused_dice = full_dice[0..(full_dice.length - 1 - @keep_number)]
+        when :keep_worst
+          used_dice = full_dice[0..(@keep_number - 1)]
+          unused_dice = full_dice[@keep_number..]
+        end
+
+        [used_dice, unused_dice]
+      end
+
+      def explain_kept_dice(used_dice)
+        separator = @single_die.maps ? ', ' : ' + '
+        ". Keep: #{used_dice.map(&:explain_total).join(separator)}"
+      end
+    end
+
+    # @!visibility private
+    # Private extension methods for GamesDice::Bunch explaining
+    module ExplainHelpers
+      private
+
+      def build_explanation(used_dice)
+        if @keep_mode || @single_die.maps
+          explanation = explain_with_keep_or_map(used_dice)
+        else
+          explanation = used_dice.map(&:explain_value).join(' + ')
+          explanation += " = #{@result}" if @ndice > 1
+        end
+
+        explanation
+      end
+
+      def explain_with_keep_or_map(used_dice)
+        explanation = result_details.map(&:explain_value).join(', ')
+        explanation += explain_kept_dice(used_dice) if @keep_mode
+        explanation += ". Successes: #{@result}" if @single_die.maps
+        explanation += " = #{@result}" if @keep_mode && !@single_die.maps && @keep_number > 1
+
+        explanation
+      end
+    end
+  end
+end

data/lib/games_dice/complex_die.rb

@@ -24,7 +24,9 @@ module GamesDice
   #  d.explain_result # => "[6+5] 11 Success"
   #
   class ComplexDie
-    include GamesDice::ComplexDieHelpers
+    include RollHelpers
+    include ProbabilityHelpers
+    include MinMaxHelpers
 
     # @!visibility private
     # arbitrary limit to speed up probability calculations. It should
@@ -35,8 +37,10 @@ module GamesDice
     # @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
+    # @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])
@@ -46,6 +50,8 @@ module GamesDice
 
       @total = nil
       @result = nil
+
+      @probabilities_complete = true
     end
 
     # The simple component used by this complex one
@@ -105,27 +111,7 @@ module GamesDice
     # 1e-9 at worst.
     # @return [GamesDice::Probabilities] Probability distribution of die.
     def probabilities
-      return @probabilities if @probabilities
-
-      @probabilities_complete = true
-      if @rerolls && @maps
-        reroll_probs = recursive_probabilities
-        prob_hash = {}
-        reroll_probs.each do |v, p|
-          add_mapped_to_prob_hash(prob_hash, v, p)
-        end
-      elsif @rerolls
-        prob_hash = recursive_probabilities
-      elsif @maps
-        prob_hash = {}
-        @basic_die.probabilities.each do |v, p|
-          add_mapped_to_prob_hash(prob_hash, v, p)
-        end
-      else
-        @probabilities = @basic_die.probabilities
-        return @probabilities
-      end
-      @probabilities = GamesDice::Probabilities.from_h(prob_hash)
+      @probabilities ||= calculate_probabilities
     end
 
     # Simulates rolling the die
@@ -140,63 +126,6 @@ module GamesDice
 
     private
 
-    def add_mapped_to_prob_hash(prob_hash, v, p)
-      m, n = calc_maps(v)
-      prob_hash[m] ||= 0.0
-      prob_hash[m] += p
-    end
-
-    def roll_apply_rerolls
-      return unless @rerolls
-
-      subtracting = false
-      rerolls_remaining = @rerolls.map(&:limit)
-
-      loop do
-        rule_idx = find_matching_reroll_rule(@basic_die.result, @result.rolls.length, rerolls_remaining)
-        break unless rule_idx
-
-        rule = @rerolls[rule_idx]
-        rerolls_remaining[rule_idx] -= 1
-        subtracting = true if rule.type == :reroll_subtract
-        roll_apply_reroll_rule rule, subtracting
-      end
-    end
-
-    def roll_apply_reroll_rule(rule, is_subtracting)
-      # Apply the rule (note reversal for additions, after a subtract)
-      if is_subtracting && rule.type == :reroll_add
-        @result.add_roll(@basic_die.roll, :reroll_subtract)
-      else
-        @result.add_roll(@basic_die.roll, rule.type)
-      end
-    end
-
-    # Find which rule, if any, is being triggered
-    def find_matching_reroll_rule(check_value, num_rolls, rerolls_remaining)
-      @rerolls.zip(rerolls_remaining).find_index do |rule, remaining|
-        next if rule.type == :reroll_subtract && num_rolls > 1
-
-        remaining.positive? && rule.applies?(check_value)
-      end
-    end
-
-    def roll_apply_maps
-      return unless @maps
-
-      m, n = calc_maps(@result.value)
-      @result.apply_map(m, n)
-    end
-
-    def calc_minmax
-      @min_result = probabilities.min
-      @max_result = probabilities.max
-      return if @probabilities_complete
-
-      logical_min, logical_max = logical_minmax
-      @min_result, @max_result = [@min_result, @max_result, logical_min, logical_max].minmax
-    end
-
     def construct_rerolls(rerolls_input)
       check_and_construct rerolls_input, GamesDice::RerollRule, 'rerolls'
     end
@@ -218,70 +147,5 @@ module GamesDice
         end
       end
     end
-
-    def calc_maps(x)
-      y = 0
-      n = ''
-      @maps.find do |rule|
-        maybe_y = rule.map_from(x)
-        if maybe_y
-          y = maybe_y
-          n = rule.mapped_name
-        end
-        maybe_y
-      end
-      [y, n]
-    end
-
-    def minmax_mappings(possible_values)
-      possible_values.map do |x|
-        m, n = calc_maps(x)
-        m
-      end.minmax
-    end
-
-    # This isn't 100% accurate, but does cover most "normal" scenarios, and we're only falling back to it when we have to
-    # The inaccuracy is that min_result..max_result may contain 'holes' which have extreme map values that cannot actually
-    # occur. In practice it is likely a non-issue unless someone went out of their way to invent a dice scheme that broke it.
-    def logical_minmax
-      return @basic_die.minmax unless @rerolls || @maps
-      return minmax_mappings(@basic_die.all_values) unless @rerolls
-
-      min_result, max_result = logical_rerolls_minmax
-      return minmax_mappings((min_result..max_result)) if @maps
-
-      [min_result, max_result]
-    end
-
-    def logical_rerolls_minmax
-      min_result = @basic_die.min
-      max_result = @basic_die.max
-      min_subtract = find_minimum_possible_subtract
-      max_add = find_maximum_possible_adds
-      min_result = [min_subtract - max_add, min_subtract - max_result].min if min_subtract
-      [min_result, max_add + max_result]
-    end
-
-    def find_minimum_possible_subtract
-      min_subtract = nil
-      @rerolls.select { |r| r.type == :reroll_subtract }.each do |rule|
-        min_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.min
-        next unless min_reroll
-
-        min_subtract = [min_reroll, min_subtract].compact.min
-      end
-      min_subtract
-    end
-
-    def find_maximum_possible_adds
-      total_add = 0
-      @rerolls.select { |r| r.type == :reroll_add }.each do |rule|
-        max_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.max
-        next unless max_reroll
-
-        total_add += max_reroll * rule.limit
-      end
-      total_add
-    end
   end
 end

data/lib/games_dice/complex_die_helpers.rb

@@ -1,68 +1,260 @@
 # frozen_string_literal: true
 
-# @!visibility private
 module GamesDice
-  # Private extension methods for GamesDice::ComplexDie
-  module ComplexDieHelpers
-    private
+  class ComplexDie
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie probability calculations
+    module ProbabilityHelpers
+      private
 
-    def recursive_probabilities(probabilities = {}, prior_probability = 1.0, depth = 0, prior_result = nil, rerolls_left = nil, roll_reason = :basic, subtracting = false)
-      each_probability = prior_probability / @basic_die.sides
-      depth += 1
-      if depth >= 20 || each_probability < 1.0e-16
-        @probabilities_complete = false
-        stop_recursing = true
+      def calculate_probabilities
+        if @rerolls && @maps
+          GamesDice::Probabilities.from_h(prob_hash_with_rerolls_and_maps)
+        elsif @rerolls
+          GamesDice::Probabilities.from_h(recursive_probabilities)
+        elsif @maps
+          GamesDice::Probabilities.from_h(prob_hash_with_just_maps)
+        else
+          @basic_die.probabilities
+        end
       end
 
-      @basic_die.each_value do |v|
-        recurse_probs_for_value(v, roll_reason, probabilities, each_probability, depth, prior_result, rerolls_left,
-                                subtracting, stop_recursing)
+      def prob_hash_with_rerolls_and_maps
+        prob_hash = {}
+        reroll_probs = recursive_probabilities
+        reroll_probs.each do |v, p|
+          add_mapped_to_prob_hash(prob_hash, v, p)
+        end
+        prob_hash
       end
-      probabilities
-    end
 
-    def recurse_probs_for_value(v, roll_reason, probabilities, each_probability, depth, prior_result, rerolls_left, subtracting, stop_recursing)
-      # calculate value, recurse if there is a reroll
-      result_so_far, rerolls_remaining = calc_result_so_far(prior_result, rerolls_left, v, roll_reason)
+      def prob_hash_with_just_maps
+        prob_hash = {}
+        @basic_die.probabilities.each do |v, p|
+          add_mapped_to_prob_hash(prob_hash, v, p)
+        end
+        prob_hash
+      end
 
-      # Find which rule, if any, is being triggered
-      rule_idx = find_matching_reroll_rule(v, result_so_far.rolls.length, rerolls_remaining)
+      def add_mapped_to_prob_hash(prob_hash, orig_val, prob)
+        mapped_val, = calc_maps(orig_val)
+        prob_hash[mapped_val] ||= 0.0
+        prob_hash[mapped_val] += prob
+      end
+
+      RecurseStack = Struct.new(:depth, :roll_reason, :subtracting, :probabilities, :prior_probability, :prior_result,
+                                :rerolls_left) do
+        def initialize
+          self.depth = 0
+          self.roll_reason = :basic
+          self.subtracting = false
+          self.probabilities = {}
+          self.prior_probability = 1.0
+        end
+      end
+      private_constant :RecurseStack
+
+      def recursive_probabilities(stack = RecurseStack.new)
+        stack.prior_probability = stack.prior_probability / @basic_die.sides
+        stack.depth += 1
+
+        @basic_die.each_value do |die_val|
+          recurse_probs_for_value(die_val, stack)
+        end
+        stack.probabilities
+      end
+
+      def recurse_probs_for_value(die_val, stack)
+        result_so_far, rerolls_remaining = calc_result_so_far(die_val, stack)
+        rule_idx = find_matching_reroll_rule(die_val, result_so_far.rolls.length, rerolls_remaining)
+
+        if conintue_recursing?(stack, rule_idx)
+          continue_recursion(stack, result_so_far, rerolls_remaining, rule_idx)
+        else
+          end_recursion_store_probs(stack, result_so_far)
+        end
+      end
+
+      def conintue_recursing?(stack, rule_idx)
+        if stack.depth >= 20 || stack.prior_probability < 1.0e-16
+          @probabilities_complete = false
+          return false
+        end
+
+        !rule_idx.nil?
+      end
 
-      if rule_idx && !stop_recursing
-        recurse_probs_with_rule(probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule_idx,
-                                subtracting)
-      else
+      def continue_recursion(stack, result_so_far, rerolls_remaining, rule_idx)
+        rule = @rerolls[rule_idx]
+        rerolls_remaining[rule_idx] -= 1
+        recurse_probs_with_rule(stack, result_so_far, rerolls_remaining, rule)
+      end
+
+      def end_recursion_store_probs(stack, result_so_far)
         t = result_so_far.total
-        probabilities[t] ||= 0.0
-        probabilities[t] += each_probability
+        stack.probabilities[t] ||= 0.0
+        stack.probabilities[t] += stack.prior_probability
       end
-    end
 
-    def recurse_probs_with_rule(probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule_idx, subtracting)
-      rule = @rerolls[rule_idx]
-      rerolls_remaining[rule_idx] -= 1
-      is_subtracting = true if subtracting || rule.type == :reroll_subtract
+      def recurse_probs_with_rule(stack, result_so_far, rerolls_remaining, rule)
+        next_stack = stack.clone
+        next_stack.prior_result = result_so_far
+        next_stack.rerolls_left = rerolls_remaining
+        next_stack.subtracting = true if stack.subtracting || rule.type == :reroll_subtract
+
+        # Apply the rule (note reversal for additions, after a subtract)
+        next_stack.roll_reason = if stack.subtracting && rule.type == :reroll_add
+                                   :reroll_subtract
+                                 else
+                                   rule.type
+                                 end
 
-      # Apply the rule (note reversal for additions, after a subtract)
-      if subtracting && rule.type == :reroll_add
-        recursive_probabilities probabilities, each_probability, depth, result_so_far, rerolls_remaining,
-                                :reroll_subtract, is_subtracting
-      else
-        recursive_probabilities probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule.type,
-                                is_subtracting
+        recursive_probabilities next_stack
+      end
+
+      def calc_result_so_far(die_val, stack)
+        if stack.prior_result
+          result_so_far = stack.prior_result.clone
+          rerolls_remaining = stack.rerolls_left.clone
+          result_so_far.add_roll(die_val, stack.roll_reason)
+        else
+          rerolls_remaining = @rerolls.map(&:limit)
+          result_so_far = GamesDice::DieResult.new(die_val, stack.roll_reason)
+        end
+        [result_so_far, rerolls_remaining]
       end
     end
 
-    def calc_result_so_far(prior_result, rerolls_left, v, roll_reason)
-      if prior_result
-        result_so_far = prior_result.clone
-        result_so_far.add_roll(v, roll_reason)
-        rerolls_remaining = rerolls_left.clone
-      else
-        result_so_far = GamesDice::DieResult.new(v, roll_reason)
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie simulating rolls
+    module RollHelpers
+      private
+
+      def roll_apply_rerolls
+        return unless @rerolls
+
+        subtracting = false
         rerolls_remaining = @rerolls.map(&:limit)
+
+        rerolls_loop(subtracting, rerolls_remaining)
+      end
+
+      def rerolls_loop(subtracting, rerolls_remaining)
+        loop do
+          rule_idx = find_matching_reroll_rule(@basic_die.result, @result.rolls.length, rerolls_remaining)
+          break unless rule_idx
+
+          rule = @rerolls[rule_idx]
+          rerolls_remaining[rule_idx] -= 1
+          subtracting = true if rule.type == :reroll_subtract
+          roll_apply_reroll_rule rule, subtracting
+        end
+      end
+
+      def roll_apply_reroll_rule(rule, is_subtracting)
+        # Apply the rule (note reversal for additions, after a subtract)
+        if is_subtracting && rule.type == :reroll_add
+          @result.add_roll(@basic_die.roll, :reroll_subtract)
+        else
+          @result.add_roll(@basic_die.roll, rule.type)
+        end
+      end
+
+      # Find which rule, if any, is being triggered
+      def find_matching_reroll_rule(check_value, num_rolls, rerolls_remaining)
+        @rerolls.zip(rerolls_remaining).find_index do |rule, remaining|
+          next if rule.type == :reroll_subtract && num_rolls > 1
+
+          remaining.positive? && rule.applies?(check_value)
+        end
+      end
+
+      def roll_apply_maps
+        return unless @maps
+
+        m, n = calc_maps(@result.value)
+        @result.apply_map(m, n)
+      end
+
+      def calc_maps(original_value)
+        y = 0
+        n = ''
+        @maps.find do |rule|
+          if (maybe_y = rule.map_from(original_value))
+            y = maybe_y
+            n = rule.mapped_name
+          end
+          maybe_y
+        end
+        [y, n]
+      end
+    end
+
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie calculating min and max (which is surprisingly complex)
+    module MinMaxHelpers
+      private
+
+      def calc_minmax
+        @min_result = probabilities.min
+        @max_result = probabilities.max
+        return if @probabilities_complete
+
+        logical_min, logical_max = logical_minmax
+        @min_result, @max_result = [@min_result, @max_result, logical_min, logical_max].minmax
+      end
+
+      def minmax_mappings(possible_values)
+        possible_values.map do |x|
+          map_val, = calc_maps(x)
+          map_val
+        end.minmax
+      end
+
+      # This isn't 100% accurate, but does cover most "normal" scenarios, and we're only falling back to it when we
+      # have to. The inaccuracy is that min_result..max_result may contain 'holes' which have extreme map values that
+      # cannot actually occur. In practice it is likely a non-issue unless someone went out of their way to invent a
+      # dice schem that broke it.
+      def logical_minmax
+        return @basic_die.minmax unless @rerolls || @maps
+        return minmax_mappings(@basic_die.all_values) unless @rerolls
+
+        min_result, max_result = logical_rerolls_minmax
+        return minmax_mappings(min_result..max_result) if @maps
+
+        [min_result, max_result]
+      end
+
+      def logical_rerolls_minmax
+        min_result = @basic_die.min
+        max_result = @basic_die.max
+        min_subtract = find_minimum_possible_subtract
+        max_add = find_maximum_possible_adds
+        min_result = [min_subtract - max_add, min_subtract - max_result].min if min_subtract
+        [min_result, max_add + max_result]
+      end
+
+      def find_minimum_possible_subtract
+        min_subtract = nil
+        @rerolls.select { |r| r.type == :reroll_subtract }.each do |rule|
+          min_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.min
+          next unless min_reroll
+
+          min_subtract = [min_reroll, min_subtract].compact.min
+        end
+        min_subtract
+      end
+
+      def find_maximum_possible_adds
+        total_add = 0
+        @rerolls.select { |r| r.type == :reroll_add }.each do |rule|
+          max_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.max
+          next unless max_reroll
+
+          total_add += max_reroll * rule.limit
+        end
+        total_add
       end
-      [result_so_far, rerolls_remaining]
     end
   end
 end

data/lib/games_dice/dice.rb

@@ -28,11 +28,14 @@ module GamesDice
     # @option bunches [Integer] :sides Number of sides on a single die in the bunch, *mandatory*
     # @option bunches [String] :name Optional name for the bunch
     # @option bunches [Array<GamesDice::RerollRule,Array>] :rerolls Optional rules that cause the die to roll again
-    # @option bunches [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result for the die
-    # @option bunches [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to GamesDice::Die's constructor
+    # @option bunches [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result
+    #   for the die
+    # @option bunches [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to
+    #   GamesDice::Die's constructor
     # @option bunches [Symbol] :keep_mode Optional, either *:keep_best* or *:keep_worst*
     # @option bunches [Integer] :keep_number Optional number of dice to keep when :keep_mode is not nil
-    # @option bunches [Integer] :multiplier Optional, defaults to 1, and typically 1 or -1 to describe whether the Bunch total is to be added or subtracted
+    # @option bunches [Integer] :multiplier Optional, defaults to 1, and typically 1 or -1 to describe whether the
+    #   Bunch total is to be added or subtracted
     # @return [GamesDice::Dice]
     def initialize(bunches, offset = 0, name = '')
       @name = name
@@ -110,14 +113,11 @@ module GamesDice
 
       explanations = @bunches.map { |bunch| "#{bunch.label}: #{bunch.explain_result}" }
 
-      return @offset.to_s if explanations.count.zero?
+      return @offset.to_s if explanations.none?
 
-      return simple_explanation(explanations.first) if explanations.count == 1
+      return simple_explanation(explanations.first) if explanations.one?
 
-      bunch_values = @bunch_multipliers.zip(@bunches).map { |m, b| m * b.result }
-      bunch_values << @offset if @offset != 0
-      explanations << array_to_sum(bunch_values)
-      explanations.join('. ')
+      multi_explanations(explanations)
     end
 
     private
@@ -128,8 +128,15 @@ module GamesDice
       "#{explanation}. #{array_to_sum([@bunches[0].result, @offset])}"
     end
 
+    def multi_explanations(explanations)
+      bunch_values = @bunch_multipliers.zip(@bunches).map { |m, b| m * b.result }
+      bunch_values << @offset if @offset != 0
+      explanations << array_to_sum(bunch_values)
+      explanations.join('. ')
+    end
+
     def array_to_sum(array)
-      (numbers_to_strings(array) + ['=', array.inject(:+)]).join(' ')
+      (numbers_to_strings(array) + ['=', array.sum]).join(' ')
     end
 
     def numbers_to_strings(array)

data/lib/games_dice/die.rb

@@ -74,8 +74,8 @@ module GamesDice
     # Iterates through all possible results on die.
     # @yieldparam [Integer] result A potential result from the die
     # @return [GamesDice::Die] this object
-    def each_value(&block)
-      (1..@sides).each(&block)
+    def each_value(&)
+      (1..@sides).each(&)
       self
     end