nerd_dice 0.1.0 → 0.4.0

data/bin/nerd_dice_benchmark

@@ -0,0 +1,322 @@
+#!/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,
+  total_magic_securerandom: 6.04,
+  total_magic_random_rand: 85.9,
+  total_magic_random_object: 89.42,
+  total_magic_randomized: 20.27,
+  roll_dice_securerandom: 4.0,
+  roll_dice_random_rand: 42.0,
+  roll_dice_random_object: 44.0,
+  roll_dice_randomized: 14.5,
+  roll_magic_securerandom: 6.04,
+  roll_magic_random_rand: 85.9,
+  roll_magic_random_object: 89.42,
+  roll_magic_randomized: 20.27,
+  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_magic_securerandom_3d6: 18.38,
+  roll_magic_random_rand_3d6: 108.54,
+  roll_magic_random_object_3d6: 118.36,
+  roll_magic_randomized_3d6: 44.39,
+  roll_ability_scores_randomized: 30.5,
+  total_ability_scores_randomized: 30.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.bm 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"
+
+puts "total_dice"
+total_dice_d1000_results = Benchmark.bm 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
+
+puts "total_ d1000s ConvenienceMethods"
+
+# NOTE: Due to method_missing overhead, using roll_ ratios for ConvenienceMethods total_dice
+total_d1000_results = Benchmark.bm do |x|
+  # NerdDice.total_dice securerandom
+  x.report("total_magic_securerandom") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.total_d1000 }
+  end
+
+  x.report("total_magic_random_rand") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.total_d1000 }
+  end
+
+  x.report("total_magic_random_object") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.total_d1000 }
+  end
+
+  x.report("total_magic_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.total_d1000 }
+  end
+end
+
+total_magic_securerandom = total_d1000_results[0]
+check_against_baseline! securerandom_baseline, total_magic_securerandom
+total_magic_random_rand = total_d1000_results[1]
+check_against_baseline! random_rand_baseline, total_magic_random_rand
+total_magic_random_object = total_d1000_results[2]
+check_against_baseline! random_rand_baseline, total_magic_random_object
+total_magic_randomized = total_d1000_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), total_magic_randomized
+
+puts "roll_dice"
+roll_dice_d1000_results = Benchmark.bm 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_ d1000s ConvenienceMethods"
+roll_d1000_results = Benchmark.bm do |x|
+  # NerdDice.roll_dice securerandom
+  x.report("roll_magic_securerandom") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.roll_d1000 }
+  end
+
+  x.report("roll_magic_random_rand") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.roll_d1000 }
+  end
+
+  x.report("roll_magic_random_object") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.roll_d1000 }
+  end
+
+  x.report("roll_magic_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.roll_d1000 }
+  end
+end
+
+roll_magic_securerandom = roll_d1000_results[0]
+check_against_baseline! securerandom_baseline, roll_magic_securerandom
+roll_magic_random_rand = roll_d1000_results[1]
+check_against_baseline! random_rand_baseline, roll_magic_random_rand
+roll_magic_random_object = roll_d1000_results[2]
+check_against_baseline! random_rand_baseline, roll_magic_random_object
+roll_magic_randomized = roll_d1000_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), roll_magic_randomized
+
+puts "Roll 3d6"
+puts "total_dice 3d6"
+total_dice_3d6_results = Benchmark.bm 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
+
+puts "roll_dice 3d6"
+roll_dice_3d6_results = Benchmark.bm 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 "roll_3d6 ConvenienceMethods"
+roll_magic_3d6_results = Benchmark.bm do |x|
+  # NerdDice.roll_magic securerandom
+  x.report("roll_magic_securerandom_3d6") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.roll_3d6 }
+  end
+
+  x.report("roll_magic_random_rand_3d6") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.roll_3d6 }
+  end
+
+  x.report("roll_magic_random_object_3d6") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.roll_3d6 }
+  end
+
+  x.report("roll_magic_randomized_3d6") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.roll_3d6 }
+  end
+end
+
+roll_magic_3d6_securerandom = roll_magic_3d6_results[0]
+check_against_baseline! securerandom_baseline, roll_magic_3d6_securerandom
+roll_magic_3d6_random_rand = roll_magic_3d6_results[1]
+check_against_baseline! random_rand_baseline, roll_magic_3d6_random_rand
+roll_magic_3d6_random_object = roll_magic_3d6_results[2]
+check_against_baseline! random_rand_baseline, roll_magic_3d6_random_object
+roll_magic_3d6_randomized = roll_magic_3d6_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), roll_magic_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.bm 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/certs/msducheminjr.pem

