nerd_dice 0.2.0 → 0.3.0

data/bin/nerd_dice_benchmark

@@ -0,0 +1,204 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "benchmark"
+require "nerd_dice"
+
+n = 50_000
+
+RATIOS = {
+  total_dice_securerandom: 2.1,
+  total_dice_random_rand: 11.1,
+  total_dice_random_object: 13.0,
+  total_dice_randomized: 5.5,
+  total_dice_securerandom_3d6: 5.5,
+  total_dice_random_rand_3d6: 30.0,
+  total_dice_random_object_3d6: 25.5,
+  total_dice_randomized_3d6: 15.5,
+  roll_dice_securerandom: 4.0,
+  roll_dice_random_rand: 42.0,
+  roll_dice_random_object: 44.0,
+  roll_dice_randomized: 14.5,
+  roll_dice_securerandom_3d6: 13.0,
+  roll_dice_random_rand_3d6: 79.0,
+  roll_dice_random_object_3d6: 86.0,
+  roll_dice_randomized_3d6: 26.5,
+  roll_ability_scores_randomized: 26.5,
+  total_ability_scores_randomized: 26.5
+}.freeze
+
+def check_against_baseline!(baseline_value, test_value)
+  ratio = RATIOS[test_value.label.to_sym]
+  error_message = "Failed benchmark for #{test_value.label}. "
+  error_message += "Allowed ratio was #{ratio} actual ratio was #{test_value.real / baseline_value}"
+  raise NerdDice::Error, error_message if test_value.real > baseline_value * ratio
+end
+
+puts "Set baseline"
+baselines = Benchmark.bmbm do |x|
+  # Random.rand()
+  x.report("Random.rand") do # standard rand()
+    n.times { Random.rand(1000) }
+  end
+
+  # SecureRandom.rand()
+  x.report("Sec.rand") do
+    n.times { SecureRandom.rand(1000) }
+  end
+end
+
+random_rand_baseline = baselines[0].real
+securerandom_baseline = baselines[1].real
+
+puts "Roll d1000s"
+total_dice_d1000_results = Benchmark.bmbm do |x|
+  # NerdDice.total_dice securerandom
+  x.report("total_dice_securerandom") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.total_dice(1000) }
+  end
+
+  x.report("total_dice_random_rand") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.total_dice(1000) }
+  end
+
+  x.report("total_dice_random_object") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.total_dice(1000) }
+  end
+
+  x.report("total_dice_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.total_dice(1000) }
+  end
+end
+
+total_dice_securerandom = total_dice_d1000_results[0]
+check_against_baseline! securerandom_baseline, total_dice_securerandom
+total_dice_random_rand = total_dice_d1000_results[1]
+check_against_baseline! random_rand_baseline, total_dice_random_rand
+total_dice_random_object = total_dice_d1000_results[2]
+check_against_baseline! random_rand_baseline, total_dice_random_object
+total_dice_randomized = total_dice_d1000_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), total_dice_randomized
+
+roll_dice_d1000_results = Benchmark.bmbm do |x|
+  # NerdDice.roll_dice securerandom
+  x.report("roll_dice_securerandom") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.roll_dice(1000) }
+  end
+
+  x.report("roll_dice_random_rand") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.roll_dice(1000) }
+  end
+
+  x.report("roll_dice_random_object") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.roll_dice(1000) }
+  end
+
+  x.report("roll_dice_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.roll_dice(1000) }
+  end
+end
+
+roll_dice_securerandom = roll_dice_d1000_results[0]
+check_against_baseline! securerandom_baseline, roll_dice_securerandom
+roll_dice_random_rand = roll_dice_d1000_results[1]
+check_against_baseline! random_rand_baseline, roll_dice_random_rand
+roll_dice_random_object = roll_dice_d1000_results[2]
+check_against_baseline! random_rand_baseline, roll_dice_random_object
+roll_dice_randomized = roll_dice_d1000_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), roll_dice_randomized
+
+puts "Roll 3d6"
+total_dice_3d6_results = Benchmark.bmbm do |x|
+  # NerdDice.total_dice securerandom
+  x.report("total_dice_securerandom_3d6") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.total_dice(6, 3) }
+  end
+
+  x.report("total_dice_random_rand_3d6") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.total_dice(6, 3) }
+  end
+
+  x.report("total_dice_random_object_3d6") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.total_dice(6, 3) }
+  end
+
+  x.report("total_dice_randomized_3d6") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.total_dice(6, 3) }
+  end
+end
+
+total_dice_3d6_securerandom = total_dice_3d6_results[0]
+check_against_baseline! securerandom_baseline, total_dice_3d6_securerandom
+total_dice_3d6_random_rand = total_dice_3d6_results[1]
+check_against_baseline! random_rand_baseline, total_dice_3d6_random_rand
+total_dice_3d6_random_object = total_dice_3d6_results[2]
+check_against_baseline! random_rand_baseline, total_dice_3d6_random_object
+total_dice_3d6_randomized = total_dice_3d6_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), total_dice_3d6_randomized
+
+roll_dice_3d6_results = Benchmark.bmbm do |x|
+  # NerdDice.roll_dice securerandom
+  x.report("roll_dice_securerandom_3d6") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.roll_dice(6, 3) }
+  end
+
+  x.report("roll_dice_random_rand_3d6") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.roll_dice(6, 3) }
+  end
+
+  x.report("roll_dice_random_object_3d6") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.roll_dice(6, 3) }
+  end
+
+  x.report("roll_dice_randomized_3d6") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.roll_dice(6, 3) }
+  end
+end
+
+roll_dice_3d6_securerandom = roll_dice_3d6_results[0]
+check_against_baseline! securerandom_baseline, roll_dice_3d6_securerandom
+roll_dice_3d6_random_rand = roll_dice_3d6_results[1]
+check_against_baseline! random_rand_baseline, roll_dice_3d6_random_rand
+roll_dice_3d6_random_object = roll_dice_3d6_results[2]
+check_against_baseline! random_rand_baseline, roll_dice_3d6_random_object
+roll_dice_3d6_randomized = roll_dice_3d6_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), roll_dice_3d6_randomized
+
+puts "Setting n down to 5,000 due to more intensive methods"
+n = 5_000
+
+puts "Roll and total ability scores"
+roll_ability_scores_results = Benchmark.bmbm do |x|
+  x.report("roll_ability_scores_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.roll_ability_scores }
+  end
+
+  x.report("total_ability_scores_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.total_ability_scores }
+  end
+end
+
+roll_ability_scores_randomized = roll_ability_scores_results[0]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), roll_ability_scores_randomized
+total_ability_scores_randomized = roll_ability_scores_results[1]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)),
+                        total_ability_scores_randomized

