droll 1.0rc5.2.3 → 1.0rc5.3.1

data/README.markdown

@@ -26,18 +26,28 @@ total to yield a final number.
 The first number following each 4 or 5 in this example is the result of a die
 immediately rolled to handle exploding die values.
 
+This brief explanation of capabilities is slightly out of date.  See RDoc and
+code comments for details.  In fact, anything in this file might be out of date
+at any given time, though I will try to update it in a timely manner.
+
 
 ## installation
 
-If you already have Ruby installed, installing droll should be easy.  Just
-download the gem package from the [Bitbucket repository][bitbucket] and use the
-gem command to install it:
+If you already have Ruby installed with rubygems, installing droll should be
+easy.  Just use the gem command.  At present, because droll is in a pre-release
+state ("release candidate"), you need to use the `--pre` option to install from
+the RubyGems archive:
+
+    $ gem install droll --pre
+
+You can also download the gem package from the [Bitbucket repo][bitbucket] and
+use the gem command to install it:
 
     $ gem install droll-<version>.gem
 
 In this example, replace `<version>` with the version number in the name of the
 gemfile you downloaded.  For version 1.0.0, for instance, the command might
-look like this:
+look like this (though as of this writing it is not yet at version 1.0.0):
 
     $ gem install droll-1.0.0.gem
 
@@ -49,15 +59,6 @@ systems, please feel free to submit patches to this README file via one of the
 approaches detailed in the **contributions** section at the bottom of this
 file.
 
-Eventually, droll will be distributed through Ruby's standard centralized
-package management system, and the entire installation process will be reduced
-to the following for most cases:
-
-    $ gem install droll
-
-That day has not yet arrived.  Special circumstances apply to the use of the
-`drollbot` command; see below.
-
 ## usage
 
 The following sections explain how to use the executable tools that come with

data/bin/droll

@@ -40,6 +40,13 @@ SYNTAX
                 than a threshold value, roll another die of that type and
                 add it to the total.
 
+            k   Only use the highest die values, up to a number of dice
+                equal to a specified value.  When the "k" is capitalized
+                "K", use the lowest die values instead.
+
+            n   Count the number of dice that yield values equal to or
+                higher than a threshhold value.
+
     3. Die Value (Mandatory; No Default)
 
         Indicates the set of values the die can produce.  Two types of die
@@ -93,6 +100,19 @@ EXAMPLES
     3e02.4  Same as 3e02, but roll an additional 1x02 if the total of the
             original 3d02 roll is equal to 4 or greater.
 
+    3k02    Roll three three-sided dice for values between 0 and 2 as
+            though rolling 3d02, but only keep the highest die.
+
+    3k02.2  Same as 3k02, but keep the highest two dice.
+
+    3K02.2  Same as 3k02.2, but keep the lowest two dice.
+
+    3n10    Roll three ten-sided dice for values between 1 and 10, and
+            count only the number of dice whose values are 10.
+
+    3n10.6  Same as 3n10, but count the number of dice whose values are 6
+            or higher.
+
 EOF
 
 version_help = <<EOF

data/lib/droll.rb

@@ -48,15 +48,53 @@ exploding occurs, leaving an 11 result from the virtual dice.  As normal, when
 all die rolling is resolved and summed, the modifier (+7 in this case) is
 applied to the total.
 
-==== Explosion Threshold
+==== Threshhold Acceptance
 
-An exploding threshold may be specified by a period/fullstop character followed
-by a number, with any modifiers coming after it:
+Using k instead of d, x, or e in the die code indicates that out of the number
+of dice rolled, only the highest of them will be kept ("k" is for "keep").
+Thus, for this die code, only the highest result is kept:
+
+        2k20
+
+If the k is capitalized, the lowest result is kept instead of the highest.
+
+==== Threshhold Counting
+
+In some cases, it may be desirable to count the number of dice that produce a
+result of the maximum value the die can produce.  Use n instead of d, x, e, or
+k in this die code:
+
+        3n4
+
+This will yield a result that is a count of four-sided dice that meet a
+threshhold equal to the maximum value of the die (4).  The "n" is short for
+"number", as in "the number of dice that meet or exceed the threshhold".
+
+==== Alternate Threshholds
+
+A threshhold number may be specified by a period/fullstop character followed by
+a number, with any modifiers coming after it:
 
         3x4.3+7
 
