games_dice 0.3.12 → 0.4.2

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,41 @@
-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
+  # 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 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
+end