games_dice 0.4.0 → 0.5.0

data/lib/games_dice/die_result.rb

@@ -1,6 +1,35 @@
 # frozen_string_literal: true
 
 module GamesDice
+  # Module supports using DieResults directly in calculations
+  # @!visibility private
+  module ExpressionHelpers
+    # all coercions simply use #value (i.e. nil or a Integer)
+    def coerce(thing)
+      @value.coerce(thing)
+    end
+
+    # addition uses #value
+    def +(other)
+      @value + other
+    end
+
+    # subtraction uses #value
+    def -(other)
+      @value - other
+    end
+
+    # multiplication uses #value
+    def *(other)
+      @value * other
+    end
+
+    # comparison <=> uses #value
+    def <=>(other)
+      value <=> other
+    end
+  end
+
   # 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
@@ -29,6 +58,7 @@ module GamesDice
   #
   class DieResult
     include Comparable
+    include ExpressionHelpers
 
     # 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.
@@ -40,13 +70,9 @@ module GamesDice
       end
 
       if first_roll_result
-        @rolls = [Integer(first_roll_result)]
-        @roll_reasons = [first_roll_reason]
-        @total = @rolls[0]
+        init_with_result(first_roll_result, first_roll_reason)
       else
-        @rolls = []
-        @roll_reasons = []
-        @total = nil
+        init_empty
       end
       @mapped = false
       @value = @total
@@ -78,32 +104,13 @@ module GamesDice
     # @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
+      raise ArgumentError, "Unrecognised roll reason #{roll_reason}" unless GamesDice::REROLL_TYPES.key?(roll_reason)
 
       @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
+      apply_roll_to_total(roll_reason, roll_result)
 
       @mapped = false
       @value = @total
@@ -125,17 +132,12 @@ module GamesDice
     # 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 = if @rolls.length < 2
+               @total.to_s
+             else
+               explain_value_multiple_rolls
+             end
+      text += " #{@map_description}" if @mapped && @map_description&.length&.positive?
       text
     end
 
@@ -143,51 +145,62 @@ module GamesDice
     # 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 += " #{@map_description}" if @mapped && @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)
+    # This is a deep clone, all attributes are also 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
 
-    # @!visibility private
-    # addition uses #value
-    def +(other)
-      @value + other
-    end
+    private
 
-    # @!visibility private
-    # subtraction uses #value
-    def -(other)
-      @value - other
+    # Splitting this method up further, or flattening it will not make it read better. If
+    # we had a few more reroll reasons, they could maybe be grouped and method split up.
+    # rubocop:disable Metrics/MethodLength
+    def apply_roll_to_total(roll_reason, roll_result)
+      case roll_reason
+      when :basic, :reroll_new_die, :reroll_new_keeper, :reroll_replace
+        @total = roll_result
+      when :reroll_add
+        @total += roll_result
+      when :reroll_subtract
+        @total -= roll_result
+      when :reroll_use_best
+        @total = [@value, roll_result].max
+      when :reroll_use_worst
+        @total = [@value, roll_result].min
+      end
     end
+    # rubocop:enable Metrics/MethodLength
 
-    # @!visibility private
-    # multiplication uses #value
-    def *(other)
-      @value * other
+    def init_with_result(first_roll_result, first_roll_reason)
+      @rolls = [Integer(first_roll_result)]
+      @roll_reasons = [first_roll_reason]
+      @total = @rolls[0]
     end
 
-    # @!visibility private
-    # comparison <=> uses #value
-    def <=>(other)
-      value <=> other
+    def init_empty
+      @rolls = []
+      @roll_reasons = []
+      @total = nil
     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
+    def explain_value_multiple_rolls
+      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
   end
 end

data/lib/games_dice/marshal.rb

@@ -1,17 +1,40 @@
 # frozen_string_literal: true
 
 module GamesDice
-  # Probability calculations
+  # This class models probability distributions for dice systems.
+  #
+  # An object of this class represents a single distribution, which might be the result of a complex
+  # combination of dice.
+  #
+  # @example Distribution for a six-sided die
+  #  probs = GamesDice::Probabilities.for_fair_die( 6 )
+  #  probs.min # => 1
+  #  probs.max # => 6
+  #  probs.expected # => 3.5
+  #  probs.p_ge( 4 ) # => 0.5
+  #
+  # @example Adding two distributions
+  #  pd6 = GamesDice::Probabilities.for_fair_die( 6 )
+  #  probs = GamesDice::Probabilities.add_distributions( pd6, pd6 )
+  #  probs.min # => 2
+  #  probs.max # => 12
+  #  probs.expected # => 7.0
+  #  probs.p_ge( 10 ) # => 0.16666666666666669
+  #
   class Probabilities
     # @!visibility private
     # Adds support for Marshal, via to_h and from_h methods
