tabletop 0.2.0 → 0.2.1

data/lib/fixnum.rb

@@ -1,16 +1,22 @@
 require 'tabletop'
 
 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)
   end
+  
+  # Returns a pool of fudge dice of size self
   def dF
     dice = []
     times {dice << Tabletop::FudgeDie.new}
     Tabletop::Pool.new(dice)
   end
+  
+  # Matches any methods of the form d(.*), and calls #dX($1.to_i)
   def method_missing(symbol, *args, &block)
     if symbol =~ /^d(.*)$/
       dX($1.to_i)
@@ -18,6 +24,8 @@ class Fixnum
       super
     end
   end
+  
+  # Returns true for :dN, where N.to_i is a number > 0
   def respond_to?(symbol, include_private = false)
     if symbol.to_s =~ /^d(.*)$/
       true if $1.to_i > 0

data/lib/tabletop/pool.rb

@@ -4,6 +4,10 @@ require 'delegate'
 module Tabletop
   class Pool < DelegateClass(Array)
     include Comparable
+    
+    # requires one parameter, which can be either of 
+    #  - an array of Die objects
+    #  - a string of d-notation
     def initialize(init_dice)
       return super(init_dice) if init_dice.instance_of?(Array)
       d_groups = init_dice.split
@@ -21,6 +25,10 @@ module Tabletop
       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
     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))}))
@@ -32,21 +40,26 @@ module Tabletop
       end
     end
     
+    #  Compares the operand to #sum  
     def <=>(operand)
         sum <=> operand.to_int
     end
       
+    # Returns #sum times the operand
     def *(operand)
       sum * operand
     end
     
-    def coerce(other)
+    def coerce(other) #:nodoc:
       [other, sum]
     end
     
+    # Returns an array of the value of each die in the pool 
     def values
       map {|die| die.value}
     end
+    
+    # Returns a string of the pool's dice in d-notation 
     def dice
       fudge = nil
       result = {}
@@ -68,18 +81,24 @@ module Tabletop
       end
       d_array
     end
+    
+    # Rolls every die in the pool, and returns the Pool.
     def roll
       each do |die|
         die.roll
       end
       self
     end
+    
+    # Returns the sum of all values of dice in the pool
     def sum
       inject(0) {|sum, d| sum + d.value}
     end
     def to_int
       sum
     end
+    
+    # Returns a string describing all sets of die values in the pool in ORE notation.
     def sets
       result = {}
       each do |die|
@@ -87,18 +106,30 @@ module Tabletop
       end
       result.sort_by{|height, width| [width, height] }.collect {|i| i[1].to_s+"x"+i[0].to_s}.reverse
     end
+    
+    # Returns a Pool containing copies of the n highest dice
     def highest(n=1)
       Pool.new(sort.reverse.first(n))
     end
+    
+    # Returns a Pool containing copies of the n lowest dice
     def lowest(n=1)
       Pool.new(sort.first(n))
     end
+    
+    # Returns a copy of the Pool, minus the n highest-value dice
     def drop_highest(n=1)
       Pool.new(self-highest(n))
     end
+    
+    # Returns a copy of the Pool, minus the n lowest-value dice.
     def drop_lowest(n=1)
       Pool.new(self-lowest(n))
     end
+    
+    # Returns a copy of the current pool, minus any 
+    # dice with values equal the value (or in the array 
+    # of values) passed. 
     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 }}

data/lib/tabletop/randomizers.rb

@@ -1,7 +1,11 @@
 module Tabletop
   class Die
     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"
@@ -17,21 +21,29 @@ module Tabletop
       end
       @value = init_value
     end
+    
+    # Sets @value to a random number n, where 1 <= n <= @sides
     def roll
       @value = rand(sides)+1
     end
     
+    # Returns a string in the form "[@value]/d@sides"
     def to_s
       "[#{value}]/d#{sides}"
     end
     
+    # 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
     end
+    
+    # Compares based on value of the die
     def <=>(operand)
       @value <=> operand.to_int
     end
+    
+    # Returns the die's value
     def to_int
       @value
     end
@@ -42,6 +54,9 @@ module Tabletop
     end
   end
   
+  
+  # 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)
@@ -50,6 +65,7 @@ module Tabletop
       @value = rand(sides)-1
     end
     
+    # Returns either "[-]", "[ ]", or "[+]", depending on @value
     def to_s
       "[#{['-', ' ', '+'][@value+1]}]"
     end
@@ -60,20 +76,25 @@ module Tabletop
     end
   end
   
+  
+  # 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)
     end
     
-    def roll
+    def roll #:nodoc:
       @value = rand(sides)
     end
     