data/checksum/nerd_dice-0.2.0.gem.sha256

@@ -0,0 +1 @@
+0a2d4765e24c21fecf99229b0cc4fad806ca256d2187c45c442b25771af1b9cc

data/checksum/nerd_dice-0.2.0.gem.sha512

@@ -0,0 +1 @@
+e345190f870eabd2a4fd6993f1a1d70d008ef8e6464767ba5697a46f7c4d6912c78a18039cec06c18dd6f0ee9f425453c078f780d36ccf65043ec3f7fba790a2

data/lib/nerd_dice/class_methods/configure.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#############################
+# Configuration class methods
+#############################
+# Usage:
+#   NerdDice.configure takes a block and yields the NerdDice::Configuration
+#   properties:
+#   If you wanted to configure several properties in a block:
+#   <tt>
+#     NerdDice.configure do |config|
+#       config.randomization_technique = :randomized
+#       config.die_background_color = "#FF0000"
+#     end
+#   </tt>
+#
+#   NerdDice.configuration returns the NerdDice::Configuration object and lets you
+#   set properties on the NerdDice::Configuration object without using a block:
+#   <tt>
+#     config = NerdDice.configuration
+#     config.randomization_technique = :randomized
+#     config.die_background_color = "#FF0000"
+#   </tt>
+module NerdDice
+  class << self
+    ############################
+    # configure class method
+    ############################
+    # Arguments: None
+    # Expects and yields to a block where configuration is specified.
+    # See README and NerdDice::Configuration class for config options
+    # Return (NerdDice::Configuration) the Configuration object tied to the
+    #   @configuration class instance variable
+    def configure
+      yield configuration
+      configuration
+    end
+
+    ############################
+    # configuration class method
+    ############################
+    # Arguments: None
+    # Provides the lazy-loaded class instance variable @configuration
+    # Return (NerdDice::Configuration) the Configuration object tied to the
+    #   @configuration class instance variable
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end