-    def _dump(*_ignored)
-      Marshal.dump to_h
+    def marshal_dump
+      to_h
     end
 
     # @!visibility private
     def self._load(buf)
+      # Use of Marshal for general-purpose object serialisation is discouraged. However, this class does support
+      # it for backwards-compatibility.
+      # rubocop:disable Security/MarshalLoad
       h = Marshal.load buf
+      # rubocop:enable Security/MarshalLoad
       from_h h
     end
   end

data/lib/games_dice/parser.rb

@@ -46,9 +46,11 @@ module GamesDice
     rule(:condition_type_and_num) do
       opint_or_int.as(:condition) >> comma >> ctl_string.as(:type) >> comma >> integer.as(:num)
     end
+
     rule(:condition_num_and_output) do
       opint_or_int.as(:condition) >> comma >> plus_minus_integer.as(:num) >> comma >> output_string.as(:output)
     end
+
     rule(:num_and_type) { integer.as(:num) >> comma >> ctl_string.as(:type) }
 
     rule(:reroll_params) { condition_type_and_num | condition_and_type | condition_only }
@@ -78,25 +80,41 @@ module GamesDice
     def parse(dice_description)
       dice_description = dice_description.to_s.strip
       # Force first item to start '+' for simpler parse rules
-      dice_description = "+#{dice_description}" unless dice_description =~ /\A[+-]/
-      dice_expressions = super(dice_description)
-      { bunches: collect_bunches(dice_expressions), offset: collect_offset(dice_expressions) }
+      dice_description = "+#{dice_description}" unless /\A[+-]/.match?(dice_description)
+      dice_expressions = super
+      {
+        bunches: ParseTreeProcessor.collect_bunches(dice_expressions),
+        offset: ParseTreeProcessor.collect_offset(dice_expressions)
+      }
     end
 
-    private
+    # Class converts parse tree to GamesDice hash model
+    # @!visibility private
+    class ParseTreeProcessor
+      class << self
+        def collect_bunches(dice_expressions)
+          dice_expressions[:bunches].select { |h| h[:ndice] }.map do |in_hash|
+            out_hash = {}
+            collect_bunch_basics(in_hash, out_hash)
+            collect_bunch_multiplier(in_hash, out_hash) if in_hash[:op]
+
+            in_hash[:mods]&.each do |mod|
+              collect_bunch_modifier(mod, out_hash)
+            end
+
+            out_hash
+          end
+        end
 
-    def collect_bunches(dice_expressions)
-      dice_expressions[:bunches].select { |h| h[:ndice] }.map do |in_hash|
-        out_hash = {}
-        # Convert integers
-        %i[ndice sides].each do |s|
-          next unless in_hash[s]
+        def collect_bunch_basics(in_hash, out_hash)
+          %i[ndice sides].each do |s|
+            next unless in_hash[s]
 
-          out_hash[s] = in_hash[s].to_i
+            out_hash[s] = in_hash[s].to_i
+          end
         end
 
-        # Multiplier
-        if in_hash[:op]
+        def collect_bunch_multiplier(in_hash, out_hash)
           optype = in_hash[:op].to_s
           out_hash[:multiplier] = case optype
                                   when '+' then 1
@@ -104,116 +122,124 @@ module GamesDice
                                   end
         end
 
-        # Modifiers
-        in_hash[:mods]&.each do |mod|
+        def collect_bunch_modifier(mod, out_hash)
           if mod[:alias]
-            collect_alias_modifier mod, out_hash
+            ParseTreeBunchModifier.collect_alias_modifier mod, out_hash
           elsif mod[:keep]
-            collect_keeper_rule mod, out_hash
+            ParseTreeBunchModifier.collect_keeper_rule mod, out_hash
           elsif mod[:map]
-            out_hash[:maps] ||= []
-            collect_map_rule mod, out_hash
+            ParseTreeBunchModifier.collect_map_rule mod, out_hash
           elsif mod[:reroll]
-            out_hash[:rerolls] ||= []
-            collect_reroll_rule mod, out_hash
+            ParseTreeBunchModifier.collect_reroll_rule mod, out_hash
           end
         end
 
