class NerdDice::DiceSet

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>

Attributes

background_color[RW]
bonus[R]
damage_type[RW]
dice[R]
foreground_color[RW]
number_of_dice[R]
number_of_sides[R]

Public Class Methods

new(number_of_sides, number_of_dice = 1, **opts) click to toggle source
# File lib/nerd_dice/dice_set.rb, line 141
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

Public Instance Methods

[](index) click to toggle source

not included by default in Enumerable: allows [] directly on the DiceSet object

# File lib/nerd_dice/dice_set.rb, line 41
def [](index)
  @dice[index]
end
bonus=(new_value) click to toggle source

custom attribute writer that ensures the argument is an Integer duck-type and calls to_i

# File lib/nerd_dice/dice_set.rb, line 123
def bonus=(new_value)
  @bonus = new_value.to_i
rescue NoMethodError
  raise ArgumentError, "Bonus must be a value that responds to :to_i"
end
each(&block) click to toggle source

required to implement Enumerable uses the @dice collection

# File lib/nerd_dice/dice_set.rb, line 36
def each(&block)
  @dice.each(&block)
end
highest(number_to_take = nil) click to toggle source

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.

# File lib/nerd_dice/dice_set.rb, line 89
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
Also aliased as: with_advantage
include_all_dice!() click to toggle source

resets is_included_in_total property back to true for each Die in the collection

# File lib/nerd_dice/dice_set.rb, line 69
def include_all_dice!
  @dice.map { |die| die.is_included_in_total = true }
end
length() click to toggle source

not included by default in Enumerable: adds length property directly to the DiceSet object

# File lib/nerd_dice/dice_set.rb, line 46
def length
  @dice.length
end
lowest(number_to_take = nil) click to toggle source

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.

# File lib/nerd_dice/dice_set.rb, line 110
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
Also aliased as: with_disadvantage
reroll_all!() click to toggle source

re-rolls each Die in the collection and sets its is_included_in_total property back to true

# File lib/nerd_dice/dice_set.rb, line 61
def reroll_all!
  @dice.map do |die|
    die.roll
    die.is_included_in_total = true
  end
end
reverse!() click to toggle source

reverses the @dice collection in place

# File lib/nerd_dice/dice_set.rb, line 56
def reverse!
  @dice.reverse!
end
sort!() click to toggle source

sorts the @dice collection in place

# File lib/nerd_dice/dice_set.rb, line 51
def sort!
  @dice.sort!
end
total() click to toggle source

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)

# File lib/nerd_dice/dice_set.rb, line 135
def total
  @dice.select(&:included_in_total?).sum(&:value) + @bonus
end
with_advantage(number_to_take = nil)
Alias for: highest
with_disadvantage(number_to_take = nil)
Alias for: lowest

Private Instance Methods

check_low_high_argument!(number_to_take) click to toggle source

validates the argument input to the highest and lowest methods sets a default value if number_to_take is nil

# File lib/nerd_dice/dice_set.rb, line 159
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
parse_options(opts) click to toggle source
# File lib/nerd_dice/dice_set.rb, line 149
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