nerd_dice 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a931b4532dcafcb4ce3aeddf3ac30399bb9334d25bf78671a0811366670d719
-  data.tar.gz: 970d96a32b68dc1fc75618376bf059707c5c711441d30edd6302dcd37e831c8b
+  metadata.gz: fa0fb8eebb2386727cce81ce7a3c301599322a3531db13f01329aa26225c88b3
+  data.tar.gz: 205640e5b275ae107e0c2ee0ff1c10b777782f21c7a3c0ae7a5aac98e27f4841
 SHA512:
-  metadata.gz: 5cdbd36e786d2c4e6f8950f4486119548bb1a62babdbf3c9ae4fadba095170b9300461411926d19ca50e5e8d277804c3f8cb61e28d96605fd5fad8b7e9c9b700
-  data.tar.gz: 21b2b92dbf7ad4060a888d267383e9c87b3e310dff4931bb1853f401fb417f480a2bea7cca859ad75d3eac83608a4631541a36afc7449955a68ea8ff84c319c7
+  metadata.gz: 0d275950feb1506a5a7602450690dab697c0ccd35b8d85a0869c4675c2dd714c85d2c744854ac7f69c7f204b1e55ecbf7e80f9209eb672ef4705d15fdbd10fd7
+  data.tar.gz: fb8d5aa2297ecbf722b9242caf2680272a502d801dbd94fd53c6bd359a21a50e6e0e1096a5c5518a25a9ef842609c6db0af7c6b5273f4a1fd2e4f2f6089d393e

data/.github/workflows/main.yml

@@ -0,0 +1,67 @@
+# This is a basic workflow to help you get started with Actions
+
+name: Nerd Dice CI
+
+# Controls when the action will run.
+on: [push, pull_request]
+
+  # Allows you to run this workflow manually from the Actions tab
+  # workflow_dispatch:
+
+jobs:
+  test_rspec:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake
+    - name: Coveralls Parallel
+      uses: coverallsapp/github-action@master
+      with:
+        github-token: ${{ secrets.github_token }}
+        flag-name: run-${{ matrix.test_number }}
+        parallel: true
+
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.0'
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run rubocop
+      run: bundle exec rubocop --parallel
+
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.0'
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run benchmark script
+      run: bin/nerd_dice_benchmark
+
+  finish:
+    needs: test_rspec
+    runs-on: ubuntu-latest
+    steps:
+    - name: Coveralls Finished
+      uses: coverallsapp/github-action@master
+      with:
+        github-token: ${{ secrets.github_token }}
+        parallel-finished: true

data/.rubocop.yml

@@ -334,3 +334,69 @@ Style/EndlessMethod: # (new in 1.8)
 
 Style/HashExcept: # (new in 1.7)
   Enabled: true
+
+# Added 2021-08-14
+Gemspec/DateAssignment: # (new in 1.10)
+  Enabled: true
+
+Layout/LineEndStringConcatenationIndentation: # (new in 1.18)
+  Enabled: true
+
+Lint/EmptyInPattern: # (new in 1.16)
+  Enabled: true
+
+Lint/NumberedParameterAssignment: # (new in 1.9)
+  Enabled: true
+
+Lint/OrAssignmentToConstant: # (new in 1.9)
+  Enabled: true
+
+Lint/SymbolConversion: # (new in 1.9)
+  Enabled: true
+
+Lint/TripleQuotes: # (new in 1.9)
+  Enabled: true
+
+Naming/InclusiveLanguage: # (new in 1.18)
+  Enabled: false
+
+Style/HashConversion: # (new in 1.10)
+  Enabled: true
+
+Style/IfWithBooleanLiteralBranches: # (new in 1.9)
+  Enabled: true
+
+Style/InPatternThen: # (new in 1.16)
+  Enabled: true
+
+Style/MultilineInPatternThen: # (new in 1.16)
+  Enabled: true
+
+Style/QuotedSymbols: # (new in 1.16)
+  Enabled: true
+
+Style/StringChars: # (new in 1.12)
+  Enabled: true
+
+Performance/MapCompact: # (new in 1.11)
+  Enabled: true
+
+Performance/RedundantEqualityComparisonBlock: # (new in 1.10)
+  Enabled: true
+
+Performance/RedundantSplitRegexpArgument: # (new in 1.10)
+  Enabled: true
+
+RSpec/IdenticalEqualityAssertion: # (new in 2.4)
+  Enabled: true
+
+RSpec/Rails/AvoidSetupHook: # (new in 2.4)
+  Enabled: true
+
+RSpec/MessageSpies:
+  EnforcedStyle: receive
+
+Lint/AmbiguousRange: # new in 1.19
+  Enabled: true
+Style/RedundantSelfAssignmentBranch: # new in 1.19
+  Enabled: true

data/CHANGELOG.md

@@ -5,7 +5,35 @@
 ### Changed
 ### Fixed
 