-        out_hash
+        def collect_offset(dice_expressions)
+          dice_expressions[:bunches].select { |h| h[:constant] }.inject(0) do |total, in_hash|
+            c = in_hash[:constant].to_i
+            optype = in_hash[:op].to_s
+            if optype == '+'
+              total + c
+            else
+              total - c
+            end
+          end
+        end
       end
     end
 
-    def collect_offset(dice_expressions)
-      dice_expressions[:bunches].select { |h| h[:constant] }.inject(0) do |total, in_hash|
-        c = in_hash[:constant].to_i
-        optype = in_hash[:op].to_s
-        if optype == '+'
-          total += c
-        else
-          total -= c
+    # Class for collating bunch data into bunch construction hash
+    # @!visibility private
+    class ParseTreeBunchModifier
+      class << self
+        # Called when we have a single letter convenient alias for common dice adjustments
+        def collect_alias_modifier(alias_mod, out_hash)
+          alias_name = alias_mod[:alias].to_s
+          case alias_name
+          when 'x' # Exploding re-roll
+            out_hash[:rerolls] ||= []
+            out_hash[:rerolls] << [out_hash[:sides], :==, :reroll_add]
+          end
         end
-        total
-      end
-    end
 
-    # Called when we have a single letter convenient alias for common dice adjustments
-    def collect_alias_modifier(alias_mod, out_hash)
-      alias_name = alias_mod[:alias].to_s
-      case alias_name
-      when 'x' # Exploding re-roll
-        out_hash[:rerolls] ||= []
-        out_hash[:rerolls] << [out_hash[:sides], :==, :reroll_add]
-      end
-    end
+        # Called for any parsed reroll rule
+        def collect_reroll_rule(reroll_mod, out_hash)
+          out_hash[:rerolls] ||= []
+          if reroll_mod[:simple_value]
+            out_hash[:rerolls] << [reroll_mod[:simple_value].to_i, :>=, :reroll_replace]
+            return
+          end
 
-    # Called for any parsed reroll rule
-    def collect_reroll_rule(reroll_mod, out_hash)
-      out_hash[:rerolls] ||= []
-      if reroll_mod[:simple_value]
-        out_hash[:rerolls] << [reroll_mod[:simple_value].to_i, :>=, :reroll_replace]
-        return
-      end
+          collect_complex_reroll_rule(reroll_mod, out_hash)
+        end
 
-      # Typical reroll_mod: {:reroll=>"r"@5, :condition=>{:compare_num=>"10"@7}, :type=>"add"@10}
-      op = get_op_symbol(reroll_mod[:condition][:comparison] || '==')
-      v = reroll_mod[:condition][:compare_num].to_i
-      type = "reroll_#{reroll_mod[:type] || 'replace'}".to_sym
+        def collect_complex_reroll_rule(reroll_mod, out_hash)
+          # Typical reroll_mod: {:reroll=>"r"@5, :condition=>{:compare_num=>"10"@7}, :type=>"add"@10}
+          op = get_op_symbol(reroll_mod[:condition][:comparison] || '==')
+          v = reroll_mod[:condition][:compare_num].to_i
+          type = :"reroll_#{reroll_mod[:type] || 'replace'}"
+
+          out_hash[:rerolls] << if reroll_mod[:num]
+                                  [v, op, type, reroll_mod[:num].to_i]
+                                else
+                                  [v, op, type]
+                                end
+        end
 
-      out_hash[:rerolls] << if reroll_mod[:num]
-                              [v, op, type, reroll_mod[:num].to_i]
-                            else
-                              [v, op, type]
-                            end
-    end
+        # Called for any parsed keeper mode
+        def collect_keeper_rule(keeper_mod, out_hash)
+          raise 'Cannot set keepers for a bunch twice' if out_hash[:keep_mode]
 
-    # Called for any parsed keeper mode
-    def collect_keeper_rule(keeper_mod, out_hash)
-      raise 'Cannot set keepers for a bunch twice' if out_hash[:keep_mode]
+          if keeper_mod[:simple_value]
+            out_hash[:keep_mode] = :keep_best
+            out_hash[:keep_number] = keeper_mod[:simple_value].to_i
+            return
+          end
 
-      if keeper_mod[:simple_value]
-        out_hash[:keep_mode] = :keep_best
-        out_hash[:keep_number] = keeper_mod[:simple_value].to_i
-        return
-      end
+          # Typical keeper_mod: {:keep=>"k"@5, :num=>"1"@7, :type=>"worst"@9}
+          out_hash[:keep_number] = keeper_mod[:num].to_i
+          out_hash[:keep_mode] = :"keep_#{keeper_mod[:type] || 'best'}"
+        end
 