data/lib/nerd_dice/class_methods/execute_die_roll.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+###############################
+# execute_die_roll class method
+###############################
+# Usage:
+#   If you wanted to execute a single d4 die roll without a Die object, you would execute:
+#   <tt>NerdDice.execute_die_roll(4)</tt>
+#
+#   If you wanted to execute a die roll with a different randomization technique
+#   than the one in NerdDice.configuration, you can supply an optional second argument
+#   <tt>NerdDice.execute_die_roll(4, :randomized)</tt>
+module NerdDice
+  class << self
+    # Arguments:
+    #   number_of_sides (Integer) =>  the number of sides of the die to roll
+    #   using_generator (Symbol) => must be one of the symbols in
+    #     RANDOMIZATION_TECHNIQUES or nil
+    #
+    # Return (Integer) => Value of the single die rolled
+    def execute_die_roll(number_of_sides, using_generator = nil)
+      @count_since_last_refresh ||= 0
+      gen = get_number_generator(using_generator)
+      result = gen.rand(number_of_sides) + 1
+      increment_and_evalutate_refresh_seed
+      result
+    end
+
+    private
+
+      def get_number_generator(using_generator = nil)
+        using_generator ||= configuration.randomization_technique
+        case using_generator
+        when :securerandom then SecureRandom
+        when :random_rand then Random
+        when :random_object then @random_object ||= Random.new
+        when :randomized then random_generator
+        else raise ArgumentError, "Unrecognized generator. Must be one of #{RANDOMIZATION_TECHNIQUES.join(', ')}"
+        end
+      end
+
+      def random_generator
+        gen = RANDOMIZATION_TECHNIQUES.reject { |el| el == :randomized }.sample
+        get_number_generator(gen)
+      end
+  end
+end

data/lib/nerd_dice/class_methods/harvest_totals.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+############################
+# harvest_totals method
+############################
+# Usage:
+#   This method will take any collection of objects where each element responds to
+#   :total and return an array of the results of the total method.
+#
+#   Example
+#   <tt>
+#     ability_score_array = NerdDice.roll_ability_scores
+#     => Array of 6 DiceSet objects
+#     totals_array = NerdDice.harvest_totals(totals_array)
+#     => [15, 14, 13, 12, 10, 8]
+#     # yes, it just happened to be the standard array by amazing coincidence
+#   </tt>
+module NerdDice
+  class << self
+    # Arguments:
+    #   collection (Enumerable) a collection where each element responds to total
+    #
+    # Return (Array) => Data type of each element will be whatever is returned by total method
+    def harvest_totals(collection)
+      collection.map(&:total)
+    rescue NoMethodError => e
+      specific_message =
+        case e.message
+        when /`total'/ then "Each element must respond to :total."
+        when /`map'/ then "Argument must respond to :map."
+        end
+      specific_message ? raise(ArgumentError, "You must provide a valid collection. #{specific_message}") : raise
+    end
+  end
+end

data/lib/nerd_dice/class_methods/refresh_seed.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+############################
+# refresh_seed! class method
+############################
+# Usage:
+#   NerdDice.refresh_seed! by default will refresh the seed for the generator
+#   configured in NerdDice.configuration. It can also be used with arguments
+#   to set a particular seed for use with deterministic testing. It sets
+#   the count_since_last_refresh to 0 whenever called.
+#
+#   It cannot refresh or manipulate the seed for SecureRandom
+#
+#   <tt>NerdDice.refresh_seed!</tt>
+#
+#   With options
+#   <tt>
+#     previous_seed_data = NerdDice.refresh_seed!(
+#       randomization_technique: :randomized,
+#       random_rand_seed: 1337,
+#       random_object_seed: 24601
+#     )
+#   </tt>
+module NerdDice
+  class << self
+    # Options: (none required)
+    #   randomization_technique (Symbol) => must be one of the symbols in
+    #     RANDOMIZATION_TECHNIQUES if specified
+    #   random_rand_seed (Integer) => Seed to set for Random
+    #   random_object_seed (Integer) => Seed to set for new Random object
+    # Return (Hash or nil) => Previous values of generator seeds that were refreshed
+    def refresh_seed!(**opts)
+      technique, random_rand_new_seed, random_object_new_seed = parse_refresh_options(opts)
+      @count_since_last_refresh = 0
+      return nil if technique == :securerandom
+
+      reset_appropriate_seeds!(technique, random_rand_new_seed, random_object_new_seed)
+    end
+
+    private
+
+      def parse_refresh_options(opts)
+        [
+          opts[:randomization_technique] || configuration.randomization_technique,
+          opts[:random_rand_seed],
+          opts[:random_object_seed]
+        ]
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def reset_appropriate_seeds!(technique, random_rand_new_seed, random_object_new_seed)
+        return_hash = {}
+        case technique
+        when :random_rand
+          return_hash[:random_rand_prior_seed] = refresh_random_rand_seed!(random_rand_new_seed)
+        when :random_object
+          return_hash[:random_object_prior_seed] = refresh_random_object_seed!(random_object_new_seed)
+        when :randomized
+          return_hash[:random_rand_prior_seed] = refresh_random_rand_seed!(random_rand_new_seed)
+          return_hash[:random_object_prior_seed] = refresh_random_object_seed!(random_object_new_seed)
+        end
+        return_hash
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def refresh_random_rand_seed!(new_seed)
+        new_seed ? Random.srand(new_seed) : Random.srand
+      end
+
+      def refresh_random_object_seed!(new_seed)
+        old_seed = @random_object&.seed
+        @random_object = new_seed ? Random.new(new_seed) : Random.new
+        old_seed
+      end
+
+      def increment_and_evalutate_refresh_seed
+        @count_since_last_refresh += 1
+        return unless configuration.refresh_seed_interval
+
+        refresh_seed! if @count_since_last_refresh >= configuration.refresh_seed_interval
+      end
+  end
+end

