nerd_dice 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa0fb8eebb2386727cce81ce7a3c301599322a3531db13f01329aa26225c88b3
-  data.tar.gz: 205640e5b275ae107e0c2ee0ff1c10b777782f21c7a3c0ae7a5aac98e27f4841
+  metadata.gz: 8f64389429514a7d0c2a8410b2e27575e5c11b316b50cee41b37c58d8f8af953
+  data.tar.gz: 4d2365e3ce8139d4675695dfe47edf9ef5d52b9cc873beb5c7c314b8955aaa33
 SHA512:
-  metadata.gz: 0d275950feb1506a5a7602450690dab697c0ccd35b8d85a0869c4675c2dd714c85d2c744854ac7f69c7f204b1e55ecbf7e80f9209eb672ef4705d15fdbd10fd7
-  data.tar.gz: fb8d5aa2297ecbf722b9242caf2680272a502d801dbd94fd53c6bd359a21a50e6e0e1096a5c5518a25a9ef842609c6db0af7c6b5273f4a1fd2e4f2f6089d393e
+  metadata.gz: d8bf0ea2c85e3aedf952d82d0f511463accedcad5122b14a7d6769a94100902887ca0e52cf85a6d8b69a75a6cd750858852ad71e34980e61624d39666bedff5b
+  data.tar.gz: ee2e8117b3071872a3d07353dabd4685c4a20e188591e80cbcb93609ba9f134ab22082ae01bee152c34c9cdd1a81a6a40aec2b1521d3e2a106d10f0c8fa313ae

data/.rubocop.yml

@@ -400,3 +400,22 @@ Lint/AmbiguousRange: # new in 1.19
   Enabled: true
 Style/RedundantSelfAssignmentBranch: # new in 1.19
   Enabled: true
+
+Lint/AmbiguousOperatorPrecedence: # new in 1.21
+  Enabled: true
+Lint/IncompatibleIoSelectWithFiberScheduler: # new in 1.21
+  Enabled: true
+Lint/RequireRelativeSelfPath: # new in 1.22
+  Enabled: true
+Security/IoMethods: # new in 1.22
+  Enabled: true
+Style/NumberedParameters: # new in 1.22
+  Enabled: true
+Style/NumberedParametersLimit: # new in 1.22
+  Enabled: true
+Style/SelectByRegexp: # new in 1.22
+  Enabled: true
+RSpec/ExcessiveDocstringSpacing: # new in 2.5
+  Enabled: true
+RSpec/SubjectDeclaration: # new in 2.5
+  Enabled: true

data/CHANGELOG.md

@@ -5,6 +5,18 @@
 ### Changed
 ### Fixed
 