+    # set to a random value, then return itself 
     def flip
       roll
       self
     end
     
+    # Returns either "( )" or "(+)" depending on @value
     def to_s
       "(#{[' ', '+'][value]})"
     end

data/lib/tabletop/roll.rb

@@ -2,18 +2,25 @@ require_relative 'pool'
 
 module Tabletop
   
-  class Possibility
-    attr_reader :outcomes, :conditions
+  class Possibility #:nodoc: all
+    attr_reader :outcomes
     
+    attr_reader :conditions
+
     def initialize(outcomes, conditions)
-      @outcomes = outcomes
-      @conditions = conditions
+      @outcomes, @conditions = outcomes, conditions
     end
   end
     
   class Roll
-    attr_reader :pool, :possibilities
+    # Rolls of necessity have a Pool object against which they check possible results.
+    attr_accessor :pool
     
+
+    # The block contains methods that further detail the roll, as described below.  
+    # pool must be (surprise!) a Pool.  It's optional, because if #sides is passed 
+    # in the block, then #roll can be called with a number of dice to roll, and a 
+    # new Pool object will be instantiated every time this is done. 
     def initialize(pool=nil, &block)
       if pool
         raise ArgumentError if pool.class != Tabletop::Pool
@@ -30,6 +37,12 @@ module Tabletop
       end
     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. 
     def effects
       results = []
       
@@ -48,7 +61,6 @@ module Tabletop
           end
         end
       end
-      
           
       if results.empty?
         results << nil 
@@ -57,6 +69,15 @@ module Tabletop
       results.unshift(result)
     end
     
+    # Without any options passed, calls Pool#roll on the roll's pool.  Returns the Roll.
+    # 
+    # opts can have a few different values:
+    # :modifier:: adds to all subsequent calls to #sum, until #roll is called again
+    # :pool:: if #sides was called in the initialize block, and this is set, then a Pool of appropriate sides and number is created and assigned to @pool.
+    # :difficulty:: see #effects 
+    #--
+    # TODO: @difficulty changes back to nil if it is not called in a given roll.
+    # TODO: abstract out ternary?
     def roll(opts={})
       @roll_modifier = opts[:modifier] ? opts[:modifier] : 0
       if @die_sides
@@ -73,6 +94,10 @@ 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 
+    #--
+    # TODO: checks #result, not #sum
     def meets?(p)
       answer = true
       if p.conditions[:>=]
@@ -86,17 +111,26 @@ module Tabletop
       answer
     end
     
+    # The sum of the values of dice in the pool, and any modifier set in 
+    # instantiation (see #add), or the most recent call to #roll.
     def sum
       @pool.sum + @static_modifier + @roll_modifier
     end
     
-    # instance_eval methods
-    
-    ## Possibility-creating methods
+    # Attaches an object to work with #meets?.
+    # 
+    # value:: An integer.
+    # outcomes:: An array of values to contribute to #effects if #meets? is true.
     def at_least(value, *outcomes)
       @possibilities << Possibility.new(outcomes, :>= => value)
     end
     
+    # Attaches an object to work with #meets?.
+    #
+    # values:: Can be either an integer, or a Range.  If it's a range, then #equals creates an object for each number in the range.  If it's an integer, it creates just one. 
+    # outcomes:: An array of values to contribute to #effects if #meets? is true.
+    #--
+    # TODO: values can be an array
     def equals(values, *outcomes)
       if values.instance_of?(Range)
         values.each do |val|
@@ -107,6 +141,19 @@ module Tabletop
       end
     end
     
+    # Defines a #result method, used by #effects.
+    # 
+    # If symbol is ':count', then args must include a :at_least option, and #result will
+    # be equal to the number of dice in @pool of value equal or greater than 
+    # args[:at_least]. 
+    # 
+    # Optionally, args can also include a :doubles option, for values that add 2 to #result
+    # 
+    # In all other cases, #result is aliased to #sum
+    # 
+    # Meant to be used in the initialize block.
+    #--
+    # TODO: raise an error symbol is :count but :at_least is not set
     def set_result(symbol, args={})
       if symbol == :count
         @count_at_least = args[:at_least]
@@ -124,11 +171,19 @@ module Tabletop
       @result_set = true
     end
     
-    # instance-variable-setting methods
+    # Sets a modifier that's added to #sum.  
+    #
+    # Meant to be used in the initialize block.
     def add(mod)
       @static_modifier = mod
     end
     
+    # Sets a default die size.  If set, roll can be called with a :pool argument to 
+    # create and roll a new Pool of the indicated number and type of dice.
+    #
+    # Can be an integer other than zero, or :fudge for fudgedice.
+    #
+    # Meant to be used in the initialize block.
     def sides(num_sides)
       @die_sides = num_sides
     end