@@ -0,0 +1,26 @@
+-----BEGIN CERTIFICATE-----
+MIIETTCCArWgAwIBAgIBATANBgkqhkiG9w0BAQsFADAoMSYwJAYDVQQDDB1zdGF0
+ZWxlc3Njb2RlL0RDPWdtYWlsL0RDPWNvbTAeFw0yMDEyMDYyMzQ1NTZaFw0yMTEy
+MDYyMzQ1NTZaMCgxJjAkBgNVBAMMHXN0YXRlbGVzc2NvZGUvREM9Z21haWwvREM9
+Y29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAyHIMJi0o3bwBZsx5
+TQ35XByFsdDRsro3T+0NY7EAILtOiU04o9C2NPOp/RQE7BXQgMjGebwp6bT6QvzN
+6noV4jPL7Fi5pWw08QygG7f+73YUBb+8d8o+3xGrC+UO5h1PZEtVcZwUWUG18QBE
+fbDinQT6P4IDQoZwhfrPCB+aBfUyQp4Ok7oD7MEWqsq9SjrSxqxfk4+oZdXUySe7
+Vi5vnzVQ5uFf56NHwWnNKCzJzmH84mBO5MzHaQpHNzKGJPoUmzLU5RBlCH6YXqBG
+KhXTMUDBWKJmJ3RDry/FpGgJLKu4wzFRYjXla6IjeKozWGuPNNJ+2mesXKhsX7bo
+vVCzRxPEupbEg/0FkJiWpiGlSPOdd6oJiwX8E6rlEeV605xrbOQewkbovHkYTMtG
++NH+u08x0z4Oj71kmDLwuj812uS0mtrCg2VhiYO0ZCQ4XrwBsBfK+/MtMlR+o6sG
+/zvz/vHVJKaLTQxRp5oGo4QH6HfbOnwzTkXdZnt5AlN31ErJAgMBAAGjgYEwfzAJ
+BgNVHRMEAjAAMAsGA1UdDwQEAwIEsDAdBgNVHQ4EFgQUC7seYydsGO6O1qT4nVVD
+G/LkiHYwIgYDVR0RBBswGYEXc3RhdGVsZXNzY29kZUBnbWFpbC5jb20wIgYDVR0S
+BBswGYEXc3RhdGVsZXNzY29kZUBnbWFpbC5jb20wDQYJKoZIhvcNAQELBQADggGB
+ADPRFRB1cjqdcE2O0jtqiDRmrR62uEYBiUbkRPVhyoEp/cK0TVhAs9mGWAyCWu0M
+LewUeqNTUvQ9MgvagcKcnxa2RTjdrP3nGnwpStMr9bm3ArNJEzvWEs0Eusk9y73x
+fjy0qH2pw5WPfWcKYlDehMXqOP+a4udYsz0YSNiI8qEfkDCSqTJN11d5kSjVjwGB
+xkauxDT68j1JZRjPmQl3dl+DCgxkoziWX2mFTPLfGg5vZ0t6gmhdUtLvJtNIo0IX
+477E5UjmE1+rULQp/fsH6n5+H+t2eCED41ST+gkKbaQBUfIuUaCmdHz9sJaIIBw2
+6ordFa1nrLV4w5Uf6qYFnWVhIWX4GToyZSPO2s0DPYp3PWFJ4VtzKa2vp1TR5ZEA
+dkij2eQ9M8bzWWmW+A7RNaI0CzLl967bKGBSaMVCsZGBarggWD8UwJnBhTuOPZGR
+WQ4faXJSevxT+x9TgyUNJINPkz/KqreClzdL83cwxPzFFQto7zF6zMCsj0slqJjW
+EQ==
+-----END CERTIFICATE-----

data/checksum/nerd_dice-0.1.0.gem.sha256

@@ -0,0 +1 @@
+39c9724b0b40e17b309b71343c5b6838f401fa9660ac53c4be8d4b0050904da3

data/checksum/nerd_dice-0.1.0.gem.sha512

@@ -0,0 +1 @@
+58f15bb3c270b530f3620afd53d17981c48871aba61b205c8cb012ae8f396bbac905d46d32f657399f787b4c8aaf3572aab030a4bfa81c1b7d9ff1b060aa5b82

data/checksum/nerd_dice-0.1.1.gem.sha256

@@ -0,0 +1 @@
+3b8e94b12954afbeb9c08746c57a19e06dc2405cb0e74f500d0111ef99e97f72

data/checksum/nerd_dice-0.1.1.gem.sha512

@@ -0,0 +1 @@
+469f2104263dbf07ab0e83e04a3b08087b3f64a7702143ed2387a04601c7db2c0e43404dd325de1d2fbe394858973e6d9bb214d9b0f602cead65b7dc4fbcb46b

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/checksum/nerd_dice-0.3.0.gem.sha256

@@ -0,0 +1 @@
+30f9d3809362099e81e414bf987b711c8dad59703c68579809bb36ce9b199d58

data/checksum/nerd_dice-0.3.0.gem.sha512

@@ -0,0 +1 @@
+1a8913b8f2878c1471f32dadaddf9965fd61c7ef2e9a255961babdb9586f2c18b7eca1cd0f1021061fb69c96a330151a97df9a102b2871e1e1c5e5675f34a511

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,40 @@
+# 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 = get_harvest_totals_error_message(e)
+      specific_message ? raise(ArgumentError, "You must provide a valid collection. #{specific_message}") : raise
+    end
+
+    private
+
+      def get_harvest_totals_error_message(rescued_error)
+        case rescued_error.message
+        when /`total'/ then "Each element must respond to :total."
+        when /`map'/ then "Argument must respond to :map."
+        end
+      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