-In this case, the die code is treated the same way as in the previous example,
-except that it explodes on 3 or 4, and not just on 4.
+In this case, the die code is treated the same way as in the previous 3x4+7
+example, except that it explodes on 3 or 4, and not just on 4.
+
+For threshhold acceptance, the threshhold number is used to determine how many
+of the highest or lowest die values will be kept.  In this die code, then, the
+result is the sum of the highest three die values:
+
+        4k6.3
+  
+In the case of threshhold counting, it would yield a result that is a count of
+four-sided dice that meet or exceed a threshhold of 3, which means a count of
+all dice with values of 3 or 4, before adding the number 7 to the total with
+this die code:
+
+        3n4.3+7
+
+Note that for threshhold counting, the modifier is applied to the count, and
+not to die roll values.
 
 ==== Alternate Minimum Value
 
@@ -66,11 +104,7 @@ a 0-N range, precede the die value with a 0 in the die code:
         3d03
 
 This die code rolls three virtual dice whose values may be anywhere in the
-range of 0-3 and returns the total for all three dice.  For other minimum
-values, apply a modifier.  For instance, for a value ranging from -3 to 0, a
-die code like the following may be used:
-
-        d03-3
+range of 0-3 and returns the total for all three dice.
 
 === Usage:
 
@@ -102,7 +136,7 @@ This method returns the version number for the Droll gem.
 
 =end
 
-  def self.version; '1.0rc5.2.3'; end
+  def self.version; '1.0rc5.3.1'; end
 
 =begin rdoc
 
@@ -149,7 +183,7 @@ The +dcode+ argument is any valid die code recognized by Droll.
     if 0 != @pcode['val'][0].to_i
       if 2 > @pcode['val'].to_i
         return false
-      elsif 2 > @pcode['thresh'].to_i
+      elsif @pcode['type'].match(/[^Kk]/) and 2 > @pcode['thresh'].to_i
         return false
       end
     end
@@ -163,7 +197,12 @@ The +dcode+ argument is any valid die code recognized by Droll.
     d['num'], d['type'], die_vals = die_roll.split(/([A-Za-z])/)
     d['val'], d['thresh'] = die_vals.split(/\./)
     d['val'] = d['val'].to_s
-    d['thresh'] ||= d['val'].sub(/^0/, '')
+
+    if d['type'].match(/[Kk]/)
+      d['thresh'] ||= 1
+    else
+      d['thresh'] ||= d['val'].sub(/^0/, '')
+    end
 
     d['num'] = 1 if d['num'] == ''
     d['sign'] ||= '+'
@@ -197,7 +236,98 @@ The +dcode+ argument is any valid die code recognized by Droll.
 
   public
 
