nerd_dice 0.2.1 → 0.3.0

data/README.md

@@ -4,6 +4,9 @@
 # NerdDice
 Nerd dice allows you to roll polyhedral dice and add bonuses as you would in a tabletop roleplaying game. You can choose to roll multiple dice and keep a specified number of dice such as rolling 4d6 and dropping the lowest for ability scores or rolling with advantage and disadvantage if those mechanics exist in your game.
 
+## Educational Videos By Stateless Code
+The end-to-end process of developing this gem has been captured as [instructional videos](https://www.youtube.com/playlist?list=PL9kkbu1kLUeOnUtMpAnJOCtHdThx1Efkt). The videos are in a one-take style so that the mistakes along the way have troubleshooting and the concepts used to develop the gem are explained as they are covered.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -28,7 +31,17 @@ You can customize the behavior of NerdDice via a configuration block as below or
 NerdDice.configure do | config|
 
   # number of ability scores to place in an ability score array
-  config.ability_score_array_size = 6
+  config.ability_score_array_size = 6 # must duck-type to positive Integer
+
+  # number of sides for each ability score Die
+  config.ability_score_number_of_sides = 6 # must duck-type to positive Integer
+
+  # total number of dice rolled for each ability score
+  config.ability_score_dice_rolled = 4 # must duck-type to positive Integer
+
+  # highest(n) dice from the total number of dice rolled that are included in the ability score total
+  # CANNOT EXCEED ability_score_dice_rolled see Note below
+  config.ability_score_dice_kept = 3 # must duck-type to positive Integer
 
   # randomization technique options are:
     # :securerandom => Uses SecureRandom.rand(). Good entropy, medium speed.
@@ -43,26 +56,167 @@ NerdDice.configure do | config|
     # 1 very slow and heavy pressure on processor and memory but very high entropy
     # 1000 would refresh the object every 1000 times you call rand()
   config.refresh_seed_interval = nil # don't refresh the seed
+  # Background and foreground die colors are string values. By default these correspond to the constants in the class
+    # Defaults: DEFAULT_BACKGROUND_COLOR = "#0000DD" DEFAULT_FOREGROUND_COLOR = "#DDDDDD"
+    # It is recommended but not enforced that these should be valid CSS color property attributes
+  config.die_background_color = "red"
+  config.die_foreground_color = "#000"
 end
 ```
+**Note:** You cannot set `ability_score_dice_kept` greater than `ability_score_dice_rolled`. If you try to set `ability_score_dice_kept` higher than `ability_score_dice_rolled`, an error will be raised. If you set `ability_score_dice_rolled` _lower_ than the existing value of `ability_score_dice_kept`, no error will be thrown, but `ability_score_dice_kept` will be _**modified**_ to match `ability_score_dice_rolled` and a warning will be printed.
 
 ### Rolling a number of dice and adding a bonus
+You can use two different methods to roll dice. The `total_dice` method returns an `Integer` representing the total of the dice plus any applicable bonuses. The `total_dice` method does not support chaining additional methods like `highest`, `lowest`, `with_advantage`, `with_disadvantage`. The `roll_dice` method returns a `DiceSet` collection object, and allows for chaining  the methods mentioned above and iterating over the individual `Die` objects. `NerdDice.roll_dice.total` and `NerdDice.total_dice` are roughly equivalent.
+
 ```ruby
 # roll a single d4
 NerdDice.total_dice(4) # => return random Integer between 1-4
+NerdDice.roll_dice(4) # => return a DiceSet with one 4-sided Die with a value between 1-4
+NerdDice.roll_dice(4).total # => return random Integer between 1-4
 
 # roll 3d6
 NerdDice.total_dice(6, 3) # => return Integer total of three 6-sided dice
+NerdDice.roll_dice(6, 3) # => return a DiceSet  with three 6-sided Die objects, each with values between 1-6
+NerdDice.roll_dice(6, 3).total # => return Integer total of three 6-sided dice
 
 # roll a d20 and add 5 to the value
-NerdDice.total_dice(20, bonus: 5)
+NerdDice.total_dice(20, bonus: 5) # rolls a d20 and adds the bonus to the total => Integer
+NerdDice.roll_dice(20, bonus: 5) # return a DiceSet with one 20-sided Die with a value between 1-20 and a bonus attribute of 5
+NerdDice.roll_dice(20, bonus: 5).total # rolls a d20 and adds the bonus to the total => Integer
 
+# without changing the config at the module level
 # roll a d20 and overide the configured randomization_technique one time
-# without changing the config
-NerdDice.total_dice(20, randomization_technique: :randomized)
+NerdDice.total_dice(20, randomization_technique: :randomized) # => Integer
+# roll a d20 and overide the configured randomization_technique for the DiceSet object will persist on the DiceSet object for subsequent rerolls
+NerdDice.roll_dice(20, randomization_technique: :randomized) # => DiceSet with randomization_technique: :randomized
 ```
 __NOTE:__ If provided, the bonus must respond to `:to_i` or an `ArgumentError` will be raised
 
+### Taking actions on the dice as objects using the DiceSet object
+The `NerdDice.roll_dice` method or the `NerdDice::DiceSet.new` methods return a collection object with an array of one or more `Die` objects. There are properties on both the `DiceSet` object and the `Die` object. Applicable properties are cascaded from the `DiceSet` to the `Die` objects in the collection by default.
+
+```ruby
+# These are equivalent
+dice_set = NerdDice.roll_dice(6, 3, bonus: 2, randomization_technique: :randomized, damage_type: 'psychic', foreground_color: '#FFF', background_color: '#0FF')
+# => NerdDice::DiceSet
+dice_set = NerdDice::DiceSet.new(6, 3, bonus: 2, randomization_technique: :randomized, damage_type: 'psychic', foreground_color: '#FFF', background_color: '#0FF')
+# => NerdDice::DiceSet
+```
+#### Available options for NerdDice::DiceSet objects
+There are a number of options that can be provided when initializing a `NerdDice::DiceSet` object after specifying the mandatory number of sides and the optional number of dice \(default: 1\). The list below provides the options and indicates whether they are cascaded to the Die objects in the collection.
+* `bonus` \(Duck-type Integer, _default: 0_\): Bonus or penalty to apply to the total after all dice are rolled.  _**Not applied** to Die objects_
+* `randomization_technique` \(Symbol, _default: nil_\): Randomization technique override to use for the `DiceSet`. If `nil` it will use the value in `NerdDice.configuration`. _**Applied** to Die objects by default with ability modify_
+* `damage_type` \(String, _default: nil_\): Optional string indicating the damage type associated with the dice for systems where it is relevant. _**Applied** to Die objects by default with ability modify_
+* `foreground_color` \(String, _default: `NerdDice.configuration.die_foreground_color`_\): Intended foreground color to apply to the dice in the `DiceSet`. Should be a valid CSS color but is not validated or enforced and doesn\'t currently have any real functionality associated with it.   _**Applied** to Die objects by default with ability modify_
+* `background_color` \(String, _default: `NerdDice.configuration.die_background_color`_\): Intended background color to apply to the dice in the `DiceSet`. Should be a valid CSS color but is not validated or enforced and doesn\'t currently have any real functionality associated with it.   _**Applied** to Die objects by default with ability modify_
+
+#### Properties of individual Die objects
+When initialized from a `DiceSet` object most of the properties of the `Die` object are inherited from the `DiceSet` object. In addition, there is an `is_included_in_total` public attribute that can be set to indicate whether the value of that particular die should be included in the total for its parent `DiceSet`. This property always starts out as true when the `Die` is initialized, but can be set to false.
+
+```ruby
+# six sided die
+die = NerdDice::Die.new(6, randomization_technique: :randomized, damage_type: 'psychic', foreground_color: '#FFF', background_color: '#0FF')
+die.is_included_in_total # => true
+die.included_in_total? # => true
+die.is_included_in_total  = false
+die.included_in_total? # => false
+
+# value property
+die.value # =>  Integer between 1 and number_of_sides
+die.roll # => Integer. Rolls/rerolls the Die and sets value to the result of the roll. Returns the new value
+```
+#### Iterating through dices in a DiceSet
+The `DiceSet` class mixes in the `Enumerable` module and the `Die` object mixes in the `Comparable` module. This allows you to iterate over the dice in the collection. The `sort` method on the dice will return the die objects in ascending value from lowest to highest.
+
+```ruby
+dice_set = NerdDice.roll_dice(6, 3) # => NerdDice::DiceSet
+dice_set.dice => Array of Die objects
+dice_set.length # => 3. (dice_set.dice.length)
+dice_set[0] # => NerdDice::Die (first element of dice array)
+# take actions on each die
+dice_set.each do |die|
+  # print the current value
+  puts "Die value before reroll is #{die.value}"
+  # set the foreground_color of the die
+  die.foreground_color = ["gray", "#FF0000#", "#d9d9d9", "green"].shuffle.first
+  # reroll the die
+  die.roll
+  # print the new value
+  puts "Die value after reroll is #{die.value}"
+  # do other things
+end
+```
+#### Methods and method chaining on the DiceSet
+Since the DiceSet is an object, you can call methods that operate on the result returned and allow for things like the 5e advantage/disadvantage mechanic, the ability to re-roll all of the dice in the `DiceSet`, or to mark them all as included in the total.
+
+```ruby
+##############################################
+# highest/with_advantage and lowest/with_disadvantage methods
+#       assuming 4d6 with values of [1, 3, 4, 6]
+##############################################
+dice_set = NerdDice.roll_dice(6, 4)
+# the 6, 4, and 3 will have is_included_in_total true while the 1 has it false
+dice_set.highest(3) # => Returns the existing DiceSet object with the changes made to dice inclusion
+dice_set.with_advantage(3) # => Alias of highest method
+# calling total after highest/with_advantage for this DiceSet
+dice_set.total # => 13
+# same DiceSet using lowest. The 1, 3, and 4 will have is_included_in_total true while the 6 has it false
+dice_set.lowest(3) # => Returns the existing DiceSet object with the changes made to dice inclusion
+dice_set.with_disadvantage(3) # => Alias of lowest method
+# calling total after lowest/with_disadvantage for this DiceSet
+dice_set.total # => 8
+# you can chain these methods (assumes the same seed as the above examples)
+NerdDice.roll_dice(6, 4).with_advantage(3).total # => 13
+NerdDice.roll_dice(6, 4).lowest(3).total # => 8
+
+# reroll_all! method
+dice_set = NerdDice.roll_dice(6, 4)
+dice_set.reroll_all! # rerolls each of the Die objects in the collection and re-includes them in the total
+
+# include_all_dice! method
+dice_set.include_all_dice! # resets is_included_in_total to true for all Die objects
+```
+
+### Rolling Ability Scores
+You can call `roll_ability_scores` or `total_ability_scores` to get back an array of `DiceSet` objects or `Integer` objects, respectively. The `total_ability_scores` method calls `total` on each `DiceSet` and returns those numbers with one value per ability score. The `Configuration` object defaults to 6 ability scores using a methodology of __4d6 drop the lowest__ by default.
+
+```ruby
+# return an array of DiceSet objects including info about the discarded dice
+#
+NerdDice.roll_ability_scores
+#=> [DiceSet0, DiceSet1, ...]
+   # => DiceSet0 hash representation { total: 12, dice: [
+   #             {value: 2, is_included_in_total: true},
+   #             {value: 6, is_included_in_total: true},
+   #             {value: 4, is_included_in_total: true},
+   #             {value: 1, is_included_in_total: false}
+   #         ]}
+# if you want to get back DiceSet objects that you can interact with
+
+# just return an array of totaled ability scores
+NerdDice.total_ability_scores
+#=> [12, 14, 13, 15, 10, 8]
+```
+
+Both methods can be called without arguments to use the values specified in `NerdDice.configuration` or passed a set of options.
+```ruby
+
+# total_dice and roll_dice take the same set of options
+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"
+     )
+# => [DiceSet0, DiceSet1, ...] with 7 ability scores that each roll 5d8 dropping the lowest
+# or if called with total_ability_scores
+# => [27, 17, 21, 17, 23, 13, 27]
+```
+**Note:** If you try to call this method with `ability_score_dice_kept` greater than `ability_score_dice_rolled` an error will be raised.
+
 ### Manually setting or refreshing the random generator seed
 For randomization techniques other than `:securerandom` you can manually set or refresh the generator's seed by calling the `refresh_seed!` method. This is automatically called at the interval specified in `NerdDice.configuration.refresh_seed_interval` if it is not nil.
 
@@ -80,6 +234,23 @@ NerdDice.refresh_seed!(randomization_technique:  :randomized,
 ```
 __NOTE:__ Ability to specify a seed it primarily provided for testing purposes. This makes all random numbers generated _transparently deterministic_ and should not be used if you want behavior approximating randomness.
 