data/lib/nerd_dice/class_methods/roll_ability_scores.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+############################
+# roll_ability_scores method
+############################
+# Usage:
+#   If you wanted to get an array of DiceSet objects with your ability scores and
+#   default configuration you would execute:
+#   <tt>ability_score_array = NerdDice.roll_ability_scores</tt>
+#
+#   If you wanted to specify configuration for the current operation without
+#   modifying the NerdDice.configuration, you can supply options for both the
+#   ability_score configuration and the properties of the DiceSet objects returned.
+#   Properties are specified in the method comment
+#   <tt>
+#     ability_score_array = NerdDice.roll_ability_scores(
+#       ability_score_array_size: 7,
+#       ability_score_number_of_sides: 8,
+#       ability_score_dice_rolled: 5,
+#       ability_score_dice_kept: 4,
+#       randomization_technique: :randomized,
+#       foreground_color: "#FF0000",
+#       background_color: "#FFFFFF"
+#     )
+#   </tt>
+module NerdDice
+  class << self
+    # Arguments:
+    #   opts (options Hash, DEFAULT: {}) any options you wish to include
+    #     ABILITY SCORE OPTIONS
+    #     :ability_score_array_size DEFAULT NerdDice.configuration.ability_score_array_size
+    #     :ability_score_number_of_sides DEFAULT NerdDice.configuration.ability_score_number_of_sides
+    #     :ability_score_dice_rolled DEFAULT NerdDice.configuration.ability_score_dice_rolled
+    #     :ability_score_dice_kept DEFAULT NerdDice.configuration.ability_score_dice_kept
+    #
+    #     DICE SET OPTIONS
+    #     :randomization_technique (Symbol) => must be one of the symbols in
+    #       RANDOMIZATION_TECHNIQUES or nil
+    #     :foreground_color (String) => should resolve to a valid CSS color (format flexible)
+    #     :background_color (String) => should resolve to a valid CSS color (format flexible)
+    #
+    # Return (Array of NerdDice::DiceSet) => One NerdDice::DiceSet element for each ability score
+    # rubocop:disable Metrics/MethodLength
+    def roll_ability_scores(**opts)
+      dice_opts = opts.reject { |key, _value| key.to_s.match?(/\Aability_score_[a-z_]+\z/) }
+      ability_score_options = interpret_ability_score_options(opts)
+      ability_score_array = []
+      ability_score_options[:ability_score_array_size].times do
+        ability_score_array << roll_dice(
+          ability_score_options[:ability_score_number_of_sides],
+          ability_score_options[:ability_score_dice_rolled],
+          **dice_opts
+        ).highest(
+          ability_score_options[:ability_score_dice_kept]
+        )
+      end
+      ability_score_array
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    private
+
+      def interpret_ability_score_options(opts)
+        return_hash = {}
+        ABILITY_SCORE_KEYS.each { |key| return_hash[key] = parse_ability_score_option(opts, key) }
+        return_hash
+      end
+
+      def parse_ability_score_option(option_hash, option_key)
+        option_hash[option_key] || configuration.send(option_key.to_s)
+      end
+  end
+end