crapshoot 0.2.0 → 0.3.0

data/.gitignore

@@ -1 +1,5 @@
 Gemfile.lock
+pkg
+.yardoc
+rdoc
+doc

data/Guardfile

@@ -1,6 +1,6 @@
  guard 'test', :runner => 'fastfail' do
-   watch('^lib/(.*)\.rb')        { |m| "test/test_#{m[1]}.rb" }
-   watch('^lib/crapshoot/(.*)\.rb') { |m| 'test/test_#{m[1]}.rb'}
-   watch('^test/(.*)_test.rb') { 'rake test' }
-   watch('^test/test_helper.rb') { 'rake test' }
+   watch('^lib/(.*)\.rb')        { |m| "test/#{m[1]}_test.rb" }
+   watch('^lib/crapshoot/(.*)\.rb') { |m| 'test/#{m[1]}_test.rb'}
+   watch('^test/(.*)_test.rb')
+   watch('^test/helper.rb') { 'rake test' }
  end

data/README.rdoc

@@ -16,6 +16,29 @@ Or you might just want nine:
 
     Crapshoot.roll '9'
 
+== Rolling Dice
+
++Crapshoot.roll+ is the method that rolls dice and returns the result. It takes one argument,
+an expression in the crapshoot language.
+
+[67] a Constant
+[4d4] a Series, rolling four four-sided dice and adding them together
+[4d6v] a Series, rolling four four-sided dice, dropping the lowest one, adding them together
+[17+17] adds two Constants together
+[4d6v - 17] subtracts a Constant from a Series
+[4d20 + 2d100 + 3d6 - 4d4 + 19] adds a whole bunch of dice, subtracts some dice, and adds nineteen
+
+Generally, whitespace is allowed around arithmetic operations, but not inside a series.
+
+== Describing a Roll
+
+The return value from +Crapshoot.roll+ is a Crapshoot::Result object,
+which is an Integer with a description field:
+
+    r = Crapshoot.roll '4d4^ + 6d6 - 10' # => 22
+    r.description # => "(2+2+2+3-3)+(1+3+5+5+6+6)-10"
+    r + 5 # => 27
+
 == Developing with Ragel
 
 I used the "Ragel" state machine compiler to generate the parser for this library. If you're changing the parser, you will need to install Ragel.
@@ -25,7 +48,7 @@ I've had good luck with the macports and homebrew packages for Ragel; I don't an
 If you are modifying the parser, you may want to generate a Graphviz .dot or PDF document of the state machine produced by the scanner. The "rake scanner:pdf" task will generate this PDF, provided your installation of Graphviz allows it. If you're developing on Mac OS X, you can get a PDF-capable copy of Graphviz from http://www.graphviz.org/Download_macos.php .
 
 == Contributing to crapshoot
- 
+
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
 * Fork the project

data/Rakefile

@@ -50,3 +50,8 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', 'README.rdoc']
+end

data/crapshoot.gemspec

@@ -27,5 +27,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency(%q<guard-test>, ["~> 0.1.4"])
   s.add_development_dependency(%q<shoulda>, ["~> 2.11.3"])
   s.add_development_dependency(%q<bundler>, ["~> 1.0.7"])
+  s.add_development_dependency(%q<yard>, ["~> 0.6.4"])
 end
 

data/lib/crapshoot.rb

@@ -1,9 +1,14 @@
+require 'delegate'
 require 'active_support'
-%w{ scanner postfixer evaluator }.each do |f|
+%w{ result scanner postfixer evaluator }.each do |f|
   require File.join(File.dirname(__FILE__), 'crapshoot', f)
 end
 
 module Crapshoot
+
+  # Rolls dice for the given expression.
+  # @param [String] crapshoot expression to evaluate, such as '4d6v + 8'
+  # @return [Crapshoot::Result] the result of the expression, can be used as a normal Integer
   def self.roll(expression)
     scanner = Scanner.new
     postfixer = Postfixer.new

data/lib/crapshoot/evaluator.rb

@@ -1,4 +1,5 @@
 module Crapshoot
+  # Stack-based calculator that relies on the "eval" method of tokens.
   class Evaluator
     def evaluate(tokens)
       @stack = []

data/lib/crapshoot/parser/scan.rb

