nerd_dice 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59cbf041543aa370bebe104866bb2101ddef377679a6d7729deb2019af2d835c
-  data.tar.gz: 1671cd3594e2129a0034bde27214e498e2ca1068e6b3c7f1096513fc6fee6117
+  metadata.gz: 88266e9421830d581588170f03cab85b95f95b0f3727c943ae36aa590c6ef338
+  data.tar.gz: 98e7fdc98609de1776400f3b4e8d04bbeff92fb0ef06814c06c967abcfd68a48
 SHA512:
-  metadata.gz: 74c5833bb18c567d482e6e093ac50cf19ad5d1d63003e2431505f5b0f82259ef353a9ae9259ee8d2fb331dc4fe72d69f2f7dfe0cc603f18a53e4287c33412092
-  data.tar.gz: e3e2a4ca90c468183c2eed3490ec36c4efc038494aaeaeaecb73e288a6d66e9b37a51bf9c42adb762ef8b04e645fbe52315570ebb9d1249be2bedfd964e500ad
+  metadata.gz: 8e0622aaeee447750ab14395eae84241ced009ff12986c29cb44c903669c7d0e5caed1916dd9693db1fc6da9c9af67bbe9ce2c845f9fa17d85c6a9614e9d9d2b
+  data.tar.gz: c9b50c852027d64160a294aaca650ab882423984a8e79159214dc1ec5e8dd5ce7daa3b13507c616b2c8f218f1ade1f752890080ce7e16b52922992d3c8d49b51

data/.github/workflows/main.yml

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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nerd_dice (0.1.2)
+    nerd_dice (0.2.1)
       securerandom (~> 0.2, >= 0.2.2)
 
 GEM
@@ -90,4 +90,4 @@ DEPENDENCIES
   simplecov-lcov (~> 0.8.0)
 
 BUNDLED WITH
-   2.4.7
+   2.2.22

data/README.md

