tabletop 0.2.1 → 0.3.0

data/.gitignore

@@ -2,4 +2,5 @@ Gemfile.lock
 .DS_Store
 pkg/
 doc/
-*.gem
+*.gem
+.idea/

data/README.markdown

@@ -2,17 +2,19 @@
 
 Tabletop aims to provide a simple way of describing, automating and tracking the tools and tasks involved in "analog" games, determining results from the motions and properties of various dice and chips.
 
-Currently, you can create pools of dice, and rolls that compare them to different possible results.
-
 ## Installation
 
     gem install tabletop
     
     require 'tabletop'
 
-## Dice
+## Usage
+
+For detailed information, I recommend the [full documentation](http://rubydoc.info/gems/tabletop/), but I want this file to give you a good primer, so let's get started.
 
-Dice are pretty straightforward.  They've got a number of sides, set on instantiation (defaulting to 6), and a current value between that number and 1 inclusive, which can be set on instantiation, or directly. They can be rolled, which gives them a new random value.
+### Dice
+
+Dice are pretty straightforward.  They've got a number of sides, set on instantiation (defaulting to 6), and a current value between that number and 1 inclusive, which can be set on instantiation, or set directly. Finally, they can be rolled, which gives them a new random value.
 
     d6 = Die.new
     d6.sides     #=> 6
@@ -22,7 +24,7 @@ Dice are pretty straightforward.  They've got a number of sides, set on instanti
     
     d8 = Die.new(8, 4)
     d8.sides     #=> 8
-    d8.to_s      #=> "[3]/d8"
+    d8.to_s      #=> "[4]/d8"
     
 One fun special kind of die is a "Fudge Die".  They are a special kind of three-sided die that have three possible values: -1, 0, or 1.  Those are usually expressed as '-', ' ' and '+', though. 
 
@@ -30,19 +32,27 @@ One fun special kind of die is a "Fudge Die".  They are a special kind of three-
     f.sides      #=> 3
     f.value      #=> 0
     f.to_s       #=> "[ ]"
+    
+You may not believe this, but coins are also a special case of die.  Coins have two sides, and have a value of either 1 or 0, aka heads or tails, aka "+" or " ".  They can be rolled if you really want, but you'd normally call that "flipping," right?
+
+    c = Coin.new
+    c.sides      #=> 2
+    c.value      #=> 1
+    c.to_s       #=> "(+)"
+    c.flip.to_s  #=> "( )"  
 
 ### Pools
 
-Pools are essentially arrays of Dice objects with some extra helpful methods.
+Pools are arrays of Dice objects with some extra helpful methods.
 
 The _best_ way to create one is exactly the way you'd expect: the same old d-notation we've been using for decades.  You can even combine them with `+`.
 
     3.d6           #=> [[3]/d6, [3]/d6, [4]/d6]
     2.d10 + 1.d8   #=> [[2]/d10, [6]/d10, [8]/d8]
-    
+
 You can also create them by passing Pool.new a literal array of dice, or (slightly more interesting) a string in die notation.
 
-The methods are common operations you might do on a pool of dice: summing, counting sets, dropping the lowest or highest valued dice, dropping all _but_ the lowest or highest valued dice, even dropping any dice  a specified list of values. 
+Pool's instance methods are common operations you might do on a pool of dice: summing, counting sets, dropping the lowest or highest valued dice, dropping all _but_ the lowest or highest valued dice, even dropping any dice  a specified list of values. 
 
     d&d = 3.d6.sum    #=> 13
     ore = 10.d10.sets #=> ["3x2", "2x8", "1x7", "1x6", "1x4", "1x3", "1x1"]
@@ -53,33 +63,33 @@ You can also #roll an entire pool, or you can interact with individual dice in t
   
 When pools are compared to each other or to numbers with <=>, it's assumed you're actually interested in their sum.  The same thing happens if you try to add a number to them.
 
-    d&d_alt = 4.d4 + 4   #=> 17
-    1.d20 > 2.d10        #=> false
+    4.d4 + 4         #=> 17
+    1.d20 > 2.d10    #=> false
     
 ### Rolls
 
-Rolls are very much under construction, but they allow you to automate randomly determining results in a variety of ways.
+Rolls are very much under construction and their API is in flux, but they allow you to automate randomly determining results in a variety of ways.
 
-Rolls have a lot of options.  Let's start by taking an example from one of my favorite games, Apocalypse World.
+Rolls have a lot of options, described in detail in the documentation.  But let's take a simple example from one of my favorite games, Apocalypse World.
 
 >When you open your brain to the world’s psychic maelstrom, roll+weird. On a hit, the MC will tell you something new and interesting about the current situation, and might ask you a question or two; answer them. On a 10+, the MC will give you good detail. On a 7–9, the MC will give you an impression.
 
-(In the parlance of the game, a "hit" is getting a 7 or higher on 2d6, plus a stat.)
+(In the parlance of the game, a "hit" is getting a 7 or higher.  "Roll+weird" means to roll 2d6 and add the character's "weird" stat, which is an integer from -1 to 3.)
 
-Here's how I'd write it out in Tabletop.
+Here's how I'd write that out in Tabletop:
 
-    cool = [-1, 0, 1, 2, 3].sample #=> get a random stat
+    weird = [-1, 0, 1, 2, 3].sample #=> get a random stat
     
     open_brain = Roll.new(2.d6) {
-      modifier cool
-      at_least 7, "the MC will tell you something new and interesting about the current situation"
+      add weird
+      at_least 7, "the MC will tell you something new and interesting about the current situation..."
       equals (7..9), "...but it's just an impression"
       at_least 10, "...and it's a good detail"
     }
     
-Simple, right?  `add` sets a value to be permanently added for the purposes of determining results.  `at_least` and `equals` take an integer (or a range, in the case of `equals`) as their first parameter, and then one or more results to trigger if the pools result meets the stated condition.
+Simple, right?  `add` sets a value to be permanently added for the purposes of determining results.  `at_least` and `equals` take an integer (or a range, in the case of `equals`) as their first parameter, and then one or more values to return if the pool's result meets the stated condition.
 
-Once they've been instantiated, Rolls have two important methods. 
+Once they've been instantiated, Rolls have three important methods. 
 
 #### #roll
  
@@ -88,25 +98,38 @@ This method which re-rolls all the dice in the pool, and returns the Roll object
     bad_luck = -1
     open_brain.roll(:modifier => bad_luck)
 
-#### #effects
+#### #result
 
-This method returns an array, based on the current state of the pool, and any conditions and modifiers. Here's what I can tell you about the Array:
+This method, by default, returns the sum of the values of the Roll's dice, plus any static modifiers from `add` or per-roll modifiers from `roll(:modifier)`.
 
-* Its first element is the "result" of the current pool, which is by default the sum of the values of its dice, plus any static or per-roll modifiers.
-* The second and subsequent elements are the results of any satisfied conditions.
-* If no conditions are satisfied, then the second and final element of the array is `nil`
+But!  When instantiating a roll, you can call `set_result` with an appropriate symbol to make `result` mean something else. 
+
+For example, in Exalted, you principally care about how many dice in your pool came up 7 or higher, counting 10s twice:
+
+    exalted = Roll.new(8.d10) do
+      set_result :count, :at_least=>7, :doubles=>10
+    end
+    
+    exalted.result   #=> 2
+    exalted.sum      #=> 30
+
+#### #effects
+
+This method returns either an array containing the results passed to any `at_least` and `equals` calls whose conditions were met, or nil if no such conditions were met.
 
 So, possible results for our cool AW roll:
 
-    open_brain.roll.effects #=> [4, nil]
-    open_brain.roll.effects #=> [8, "the MC will tell you something new and interesting about the current situation", "...but it's just an impression"]
-    roll, *effects = open_brain.roll.effects 
-    puts roll               #=> 10 
-    puts effects            #=> ["the MC will tell you something new and interesting about the current situation", "...and it's a good detail"]
+    open_brain.roll.effects #=> nil
+    open_brain.roll.effects #=> ["the MC will tell you something new and interesting about the current situation", "...but it's just an impression"]
+    open_brain.roll 
+    puts open_brain.result  #=> 10 
+    puts open_brain.effects #=> ["the MC will tell you something new and interesting about the current situation", "...and it's a good detail"]
     
-Just these few functions already give enough functionality to do different kinds of rolls, but there's a lot more in store.
+### Coming Soon
+
+That's already enough functionality to do many different kinds of rolls, but there's a lot more in store.
 
-One last thing I'll briefly note is that Rolls can be nested. 
+One bonus thing I'll briefly note is that Rolls can be nested, and `effects` returns them as such. 
 
     rps = Roll.new(1.d3) {
       equals 1, "rock"
@@ -122,21 +145,20 @@ One last thing I'll briefly note is that Rolls can be nested.
       equals 1, "Rock Paper Scissors", rps
       equals 2, "JanKenPon", jkp 
     }
-    fist_game.roll.effects   #=> [2, "JanKenPon", [1, "guu"]]
+    fist_game.roll.effects   #=> ["JanKenPon", ["guu"]]
 
 This can lead to some surprisingly sophisticated constructions.  Remember that "tables" are really just a special case of a roll!
 
 ## How to contribute
 
-*First and most importantly*, any complaints or suggestions, *regardless of coding knowledge*, are *always welcome* at <nick.novitski@gmail.com>.
+*First and most importantly*, if you're reading this and you make games, please tell me about them!  Second, any complaints or suggestions are always welcome, _regardless of coding knowledge_.  Feel free to communicate your opinions by [creating an issue on github](https://github.com/njay/tabletop/issues), or just dropping me a line at <nick.novitski@gmail.com>.
 
-But, if you're feeling up to it, you can always do more.  You probably already know the drill by this point.
+If you have clear ideas about what more the project should do, and you think you can do something about it, then make it so!  Don't even bother asking me about it, you know the drill:
 
 * Fork the project.
-* Create a topic branch
+* Create a topic branch.
 * Make tests that describe your feature addition or bug fix.
-* Write code that passes those tests
-* Commit, without altering the version.
+* Write code that passes those tests.
 * Send me a pull request.
 
 ## Copyright

data/Rakefile

@@ -55,8 +55,12 @@ task :clean do
   FileUtils.rm_rf "pkg"
 end
 
+desc "Update master and develop branches on github"
+task :github do
+  system "git push origin : --tags"
+end
+
 desc "Push changes to github and rubygems"
-task :publish do
-  system "git push origin master --tags"
+task :publish => :github do
   system "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
 end

data/lib/fixnum.rb

@@ -4,21 +4,17 @@ class Fixnum
   
   # Returns a pool of dice of the given sides and size self
   def dX(sides)
-    dice = []
-    times { dice << Tabletop::Die.new(sides) }
-    Tabletop::Pool.new(dice)
+    Tabletop::Pool.new("#{self}d#{sides}")
   end
   
   # Returns a pool of fudge dice of size self
   def dF
-    dice = []
-    times {dice << Tabletop::FudgeDie.new}
-    Tabletop::Pool.new(dice)
+    Tabletop::Pool.new("#{self}dF")
   end
   
-  # Matches any methods of the form d(.*), and calls #dX($1.to_i)
+  # Matches any methods of the form dN, where N > 0, and calls #dX(N)
   def method_missing(symbol, *args, &block)
-    if symbol =~ /^d(.*)$/
+    if symbol =~ /^d(.*)$/ and $1.to_i > 0
       dX($1.to_i)
     else
       super

data/lib/tabletop/condition.rb

@@ -0,0 +1,20 @@
+module Tabletop
+
+  # Stores a block to evaluate against a Pool
+  class Condition
+    def initialize(&block)
+      @test = block
+    end
+
+    # returns false if the stored block evaluates to false or nil,
+    # otherwise returns true
+    def met_by?(pool)
+      if @test.call(pool)
+        true
+      else
+        false
+      end
+    end
+  end
+
+end

data/lib/tabletop/pool.rb

@@ -1,42 +1,59 @@
 require_relative 'randomizers'
-require 'delegate'
 
 module Tabletop
-  class Pool < DelegateClass(Array)
+  class Pool < Array
     include Comparable
     
-    # requires one parameter, which can be either of 
+    # Requires one parameter, which can be either of 
     #  - an array of Die objects
-    #  - a string of d-notation
+    #  - a string of elements separated by spaces which can be in two different formats:
+    #     + d-notation (ie, "d20", "3dF", etc) denoting dice that will be given random values
+    #     + a value, a slash, then a number of sides (ie, "2/6", "47/100", etc)
     def initialize(init_dice)
-      return super(init_dice) if init_dice.instance_of?(Array)
+      return super(init_dice) if init_dice.kind_of?(Array)
       d_groups = init_dice.split
       dice = []
-      d_groups.each do |d_notation|
-        number, sides = d_notation.split('d')
-        number = number.to_i
-        number += 1 if number == 0
-        if sides.to_i > 0
-          number.times { dice << Die.new(sides.to_i)}
-        elsif sides == "F"
-          number.times {dice << FudgeDie.new}
+      d_groups.each do |d|
+        if d =~ /d/ # d_notation
+          number, sides = d.split('d')
+          number = number.to_i
+          number += 1 if number == 0
+          if sides.to_i > 0
+            number.times { dice << Die.new(sides: sides.to_i)}
+          elsif sides == "F"
+            number.times {dice << FudgeDie.new}
+          end
+        else
+          dice << Die.new_from_string(d)
         end
       end
       super(dice)
     end
     
-    # Behavior depends on the class of what is passed to it.
-    # Numeric::  returns the sum of the operand and the values of all dice in the receiving pool
-    # Pool:: returns a new pool with copies of all the dice in both operands
-    # AnythingElse:: raises an ArgumentError
+    # If adding a pool or array of dice objects, returns the the union of these pools.
+    #
+    # If adding a number, returns the sum of that number and all die values in the pool.
+    #
+    # Otherwise, raises an ArgumentError.
     def +(operand)
-      # if the operator is a pool, or an array only of Die objects...
-      if operand.instance_of?(Pool) or (operand.instance_of?(Array) and !(operand.detect{|obj| !(obj.instance_of?(Die))}))
+      # if the parameter seems to be an array of dice (this includes pools)
+      if operand.respond_to?(:all?) and operand.all?{|obj| obj.respond_to?(:roll)}
         new_union(operand)
-      elsif operand.kind_of? Numeric
+      # if the parameter seems to be a randomizer
+      elsif operand.respond_to?(:sides)
+        new_union([operand])
+      elsif operand.respond_to?(:to_int)
         sum + operand
       else
-        raise ArgumentError, "Cannot add operand of class #{operand.class}"
+         raise ArgumentError, "Only numbers and other pools can be added to pools"
+      end
+    end
+
+    def -(operand)
+      if operand.respond_to?(:to_a)
+        super
+      else
+        sum - operand
       end
     end
     
@@ -89,6 +106,12 @@ module Tabletop
       end
       self
     end
+
+    def roll_if(&block)
+      each do |die|
+        die.roll if block.call(die)
+      end
+    end
     
     # Returns the sum of all values of dice in the pool
     def sum
@@ -109,12 +132,24 @@ module Tabletop
     
     # Returns a Pool containing copies of the n highest dice
     def highest(n=1)
-      Pool.new(sort.reverse.first(n))
+      if n < length
+        drop_lowest(length-n)
+      else
+        self
+      end
     end
     
     # Returns a Pool containing copies of the n lowest dice
     def lowest(n=1)
-      Pool.new(sort.first(n))
+      sorted = sort.first(n)
+      in_order = []
+      each do |d|
+        if sorted.include?(d)
+          in_order << d
+          sorted -= [d]
+        end
+      end
+      Pool.new(in_order)
     end
     
     # Returns a copy of the Pool, minus the n highest-value dice
@@ -133,19 +168,15 @@ module Tabletop
     def drop(to_drop)
       to_drop = [to_drop].flatten #turn it into an array if it isn't one.
       kept = reject{|die| to_drop.any?{|drop_value| die.value == drop_value }}
-      return Pool.new(kept)
+      Pool.new(kept)
     end
     
     private
     def new_union(array)
       union = [self, array].flatten
       new_pool =[]
-      union.each do |die| 
-        if die.instance_of?(FudgeDie)
-          new_pool << FudgeDie.new(die.value)
-        else
-          new_pool << Die.new(die.sides, die.value)
-        end
+      union.each do |die|
+        new_pool << die.class.new(sides:die.sides, value:die.value)
       end
       Pool.new(new_pool)
     end

data/lib/tabletop/randomizers.rb

@@ -3,23 +3,29 @@ module Tabletop
     include Comparable
     
     attr_reader :sides, :value
-    
-    # Sides must be greater then or equal to 1.  
-    # If init_value is nil, then #roll is called. 
-    def initialize(sides=6, init_value=nil)
-      if sides <= 1
-        raise ArgumentError, "Die cannot have #{sides} sides"
-      end
-      unless sides.kind_of? Integer
-        raise ArgumentError, "Parameter must be Integer, not #{sides.class}"
+
+    # :sides must be greater then or equal to 1.  By default it is 6.
+    # If :value is nil, then #roll is called.
+    def initialize(params={})
+
+      if params[:sides].nil?
+        @sides = 6
+      else
+        @sides = Integer(params[:sides])
+        raise ArgumentError if @sides < 2
       end
-      @sides = sides
-      if init_value.nil?
-        init_value = roll
+
+      if params[:value].nil?
+        roll
       else
-        raise ArgumentError unless valid_value?(init_value)
+        self.value = params[:value]
       end
-      @value = init_value
+    end
+
+    def self.new_from_string(string)
+      raise ArgumentError unless string.respond_to?(:split)
+      v, s = string.split('/')
+      Die.new(sides: s.to_i, value: v.to_i)
     end
     
     # Sets @value to a random number n, where 1 <= n <= @sides
@@ -34,8 +40,9 @@ module Tabletop
     
     # Raises ArgumentError if new_value isn't between 1 and @sides inclusive
     def value=(new_value)
-      raise ArgumentError unless valid_value?(new_value)  
-      @value = new_value
+      integer_value = Integer(new_value)
+      raise ArgumentError unless valid_value?(integer_value)
+      @value = integer_value
     end
     
     # Compares based on value of the die
@@ -50,7 +57,7 @@ module Tabletop
     
     protected
     def valid_value?(val)
-      val > 0 and val <= @sides
+      0 < val and @sides >= val
     end
   end
   
@@ -58,8 +65,8 @@ module Tabletop
   # A FudgeDie is a kind of three-sided Die that has a value
   # of either 0, 1, or -1.
   class FudgeDie < Die
-    def initialize(init_value = nil)
-      super(3, init_value)
+    def initialize(params = {})
+      super(sides: 3, value: params[:value])
     end
     def roll
       @value = rand(sides)-1
@@ -80,8 +87,8 @@ module Tabletop
   # A coin is a kind of two-sided Die that has a value of
   # either 0 or 1
   class Coin < Die
-    def initialize(value=nil)
-      super(2, value)
+    def initialize(params={})
+      super(sides: 2, value: params[:value])
     end
     
     def roll #:nodoc:
@@ -93,7 +100,15 @@ module Tabletop
       roll
       self
     end
-    
+
+    def heads?
+      @value == 1
+    end
+
+    def tails?
+      @value == 0
+    end
+
     # Returns either "( )" or "(+)" depending on @value
     def to_s
       "(#{[' ', '+'][value]})"

data/lib/tabletop/roll.rb

@@ -10,6 +10,7 @@ module Tabletop
     def initialize(outcomes, conditions)
       @outcomes, @conditions = outcomes, conditions
     end
+    
   end
     
   class Roll
@@ -38,11 +39,10 @@ module Tabletop
     end
     
     
-    # Returns an array.
-    # + The first value in the array is #result
-    # + If a "difficulty" was set in the most call of #roll, and #result meets or exceeds it, then the second element will be "Success". 
-    # + if the conditions of any of the roll's @possibilities are met (see #meets?), then their outcomes will be all following elements.
-    # + if none of the above conditions are met, the second and final element is nil. 
+    # Returns either an array or nil.
+    # + If a "difficulty" was set in the most recent call of #roll, and #result meets or exceeds it, then the first element will be "Success". 
+    # + If the conditions of any of the roll's @possibilities are met (see #meets?), then their outcomes will be all following elements. 
+    # + If none of these conditions are met, returns nil
     def effects
       results = []
       
@@ -51,22 +51,15 @@ module Tabletop
       end
       
       @possibilities.each do |poss|
-        if meets?(poss)
-          poss.outcomes.each do |outcome|
-            if outcome.instance_of?(Roll)
-              results << outcome.roll.effects
-            else
-              results << outcome
-            end
-          end
-        end
+        results.concat(check(poss))
       end
-          
+      
+      results.compact!
+
       if results.empty?
-        results << nil 
+        results = nil
       end
-      
-      results.unshift(result)
+      results
     end
     
     # Without any options passed, calls Pool#roll on the roll's pool.  Returns the Roll.
@@ -94,21 +87,36 @@ module Tabletop
       self 
     end
     
-    # Takes an object, returns false if anything set in the object's conditions hash 
-    # are not met by #sum, otherwise returns true 
+    # Takes a Possibility, returns an Array containing nil if any of it's conditions
+    # aren't met. Otherwise, returns an Array containing all the Possibility's
+    # outcomes.  If any of those outcomes are Roll objects, they are rolled and their
+    # #effects are returned as an outcome.
     #--
     # TODO: checks #result, not #sum
-    def meets?(p)
-      answer = true
-      if p.conditions[:>=]
-        if p.conditions[:>=] > sum
-          answer = false
-        end
+    def check(p) #:nodoc:
+      conditions_met = true
+      
+      if p.conditions[:>=] and sum < p.conditions[:>=]
+        conditions_met = false
+      end
+      
+      if p.conditions[:==] and p.conditions[:==] != sum
+        conditions_met = false
       end
-      if p.conditions[:==]
-        answer = false if p.conditions[:==] != sum
+      
+      if conditions_met
+        results = []
+        p.outcomes.each do |outcome|
+          if outcome.instance_of?(Roll)
+            results << outcome.roll.effects
+          else
+            results << outcome
+          end
+        end
+        results
+      else
+        [nil]
       end
-      answer
     end
     
     # The sum of the values of dice in the pool, and any modifier set in