@@ -30,7 +30,7 @@ self._scanner_trans_keys = [
 	0, 0, 48, 57, 9, 45, 
 	9, 57, 9, 57, 48, 
 	57, 9, 100, 9, 118, 
-	9, 45, 9, 45, 0
+	9, 45, 0
 ]
 
 class << self
@@ -39,7 +39,7 @@ class << self
 end
 self._scanner_key_spans = [
 	0, 10, 37, 49, 49, 10, 92, 110, 
-	37, 37
+	37
 ]
 
 class << self
@@ -48,7 +48,7 @@ class << self
 end
 self._scanner_index_offsets = [
 	0, 0, 11, 49, 99, 149, 160, 253, 
-	364, 402
+	364
 ]
 
 class << self
@@ -101,17 +101,12 @@ self._scanner_indicies = [
 	1, 1, 15, 1, 1, 1, 1, 1, 
 	1, 1, 1, 1, 1, 1, 1, 1, 
 	1, 1, 1, 1, 1, 1, 1, 1, 
-	1, 1, 16, 1, 17, 17, 17, 17, 
-	17, 1, 1, 1, 1, 1, 1, 1, 
+	1, 1, 15, 1, 16, 16, 16, 16, 
+	16, 1, 1, 1, 1, 1, 1, 1, 
 	1, 1, 1, 1, 1, 1, 1, 1, 
-	1, 1, 1, 17, 1, 1, 1, 1, 
-	1, 1, 1, 1, 1, 1, 18, 1, 
-	18, 1, 19, 19, 19, 19, 19, 1, 
-	1, 1, 1, 1, 1, 1, 1, 1, 
-	1, 1, 1, 1, 1, 1, 1, 1, 
-	1, 19, 1, 1, 1, 1, 1, 1, 
-	1, 1, 1, 1, 20, 1, 20, 1, 
-	0
+	1, 1, 1, 16, 1, 1, 1, 1, 
+	1, 1, 1, 1, 1, 1, 17, 1, 
+	17, 1, 0
 ]
 
 class << self
@@ -121,7 +116,7 @@ end
 self._scanner_trans_targs = [
 	6, 0, 2, 3, 4, 6, 4, 7, 
 	2, 3, 6, 5, 2, 3, 7, 8, 
-	9, 2, 3, 2, 3
+	2, 3
 ]
 
 class << self
@@ -131,7 +126,7 @@ end
 self._scanner_trans_actions = [
 	1, 0, 0, 0, 2, 3, 0, 1, 
 	4, 4, 0, 5, 6, 6, 0, 5, 
-	5, 7, 7, 8, 8
+	7, 7
 ]
 
 class << self
@@ -140,7 +135,7 @@ class << self
 end
 self._scanner_eof_actions = [
 	0, 0, 0, 0, 0, 0, 4, 6, 
-	7, 8
+	7
 ]
 
 class << self
@@ -164,7 +159,7 @@ self.scanner_en_main = 1;
 
 # line 52 "lib/crapshoot/parser/scan.rl"
         
-# line 168 "lib/crapshoot/parser/scan.rb"
+# line 163 "lib/crapshoot/parser/scan.rb"
 begin
 	p ||= 0
 	pe ||= data.length
@@ -173,7 +168,7 @@ end
 
 # line 53 "lib/crapshoot/parser/scan.rl"
         
-# line 177 "lib/crapshoot/parser/scan.rb"
+# line 172 "lib/crapshoot/parser/scan.rb"
 begin
 	testEof = false
 	_slen, _trans, _keys, _inds, _acts, _nacts = nil
@@ -213,42 +208,25 @@ begin
 # line 4 "lib/crapshoot/parser/scan.rl"
 		begin
  @mark_num = p 		end
-# line 4 "lib/crapshoot/parser/scan.rl"
 	when 5 then
 # line 5 "lib/crapshoot/parser/scan.rl"
 		begin
  @num_stack.push atos(data[@mark_num..p-1]) 		end
-# line 5 "lib/crapshoot/parser/scan.rl"
-	when 7 then
-# line 8 "lib/crapshoot/parser/scan.rl"
-		begin
-
-    drop = @drop_current
-    @drop_current = nil
-    sides = @num_stack.pop
-    count = @num_stack.pop
-    @tokens << Tokens::Series.new(count, sides, drop)
-  		end
-# line 8 "lib/crapshoot/parser/scan.rl"
 	when 2 then
 # line 15 "lib/crapshoot/parser/scan.rl"
 		begin
  @tokens << Tokens::Arithmetic.new(data[p-1].chr) 		end
