nerd_dice 0.2.0 → 0.3.0

data/lib/nerd_dice/class_methods/roll_dice.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+############################
+# roll_dice class method
+############################
+# Usage:
+#   If you wanted to roll a single d4, you would execute:
+#   <tt>dice_set = NerdDice.roll_dice(4)</tt>
+#
+#   If you wanted to roll 3d6, you would execute
+#   <tt>dice_set = NerdDice.roll_dice(6, 3)</tt>
+#
+#   If you wanted to roll a d20 and add 5 to the value, you would execute
+#   <tt>dice_set = NerdDice.roll_dice(20, 1, bonus: 5)</tt>
+#
+#   Since this method returns a DiceSet, you can call any of the DiceSet
+#   methods on the result. See the README for more details and options
+module NerdDice
+  class << self
+    ############################
+    # roll_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.
+    #   opts (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
+    #     :randomization_technique (Symbol) => must be one of the symbols in
+    #       RANDOMIZATION_TECHNIQUES or nil
+    #     :foreground_color (String) => should resolve to a valid CSS color (format flexible)
+    #     :background_color (String) => should resolve to a valid CSS color (format flexible)
+    #     :damage_type: (String) => damage type for the dice set, if applicable
+    #
+    # Return (NerdDice::DiceSet) => Collection object with one or more Die objects
+    #
+    # You can call roll_dice().total to get similar functionality to total_dice
+    # or you can chain methods together roll_dice(6, 4, bonus: 3).with_advantage(3).total
+    def roll_dice(number_of_sides, number_of_dice = 1, **opts)
+      DiceSet.new(number_of_sides, number_of_dice, **opts)
+    end
+  end
+end

data/lib/nerd_dice/class_methods/total_ability_scores.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+############################
+# total_ability_scores method
+############################
+# Usage:
+#   If you wanted to get an array of only the values of ability scores and
+#   default configuration you would execute:
+#   <tt>ability_score_array = NerdDice.total_ability_scores</tt>
+#     => [15, 14, 13, 12, 10, 8]
+#
+#   If you wanted to specify configuration for the current operation without
+#   modifying the NerdDice.configuration, you can supply options for both the
+#   ability_score configuration and the properties of the DiceSet objects returned.
+#
+#   Many of the properties available in roll_ability_scores will not be relevant
+#   to total_ability_scores but the method delegates all options passed without
+#   filtering.
+#   <tt>
+#     ability_score_array = NerdDice.total_ability_scores(
+#       ability_score_array_size: 7,
+#       ability_score_number_of_sides: 8,
+#       ability_score_dice_rolled: 5,
+#       ability_score_dice_kept: 4,
+#       randomization_technique: :randomized
+#     )
+#     => [27, 22, 13, 23, 20, 24, 23]
+#   </tt>
+module NerdDice
+  class << self
+    # Arguments:
+    #   opts (options Hash, DEFAULT: {}) any options you wish to include
+    #     ABILITY SCORE OPTIONS
+    #     :ability_score_array_size DEFAULT NerdDice.configuration.ability_score_array_size
+    #     :ability_score_number_of_sides DEFAULT NerdDice.configuration.ability_score_number_of_sides
+    #     :ability_score_dice_rolled DEFAULT NerdDice.configuration.ability_score_dice_rolled
+    #     :ability_score_dice_kept DEFAULT NerdDice.configuration.ability_score_dice_kept
+    #
+    #     DICE SET OPTIONS
+    #     :randomization_technique (Symbol) => must be one of the symbols in
+    #       RANDOMIZATION_TECHNIQUES or nil
+    #
+    #     ARGUMENTS PASSED ON THAT DO NOT REALLY MATTER
+    #     :foreground_color (String) => should resolve to a valid CSS color (format flexible)
+    #     :background_color (String) => should resolve to a valid CSS color (format flexible)
+    #
+    # Return (Array of Integers) => One Integer element for each ability score
+    def total_ability_scores(**opts)
+      harvest_totals(roll_ability_scores(**opts))
+    end
+  end
+end