-## 0.2.0 \(2020-12-12\)
+## 0.3.0 \(2021-09-11\)
+### Added
+* Add new options to `NerdDice::Configuration`
+  - `ability_score_number_of_sides`
+  - `ability_score_dice_rolled`
+  - `ability_score_dice_kept`
+* Add `NerdDice.harvest_totals` method that takes in a collection and returns the results of calling `total` on each element
+* Add `NerdDice.roll_ability_scores` convenience method that returns an array of `DiceSet` objects based on options and/or configuration
+* Add `NerdDice.total_ability_scores` convenience method that returns an array of integers based on options and/or configuration
+* Add `NerdDice::Die` class that represents a single die object and mixes in the `Comparable` module
+* Add `NerdDice::DiceSet` class that represents a collection of `Die` objects and mixes in the `Enumerable` module
+* Add `NerdDice::SetsRandomizationTechnique` mixin module and include in the `DiceSet` and `Die` classes
+* Add `die_background_color` and `die_foreground_color` to `Configuration` class with defaults defined as constants
+* Add `NerdDice.roll_dice` method that behaves in a similar fashion to `total_dice` but returns a `DiceSet` object instead of an `Integer` and has additional optional arguments relating to the non-numeric attributes of the dice
+* Add `coveralls_reborn` to RSpec and GitHub actions
+* Add build badge to README
+* Add Code Climate maintainability integration and badge to README
+* Add `nerd_dice_benchmark` script to bin directory
+* Add GitHub Action CI build
+  - Run RSpec test suite, fail if specs fail, report coverage via Coveralls
+  - Run RuboCop and fail if violations
+  - Run benchmark suite and fail if outside of allowed ratios
+### Changed
+* Update RuboCop version and configuration
+* Break up the NerdDice source code file into several smaller files that are included by the module
+* Enforce that `NerdDice.configuration.ability_score_array_size` must be a positive duck-type integer
+### Fixed
+
+## 0.2.0 \(2021-01-28\)
 ### Added
 * Add ability to configure with `NerdDice.configure` block or `NerdDice.configuration`
   - Configure `randomization_technique` as `:random_rand`, `:securerandom`, `:random_object`, or `randomized`

data/Gemfile.lock

@@ -1,21 +1,27 @@
 PATH
   remote: .
   specs:
-    nerd_dice (0.2.0)
+    nerd_dice (0.3.0)
       securerandom (~> 0.1, >= 0.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    coveralls_reborn (0.22.0)
+      simplecov (>= 0.18.1, < 0.22.0)
+      term-ansicolor (~> 1.6)
+      thor (>= 0.20.3, < 2.0)
+      tins (~> 1.16)
     diff-lcs (1.4.4)
+    docile (1.4.0)
     parallel (1.20.1)
-    parser (3.0.0.0)
+    parser (3.0.2.0)
       ast (~> 2.4.1)
     rainbow (3.0.0)
     rake (12.3.3)
-    regexp_parser (2.0.3)
-    rexml (3.2.4)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
       rspec-expectations (~> 3.10.0)
@@ -25,44 +31,59 @@ GEM
     rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.1)
+    rspec-mocks (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-support (3.10.1)
-    rubocop (1.8.1)
+    rspec-support (3.10.2)
+    rubocop (1.20.0)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.2.0, < 2.0)
+      rubocop-ast (>= 1.9.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.4.1)
-      parser (>= 2.7.1.5)
-    rubocop-performance (1.9.2)
-      rubocop (>= 0.90.0, < 2.0)
+    rubocop-ast (1.11.0)
+      parser (>= 3.0.1.1)
+    rubocop-performance (1.11.5)
+      rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
-    rubocop-rake (0.5.1)
-      rubocop
-    rubocop-rspec (2.1.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.4.0)
       rubocop (~> 1.0)
       rubocop-ast (>= 1.1.0)
     ruby-progressbar (1.11.0)
     securerandom (0.1.0)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov-lcov (0.8.0)
+    simplecov_json_formatter (0.1.3)
+    sync (0.5.0)
+    term-ansicolor (1.7.1)
+      tins (~> 1.0)
+    thor (1.1.0)
+    tins (1.29.1)
+      sync
     unicode-display_width (2.0.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  coveralls_reborn (~> 0.22.0)
   nerd_dice!
   rake (~> 12.0)
   rspec (~> 3.0)
-  rubocop (~> 1.8, >= 1.8.1)
-  rubocop-performance (~> 1.9, >= 1.9.1)
-  rubocop-rake (~> 0.5, >= 0.5.1)
-  rubocop-rspec (~> 2.1, >= 2.1.0)
+  rubocop (~> 1.20, >= 1.20.0)
+  rubocop-performance (~> 1.11, >= 1.11.5)
+  rubocop-rake (~> 0.6, >= 0.6.0)
+  rubocop-rspec (~> 2.4, >= 2.4.0)
+  simplecov-lcov (~> 0.8.0)
 
 BUNDLED WITH
-   2.2.3
+   2.2.22

data/README.md

@@ -1,6 +1,12 @@
+[![Coverage Status](https://coveralls.io/repos/github/statelesscode/nerd_dice/badge.svg?branch=master)](https://coveralls.io/github/statelesscode/nerd_dice?branch=master)
+![Build](https://github.com/statelesscode/nerd_dice/actions/workflows/main.yml/badge.svg)
+[![Maintainability](https://api.codeclimate.com/v1/badges/721f587b792d583065be/maintainability)](https://codeclimate.com/github/statelesscode/nerd_dice/maintainability)
 # 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:
@@ -25,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.
@@ -40,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.
 
@@ -77,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.
@@ -90,4 +264,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/statel
 
 ## 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\.