data/lib/tabletop/token.rb

@@ -4,11 +4,13 @@ module Tabletop
   end
   
   class TokenStack
+    
+    # The number of tokens in the Stack
     attr_accessor :count
     include Comparable
     
-    def initialize(n = 1)
-      @count = n
+    def initialize(num_tokens = 1)
+      @count = num_tokens
     end
     
     def <=>(operand)
@@ -20,6 +22,7 @@ module Tabletop
       @count += n
     end
     
+    # Raises NotEnoughTokensError if there aren't enough tokens to remove 
     def remove(n=1)
       raise ArgumentError unless n.instance_of?(Fixnum) and n > 0
       if n > @count
@@ -36,12 +39,12 @@ module Tabletop
       @count -= n
     end
     
+    # Removes N tokens from the receiver stack, then 
+    # adds them to the stack in opts[:to] 
     def move(n, opts)
       raise(ArgumentError, "target is #{opts[:to].class}, not TokenStack") unless opts[:to].instance_of?(TokenStack)
       remove(n)
       opts[:to].add(n)
     end
   end
-  
-
 end

data/lib/tabletop/version.rb

@@ -1,3 +1,3 @@
 module Tabletop
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/spec/randomizers_spec.rb

@@ -191,8 +191,13 @@ module Tabletop
     describe "#flip" do
       it {subject.flip.should be_instance_of(Coin)}
       it "should alias roll" do
-        subject.should_receive(:roll)
+        mock(subject).roll
         subject.flip
+        # I have to use implicit expectations, because the below code doesn't
+        # work in rspec2
+        #stub(subject).roll
+        #subject.flip
+        #subject.should have_received.roll
       end
     end
     

data/spec/spec_helper.rb

@@ -15,5 +15,5 @@ require 'tabletop'
 Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
 
 RSpec.configure do |config|
-  
+  config.mock_framework = :rr
 end

data/tabletop.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
   s.require_paths = ['lib']
 
   s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rr'
   s.add_development_dependency 'bundler'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'rdoc'

metadata

@@ -2,7 +2,7 @@
 name: tabletop
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Nick Novitski
@@ -24,7 +24,7 @@ dependencies:
   prerelease: false
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: bundler
+  name: rr
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -35,7 +35,7 @@ dependencies:
   prerelease: false
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rake
+  name: bundler
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -46,7 +46,7 @@ dependencies:
   prerelease: false
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: rdoc
+  name: rake
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -56,6 +56,17 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id005
 description: 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.
 email: nicknovitski@gmail.com
 executables: []
@@ -66,6 +77,50 @@ extra_rdoc_files:
 - LICENSE
 - README.markdown
 files: 
+- doc/created.rid
+- doc/Fixnum.html
+- doc/images/brick.png
+- doc/images/brick_link.png
+- doc/images/bug.png
+- doc/images/bullet_black.png
+- doc/images/bullet_toggle_minus.png
+- doc/images/bullet_toggle_plus.png
+- doc/images/date.png
+- doc/images/find.png
+- doc/images/loadingAnimation.gif
+- doc/images/macFFBgHack.png
+- doc/images/package.png
+- doc/images/page_green.png
+- doc/images/page_white_text.png
+- doc/images/page_white_width.png
+- doc/images/plugin.png
+- doc/images/ruby.png
+- doc/images/tag_green.png
+- doc/images/wrench.png
+- doc/images/wrench_orange.png
+- doc/images/zoom.png
+- doc/index.html
+- doc/js/darkfish.js
+- doc/js/jquery.js
+- doc/js/quicksearch.js
+- doc/js/thickbox-compressed.js
+- doc/lib/fixnum_rb.html
+- doc/lib/tabletop/pool_rb.html
+- doc/lib/tabletop/randomizers_rb.html
+- doc/lib/tabletop/roll_rb.html
+- doc/lib/tabletop/token_rb.html
+- doc/lib/tabletop/version_rb.html
+- doc/lib/tabletop_rb.html
+- doc/rdoc.css
+- doc/Tabletop/Coin.html
+- doc/Tabletop/Die.html
+- doc/Tabletop/FudgeDie.html
+- doc/Tabletop/NotEnoughTokensError.html
+- doc/Tabletop/Pool.html
+- doc/Tabletop/Possibility.html
+- doc/Tabletop/Roll.html
+- doc/Tabletop/TokenStack.html
+- doc/Tabletop.html
 - Gemfile
 - lib/fixnum.rb
 - lib/tabletop/pool.rb
@@ -98,7 +153,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3490526089610525128
+      hash: 4463756612085784934
       segments: 
       - 0
       version: "0"