data/lib/nerd_dice/class_methods/total_dice.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+############################
+# total_dice class method
+############################
+# Usage:
+#   If you wanted to roll a single d4, you would execute:
+#   <tt>NerdDice.total_dice(4)</tt>
+#
+#   If you wanted to roll 3d6, you would execute
+#   <tt>NerdDice.total_dice(6, 3)</tt>
+#
+#   If you wanted to roll a d20 and add 5 to the value, you would execute
+#   <tt>NerdDice.total_dice(20, 1, bonus: 5)</tt>
+#
+#   The bonus in the options hash must be an Integer duck type or nil
+module NerdDice
+  class << self
+    # 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.
+    #   opts (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
+    #     :randomization_technique (Symbol) => must be one of the symbols in
+    #       RANDOMIZATION_TECHNIQUES or nil
+    #
+    # 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
+  end
+end

data/lib/nerd_dice/class_methods.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "nerd_dice/class_methods/configure"
+require "nerd_dice/class_methods/refresh_seed"
+require "nerd_dice/class_methods/execute_die_roll"
+require "nerd_dice/class_methods/total_dice"
+require "nerd_dice/class_methods/roll_dice"
+require "nerd_dice/class_methods/roll_ability_scores"
+require "nerd_dice/class_methods/harvest_totals"
+require "nerd_dice/class_methods/total_ability_scores"
+
+############################
+# NerdDice class methods
+# This file contains module-level attribute readers and writers and includes the other
+# files that provide the class method functionality.
+#
+# PUBLIC METHODS
+# NerdDice.configure => ./class_methods/configure.rb
+# NerdDice.configuration => ./class_methods/configure.rb
+# NerdDice.refresh_seed => ./class_methods/refresh_seed.rb
+# NerdDice.execute_die_roll => ./class_methods/execute_die_roll.rb
+# NerdDice.total_dice => ./class_methods/total_dice.rb
+# NerdDice.roll_dice => ./class_methods/roll_dice.rb
+# NerdDice.roll_ability_scores => ./class_methods/roll_ability_scores.rb
+############################
+module NerdDice
+  class << self
+    attr_reader :count_since_last_refresh
+  end
+end

data/lib/nerd_dice/configuration.rb

@@ -18,8 +18,12 @@ module NerdDice
   #   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
+    attr_reader :randomization_technique, :refresh_seed_interval, :ability_score_array_size,
+                :ability_score_dice_rolled, :ability_score_number_of_sides, :ability_score_dice_kept
+    attr_accessor :die_background_color, :die_foreground_color
+
+    DEFAULT_BACKGROUND_COLOR = "#0000DD"
+    DEFAULT_FOREGROUND_COLOR = "#DDDDDD"
 
     def randomization_technique=(value)
       unless RANDOMIZATION_TECHNIQUES.include?(value)
@@ -37,11 +41,51 @@ module NerdDice
       @refresh_seed_interval = value
     end
 
+    def ability_score_array_size=(value)
+      @ability_score_array_size = ensure_positive_integer!("ability_score_array_size", value)
+    end
+
+    def ability_score_number_of_sides=(value)
+      @ability_score_number_of_sides = ensure_positive_integer!("ability_score_number_of_sides", value)
+    end
+
+    def ability_score_dice_rolled=(value)
+      @ability_score_dice_rolled = ensure_positive_integer!("ability_score_dice_rolled", value)
+      return unless ability_score_dice_kept > @ability_score_dice_rolled
+
+      warn "WARNING: ability_score_dice_rolled set to lower value than ability_score_dice_kept. " \
+           "Reducing ability_score_dice_kept from #{ability_score_dice_kept} to #{@ability_score_dice_rolled}"
+      self.ability_score_dice_kept = @ability_score_dice_rolled
+    end
+
+    def ability_score_dice_kept=(value)
+      compare_error_message = "cannot set ability_score_dice_kept greater than ability_score_dice_rolled"
+      new_value = ensure_positive_integer!("ability_score_dice_kept", value)
+      raise NerdDice::Error, compare_error_message if new_value > @ability_score_dice_rolled
+
+      @ability_score_dice_kept = new_value
+    end
+
     private
 
       def initialize
         @ability_score_array_size = 6
+        @ability_score_number_of_sides = 6
+        @ability_score_dice_rolled = 4
+        @ability_score_dice_kept = 3
         @randomization_technique = :random_object
