nerd_dice 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c50b3a0288e78cec77247885129b370ba6d88f7a012cfefd8fceed049363487
-  data.tar.gz: 456c3ff3d8816a567e4b80cbc49641811270483ce79cabf5fd8f4738bcd23722
+  metadata.gz: 8f64389429514a7d0c2a8410b2e27575e5c11b316b50cee41b37c58d8f8af953
+  data.tar.gz: 4d2365e3ce8139d4675695dfe47edf9ef5d52b9cc873beb5c7c314b8955aaa33
 SHA512:
-  metadata.gz: fa26b32b8b95d4d926faa59071535b5958cc271ad190eea66a23a2fb25280c33c7d563962800a19f3f7c4947e130464450a76b8a59279b6fef9768278dbd61ec
-  data.tar.gz: faae3546363de7437f9425f08666ba934bdb5bb4bd626e4dd3cf4c33c85147453f080c7a42cc3a9d594dc8fdb2f976aecc909261a8533f5c348fa25ee2414bdd
+  metadata.gz: d8bf0ea2c85e3aedf952d82d0f511463accedcad5122b14a7d6769a94100902887ca0e52cf85a6d8b69a75a6cd750858852ad71e34980e61624d39666bedff5b
+  data.tar.gz: ee2e8117b3071872a3d07353dabd4685c4a20e188591e80cbcb93609ba9f134ab22082ae01bee152c34c9cdd1a81a6a40aec2b1521d3e2a106d10f0c8fa313ae

data/.github/workflows/main.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.0', '3.1', '3.2']
+        ruby-version: ['2.7', '3.0']
 
     steps:
     - uses: actions/checkout@v2
@@ -39,7 +39,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.2'
+        ruby-version: '3.0'
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically
     - name: Run rubocop
       run: bundle exec rubocop --parallel
@@ -51,7 +51,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.2'
+        ruby-version: '3.0'
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically
     - name: Run benchmark script
       run: bin/nerd_dice_benchmark

data/.rubocop.yml

@@ -1,11 +1,3 @@
-# RuboCop configuration file for NerdDice gem
-#
-# This is the RuboCop configuration for the gem. By default new cops are enabled
-# by default when the RuboCop gems are updated in the bundle. Before the would
-# show up as warnings until they were added to the configuration file. Now they
-# will be enabled by default, and a case-by-case descision can be made whether
-# to exclude new violations in the configuration explicitly or update the
-# codebase to the gem to conform to the new standard.
 require:
     - rubocop-performance
     - rubocop-rake
@@ -16,12 +8,14 @@ AllCops:
   # RuboCop has a bunch of cops enabled by default. This setting tells RuboCop
   # to ignore them, so only the ones explicitly set in this file are enabled.
   #DisabledByDefault: true
-
-  # New cops are now enabled by default as of 2023-02-20
-  NewCops: enable
   Exclude:
     - '**/templates/**/*'
     - '**/vendor/**/*'
+    - 'node_modules/**/*'
+
+Performance:
+  Exclude:
+    - '**/test/**/*'
 
 # Prefer &&/|| over and/or.
 Style/AndOr:
@@ -117,6 +111,15 @@ Style/MethodDefParentheses:
 Style/FrozenStringLiteralComment:
   Enabled: true
   EnforcedStyle: always
+  Exclude:
+    - 'actionview/test/**/*.builder'
+    - 'actionview/test/**/*.ruby'
+    - 'actionpack/test/**/*.builder'
+    - 'actionpack/test/**/*.ruby'
+    - 'activestorage/db/migrate/**/*.rb'
+    - 'activestorage/db/update_migrate/**/*.rb'
+    - 'actionmailbox/db/migrate/**/*.rb'
+    - 'actiontext/db/migrate/**/*.rb'
 
 Style/RedundantFreeze:
   Enabled: true
@@ -188,6 +191,30 @@ Lint/UselessAssignment:
 Lint/DeprecatedClassMethods:
   Enabled: true
 