-=begin
+=begin rdoc
+
+This method takes an array of numeric values as its sole argument, and compares
+it to the instantiated die code's threshhold value.  It returns an integer
+value equal to the number of values in the array argument that are equal to or
+greater than the threshhold value.
+
+Given a threshhold of 2:
+
+        count_dice_min_thresh([0,1,2,3])        #=> 2
+
+        count_dice_min_thresh([0,1])            #=> 0
+
+=end
+
+  def count_dice_min_thresh(dresults)
+    num_dice_min_thresh = dresults.reject do |n|
+      n < @pcode['thresh'].to_i
+    end.size
+  end
+
+=begin rdoc
+
+This method takes an array of numeric values as its sole argument, and returns
+the total of the highest N values in the array, where N is the instantiated die
+code's threshhold value.
+
+Given a die code of 3k02:
+
+        sum_thresh_high_dice([2, 2, 2])         #=> 2
+
+        sum_thresh_high_dice([0, 0, 1])         #=> 1
+
+Given a die code of 3k02.2:
+
+        sum_thresh_high_dice([0, 1, 2])         #=> 3
+
+        sum_thresh_high_dice([0, 0, 1])         #=> 1
+
+=end
+
+  def sum_thresh_high_dice(dresults)
+    dresults.sort.reverse[0..(@pcode['thresh'].to_i - 1)].inject(:+)
+  end
+
+=begin rdoc
+
+This method takes an array of numeric values as its sole argument, and returns
+the total of the lowest N values in the array, where N is the instantiated die
+code's threshhold value.
+
+Given a die code of 3K02:
+
+        sum_thresh_low_dice([1, 1, 1])          #=> 1
+
+        sum_thresh_low_dice([0, 1, 2])          #=> 0
+
+Given a die code of 3K02.2:
+
+        sum_thresh_low_dice([0, 1, 2])          #=> 1
+
+        sum_thresh_low_dice([1, 2, 2])          #=> 3
+
+=end
+
+  def sum_thresh_low_dice(dresults)
+    dresults.sort[0..(@pcode['thresh'].to_i - 1)].inject(:+)
+  end
+
+=begin rdoc
+
+This method takes an array of numeric values as its sole argument, and compares the total of the values in the array to the product of the instantiated die code's threshhold value and number of dice value.  Unless that product is greater than that total, the results of a die roll of 1xX.Y are appended to the array provided in the method argument, where X is the value of the instantiated die code and Y is the threshhold of the instantiated die code.
+
+Given a die code of 2e2:
+
+    explode_on_max_total([2, 2])                #=> [2, 2, ...]
+
+    explode_on_max_total([2, 1])                #=> [2, 1]
+
+=end
+
+  def explode_on_max_total(dresults)
+    dice_total = dresults.map {|s| s.to_i }.inject(:+)
+    unless (@pcode['thresh'].to_i * @pcode['num'].to_i) > dice_total
+      dresults.push(
+        roll_die @pcode['val'], 'x', @pcode['thresh']
+      )
+    end
+    dresults.flatten
+  end
+
+=begin rdoc
 
 By default, this method returns a string showing the die code rolled, the
 individual die rolls that make up the complete roll of dice, the modifier
@@ -224,17 +354,19 @@ an integer equal to the total result.
     end
 
     if @pcode['type'] == 'e'
-      dice_total = running_totals.map {|s| s.to_i}.inject(:+)
-      if dice_total >= @pcode['thresh'].to_i
-        running_totals.push(
-          roll_die @pcode['val'], 'x', @pcode['thresh']
-        )
-      end
-      running_totals.flatten!
+      running_totals = explode_on_max_total(running_totals)
     end
 
-    total_result = running_totals.map {|s| s.to_i }.inject do |sum,n|
-      sum ? sum+n : n
+    if @pcode['type'] == 'k'
+        total_result = sum_thresh_high_dice running_totals
+    elsif @pcode['type'] == 'K'
+        total_result = sum_thresh_low_dice running_totals
+    elsif @pcode['type'] == 'n'
+      total_result = count_dice_min_thresh running_totals
+    else # "normal" totaling
+      total_result = running_totals.map {|s| s.to_i }.inject do |sum,n|
+        sum ? sum+n : n
+      end
     end
 
     case @pcode['sign']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: droll
 version: !ruby/object:Gem::Version
-  version: 1.0rc5.2.3
+  version: 1.0rc5.3.1
   prerelease: 3
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-16 00:00:00.000000000 Z
+date: 2012-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: isaac
-  requirement: &12637340 !ruby/object:Gem::Requirement
+  requirement: &6030100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,7 +21,7 @@ dependencies:
         version: '0.2'
   type: :runtime
   prerelease: false
-  version_requirements: *12637340
+  version_requirements: *6030100
 description: ! "    Droll is a Ruby library providing dice roller functionality, with
   a\n    command line utility and an IRC bot as included user interfaces.\n"
 email: code@apotheon.net