+        @die_background_color = DEFAULT_BACKGROUND_COLOR
+        @die_foreground_color = DEFAULT_FOREGROUND_COLOR
+      end
+
+      def ensure_positive_integer!(attribute_name, argument_value)
+        error_message = "#{attribute_name} must be must be a positive value that responds to :to_i"
+        new_value = argument_value.to_i
+        raise ArgumentError, error_message unless new_value.positive?
+
+        new_value
+      rescue NoMethodError
+        raise ArgumentError, error_message
       end
   end
 end

data/lib/nerd_dice/dice_set.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module NerdDice
+  # The NerdDice::DiceSet class allows you to instantiate and roll a set of dice by specifying
+  # the number of sides, the number of dice (with a default of 1) and other options. As part of
+  # initialization the DiceSet will initialize and roll the Die objects specified by the
+  # DiceSet.new method. The parameters align with the NerdDice.total_dice method and
+  # NerdDice::DiceSet.new(6, 3, bonus: 5).total would be equivalent to
+  # NerdDice.total_dice(6, 3, bonus: 5)
+  #
+  # Usage:
+  #   Instantiate a d20:
+  #   <tt>dice = NerdDice::DiceSet.new(20)
+  #       dice.total # between 1 and 20
+  #   </tt>
+  #
+  #   Instantiate 3d6 + 5:
+  #   <tt>dice = NerdDice::DiceSet.new(6, 3, bonus: 5)
+  #       dice.total # between 8 and 23
+  #   </tt>
+  #
+  #   You can also specify options that will cascade to the member dice when instantiating
+  #   <tt>NerdDice::DiceSet.new(6, 3, randomization_technique: :randomized,
+  #                        foreground_color: "#FF0000",
+  #                        background_color: "#FFFFFF"
+  #                        damage_type: "necrotic"))
+  #   </tt>
+  class DiceSet
+    include Enumerable
+    include SetsRandomizationTechnique
+
+    attr_reader :number_of_sides, :number_of_dice, :dice, :bonus
+    attr_accessor :background_color, :foreground_color, :damage_type
+
+    # required to implement Enumerable uses the @dice collection
+    def each(&block)
+      @dice.each(&block)
+    end
+
+    # not included by default in Enumerable: allows [] directly on the DiceSet object
+    def [](index)
+      @dice[index]
+    end
+
+    # not included by default in Enumerable: adds length property directly to the DiceSet object
+    def length
+      @dice.length
+    end
+
+    # sorts the @dice collection in place
+    def sort!
+      @dice.sort!
+    end
+
+    # reverses the @dice collection in place
+    def reverse!
+      @dice.reverse!
+    end
+
+    # re-rolls each Die in the collection and sets its is_included_in_total property back to true
+    def reroll_all!
+      @dice.map do |die|
+        die.roll
+        die.is_included_in_total = true
+      end
+    end
+
+    # resets is_included_in_total property back to true for each Die in the collection
+    def include_all_dice!
+      @dice.map { |die| die.is_included_in_total = true }
+    end
+
+    ###################################
+    # highest instance method
+    # (aliased as with_advantage)
+    ###################################
+    # Arguments:
+    #   number_to_take (Integer default: nil) =>  the number dice to take
+    #
+    # Notes:
+    # * If the method is called with a nil value it will take all but one of the dice
+    # * If the method is called on a DiceSet with one Die, the lone Die will remain included
+    # * The method will raise an ArgumentError if you try to take more dice than the DiceSet contains
+    # * Even though this method doesn't have a bang at the end, it does call other bang methods
+    #
+    # Return (NerdDice::DiceSet) => Returns the instance the method was called on with
+    # die objects that have is_included_in_total property modified as true for the highest(n)
+    # dice and false for the remaining dice.
+    def highest(number_to_take = nil)
+      include_all_dice!
+      number_to_take = check_low_high_argument!(number_to_take)
+      get_default_to_take if number_to_take.nil?
+      @dice.sort.reverse.each_with_index do |die, index|
+        die.is_included_in_total = false if index >= number_to_take
+      end
+      self
+    end
+
+    alias with_advantage highest
+
+    ###################################
+    # lowest instance method
+    # (aliased as with_disadvantage)
+    ###################################
+    # Arguments and Notes are the same as for the highest method documented above
+    #
+    # Return (NerdDice::DiceSet) => Returns the instance the method was called on with
+    # die objects that have is_included_in_total property modified as true for the lowest(n)
+    # dice and false for the remaining dice.
+    def lowest(number_to_take = nil)
+      include_all_dice!
+      number_to_take = check_low_high_argument!(number_to_take)
+      get_default_to_take if number_to_take.nil?
+      @dice.sort.each_with_index do |die, index|
+        die.is_included_in_total = false if index >= number_to_take
+      end
+      self
+    end
+
+    alias with_disadvantage lowest
+
+    # custom attribute writer that ensures the argument is an Integer duck-type and calls to_i
+    def bonus=(new_value)
+      @bonus = new_value.to_i
+    rescue NoMethodError
+      raise ArgumentError, "Bonus must be a value that responds to :to_i"
+    end
+
+    ###################################
+    # total method
+    ###################################
+    # Return (Integer) => Returns the sum of the values on the Die objects in the collection
+    # where is_included_in_total is set to true and then adds the value of the bonus
+    # attribute (which may be negative)
+    def total
+      @dice.select(&:included_in_total?).sum(&:value) + @bonus
+    end
+
+    private
+
+      def initialize(number_of_sides, number_of_dice = 1, **opts)
+        @number_of_sides = number_of_sides
+        @number_of_dice = number_of_dice
+        parse_options(opts)
+        @dice = []
+        @number_of_dice.times { @dice << Die.new(@number_of_sides, **opts) }
+      end
+
+      def parse_options(opts)
+        self.randomization_technique = opts[:randomization_technique]
+        @background_color = opts[:background_color] || NerdDice.configuration.die_background_color
+        @foreground_color = opts[:foreground_color] || NerdDice.configuration.die_foreground_color
+        @damage_type = opts[:damage_type]
+        self.bonus = opts[:bonus]
+      end
+
+      # validates the argument input to the highest and lowest methods
+      # sets a default value if number_to_take is nil
+      def check_low_high_argument!(number_to_take)
+        number_to_take ||= number_of_dice == 1 ? 1 : number_of_dice - 1
+        raise ArgumentError, "Argument cannot exceed number of dice" if number_to_take > number_of_dice
+
+        number_to_take
+      end
+  end
+end