+Lint/DuplicateBranch: # (new in 1.3)
+  Enabled: true
+
+Lint/DuplicateRegexpCharacterClassElement: # (new in 1.1)
+  Enabled: true
+
+Lint/EmptyBlock: # (new in 1.1)
+  Enabled: true
+
+Lint/EmptyClass: # (new in 1.3)
+  Enabled: true
+
+Lint/NoReturnInBeginEndBlocks: # (new in 1.2)
+  Enabled: true
+
+Lint/ToEnumArguments: # (new in 1.1)
+  Enabled: true
+
+Lint/UnexpectedBlockArity: # (new in 1.5)
+  Enabled: true
+
+Lint/UnmodifiedReduceAccumulator: # (new in 1.1)
+  Enabled: true
+
 Style/ParenthesesAroundCondition:
   Enabled: true
 
@@ -209,6 +236,27 @@ Style/ColonMethodCall:
 Style/TrivialAccessors:
   Enabled: true
 
+Style/ArgumentsForwarding: # (new in 1.1)
+  Enabled: true
+
+Style/CollectionCompact: # (new in 1.2)
+  Enabled: true
+
+Style/DocumentDynamicEvalDefinition: # (new in 1.1)
+  Enabled: true
+
+Style/NegatedIfElseCondition: # (new in 1.2)
+  Enabled: true
+
+Style/NilLambda: # (new in 1.3)
+  Enabled: true
+
+Style/RedundantArgument: # (new in 1.4)
+  Enabled: true
+
+Style/SwapValues: # (new in 1.1)
+  Enabled: true
+
 Performance/FlatMap:
   Enabled: true
 
@@ -227,9 +275,147 @@ Performance/RegexpMatch:
 Performance/UnfreezeString:
   Enabled: true
 
+Performance/AncestorsInclude: # (new in 1.7)
+  Enabled: true
+
+Performance/BigDecimalWithNumericArgument: # (new in 1.7)
+  Enabled: true
+
+Performance/BlockGivenWithExplicitBlock: # (new in 1.9)
+  Enabled: true
+
+Performance/CollectionLiteralInLoop: # (new in 1.8)
+  Enabled: true
+
+Performance/ConstantRegexp: # (new in 1.9)
+  Enabled: true
+
+Performance/MethodObjectAsBlock: # (new in 1.9)
+  Enabled: true
+
+Performance/RedundantSortBlock: # (new in 1.7)
+  Enabled: true
+
+Performance/RedundantStringChars: # (new in 1.7)
+  Enabled: true
+
+Performance/ReverseFirst: # (new in 1.7)
+  Enabled: true
+
+Performance/SortReverse: # (new in 1.7)
+  Enabled: true
+
+Performance/Squeeze: # (new in 1.7)
+  Enabled: true
+
+Performance/StringInclude: # (new in 1.7)
+  Enabled: true
+
+Performance/Sum: # (new in 1.8)
+  Enabled: true
+
+Layout/SpaceBeforeBrackets: # (new in 1.7)
+  Enabled: true
+
+Lint/AmbiguousAssignment: # (new in 1.7)
+  Enabled: true
+
+Lint/DeprecatedConstants: # (new in 1.8)
+  Enabled: true
+
+Lint/LambdaWithoutLiteralBlock: # (new in 1.8)
+  Enabled: true
+
+Lint/RedundantDirGlobSort: # (new in 1.8)
+  Enabled: true
+
+Style/EndlessMethod: # (new in 1.8)
+  Enabled: true
+
+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
 
-# Disable inclusive language cop. None of RuboCop's business
-Naming/InclusiveLanguage:
-  Enabled: false
+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

@@ -1,8 +1,82 @@
 # Nerd Dice Changelog
 
-<img src="https://i.kym-cdn.com/photos/images/newsfeed/000/186/610/thankyou.png?1318726198" alt="Our CHANGELOG is in another castle" />
+## master \(unreleased\)
+### Added
+### Changed
+### Fixed
 
-## Legacy Branch: See master
-This is a legacy maintenance branch.
+## 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
 