-# line 15 "lib/crapshoot/parser/scan.rl"
 	when 4 then
 # line 5 "lib/crapshoot/parser/scan.rl"
 		begin
  @num_stack.push atos(data[@mark_num..p-1]) 		end
-# line 5 "lib/crapshoot/parser/scan.rl"
 # line 7 "lib/crapshoot/parser/scan.rl"
 		begin
  @tokens << Tokens::Constant.new(@num_stack.pop) 		end
-# line 7 "lib/crapshoot/parser/scan.rl"
 	when 6 then
 # line 5 "lib/crapshoot/parser/scan.rl"
 		begin
  @num_stack.push atos(data[@mark_num..p-1]) 		end
-# line 5 "lib/crapshoot/parser/scan.rl"
 # line 8 "lib/crapshoot/parser/scan.rl"
 		begin
 
@@ -258,21 +236,17 @@ begin
     count = @num_stack.pop
     @tokens << Tokens::Series.new(count, sides, drop)
   		end
-# line 8 "lib/crapshoot/parser/scan.rl"
 	when 3 then
 # line 15 "lib/crapshoot/parser/scan.rl"
 		begin
  @tokens << Tokens::Arithmetic.new(data[p-1].chr) 		end
-# line 15 "lib/crapshoot/parser/scan.rl"
 # line 4 "lib/crapshoot/parser/scan.rl"
 		begin
  @mark_num = p 		end
-# line 4 "lib/crapshoot/parser/scan.rl"
-	when 8 then
+	when 7 then
 # line 17 "lib/crapshoot/parser/scan.rl"
 		begin
  @drop_current = data[p-1].chr 		end
-# line 17 "lib/crapshoot/parser/scan.rl"
 # line 8 "lib/crapshoot/parser/scan.rl"
 		begin
 
@@ -282,8 +256,7 @@ begin
     count = @num_stack.pop
     @tokens << Tokens::Series.new(count, sides, drop)
   		end
-# line 8 "lib/crapshoot/parser/scan.rl"
-# line 287 "lib/crapshoot/parser/scan.rb"
+# line 260 "lib/crapshoot/parser/scan.rb"
 	end
 	end
 	end
@@ -301,31 +274,17 @@ begin
 	if _goto_level <= _test_eof
 	if p == eof
 	  case _scanner_eof_actions[cs]
-	when 7 then
-# line 8 "lib/crapshoot/parser/scan.rl"
-		begin
-
-    drop = @drop_current
-    @drop_current = nil
-    sides = @num_stack.pop
-    count = @num_stack.pop
-    @tokens << Tokens::Series.new(count, sides, drop)
-  		end
-# line 8 "lib/crapshoot/parser/scan.rl"
 	when 4 then
 # line 5 "lib/crapshoot/parser/scan.rl"
 		begin
  @num_stack.push atos(data[@mark_num..p-1]) 		end
-# line 5 "lib/crapshoot/parser/scan.rl"
 # line 7 "lib/crapshoot/parser/scan.rl"
 		begin
  @tokens << Tokens::Constant.new(@num_stack.pop) 		end
-# line 7 "lib/crapshoot/parser/scan.rl"
 	when 6 then
 # line 5 "lib/crapshoot/parser/scan.rl"
 		begin
  @num_stack.push atos(data[@mark_num..p-1]) 		end
-# line 5 "lib/crapshoot/parser/scan.rl"
 # line 8 "lib/crapshoot/parser/scan.rl"
 		begin
 
@@ -335,12 +294,10 @@ begin
     count = @num_stack.pop
     @tokens << Tokens::Series.new(count, sides, drop)
   		end
-# line 8 "lib/crapshoot/parser/scan.rl"
-	when 8 then
+	when 7 then
 # line 17 "lib/crapshoot/parser/scan.rl"
 		begin
  @drop_current = data[p-1].chr 		end
-# line 17 "lib/crapshoot/parser/scan.rl"
 # line 8 "lib/crapshoot/parser/scan.rl"
 		begin
 
@@ -350,8 +307,7 @@ begin
     count = @num_stack.pop
     @tokens << Tokens::Series.new(count, sides, drop)
   		end
-# line 8 "lib/crapshoot/parser/scan.rl"
-# line 355 "lib/crapshoot/parser/scan.rb"
+# line 311 "lib/crapshoot/parser/scan.rb"
 	  end
 	end
 