+### Utility Methods
+
+#### Harvesting Totals from DiceSets
+The `harvest_totals` method take any collection of objects where each element responds to `total` and return an array of the results of the total method.
+```ruby
+ability_score_array = NerdDice.roll_ability_scores
+# => Array of 6 DiceSet objects
+
+# 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
+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
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -88,8 +259,9 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/statelesscode/nerd_dice/issues. We welcome and encourage your participation in this open-source project. We welcome those of all backgrounds and abilities, but we refuse to adopt the Contributor Covenant for reasons outlined in [BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md](BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md)
+Bug reports and pull requests are welcome on GitHub at https://github.com/statelesscode/nerd_dice/issues. We welcome and encourage your participation in this open-source project. We welcome those of all backgrounds and abilities, but we refuse to adopt the Contributor Covenant for reasons outlined in [BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md](https://github.com/statelesscode/nerd_dice/blob/master/BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md)
+
 
 ## Unlicense, License, and Copyright
 
-The document is dual-licensed under the [MIT](https://opensource.org/licenses/MIT) license and the [UNLICENSE](https://unlicense.org/) \(with strong preference toward the UNLICENSE\)\. The content is released under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) \(no rights reserved\). You are free to include it in its original form or modified with or without modification in your own project\.
+The document is dual-licensed under the [MIT](https://opensource.org/licenses/MIT) license and the [UNLICENSE](https://unlicense.org/) \(with strong preference toward the UNLICENSE\)\. The content is released under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) \(no rights reserved\). You are free to include it in its original form or modified with or without additional modification in your own project\.

data/bin/generate_checksums

@@ -7,7 +7,7 @@ version = ARGV[0]
 built_gem_path = "pkg/nerd_dice-#{version}.gem"
 checksum = Digest::SHA512.new.hexdigest(File.read(built_gem_path))
 checksum_path = "checksum/nerd_dice-#{version}.gem.sha512"
-File.write(checksum_path, checksum)
+File.open(checksum_path, "w") { |f| f.write(checksum) }
 sha256 = Digest::SHA256.new.hexdigest(File.read(built_gem_path))
 checksum_256_path = "checksum/nerd_dice-#{version}.gem.sha256"
-File.write(checksum_256_path, sha256)
+File.open(checksum_256_path, "w") { |f| f.write(sha256) }

data/bin/nerd_dice_benchmark

@@ -8,14 +8,24 @@ require "nerd_dice"
 n = 50_000
 
 RATIOS = {
-  nerd_dice_securerandom: 1.7,
-  nerd_dice_random_rand: 11.1,
-  nerd_dice_random_object: 13.0,
-  nerd_dice_randomized: 5.5,
-  nerd_dice_securerandom_3d6: 5.5,
-  nerd_dice_random_rand_3d6: 25.0,
-  nerd_dice_random_object_3d6: 25.5,
-  nerd_dice_randomized_3d6: 14.5
+  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)
@@ -44,22 +54,22 @@ securerandom_baseline = baselines[1].real
 puts "Roll d1000s"
 total_dice_d1000_results = Benchmark.bmbm do |x|
   # NerdDice.total_dice securerandom
-  x.report("nerd_dice_securerandom") do
+  x.report("total_dice_securerandom") do
     NerdDice.configuration.randomization_technique = :securerandom
     n.times { NerdDice.total_dice(1000) }
   end
 
-  x.report("nerd_dice_random_rand") do
+  x.report("total_dice_random_rand") do
     NerdDice.configuration.randomization_technique = :random_rand
     n.times { NerdDice.total_dice(1000) }
   end
 
-  x.report("nerd_dice_random_object") do
+  x.report("total_dice_random_object") do
     NerdDice.configuration.randomization_technique = :random_object
     n.times { NerdDice.total_dice(1000) }
   end
 
-  x.report("nerd_dice_randomized") do
+  x.report("total_dice_randomized") do
     NerdDice.configuration.randomization_technique = :randomized
     n.times { NerdDice.total_dice(1000) }
   end
@@ -74,25 +84,57 @@ 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("nerd_dice_securerandom_3d6") do
+  x.report("total_dice_securerandom_3d6") do
     NerdDice.configuration.randomization_technique = :securerandom
     n.times { NerdDice.total_dice(6, 3) }
   end
 
-  x.report("nerd_dice_random_rand_3d6") do
+  x.report("total_dice_random_rand_3d6") do
     NerdDice.configuration.randomization_technique = :random_rand
     n.times { NerdDice.total_dice(6, 3) }
   end
 
-  x.report("nerd_dice_random_object_3d6") do
+  x.report("total_dice_random_object_3d6") do
     NerdDice.configuration.randomization_technique = :random_object
     n.times { NerdDice.total_dice(6, 3) }
   end
 
-  x.report("nerd_dice_randomized_3d6") do
+  x.report("total_dice_randomized_3d6") do
     NerdDice.configuration.randomization_technique = :randomized
     n.times { NerdDice.total_dice(6, 3) }
   end
@@ -106,3 +148,57 @@ 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/certs/msducheminjr.pem

@@ -1,27 +1,26 @@
 -----BEGIN CERTIFICATE-----
-MIIEhTCCAu2gAwIBAgIBATANBgkqhkiG9w0BAQsFADBEMRYwFAYDVQQDDA1zdGF0
-ZWxlc3Njb2RlMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZ
-FgNjb20wHhcNMjMwMjIzMjMyMTQwWhcNMjQwMjIzMjMyMTQwWjBEMRYwFAYDVQQD
-DA1zdGF0ZWxlc3Njb2RlMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJ
-k/IsZAEZFgNjb20wggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQCxVzHS
-gYszan//tjTSO0z59UO1rUiT5G0//iyhiaYIiuwxhYFbfD+wOCou4M18pQtEb4qx
-o67tPfGimBAVak6fGfo8fo1ByHiKCvx3jgOjxNifT9pRFlBSr6ZvyXeu7zA0ddLr
-slw92DNqeRlZXqB0mxDtpKWONGc1XhAqEjEP3VL7g7x0xPQShcpXg/OyRPR5vyv8
-66pXdFrXYZGrySfIB6ZOWFV6wGBj603rPdXOeYVeks6hKvw3wb4G1s7tvwTA5MWI
-otw6Mp9TaMdms9zTc5A3N58pueKfBJfwkICkdAGJDWC6sIXECoaTDRqVK96RSH/1
-8tEPDoFYpJDOa5byX1j7srwO0B6WOtPxix7gW1wBbEp7eWSQf1k3k9XEh32SRsPq
-NJObRfhkzoa9p1tPkVP3nasDTK5gtisolwhb7Vimeup54yKfT/THv2iNEnGTvK1P
-sV4vC8nch88lBI1mIecmSh/mwED4Mb1dNtcyuB/+XnSI8vIzXJKAAKaT0eMCAwEA
-AaOBgTB/MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBRP42hSa0JV
-QGDSobiGTYyfM570hjAiBgNVHREEGzAZgRdzdGF0ZWxlc3Njb2RlQGdtYWlsLmNv
-bTAiBgNVHRIEGzAZgRdzdGF0ZWxlc3Njb2RlQGdtYWlsLmNvbTANBgkqhkiG9w0B
-AQsFAAOCAYEANtaR6OV7p1IJOsvVgGQzVg88NIOeXrfOaEDUPb6eg4JMOSL0Cvvl
-2F7lB/ykbQcO4Oe7NucuavC7ClyG3c/V5eQ5TtPNWkMbVN9ESVR8wk5SjhiI8L35
-MBxJ6YU27eyDmazQJ7eCYcRJkuyWt3KcqgsEh7JyNnKcJ/3rgf1QW0IyJiGsXM1I
-SssQ/t7Ia2tVMrVMsvs834v9FRpVbO3dHdCO4t7zQBIADVcj4NqCDV10D6aji/Aa
-35YJHwlkhuZH6AYC45QHt9dW0/OLmbFwoJqW7syrso2PParyMr4YcJwucXViRiL7
-l5aVpYdz/RTqdB92Mmud5Hj5zkuEE4CHBh8L8AJC5kZu/YUXXDtuECSMVhg5O84h
-QsdcuygyVASmw2aliMAFXfIBDYelduG0XwjdOREN3q4SDTKP+pfBxx6OdD1RfsYF
-/9HhtVbKLq34iQftF4oIH66bYDEyG5y4CLKQ8Nq0WDWq50OcaP9KpDiS21BC43SW
-t+NX7PDOWx4k
+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/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