data/lib/nerd_dice/die.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module NerdDice
+  # The NerdDice::Die class allows you to instantiate and roll a die by specifying
+  # the number of sides with other options. As part of initialization the die will
+  # be rolled and have a value
+  #
+  # Usage:
+  #   Instantiate a d20:
+  #   <tt>die = NerdDice::Die.new(20)
+  #       die.value # between 1 and 20
+  #   </tt>
+  #
+  #   You can also specify options when instantiating
+  #   <tt>NerdDice::Die.new(12, randomization_technique: :randomized,
+  #                        foreground_color: "#FF0000",
+  #                        background_color: "#FFFFFF",
+  #                        damage_type: "necrotic"))
+  #   </tt>
+  class Die
+    include Comparable
+    include SetsRandomizationTechnique
+
+    attr_reader :number_of_sides, :value
+    attr_accessor :background_color, :foreground_color, :damage_type, :is_included_in_total
+
+    # comparison operator override using value: required to implement Comparable
+    def <=>(other)
+      value <=> other.value
+    end
+
+    # rolls the die, setting the value to the new roll and returning that value
+    def roll
+      @value = NerdDice.execute_die_roll(@number_of_sides, @randomization_technique)
+    end
+
+    alias included_in_total? is_included_in_total
+
+    private
+
+      def initialize(number_of_sides, **opts)
+        @number_of_sides = number_of_sides
+        self.randomization_technique = opts[:randomization_technique]
+        @background_color = opts[:background_color] || NerdDice.configuration.die_background_color
+        @foreground_color = opts[:foreground_color] || NerdDice.configuration.die_foreground_color
+        @damage_type = opts[:damage_type]
+        @is_included_in_total = true
+        roll
+      end
+  end
+end