data/lib/crapshoot/parser/scan.rl

@@ -20,7 +20,7 @@
 
   Constant = Number %constant;
 
-  Drop = '^' | 'v' %drop;
+  Drop = ('^' | 'v') %drop;
   Series = Number 'd' Number Drop? %series;
 
   Arithmetic = ('+' | '-') %arithmetic;

data/lib/crapshoot/postfixer.rb

@@ -1,4 +1,5 @@
 module Crapshoot
+  # Translate the infix-notation tokens into postfix notation to make evaluating them easier.
   class Postfixer
     def postfixify(infix_tokens)
       @infix_orig = infix_tokens

data/lib/crapshoot/result.rb

@@ -0,0 +1,14 @@
+module Crapshoot
+  # An Integer with a description, uses DelegateClass from the stdlib to do this
+  class Result < DelegateClass(Integer)
+    # Creates a new result with the given value.
+    #
+    # Everything except the description is delegated to this value.
+    def initialize(value)
+      super value
+    end
+
+    # The derivation of the result, as a String.
+    attr_accessor :description
+  end
+end

data/lib/crapshoot/scanner.rb

@@ -4,6 +4,7 @@ require File.join(File.dirname(__FILE__), 'parser', 'scan.rb')
 end
 
 module Crapshoot
+  # Turns a string into an array of tokens.
   class Scanner
     def initialize
       @parser = Parser::Scan.new

data/lib/crapshoot/tokens/arithmetic.rb

@@ -12,8 +12,9 @@ module Crapshoot
       def eval(stack)
         r = stack.pop
         l = stack.pop
-        @result = l.send(@operation.to_sym, r)
-        @result
+        @result = Result.new l.send(@operation.to_sym, r)
+        @result.description = "#{l.description}#{@operation}#{r.description}"
+        return @result
       end
 
       def inspect

data/lib/crapshoot/tokens/constant.rb

@@ -2,7 +2,8 @@ module Crapshoot
   module Tokens
     class Constant < Base
       def initialize(number)
-        @value = number.to_i
+        @value = Result.new number.to_i
+        @value.description = @value.to_s
       end
 
       def eval(stack)

data/lib/crapshoot/tokens/series.rb

@@ -8,21 +8,22 @@ module Crapshoot
       end
 
       def eval(stack)
+        raise TooManyDiceException.new(@count) if @count > 50_000
         results_array = (1..@count).to_a.map{ roll_a_die }.sort
-        @result = results_array.inject(&:+)
+        numeric_result = results_array.inject(&:+)
         roll_description = results_array.join '+'
-
         case @drop
         when '^'
-          max = results_array[0]
-          @result -= max
-          roll_description += '-#{max}'
+          max = results_array.last
+          numeric_result -= max
+          roll_description += "-#{max}"
         when 'v'
-          min = results_array[-1]
-          @result -= min
-          roll_description += '-#{min}'
+          min = results_array.first
+          numeric_result -= min
+          roll_description += "-#{min}"
         end
-        @description = "(#{roll_description})"
+        @result = Result.new numeric_result
+        @result.description = "(#{roll_description})"
 
         return @result
       end
@@ -37,6 +38,13 @@ module Crapshoot
         # +1 because we can roll a zero
         ActiveSupport::SecureRandom.random_number(@sides) + 1
       end
+
+      class TooManyDiceException < RuntimeError
+        def initialize(number_of_dice)
+          @number_of_dice = number_of_dice
+          super "#{@number_of_dice} dice is too many"
+        end
+      end
     end
   end
 end

data/lib/crapshoot/version.rb

@@ -1,3 +1,3 @@
 module Crapshoot
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/test/crapshoot_test.rb

@@ -1,6 +1,7 @@
 require 'helper'
 
 class TestCrapshoot < Test::Unit::TestCase
+
   def self.should_roll(from, options)
     keys = options.keys
 
@@ -12,8 +13,25 @@ class TestCrapshoot < Test::Unit::TestCase
       end
     end
   end
+
+  def self.should_describe(from, matcher)
+    should "evaluate #{from.inspect} into something resembling #{matcher.inspect}" do
+      result = Crapshoot.roll from
+      assert_match matcher, result.description
+    end
+  end
+
   context 'The Crapshoot module' do
     should_roll '4d6', '>='=>4, '<='=>24
     should_roll '4d6 + 200', '>='=>204, '<='=>224