-      # Typical keeper_mod: {:keep=>"k"@5, :num=>"1"@7, :type=>"worst"@9}
-      out_hash[:keep_number] = keeper_mod[:num].to_i
-      out_hash[:keep_mode] = "keep_#{keeper_mod[:type] || 'best'}".to_sym
-    end
+        # Called for any parsed map mode
+        def collect_map_rule(map_mod, out_hash)
+          out_hash[:maps] ||= []
+          if map_mod[:simple_value]
+            out_hash[:maps] << [map_mod[:simple_value].to_i, :<=, 1]
+            return
+          end
 
-    # Called for any parsed map mode
-    def collect_map_rule(map_mod, out_hash)
-      out_hash[:maps] ||= []
-      if map_mod[:simple_value]
-        out_hash[:maps] << [map_mod[:simple_value].to_i, :<=, 1]
-        return
-      end
+          collect_complex_map_rule(map_mod, out_hash)
+        end
 
-      # Typical map_mod: {:map=>"m"@4, :condition=>{:compare_num=>"5"@6}, :num=>"2"@8, :output=>"Qwerty"@10}
-      op = get_op_symbol(map_mod[:condition][:comparison] || '>=')
-      v = map_mod[:condition][:compare_num].to_i
-      out_val = 1
-      out_val = map_mod[:num].to_i if map_mod[:num]
-
-      out_hash[:maps] << if map_mod[:output]
-                           [v, op, out_val, map_mod[:output].to_s]
-                         else
-                           [v, op, out_val]
-                         end
-    end
+        def collect_complex_map_rule(map_mod, out_hash)
+          # Typical map_mod: {:map=>"m"@4, :condition=>{:compare_num=>"5"@6}, :num=>"2"@8, :output=>"Qwerty"@10}
+          op = get_op_symbol(map_mod[:condition][:comparison] || '>=')
+          v = map_mod[:condition][:compare_num].to_i
+          out_val = 1
+          out_val = map_mod[:num].to_i if map_mod[:num]
+
+          out_hash[:maps] << if map_mod[:output]
+                               [v, op, out_val, map_mod[:output].to_s]
+                             else
+                               [v, op, out_val]
+                             end
+        end
 
-    # The dice description language uses (r).op.x, whilst GamesDice::RerollRule uses x.op.(r), so
-    # as well as converting to a symbol, we must reverse sense of input to constructor
-    OP_CONVERSION = {
-      '==' => :==,
-      '>=' => :<=,
-      '>' => :<,
-      '<' => :>,
-      '<=' => :>=
-    }.freeze
-
-    def get_op_symbol(parsed_op_string)
-      OP_CONVERSION[parsed_op_string.to_s]
+        # The dice description language uses (r).op.x, whilst GamesDice::RerollRule uses x.op.(r), so
+        # as well as converting to a symbol, we must reverse sense of input to constructor
+        OP_CONVERSION = {
+          '==' => :==,
+          '>=' => :<=,
+          '>' => :<,
+          '<' => :>,
+          '<=' => :>=
+        }.freeze
+
+        def get_op_symbol(parsed_op_string)
+          OP_CONVERSION[parsed_op_string.to_s]
+        end
+      end
     end
   end
 end

data/lib/games_dice/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module GamesDice
-  VERSION = '0.4.0'
+  # Current version of the gem.
+  VERSION = '0.5.0'
 end

data/lib/games_dice.rb

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
 require 'games_dice/version'
-begin
-  require 'games_dice/games_dice'
-rescue LoadError
-  require 'games_dice/probabilities'
-end
 require 'games_dice/constants'
 require 'games_dice/die'
 require 'games_dice/die_result'
@@ -15,20 +10,23 @@ require 'games_dice/complex_die'
 require 'games_dice/bunch'
 require 'games_dice/dice'
 require 'games_dice/parser'
+require 'games_dice/games_dice'
 require 'games_dice/marshal'
 
+# GamesDice is a library for simulating dice combinations used in dice and board games.
 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)
+    parsed = parser.parse(dice_description)
     parsed[:bunches].each { |bunch| bunch.merge!(prng: prng) } if prng
     GamesDice::Dice.new(parsed[:bunches], parsed[:offset])
   end
+
+  def self.parser
+    @parser ||= GamesDice::Parser.new
+  end
 end