@@ -1,3 +1,6 @@
+[![Coverage Status](https://coveralls.io/repos/github/statelesscode/nerd_dice/badge.svg?branch=master)](https://coveralls.io/github/statelesscode/nerd_dice?branch=master)
+![Build](https://github.com/statelesscode/nerd_dice/actions/workflows/main.yml/badge.svg)
+[![Maintainability](https://api.codeclimate.com/v1/badges/721f587b792d583065be/maintainability)](https://codeclimate.com/github/statelesscode/nerd_dice/maintainability)
 # NerdDice
 Nerd dice allows you to roll polyhedral dice and add bonuses as you would in a tabletop roleplaying game. You can choose to roll multiple dice and keep a specified number of dice such as rolling 4d6 and dropping the lowest for ability scores or rolling with advantage and disadvantage if those mechanics exist in your game.
 
@@ -18,18 +21,64 @@ Or install it yourself as:
     $ gem install nerd_dice
 
 ## Usage
+### 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:
+
+```ruby
+NerdDice.configure do | config|
+
+  # number of ability scores to place in an ability score array
+  config.ability_score_array_size = 6
+
+  # randomization technique options are:
+    # :securerandom => Uses SecureRandom.rand(). Good entropy, medium speed.
+    # :random_rand => Uses Random.rand(). Class method. Poor entropy, fastest speed.
+      # (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
+  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
+end
+```
+
 ### Rolling a number of dice and adding a bonus
 ```ruby
 # roll a single d4
 NerdDice.total_dice(4) # => return random Integer between 1-4
 
 # roll 3d6
-NerdDice.total_dice(6, 3) => return Integer total of three 6-sided dice
+NerdDice.total_dice(6, 3) # => return Integer total of three 6-sided dice
 
 # roll a d20 and add 5 to the value
-NerdDice.total_dice(20, 1, { bonus: 5 })
+NerdDice.total_dice(20, bonus: 5)
+
+# roll a d20 and overide the configured randomization_technique one time
+# without changing the config
+NerdDice.total_dice(20, randomization_technique: :randomized)
+```
+__NOTE:__ If provided, the bonus must respond to `:to_i` or an `ArgumentError` will be raised
+
+### Manually setting or refreshing the random generator seed
+For randomization techniques other than `:securerandom` you can manually set or refresh the generator's seed by calling the `refresh_seed!` method. This is automatically called at the interval specified in `NerdDice.configuration.refresh_seed_interval` if it is not nil.
+
+```ruby
+# no arguments, will refresh the seed for the configured generator(s) only
+NerdDice.refresh_seed! # => hash with old seed(s) or nil if :securerandom
+
+# OPTIONS:
+    #   randomization_technique (Symbol) => NerdDice::RANDOMIZATION_TECHNIQUES
+    #   random_rand_seed (Integer) => Seed to set for Random
+    #   random_object_seed (Integer) => Seed to set for new Random object
+NerdDice.refresh_seed!(randomization_technique:  :randomized,
+                       random_rand_seed:         1337,
+                       random_object_seed:       24601)
 ```
-__NOTE:__ If provided, the bonus must be an ```Integer``` or it will be ignored
+__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.
 
 ## Development
 
@@ -43,4 +92,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/statel
 
 ## Unlicense, License, and Copyright
 
-The document is dual-licensed under the [MIT](https://opensource.org/licenses/MIT) license and the [UNLICENSE](https://unlicense.org/) \(with strong preference toward the UNLICENSE\)\. The content is released under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) \(no rights reserved\). You are free to include it in its original form or modified with or without modification in your own project\.
+The document is dual-licensed under the [MIT](https://opensource.org/licenses/MIT) license and the [UNLICENSE](https://unlicense.org/) \(with strong preference toward the UNLICENSE\)\. The content is released under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) \(no rights reserved\). You are free to include it in its original form or modified with or without modification in your own project\.

data/bin/nerd_dice_benchmark

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "benchmark"
+require "nerd_dice"
+
+n = 50_000
+
+RATIOS = {
+  nerd_dice_securerandom: 1.7,
+  nerd_dice_random_rand: 11.1,
+  nerd_dice_random_object: 13.0,
+  nerd_dice_randomized: 5.5,
+  nerd_dice_securerandom_3d6: 5.5,
+  nerd_dice_random_rand_3d6: 25.0,
+  nerd_dice_random_object_3d6: 25.5,
+  nerd_dice_randomized_3d6: 14.5
+}.freeze
+
+def check_against_baseline!(baseline_value, test_value)
+  ratio = RATIOS[test_value.label.to_sym]
+  error_message = "Failed benchmark for #{test_value.label}. "
+  error_message += "Allowed ratio was #{ratio} actual ratio was #{test_value.real / baseline_value}"
+  raise NerdDice::Error, error_message if test_value.real > baseline_value * ratio
+end
+
+puts "Set baseline"
+baselines = Benchmark.bmbm do |x|
+  # Random.rand()
+  x.report("Random.rand") do # standard rand()
+    n.times { Random.rand(1000) }
+  end
+
+  # SecureRandom.rand()
+  x.report("Sec.rand") do
+    n.times { SecureRandom.rand(1000) }
+  end
+end
+
+random_rand_baseline = baselines[0].real
+securerandom_baseline = baselines[1].real
+
+puts "Roll d1000s"
+total_dice_d1000_results = Benchmark.bmbm do |x|
+  # NerdDice.total_dice securerandom
+  x.report("nerd_dice_securerandom") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.total_dice(1000) }
+  end
+
+  x.report("nerd_dice_random_rand") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.total_dice(1000) }
+  end
+
+  x.report("nerd_dice_random_object") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.total_dice(1000) }
+  end
+
+  x.report("nerd_dice_randomized") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.total_dice(1000) }
+  end
+end
+
+total_dice_securerandom = total_dice_d1000_results[0]
+check_against_baseline! securerandom_baseline, total_dice_securerandom
+total_dice_random_rand = total_dice_d1000_results[1]
+check_against_baseline! random_rand_baseline, total_dice_random_rand
+total_dice_random_object = total_dice_d1000_results[2]
+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 "Roll 3d6"
+total_dice_3d6_results = Benchmark.bmbm do |x|
+  # NerdDice.total_dice securerandom
+  x.report("nerd_dice_securerandom_3d6") do
+    NerdDice.configuration.randomization_technique = :securerandom
+    n.times { NerdDice.total_dice(6, 3) }
+  end
+
+  x.report("nerd_dice_random_rand_3d6") do
+    NerdDice.configuration.randomization_technique = :random_rand
+    n.times { NerdDice.total_dice(6, 3) }
+  end
+
+  x.report("nerd_dice_random_object_3d6") do
+    NerdDice.configuration.randomization_technique = :random_object
+    n.times { NerdDice.total_dice(6, 3) }
+  end
+
+  x.report("nerd_dice_randomized_3d6") do
+    NerdDice.configuration.randomization_technique = :randomized
+    n.times { NerdDice.total_dice(6, 3) }
+  end
+end
+
+total_dice_3d6_securerandom = total_dice_3d6_results[0]
+check_against_baseline! securerandom_baseline, total_dice_3d6_securerandom
+total_dice_3d6_random_rand = total_dice_3d6_results[1]
+check_against_baseline! random_rand_baseline, total_dice_3d6_random_rand
+total_dice_3d6_random_object = total_dice_3d6_results[2]
+check_against_baseline! random_rand_baseline, total_dice_3d6_random_object
+total_dice_3d6_randomized = total_dice_3d6_results[3]
+check_against_baseline! ((random_rand_baseline * 0.75) + (securerandom_baseline * 0.25)), total_dice_3d6_randomized

data/checksum/nerd_dice-0.2.0.gem.sha256

@@ -0,0 +1 @@
+0a2d4765e24c21fecf99229b0cc4fad806ca256d2187c45c442b25771af1b9cc

data/checksum/nerd_dice-0.2.0.gem.sha512

@@ -0,0 +1 @@
+e345190f870eabd2a4fd6993f1a1d70d008ef8e6464767ba5697a46f7c4d6912c78a18039cec06c18dd6f0ee9f425453c078f780d36ccf65043ec3f7fba790a2

data/lib/nerd_dice/configuration.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module NerdDice
+  # The NerdDice::Configuration class allows you to configure and customize the
+  # options of the NerdDice gem to suit your specific needs. You can specify
+  # properties like the randomization technique used by the gem, the number of
+  # ability scores in an ability score array, etc. See the README for a list of
+  # configurable attributes.
+  #
+  # Usage:
+  #   The configuration can either be set via a configure block:
+  #   <tt>NerdDice.configure do |config|
+  #         config.randomization_technique = :random_new_interval
+  #         config.new_random_interval     = 100
+  #       end
+  #   </tt>
+  #
+  #   You can also set a particular property without a block using inline assignment
+  #   <tt>NerdDice.configuration.randomization_technique = :random_new_once</tt>
+  class Configuration
+    attr_reader :randomization_technique, :refresh_seed_interval
+    attr_accessor :ability_score_array_size
+
+    def randomization_technique=(value)
+      unless RANDOMIZATION_TECHNIQUES.include?(value)
+        raise NerdDice::Error, "randomization_technique must be one of #{RANDOMIZATION_TECHNIQUES.join(', ')}"
+      end
+
+      @randomization_technique = value
+    end
+
+    def refresh_seed_interval=(value)
+      unless value.nil?
+        value = value&.to_i
+        raise NerdDice::Error, "refresh_seed_interval must be a positive integer or nil" unless value.positive?
+      end
+      @refresh_seed_interval = value
+    end
+
+    private
+
+      def initialize
+        @ability_score_array_size = 6
+        @randomization_technique = :random_object
+      end
+  end
+end

data/lib/nerd_dice/version.rb

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

data/lib/nerd_dice.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "nerd_dice/version"
+require "nerd_dice/configuration"
+require "securerandom"
 # 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,25 +25,152 @@ require "nerd_dice/version"
 module NerdDice
   class Error < StandardError; end
 
-  ############################
-  # total_dice class method
-  ############################
-  # Arguments:
-  #   number_of_sides (Integer) =>  the number of sides of the dice to roll
-  #   number_of_dice (Integer, DEFAULT: 1) => the quantity to roll of the type
-  #     of die specified in the number_of_sides argument.
-  #   options (Hash, DEFAULT: {}) any additional options you wish to include
-  #     :bonus (Integer) => The total bonus (positive integer) or penalty
-  #       (negative integer) to modify the total by. Is added to the total of
-  #       all dice after they are totaled, not to each die rolled
-  #
-  # Return (Integer) => Total of the dice rolled, plus modifier if applicable
-  def self.total_dice(number_of_sides, number_of_dice = 1, opts = {})
-    total = 0
-    number_of_dice.times do
-      total += rand(number_of_sides) + 1
+  RANDOMIZATION_TECHNIQUES = %i[securerandom random_rand random_object randomized].freeze
+
+  class << self
+    attr_reader :count_since_last_refresh
+
+    ############################
+    # configure class method
+    ############################
+    # Arguments: None
+    # Expects and yields to a block where configuration is specified.
+    # See README and NerdDice::Configuration class for config options
+    # Return (NerdDice::Configuration) the Configuration object tied to the
+    #   @configuration class instance variable
+    def configure
+      yield configuration
+      configuration
+    end
+
+    ############################
+    # configuration class method
+    ############################
+    # Arguments: None
+    # Provides the lazy-loaded class instance variable @configuration
+    # Return (NerdDice::Configuration) the Configuration object tied to the
+    #   @configuration class instance variable
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    ############################
+    # total_dice class method
+    ############################
+    # Arguments:
+    #   number_of_sides (Integer) =>  the number of sides of the dice to roll
+    #   number_of_dice (Integer, DEFAULT: 1) => the quantity to roll of the type
+    #     of die specified in the number_of_sides argument.
+    #   options (Hash, DEFAULT: {}) any additional options you wish to include
+    #     :bonus (Integer) => The total bonus (positive integer) or penalty
+    #       (negative integer) to modify the total by. Is added to the total of
+    #       all dice after they are totaled, not to each die rolled
+    #
+    # Return (Integer) => Total of the dice rolled, plus modifier if applicable
+    def total_dice(number_of_sides, number_of_dice = 1, **opts)
+      total = 0
+      number_of_dice.times do
+        total += execute_die_roll(number_of_sides, opts[:randomization_technique])
+      end
+      begin
+        total += opts[:bonus].to_i
+      rescue NoMethodError
+        raise ArgumentError, "Bonus must be a value that responds to :to_i"
+      end
+      total
+    end
+
+    ############################
+    # execute_die_roll class method
+    ############################
+    # Arguments:
+    #   number_of_sides (Integer) =>  the number of sides of the die to roll
+    #   using_generator (Symbol) => must be one of the symbols in
+    #     RANDOMIZATION_TECHNIQUES or nil
+    #
+    # Return (Integer) => Value of the single die rolled
+    def execute_die_roll(number_of_sides, using_generator = nil)
+      @count_since_last_refresh ||= 0
+      gen = get_number_generator(using_generator)
+      result = gen.rand(number_of_sides) + 1
+      increment_and_evalutate_refresh_seed
+      result
+    end
+
+    ############################
+    # refresh_seed! class method
+    ############################
+    # Options: (none required)
+    #   randomization_technique (Symbol) => must be one of the symbols in
+    #     RANDOMIZATION_TECHNIQUES if specified
+    #   random_rand_seed (Integer) => Seed to set for Random
+    #   random_object_seed (Integer) => Seed to set for new Random object
+    # Return (Hash or nil) => Previous values of generator seeds that were refreshed
+    def refresh_seed!(**opts)
+      technique, random_rand_new_seed, random_object_new_seed = parse_refresh_options(opts)
+      @count_since_last_refresh = 0
+      return nil if technique == :securerandom
+
+      reset_appropriate_seeds!(technique, random_rand_new_seed, random_object_new_seed)
     end
-    total += opts[:bonus] if opts[:bonus].is_a?(Integer)
-    total
+
+    private
+
+      def get_number_generator(using_generator = nil)
+        using_generator ||= configuration.randomization_technique
+        case using_generator
+        when :securerandom then SecureRandom
+        when :random_rand then Random
+        when :random_object then @random_object ||= Random.new
+        when :randomized then random_generator
+        else raise ArgumentError, "Unrecognized generator. Must be one of #{RANDOMIZATION_TECHNIQUES.join(', ')}"
+        end
+      end
+
+      def random_generator
+        gen = RANDOMIZATION_TECHNIQUES.reject { |el| el == :randomized }.sample
+        get_number_generator(gen)
+      end
+
+      def refresh_random_rand_seed!(new_seed)
+        new_seed ? Random.srand(new_seed) : Random.srand
+      end
+
+      def refresh_random_object_seed!(new_seed)
+        old_seed = @random_object&.seed
+        @random_object = new_seed ? Random.new(new_seed) : Random.new
+        old_seed
+      end
+
+      def parse_refresh_options(opts)
+        [
+          opts[:randomization_technique] || configuration.randomization_technique,
+          opts[:random_rand_seed],
+          opts[:random_object_seed]
+        ]
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def reset_appropriate_seeds!(technique, random_rand_new_seed, random_object_new_seed)
+        return_hash = {}
+        case technique
+        when :random_rand
+          return_hash[:random_rand_prior_seed] = refresh_random_rand_seed!(random_rand_new_seed)
+        when :random_object
+          return_hash[:random_object_prior_seed] = refresh_random_object_seed!(random_object_new_seed)
+        when :randomized
+          return_hash[:random_rand_prior_seed] = refresh_random_rand_seed!(random_rand_new_seed)
+          return_hash[:random_object_prior_seed] = refresh_random_object_seed!(random_object_new_seed)
+        end
+        return_hash
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def increment_and_evalutate_refresh_seed
+        @count_since_last_refresh += 1
+        return unless configuration.refresh_seed_interval
+
+        refresh_seed! if @count_since_last_refresh >= configuration.refresh_seed_interval
+      end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nerd_dice
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Michael Duchemin
@@ -177,14 +177,15 @@ email:
 executables:
 - console
 - generate_checksums
+- nerd_dice_benchmark
 - setup
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/main.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
 - BURN_THE_CONTRIBUTOR_COVENANT_WITH_FIRE.md
 - CHANGELOG.md
 - Gemfile
@@ -195,13 +196,17 @@ files:
 - UNLICENSE.txt
 - bin/console
 - bin/generate_checksums
+- bin/nerd_dice_benchmark
 - bin/setup
 - certs/msducheminjr.pem
 - checksum/nerd_dice-0.1.0.gem.sha256
 - checksum/nerd_dice-0.1.0.gem.sha512
 - checksum/nerd_dice-0.1.1.gem.sha256
 - checksum/nerd_dice-0.1.1.gem.sha512
+- checksum/nerd_dice-0.2.0.gem.sha256
+- checksum/nerd_dice-0.2.0.gem.sha512
 - lib/nerd_dice.rb
+- lib/nerd_dice/configuration.rb
 - lib/nerd_dice/version.rb
 - nerd_dice.gemspec
 homepage: https://github.com/statelesscode/nerd_dice

data/.travis.yml

@@ -1,6 +0,0 @@
----
-language: ruby
-cache: bundler
-rvm:
-  - 2.7.2
-before_install: gem install bundler -v 2.1.4