+    should_roll '10-5', '=='=>5
+    should_roll '5-10', '=='=>-5
+
+    should_describe '1 + 2', '1+2'
+    should_describe '10 - 5', '10-5'
+    should_describe '2d6', /\(\d\+\d\)/
+    should_describe '2d6 + 5', /\(\d\+\d\)\+5/
+    should_describe '2d6 + 5 + 4d2v', /\(\d\+\d\)\+5\+\(\d\+\d\+\d\+\d\-\d\)/
+    should_describe '2d6 + 5 + 4d2^', /\(\d\+\d\)\+5\+\(\d\+\d\+\d\+\d\-\d\)/
   end
 end

data/test/evaluator_test.rb

@@ -26,8 +26,8 @@ class TestEvaluator < Test::Unit::TestCase
     series1 = Series.new '5', '6', nil
     series2 = Series.new '4', '20', 'v'
     series3 = Series.new '20', '2'
-    series4 = Series.new '20', 1, 'v'
-    series5 = Series.new '20', 1, '^'
+    series4 = Series.new '20', '1', 'v'
+    series5 = Series.new '20', '1', '^'
 
     should_evaluate [five, six, plus], '=='=> 11
     should_evaluate [series1, series1, plus], '>=' => 10, '<=' => 60
@@ -35,5 +35,17 @@ class TestEvaluator < Test::Unit::TestCase
     should_evaluate [series3], '>=' => 20, '<=' => 40
     should_evaluate [series4], '=='=>19
     should_evaluate [series5], '=='=>19
+
+    should 'raise an exception when rolling over 50,000 dice' do
+      assert_raises do
+        @evaluator.evaluate [Series.new('50001', '6')]
+      end
+    end
+
+    should 'not raise an exception when rolling exactly 50,000 dice' do
+      assert_nothing_raised do
+        @evaluator.evaluate [Series.new('50000', '6')]
+      end
+    end
   end
 end

data/test/result_test.rb

@@ -0,0 +1,19 @@
+require 'helper'
+
+class TestResult < Test::Unit::TestCase
+  context 'a result' do
+    setup do
+      @result = Crapshoot::Result.new 5
+    end
+
+    should 'have a description' do
+      assert_respond_to @result, :description
+      assert_respond_to @result, :description=
+    end
+
+    should 'behave like an integer' do
+      assert_equal 11, (@result + 6)
+      assert_equal 1, (@result / 5)
+    end
+  end
+end

data/test/scanner_test.rb

@@ -31,6 +31,7 @@ class TestScanner < Test::Unit::TestCase
     should_parse '1+2', Constant, Arithmetic, Constant
     should_parse '4d6 + 4d6', Series, Arithmetic, Series
     should_parse '4d6v', Series
+    should_parse '4d6^', Series
     should_parse '4d6 + 2', Series, Arithmetic, Constant
     should_parse '15', Constant
     should_parse '14d100v + 8d8 + 3', Series, Arithmetic, Series, Arithmetic, Constant

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Bryce Kerley
@@ -76,6 +76,21 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: yard
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 6
+        - 4
+        version: 0.6.4
+  type: :development
+  prerelease: false
+  version_requirements: *id005
 description: Crapshoot is a dice-rolling gem for most of your pen-and-paper gaming needs; roll 4d6v to find out how much time it will save.
 email: bkerley@brycekerley.net
 executables: []
@@ -99,6 +114,7 @@ files:
 - lib/crapshoot/parser/scan.rb
 - lib/crapshoot/parser/scan.rl
 - lib/crapshoot/postfixer.rb
+- lib/crapshoot/result.rb
 - lib/crapshoot/scanner.rb
 - lib/crapshoot/tokens/arithmetic.rb
 - lib/crapshoot/tokens/base.rb
@@ -109,6 +125,7 @@ files:
 - test/evaluator_test.rb
 - test/helper.rb
 - test/postfixer_test.rb
+- test/result_test.rb
 - test/scanner_test.rb
 has_rdoc: true
 homepage: http://github.com/bkerley/crapshoot
@@ -149,4 +166,5 @@ test_files:
 - test/evaluator_test.rb
 - test/helper.rb
 - test/postfixer_test.rb
+- test/result_test.rb
 - test/scanner_test.rb