-The [authoritative version of the CHANGELOG](https://github.com/statelesscode/nerd_dice/blob/master/CHANGELOG.md) is found on the master branch. All other release and maintenance branches are updated to point to master after being created.
+## 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`
+  - Configure `refresh_seed_interval` to allow a periodic refresh of the seed
+* Add `randomization_technique` option to `NerdDice.total_dice` method keyword arguments
+* Add a lower-level `execute_die_roll` method that allows you to roll a single die with a generator specified
+* Add ability to manually refresh or specify seed with `:refresh_seed!` method
+### Changed
+* Change `opts = {}` final argument to use keyword args `**opts` in the `NerdDice.total_dice` method. Now the method can be called as follows:
+```ruby
+# old
+NerdDice.total_dice(20, 1, {bonus: 5})
+NerdDice.total_dice(6, 3, {bonus: 1})
+
+# new
+NerdDice.total_dice(20, bonus: 5)
+NerdDice.total_dice(6, 3, bonus: 1)
+```
+* Call `:to_i` on bonus instead of using `:is_a?` and raise ArgumentError in the `NerdDice.total_dice` method if it doesn't respond to `:to_i`
+* Added `securerandom` as an explicit dependency due to Ruby 3.x change to bundled gem
+* `total_dice` no longer calls unqualified `.rand` which improves performance on all generators except for `:securerandom`
+### Fixed
+
+## 0.1.1 \(2020-12-12\)
+### Added
+### Changed
+### Fixed
+* Fix broken link to CHANGELOG in gemspec
+* Fix rubocop offenses from 0.1.0 and refactor specs
+
+## 0.1.0 \(2020-12-07\)
+
+### Added
+* Add NerdDice.total_dice class method with the ability to roll multiple polyhedral dice and add a bonus

data/Gemfile

@@ -6,4 +6,4 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake", "~> 13.0"
-gem "rspec", "~> 3.12"
+gem "rspec", "~> 3.10"

data/Gemfile.lock

@@ -1,92 +1,87 @@
 PATH
   remote: .
   specs:
-    nerd_dice (0.3.1)
-      securerandom (~> 0.2, >= 0.2.2)
+    nerd_dice (0.4.0)
+      securerandom (~> 0.1, >= 0.1.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    coveralls_reborn (0.27.0)
-      simplecov (~> 0.22.0)
-      term-ansicolor (~> 1.7)
-      thor (~> 1.2)
-      tins (~> 1.32)
-    diff-lcs (1.5.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)
-    json (2.6.3)
-    parallel (1.22.1)
-    parser (3.2.1.0)
+    parallel (1.21.0)
+    parser (3.0.2.0)
       ast (~> 2.4.1)
-    rainbow (3.1.1)
+    rainbow (3.0.0)
     rake (13.0.6)
-    regexp_parser (2.7.0)
+    regexp_parser (2.1.1)
     rexml (3.2.5)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.1)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.2)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.3)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-support (3.12.0)
-    rubocop (1.46.0)
-      json (~> 2.3)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rubocop (1.22.2)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.26.0, < 2.0)
+      rexml
+      rubocop-ast (>= 1.12.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.26.0)
-      parser (>= 3.2.1.0)
-    rubocop-capybara (2.17.1)
-      rubocop (~> 1.41)
-    rubocop-performance (1.16.0)
+      unicode-display_width (>= 1.4.0, < 3.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.18.1)
-      rubocop (~> 1.33)
-      rubocop-capybara (~> 2.17)
+    rubocop-rspec (2.5.0)
+      rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
-    securerandom (0.2.2)
-    simplecov (0.22.0)
+    securerandom (0.1.1)
+    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.4)
+    simplecov_json_formatter (0.1.3)
     sync (0.5.0)
     term-ansicolor (1.7.1)
       tins (~> 1.0)
-    thor (1.2.1)
-    tins (1.32.1)
+    thor (1.1.0)
+    tins (1.29.1)
       sync
-    unicode-display_width (2.4.2)
+    unicode-display_width (2.1.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  coveralls_reborn (~> 0.27.0)
+  coveralls_reborn (~> 0.23.0)
   nerd_dice!
   rake (~> 13.0)
-  rspec (~> 3.12)
-  rubocop (~> 1.46, >= 1.46.0)
-  rubocop-performance (~> 1.16, >= 1.16.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.18, >= 2.18.1)
+  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:
 
@@ -268,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
 
@@ -277,7 +406,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/statelesscode/nerd_dice/issues. We welcome and encourage your participation in this open-source project. We welcome those of all backgrounds and abilities, but we refuse to adopt the Contributor Covenant for reasons outlined in [BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md](BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md)
+Bug reports and pull requests are welcome on GitHub at https://github.com/statelesscode/nerd_dice/issues. We welcome and encourage your participation in this open-source project. We welcome those of all backgrounds and abilities, but we refuse to adopt the Contributor Covenant for reasons outlined in [BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md](https://github.com/statelesscode/nerd_dice/blob/master/BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md)
+
 
 ## Unlicense, License, and Copyright