+## 0.4.0 \(2021-10-23\)
+### Added
+* Add `NerdDice::ConvenienceMethods` method_missing mixin module that allows for dynamic invocation of patterns in the method name that get converted into calls to `NerdDice.roll_dice` or `NerdDice.total_dice` along with allowing the advantage/disadvantage mechanic or bonuses to be parsed from the method name. Full documentation of the module can be found in the [Convenience Methods Mixin](README.md#convenience-methods-mixin) section of the README.
+* Add exensive specs to support the ConvenienceMethods module
+### Changed
+* Replace `Benchmark.bmbm` with `Benchmark.bm` in the nerd_dice_benchmark
+* Add convenience_methods to nerd_dice_benchmark
+* Extend `NerdDice::ConvenienceMethods` into top-level module as class methods
+### Fixed
+* Fix typos and horizontal scrolling in README
+* Fix CodeClimate Code Smell on harvest_totals
+
 ## 0.3.0 \(2021-09-11\)
 ### Added
 * Add new options to `NerdDice::Configuration`

data/Gemfile

@@ -5,5 +5,5 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in nerd_dice.gemspec
 gemspec
 
-gem "rake", "~> 12.0"
-gem "rspec", "~> 3.0"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.10"

data/Gemfile.lock

@@ -1,25 +1,25 @@
 PATH
   remote: .
   specs:
-    nerd_dice (0.3.0)
-      securerandom (~> 0.1, >= 0.1.0)
+    nerd_dice (0.4.0)
+      securerandom (~> 0.1, >= 0.1.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    coveralls_reborn (0.22.0)
+    coveralls_reborn (0.23.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)
+    parallel (1.21.0)
     parser (3.0.2.0)
       ast (~> 2.4.1)
     rainbow (3.0.0)
-    rake (12.3.3)
+    rake (13.0.6)
     regexp_parser (2.1.1)
     rexml (3.2.5)
     rspec (3.10.0)
@@ -35,27 +35,26 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
-    rubocop (1.20.0)
+    rubocop (1.22.2)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.9.1, < 2.0)
+      rubocop-ast (>= 1.12.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.11.0)
+    rubocop-ast (1.12.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.6.0)
       rubocop (~> 1.0)
-    rubocop-rspec (2.4.0)
-      rubocop (~> 1.0)
-      rubocop-ast (>= 1.1.0)
+    rubocop-rspec (2.5.0)
+      rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
-    securerandom (0.1.0)
+    securerandom (0.1.1)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -69,20 +68,20 @@ GEM
     thor (1.1.0)
     tins (1.29.1)
       sync
-    unicode-display_width (2.0.0)
+    unicode-display_width (2.1.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  coveralls_reborn (~> 0.22.0)
+  coveralls_reborn (~> 0.23.0)
   nerd_dice!
-  rake (~> 12.0)
-  rspec (~> 3.0)
-  rubocop (~> 1.20, >= 1.20.0)
+  rake (~> 13.0)
+  rspec (~> 3.10)
+  rubocop (~> 1.22, >= 1.22.2)
   rubocop-performance (~> 1.11, >= 1.11.5)
   rubocop-rake (~> 0.6, >= 0.6.0)
-  rubocop-rspec (~> 2.4, >= 2.4.0)
+  rubocop-rspec (~> 2.5, >= 2.5.0)
   simplecov-lcov (~> 0.8.0)
 
 BUNDLED WITH

data/README.md

@@ -24,6 +24,15 @@ Or install it yourself as:
     $ gem install nerd_dice
 
 ## Usage
+After the gem is installed, you can require it as you would any other gem.
+
+```ruby
+require 'nerd_dice'
+```
+
+### Module methods or a dynamic method_missing DSL
+There are two main patterns for using NerdDice in your project. You can invoke the module-level methods like `NerdDice.total_dice` or you can include the `NerdDice::ConvenienceMethods` module to your class \(or IRB \). Once mixed in, you can dynamically invoke methods like `roll_d20_with_advantage` or `total_3d8_plus5`. See the [Convenience Methods Mixin](#convenience-methods-mixin)  section for usage details.
+
 ### Configuration
 You can customize the behavior of NerdDice via a configuration block as below or by assigning an individual property via the ```NerdDice.configuration.property = value``` syntax \(where ```property``` is the config property and ```value``` is the value you want to assign\)\. The available configuration options as well as their defaults, if applicable, are listed in the example configuration block below:
 
@@ -39,7 +48,9 @@ NerdDice.configure do | config|
   # 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
+  # highest(n) dice from the total number of dice rolled
+  # that are included in the ability scoretotal
+  #
   # CANNOT EXCEED ability_score_dice_rolled see Note below
   config.ability_score_dice_kept = 3 # must duck-type to positive Integer
 
@@ -49,14 +60,16 @@ NerdDice.configure do | config|
       # (Seed is shared with other processes. Too predictable)
     # :random_object => Uses Random.new() and calls rand()
       # Medium entropy, fastest speed. (Performs the best under speed benchmark)
-    # :randomized => Uses a random choice of the :securerandom, :rand, and :random_new_interval options above
+    # :randomized =>
+    #  Uses a random choice of the :securerandom, :rand, and :random_new_interval options above
   config.randomization_technique = :random_object # fast with independent seed
 
   # Number of iterations to use on a generator before refreshing the seed
     # 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
+  # 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"
@@ -70,25 +83,26 @@ You can use two different methods to roll dice. The `total_dice` method returns
 
 ```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
+NerdDice.total_dice(4) # => Integer: between 1-4
+NerdDice.roll_dice(4) # => DiceSet: with one 4-sided Die with a value between 1-4
+NerdDice.roll_dice(4).total # => 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
+NerdDice.total_dice(6, 3) # => Integer: total of three 6-sided dice
+NerdDice.roll_dice(6, 3) # => DiceSet: three 6-sided Die objects, each with values between 1-6
+NerdDice.roll_dice(6, 3).total # => Integer: total of three 6-sided dice
 
 # roll a d20 and add 5 to the value
-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
+NerdDice.total_dice(20, bonus: 5) # => Integer: roll a d20 and add the bonus to the total
+NerdDice.roll_dice(20, bonus: 5) # => DiceSet: one 20-sided Die and bonus of 5
+NerdDice.roll_dice(20, bonus: 5).total # => Integer: roll a d20 and add the bonus to the total
 
 # without changing the config at the module level
 # roll a d20 and overide the configured randomization_technique one time
 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
+# 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 :randomized
 ```
 __NOTE:__ If provided, the bonus must respond to `:to_i` or an `ArgumentError` will be raised
 
@@ -96,26 +110,29 @@ __NOTE:__ If provided, the bonus must respond to `:to_i` or an `ArgumentError` w
 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
+# These are equivalent. Both return a NerdDice::DiceSet
+dice_set = NerdDice.roll_dice(6, 3, bonus: 2, randomization_technique: :randomized,
+                       damage_type: 'psychic', foreground_color: '#FFF', background_color: '#0FF')
+
+dice_set = NerdDice::DiceSet.new(6, 3, bonus: 2, randomization_technique: :randomized,
+                       damage_type: 'psychic', foreground_color: '#FFF', background_color: '#0FF')
+
 ```
 #### 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_
+* `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 to 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 to 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 to 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 to 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 = 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
@@ -123,9 +140,11 @@ 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
+
+# Rolls/rerolls the Die, sets value to the result of the roll, and returns the new value
+die.roll # => Integer.
 ```
-#### Iterating through dices in a DiceSet
+#### Iterating through dice 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
@@ -155,23 +174,31 @@ Since the DiceSet is an object, you can call methods that operate on the result
 #       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
+# Returns the existing DiceSet object with the changes made to dice inclusion
+dice_set.highest(3) # => DiceSet
+dice_set.with_advantage(3) # => DiceSet (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
+
+# 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) # => DiceSet
+dice_set.with_disadvantage(3) # => DiceSet (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
+# rerolls each of the Die objects in the collection and re-includes them in the total
+dice_set.reroll_all!
 
 # include_all_dice! method
 dice_set.include_all_dice! # resets is_included_in_total to true for all Die objects
@@ -232,7 +259,7 @@ NerdDice.refresh_seed!(randomization_technique:  :randomized,
                        random_rand_seed:         1337,
                        random_object_seed:       24601)
 ```
-__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.
+__NOTE:__ Ability to specify a seed is 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
 
@@ -250,6 +277,126 @@ 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
 ```
+<a name="convenience-methods-mixin"></a>
+### Convenience Methods Mixin
+NerdDice provides an optional mixin `NerdDice::ConvenienceMethods` that uses Ruby\'s `method_missing` metaprogramming pattern to allow you to roll any number of dice with bonuses and/or the advantage/disadvantage mechanic by dynamically responding to methods that you type that match the `roll_` or `total_` pattern.
+
+#### Considerations for ConvenienceMethods
+Before mixing in this method with a class, be aware of other `method_missing` gems that you are also mixing into your project and be sure to write robust tests. We have sought to use `method_missing` in a responsible manner that delegates back to the default implementation using `super` if the method does not match the `ConvenienceMethods` pattern, but there is no guarantee that other gems included in your project are doing the same. If you run into problems with the `ConvenienceMethods` module interacting with other `method_missing` gems, everything that the `ConvenienceMethods` module does can be replicated using the module\-level methods described above or by calling the convenience method on `NerdDice`.
+
+Once a particular method has been called, it will define that method so that the next time it will invoke the method directly instead of traversing up the call stack for `method_missing`, which improves performance. The method will remain defined for the duration of the Ruby interpreter process.
+
+#### Calling ConvenienceMethods as NerdDice class methods
+NerdDice extends the `ConvenienceMethods` module into the top-level module as class methods, so you can call the methods on the NerdDice module without needing to worry about the implications of extending it into your own class.
+```ruby
+require 'nerd_dice'
+# works with all the examples and patterns below
+NerdDice.roll_3d6_lowest2_minus1
+NerdDice.total_d20_with_advantage_p6
+```
+
+#### Mixing in the ConvenienceMethods module
+To mix the NerdDice DSL into your class, make sure the gem is required if not already and then use `include NerdDice::ConvenienceMethods` as shown below:
+```ruby
+# example of a class that mixes in NerdDice::ConvenienceMethods
+require 'nerd_dice'
+class Monster
+  include NerdDice::ConvenienceMethods
+
+  # hard-coding probably not the best solution
+  # but gives you an idea how to mix in to a simple class
+  def hits_the_monster
+    # using the ConvenienceMethods version
+    total_d20_plus5 >= @armor_class ? "hit" : "miss"
+  end
+
+  def initialize(armor_class=16)
+    @armor_class = armor_class
+  end
+end
+```
+To mix in the module as class methods, you can use `extend NerdDice::ConvenienceMethods`
+```ruby
+# example of a class that mixes in NerdDice::ConvenienceMethods
+require 'nerd_dice'
+class OtherClass
+  extend NerdDice::ConvenienceMethods
+end
+OtherClass.roll_3d6_lowest2_minus1 # returns NerdDice::DiceSet
+```
+
+#### ConvenienceMethods usage examples
+Any invocation of `NerdDice.roll_dice` and `NerdDice.total_dice` can be duplicated using the `NerdDice::ConvenienceMethods` mixin. Here are some examples of what you can do with the return types and equivalent methods in the comments:
+
+* `roll_dNN` and `total_dNN` roll one die
+```ruby
+roll_d20 # => DiceSet: NerdDice.roll_dice(20)
+roll_d8 # => DiceSet: NerdDice.roll_dice(8)
+roll_d1000 # => DiceSet: NerdDice.roll_dice(1000)
+total_d20 # => Integer NerdDice.total_dice(20)
+total_d8 # => Integer NerdDice.total_dice(8)
+total_d1000 # => Integer NerdDice.total_dice(1000)
+```
+* `roll_NNdNN` and `total_NNdNN` roll specified quantity of dice
+```ruby
+roll_2d20 # => DiceSet: NerdDice.roll_dice(20, 2)
+roll_3d8 # => DiceSet: NerdDice.roll_dice(8, 3)
+roll_22d1000 # => DiceSet: NerdDice.roll_dice(1000, 22)
+total_2d20 # => Integer NerdDice.total_dice(20, 2)
+total_3d8 # => Integer NerdDice.total_dice(8, 3)
+total_22d1000 # => Integer NerdDice.total_dice(1000, 22)
+```
+* Keyword arguments are passed on to `roll_dice`/`total_dice` method
+```ruby
+roll_2d20 foreground_color: "blue" # => DiceSet: NerdDice.roll_dice(20, 2, foreground_color: "blue")
+
+total_d12 randomization_technique: :randomized
+# => Integer NerdDice.total_dice(12, randomization_technique: :randomized)
+total_22d1000 randomization_technique: :random_rand
+# => Integer NerdDice.total_dice(1000, 22, randomization_technique: :random_rand)
+
+roll_4d6_with_advantage3 background_color: 'blue'
+# => DiceSet: NerdDice.roll_dice(4, 3, background_color: 'blue').highest(3)
+total_4d6_with_advantage3 randomization_technique: :random_rand
+# => Integer: NerdDice.roll_dice(4, 3, randomization_technique: :random_rand).highest(3).total
+```
+* Positive and negative bonuses can be used with `plus` (alias `p`) or `minus` (alias `m`)
+```ruby
+roll_d20_plus6 # => DiceSet: NerdDice.roll_dice(20, bonus: 6)
+total_3d8_p2 # => Integer: NerdDice.total_dice(8, 3, bonus: 2)
+total_d20_minus5 # => Integer: NerdDice.total_dice(20, bonus: -6)
+roll_3d8_m3 # => DiceSet: NerdDice.roll_dice(8, 3, bonus: -3)
+```
+* `_with_advantageN` or `highestN` roll with advantage
+* `_with_disadvantageN` or `lowestN` roll with disadvantage
+* Calling `roll_dNN_with_advantage` \(and variants\) rolls 2 dice and keeps one
+```ruby
+# equivalent
+roll_3d8_with_advantage1
+roll_3d8_highest1
+# => DiceSet: NerdDice.roll_dice(8, 3).with_advantage(1)
+
+# calls roll_dice and total to return an integer
+total_3d8_with_advantage1
+total_3d8_highest1
+# => Integer: NerdDice.roll_dice(8, 3).with_advantage(1).total
+
+# rolls two dice in this case
+# equal to roll_2d20_with_advantage but more natural
+roll_d20_with_advantage # => DiceSet: NerdDice.roll_dice(20, 2).with_advantage(1)
+# equal to total_2d20_with_advantage but more natural
+total_d20_with_advantage # => Integer: NerdDice.roll_dice(20, 2).with_advantage(1).total
+```
+#### ConvenienceMethods error handling
+* If you try to call with a plus and a minus, an Exception is raised
+* If you call with a bonus and a keyword argument and they don't match, an Exception is raised
+* Any combination not expressly allowed or matched will call `super` on `method_missing`
+```ruby
+roll_3d8_plus3_m2 # will raise NameError using super method_missing
+roll_3d8_plus3 bonus: 1 # will raise NerdDice::Error with message about "Bonus integrity failure"
+roll_d20_with_advantage_lowest # will raise NameError using super method_missing
+total_4d6_lowest3_highest2 # will raise NameError using super method_missing
+```
 
 ## Development
 
@@ -264,4 +411,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 additional modification in your own project\.
+The project 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/nerd_dice_benchmark

@@ -16,16 +16,28 @@ RATIOS = {
   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_ability_scores_randomized: 26.5,
-  total_ability_scores_randomized: 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)
@@ -36,7 +48,7 @@ def check_against_baseline!(baseline_value, test_value)
 end
 
 puts "Set baseline"
-baselines = Benchmark.bmbm do |x|
+baselines = Benchmark.bm do |x|
   # Random.rand()
   x.report("Random.rand") do # standard rand()
     n.times { Random.rand(1000) }
@@ -52,7 +64,9 @@ random_rand_baseline = baselines[0].real
 securerandom_baseline = baselines[1].real
 
 puts "Roll d1000s"
-total_dice_d1000_results = Benchmark.bmbm do |x|
+
+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
@@ -84,7 +98,43 @@ 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|
+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
@@ -116,8 +166,42 @@ 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"
-total_dice_3d6_results = Benchmark.bmbm do |x|
+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
@@ -149,7 +233,8 @@ 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|
+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
@@ -181,11 +266,44 @@ 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.bmbm do |x|
+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 }

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/harvest_totals.rb

@@ -24,12 +24,17 @@ module NerdDice
     def harvest_totals(collection)
       collection.map(&:total)
     rescue NoMethodError => e
-      specific_message =
-        case e.message
+      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
-      specific_message ? raise(ArgumentError, "You must provide a valid collection. #{specific_message}") : raise
-    end
+      end
   end
 end

data/lib/nerd_dice/convenience_methods.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module NerdDice
+  # The NerdDice::ConvenienceMethods module overrides the default behavior of method_missing to
+  # provide the ability to dynamically roll dice with methods names that match specific patterns.
+  #
+  # Examples:
+  #  `roll_dNN` and `total_dNN` roll one die
+  #     <tt>
+  #     roll_d20 # => DiceSet: NerdDice.roll_dice(20)
+  #     roll_d8 # => DiceSet: NerdDice.roll_dice(8)
+  #     roll_d1000 # => DiceSet: NerdDice.roll_dice(1000)
+  #     total_d20 # => Integer NerdDice.total_dice(20)
+  #     total_d8 # => Integer NerdDice.total_dice(8)
+  #     total_d1000 # => Integer NerdDice.total_dice(1000)
+  #     </tt>
+  #
+  # `roll_NNdNN` and `total_NNdNN` roll specified quantity of dice
+  #     <tt>
+  #     roll_2d20 # => DiceSet: NerdDice.roll_dice(20, 2)
+  #     roll_3d8 # => DiceSet: NerdDice.roll_dice(8, 3)
+  #     roll_22d1000 # => DiceSet: NerdDice.roll_dice(1000, 22)
+  #     total_2d20 # => Integer NerdDice.total_dice(20, 2)
+  #     total_3d8 # => Integer NerdDice.total_dice(8, 3)
+  #     total_22d1000 # => Integer NerdDice.total_dice(1000, 22)
+  #     </tt>
+  #
+  # Keyword arguments are passed on to `roll_dice`/`total_dice` method
+  #     <tt>
+  #     roll_2d20 foreground_color: 'blue' # => DiceSet: NerdDice.roll_dice(20, 2, foreground_color: 'blue')
+  #     roll_2d20 foreground_color: 'blue' # => DiceSet: NerdDice.roll_dice(20, 2, foreground_color: 'blue')
+  #     total_d12 randomization_technique: :randomized
+  #     # => Integer NerdDice.total_dice(12, randomization_technique: :randomized)
+  #     total_22d1000 randomization_technique: :random_rand
+  #     # => Integer NerdDice.total_dice(1000, 22, randomization_technique: :random_rand)
+  #     roll_4d6_with_advantage3 foreground_color: 'blue'
+  #     # => DiceSet: NerdDice.roll_dice(4, 3, foreground_color: 'blue').highest(3)
+  #     total_4d6_with_advantage3 randomization_technique: :random_rand
+  #     # => Integer: NerdDice.roll_dice(4, 3, randomization_technique: :random_rand).highest(3).total
+  #     </tt>
+  #
+  # Positive and negative bonuses can be used with `plus` (alias `p`) or `minus` (alias `m`) in DSL
+  #     <tt>
+  #     roll_d20_plus6 # => DiceSet: NerdDice.roll_dice(20, bonus: 6)
+  #     total_3d8_p2 # => Integer: NerdDice.total_dice(8, 3, bonus: 2)
+  #     total_d20_minus5 # => Integer: NerdDice.total_dice(20, bonus: -6)
+  #     roll_3d8_m3 # => DiceSet: NerdDice.roll_dice(8, 3, bonus: -3)
+  #     </tt>
+  #
+  # Advantage and disadvantage
+  #  * `_with_advantageN` or `highestN` roll with advantage
+  #  * `_with_disadvantageN` or `lowestN` roll with disadvantage
+  #  * Calling `roll_dNN_with_advantage` \(and variants\) rolls 2 dice and keeps one
+  #     <tt>
+  #     # equivalent
+  #     roll_3d8_with_advantage1
+  #     roll_3d8_highest1
+  #     # => DiceSet: NerdDice.roll_dice(8, 3).with_advantage(1)
+  #     # calls roll_dice and total to return an integer
+  #     total_3d8_with_advantage1
+  #     total_3d8_highest1
+  #     # => Integer: NerdDice.roll_dice(8, 3).with_advantage(1).total
+  #     # rolls two dice in this case
+  #     # equal to roll_2d20_with_advantage but more natural
+  #     roll_d20_with_advantage # => DiceSet: NerdDice.roll_dice(20, 2).with_advantage(1)
+  #     # equal to total_2d20_with_advantage but more natural
+  #     total_d20_with_advantage # => Integer: NerdDice.roll_dice(20, 2).with_advantage(1).total
+  #     </tt>
+  #
+  # Error Handling
+  #  * If you try to call with a plus and a minus, an Exception is raised
+  #  * If you call with a bonus and a keyword argument and they don't match, an Exception is raised
+  #  * Any combination not expressly allowed or matched will call `super`
+  #     <tt>
+  #     roll_3d8_plus3_m2 # raise NerdDice::Error
+  #     roll_3d8_plus3 bonus: 1 # raise NerdDice::Error
+  #     roll_d20_with_advantage_lowest # will raise NameError using super method_missing
+  #     total_4d6_lowest3_highest2 # will raise NameError using super method_missing
+  module ConvenienceMethods
+    DIS = /_(with_disadvantage|lowest)/.freeze
+    ADV = /_(with_advantage|highest)/.freeze
+    MOD = /(_p(lus)?\d+|_m(inus)?\d+)/.freeze
+    OVERALL_REGEXP = /\A(roll|total)_\d*d\d+((#{ADV}|#{DIS})\d*)?#{MOD}?\z/.freeze
+
+    # Override of method_missing
+    # * Attempts to match pattern to the regular expression matching the methods
+    #   we want to intercept
+    # * If the method matches the pattern, it is defined and executed with send
+    # * Subsequent calls to the same method name will not hit method_missing
+    # * If the method name does not match the regular expression pattern, the default
+    #   implementation of method_missing is called by invoking super
+    def method_missing(method_name, *args, **kwargs, &block)
+      # returns false if no match
+      if match_pattern_and_delegate(method_name, *args, **kwargs, &block)
+        # send the method after defining it
+        send(method_name, *args, **kwargs, &block)
+      else
+        super
+      end
+    end
+
+    # Override :respond_to_missing? so that :respond_to? works as expected when the
+    # module is included.
+    def respond_to_missing?(symbol, include_all)
+      symbol.to_s.match?(OVERALL_REGEXP) || super
+    end
+
+    private
+
+      # Compares the method name to the regular expression patterns for the module
+      # * If the pattern matches the convenience method is defined and a truthy value is returned
+      # * If the pattern does not match then the method returns false and method_missing invokes `super`
+      def match_pattern_and_delegate(method_name, *args, **kwargs, &block)
+        case method_name.to_s
+        when /\Aroll_\d*d\d+((#{ADV}|#{DIS})\d*)?#{MOD}?\z/o then define_roll_nndnn(method_name, *args, **kwargs,
+                                                                                    &block)
+        when /\Atotal_\d*d\d+((#{ADV}|#{DIS})\d*)?#{MOD}?\z/o then define_total_nndnn(method_name, *args, **kwargs,
+                                                                                      &block)
+        else
+          false
+        end
+      end
+
+      # * Evaluates the method name and then uses class_eval and define_method to define the method
+      # * Subsequent calls to the method will bypass method_missing
+      #
+      # Defined method will return a NerdDice::DiceSet
+      def define_roll_nndnn(method_name, *_args, **_kwargs)
+        sides, number_of_dice, number_to_keep = parse_from_method_name(method_name)
+        # defines the method on the class mixing in the module
+        (class << self; self; end).class_eval do
+          define_method method_name do |*_args, **kwargs|
+            modifier = get_modifier_from_method_name!(method_name, kwargs)
+            kwargs[:bonus] = modifier if modifier
+            # NerdDice::DiceSet object
+            dice = NerdDice.roll_dice(sides, number_of_dice, **kwargs)
+            # invoke highest or lowest on the DiceSet if applicable
+            parse_number_to_keep(dice, method_name, number_to_keep)
+          end
+        end
+      end
+
+      # The implementation of this is different than the roll_ version because NerdDice.total_dice
+      # cannot deal with highest/lowest calls
+      # * Evaluates the method name and then uses class_eval and define_method to define the method
+      # * Calls :determine_total_method to allow for handling of highest/lowest mechanic
+      # * Subsequent calls to the method will bypass method_missing
+      #
+      # Defined method will return an Integer
+      def define_total_nndnn(method_name, *_args, **_kwargs)
+        (class << self; self; end).class_eval do
+          define_method method_name do |*_args, **kwargs|
+            # parse out bonus before calling determine_total_method
+            modifier = get_modifier_from_method_name!(method_name, kwargs)
+            kwargs[:bonus] = modifier if modifier
+            # parse the method and take different actions based on method_name pattern
+            determine_total_method(method_name, kwargs)
+          end
+        end
+      end
+
+      # Determines whether to call NerdDice.total_dice or NerdDice.roll_dice.total based on RegEx pattern
+      # * If the method matches the ADV or DIS regular expressions, the method will call :roll_dice and :total
+      # * If the method does not match ADV or DIS, the method will call :total_dice (which is faster)
+      #
+      # Returns Integer irrespective of which methodology is used
+      def determine_total_method(method_name, kwargs)
+        sides, number_of_dice, number_to_keep = parse_from_method_name(method_name)
+        if number_to_keep
+          # NerdDice::DiceSet
+          dice = NerdDice.roll_dice(sides, number_of_dice, **kwargs)
+          # invoke the highest or lowest method to define dice included and then return the total
+          parse_number_to_keep(dice, method_name, number_to_keep).total
+        else
+          NerdDice.total_dice(sides, number_of_dice, **kwargs)
+        end
+      end
+
+      # calls a series of parse methods and then returns them as an array so the define_ methods above can
+      # use a one-liner to assign the variables
+      def parse_from_method_name(method_name)
+        sides = get_sides_from_method_name(method_name)
+        number_of_dice = get_number_of_dice_from_method_name(method_name)
+        number_to_keep = get_number_to_keep_from_method_name(method_name, number_of_dice)
+        [sides, number_of_dice, number_to_keep]
+      end
+
+      # parses out the Integer value of number of sides from the method name
+      # will only ever get called if the pattern matches so no need for guard against nil
+      def get_sides_from_method_name(method_name)
+        method_name.to_s.match(/d\d+/).to_s[1..].to_i
+      end
+
+      # parses the number of dice from the method name and returns the applicable Integer value
+      # * If number of dice are specified in the method name, that value is used
+      # * If number of dice are not specified and ADV or DIS match, the number is set to 2
+      # * If number of dice are not specified and no ADV or DIS match, the number is set to 1
+      def get_number_of_dice_from_method_name(method_name)
+        match_data = method_name.to_s.match(/_\d+d/)
+        default = method_name.to_s.match?(/_d\d+((#{ADV}|#{DIS})\d*)/o) ? 2 : 1
+        match_data ? match_data.to_s[1...-1].to_i : default
+      end
+
+      # parses out the modifier from the method name
+      # * Input must be a valid MatchData object matching the MOD regular expression
+      # * Does not handle nil
+      # * Only called from get_modifier_from_method_name!
+      def get_modifier_from_match_data(match_data)
+        if match_data.to_s.match?(/_p(lus)?\d+/)
+          match_data.to_s.match(/_p(lus)?\d+/).to_s.match(/\d+/).to_s.to_i
+        else
+          match_data.to_s.match(/_m(inus)?\d+/).to_s.match(/\d+/).to_s.to_i * -1
+        end
+      end
+
+      # Parses the method name to determine if the modifier pattern is present
+      # * Returns nil if method name does not match pattern
+      # * Calls get_modifier_from_match_data to get the Integer value of the modifier
+      # * Calls check_bonus_integrity! to ensure that the parsed modifier matches the
+      #   keyword argument if present (which will raise an error if they don't match)
+      # * Returns the Integer value of the modifier
+      def get_modifier_from_method_name!(method_name, kwargs)
+        match_data = method_name.to_s.match(MOD)
+
+        return nil unless match_data
+
+        modifier = get_modifier_from_match_data(match_data)
+
+        # will raise error if mismatch
+        check_bonus_integrity!(kwargs, modifier)
+        modifier
+      end
+
+      # Determines whether the highest/lowest/with_advantage/with_disadvantage pattern is present in the
+      # method name and takes appropriate action
+      # * Returns nil if no match
+      # * Returns Integer value of number to keep otherwise (irrespective of highest/lowest)
+      # * Takes the number to keep from the method name if specified
+      # * Returns 1 if number to keep not specified and number of dice equals 1
+      # * Returns number_of_dice -1 if number to keep not specified and more than one die
+      def get_number_to_keep_from_method_name(method_name, number_of_dice)
+        return nil unless method_name.to_s.match?(/(#{ADV}|#{DIS})/o)
+
+        specified_number = method_name.to_s.match(/(#{ADV}|#{DIS})\d+/o)
+
+        # set the default to 1 if only one die or number minus 1 if multiple
+        default = number_of_dice == 1 ? 1 : number_of_dice - 1
+
+        # return pattern match if one exists or number of dice -1 if no pattern match
+        specified_number ? specified_number.to_s.match(/\d+/).to_s.to_i : default
+      end
+
+      # Checks that there is not a mismatch between the modifier specified in the method name and the
+      # modifier specified in the keyword arguments if one is specified
+      # * Raises a NerdDice::Error if there is a mismatch
+      # * Returns true if no keyword argument bonus
+      # * Returns true if keyword argument bonus and method name modifier are consistent
+      def check_bonus_integrity!(kwargs, bonus)
+        bonus_error_message = "Bonus integrity failure: "
+        bonus_error_message += "Modifier specified in keyword arguments was #{kwargs[:bonus]}. "
+        bonus_error_message += "Modifier specified in method_name was #{bonus}. "
+        raise NerdDice::Error, bonus_error_message if kwargs && kwargs[:bonus] && kwargs[:bonus].to_i != bonus
+
+        true
+      end
+
+      # Parses number to keep on a NerdDice::DiceSet
+      # * If number_to_keep falsey, just return the DiceSet object
+      # * If number_to_keep matches ADV pattern return DiceSet with highest called
+      # * If number_to_keep matches DIS pattern return DiceSet with lowest called
+      def parse_number_to_keep(dice, method_name, number_to_keep)
+        return dice unless number_to_keep
+
+        # use match against ADV to determine truth value of ternary expression
+        match_data = method_name.to_s.match(ADV)
+        match_data ? dice.highest(number_to_keep) : dice.lowest(number_to_keep)
+      end
+  end
+end

data/lib/nerd_dice/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NerdDice
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/nerd_dice.rb

@@ -7,6 +7,7 @@ require "nerd_dice/die"
 require "nerd_dice/dice_set"
 require "nerd_dice/class_methods"
 require "securerandom"
+require "nerd_dice/convenience_methods"
 # 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
@@ -23,4 +24,6 @@ module NerdDice
   RANDOMIZATION_TECHNIQUES = %i[securerandom random_rand random_object randomized].freeze
   ABILITY_SCORE_KEYS = %i[ability_score_array_size ability_score_number_of_sides ability_score_dice_rolled
                           ability_score_dice_kept].freeze
+
+  extend ConvenienceMethods
 end

data/nerd_dice.gemspec

@@ -43,13 +43,13 @@ Gem::Specification.new do |spec|
   spec.signing_key = File.expand_path("~/.ssh/gem-private_key.pem") if $PROGRAM_NAME.end_with?("gem")
 
   # Dependencies
-  spec.add_dependency "securerandom", "~> 0.1", ">= 0.1.0"
+  spec.add_dependency "securerandom", "~> 0.1", ">= 0.1.1"
 
   # Development Dependencies
-  spec.add_development_dependency "coveralls_reborn", "~> 0.22.0"
-  spec.add_development_dependency "rubocop", "~> 1.20", ">= 1.20.0"
+  spec.add_development_dependency "coveralls_reborn", "~> 0.23.0"
+  spec.add_development_dependency "rubocop", "~> 1.22", ">= 1.22.2"
   spec.add_development_dependency "rubocop-performance", "~> 1.11", ">= 1.11.5"
   spec.add_development_dependency "rubocop-rake", "~> 0.6", ">= 0.6.0"
-  spec.add_development_dependency "rubocop-rspec", "~> 2.4", ">= 2.4.0"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.5", ">= 2.5.0"
   spec.add_development_dependency "simplecov-lcov", "~> 0.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nerd_dice
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Michael Duchemin
@@ -35,7 +35,7 @@ cert_chain:
   WQ4faXJSevxT+x9TgyUNJINPkz/KqreClzdL83cwxPzFFQto7zF6zMCsj0slqJjW
   EQ==
   -----END CERTIFICATE-----
-date: 2021-09-11 00:00:00.000000000 Z
+date: 2021-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: securerandom
@@ -46,7 +46,7 @@ dependencies:
         version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -56,41 +56,41 @@ dependencies:
         version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: coveralls_reborn
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.22.0
+        version: 0.23.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.22.0
+        version: 0.23.0
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.20'
+        version: '1.22'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.20.0
+        version: 1.22.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.20'
+        version: '1.22'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.20.0
+        version: 1.22.2
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
@@ -137,20 +137,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.4.0
+        version: 2.5.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '2.5'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.4.0
+        version: 2.5.0
 - !ruby/object:Gem::Dependency
   name: simplecov-lcov
   requirement: !ruby/object:Gem::Requirement
@@ -204,6 +204,8 @@ files:
 - checksum/nerd_dice-0.1.1.gem.sha512
 - checksum/nerd_dice-0.2.0.gem.sha256
 - checksum/nerd_dice-0.2.0.gem.sha512
+- checksum/nerd_dice-0.3.0.gem.sha256
+- checksum/nerd_dice-0.3.0.gem.sha512
 - lib/nerd_dice.rb
 - lib/nerd_dice/class_methods.rb
 - lib/nerd_dice/class_methods/configure.rb
@@ -215,6 +217,7 @@ files:
 - lib/nerd_dice/class_methods/total_ability_scores.rb
 - lib/nerd_dice/class_methods/total_dice.rb
 - lib/nerd_dice/configuration.rb
+- lib/nerd_dice/convenience_methods.rb
 - lib/nerd_dice/dice_set.rb
 - lib/nerd_dice/die.rb
 - lib/nerd_dice/sets_randomization_technique.rb

metadata.gz.sig

@@ -1,3 +1,2 @@
-C����w
-�g4���]�T۞~����s�����ul�!�
�o��D���#����`t��r��r̋8l��������M]�Tu���M���X�Ʌe/���ϧ9��.�>�G��B��'��R����۽/r"wa�����P��p�0���pd޼�v�,�N�_㼨�����krd��PT������͋)V�c�"#RG�З{��|�nP	9�X�s�p�i���>�?^�6LXQ�.4 
�O�ء6怳�`ݣ�D.����ڠ|�S��:a�P��j���"��1ȩF�*V7��
-�-�w�r���[�5�7��,�4���_��}�SJ:
+����vܕu&��rXsϴ����j]4_�|F���k��Ū�eQl��?n�WC.,E
(��;�B�/�(%َWۊ��#sՉ�	�~ګj0U6H����M9��b/�ơ�H���|
+N&Y{�2p�M��4Mյ��V��M!a�Ӛ��9($���!y^bTq�ה��GZ�;������c-�a)����e4��.������a�gr=0�a�͖=