nerd_dice 0.3.1 → 0.4.0

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

@@ -16,14 +16,26 @@ 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_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
@@ -52,6 +64,8 @@ random_rand_baseline = baselines[0].real
 securerandom_baseline = baselines[1].real
 
 puts "Roll d1000s"
+
+puts "total_dice"
 total_dice_d1000_results = Benchmark.bm do |x|
   # NerdDice.total_dice securerandom
   x.report("total_dice_securerandom") do
@@ -84,6 +98,42 @@ check_against_baseline! random_rand_baseline, total_dice_random_object
 total_dice_randomized = total_dice_d1000_results[3]
 check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), total_dice_randomized
 
+puts "total_ d1000s ConvenienceMethods"
+
+# NOTE: Due to method_missing overhead, using roll_ ratios for ConvenienceMethods total_dice
+total_d1000_results = Benchmark.bm do |x|
+  # NerdDice.total_dice securerandom
+  x.report("total_magic_securerandom") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.total_d1000 }
+  end
+
+  x.report("total_magic_random_rand") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.total_d1000 }
+  end
+
+  x.report("total_magic_random_object") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.total_d1000 }
+  end
+
+  x.report("total_magic_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.total_d1000 }
+  end
+end
+
+total_magic_securerandom = total_d1000_results[0]
+check_against_baseline! securerandom_baseline, total_magic_securerandom
+total_magic_random_rand = total_d1000_results[1]
+check_against_baseline! random_rand_baseline, total_magic_random_rand
+total_magic_random_object = total_d1000_results[2]
+check_against_baseline! random_rand_baseline, total_magic_random_object
+total_magic_randomized = total_d1000_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), total_magic_randomized
+
+puts "roll_dice"
 roll_dice_d1000_results = Benchmark.bm do |x|
   # NerdDice.roll_dice securerandom
   x.report("roll_dice_securerandom") do
@@ -116,7 +166,41 @@ check_against_baseline! random_rand_baseline, roll_dice_random_object
 roll_dice_randomized = roll_dice_d1000_results[3]
 check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), roll_dice_randomized
 
+puts "roll_ d1000s ConvenienceMethods"
+roll_d1000_results = Benchmark.bm do |x|
+  # NerdDice.roll_dice securerandom
+  x.report("roll_magic_securerandom") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.roll_d1000 }
+  end
+
+  x.report("roll_magic_random_rand") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.roll_d1000 }
+  end
+
+  x.report("roll_magic_random_object") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.roll_d1000 }
+  end
+
+  x.report("roll_magic_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.roll_d1000 }
+  end
+end
+
+roll_magic_securerandom = roll_d1000_results[0]
+check_against_baseline! securerandom_baseline, roll_magic_securerandom
+roll_magic_random_rand = roll_d1000_results[1]
+check_against_baseline! random_rand_baseline, roll_magic_random_rand
+roll_magic_random_object = roll_d1000_results[2]
+check_against_baseline! random_rand_baseline, roll_magic_random_object
+roll_magic_randomized = roll_d1000_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), roll_magic_randomized
+
 puts "Roll 3d6"
+puts "total_dice 3d6"
 total_dice_3d6_results = Benchmark.bm do |x|
   # NerdDice.total_dice securerandom
   x.report("total_dice_securerandom_3d6") do
@@ -149,6 +233,7 @@ check_against_baseline! random_rand_baseline, total_dice_3d6_random_object
 total_dice_3d6_randomized = total_dice_3d6_results[3]
 check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), total_dice_3d6_randomized
 
+puts "roll_dice 3d6"
 roll_dice_3d6_results = Benchmark.bm do |x|
   # NerdDice.roll_dice securerandom
   x.report("roll_dice_securerandom_3d6") do
@@ -181,6 +266,39 @@ 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
 

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/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.1"
+  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

@@ -28,7 +28,6 @@ Gem::Specification.new do |spec|
   spec.metadata["bug_tracker_uri"] = "https://github.com/statelesscode/nerd_dice/issues"
   spec.metadata["documentation_uri"] = "https://github.com/statelesscode/nerd_dice/README.md"
   spec.metadata["github_repo"] = "https://github.com/statelesscode/nerd_dice"
-  spec.metadata["rubygems_mfa_required"] = "true"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -44,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.2", ">= 0.2.2"
+  spec.add_dependency "securerandom", "~> 0.1", ">= 0.1.1"
 
   # Development Dependencies
-  spec.add_development_dependency "coveralls_reborn", "~> 0.27.0"
-  spec.add_development_dependency "rubocop", "~> 1.46", ">= 1.46.0"
-  spec.add_development_dependency "rubocop-performance", "~> 1.16", ">= 1.16.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.18", ">= 2.18.1"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.5", ">= 2.5.0"
   spec.add_development_dependency "simplecov-lcov", "~> 0.8.0"
 end