games_dice 0.0.5 → 0.0.6

data/README.md

@@ -5,16 +5,31 @@
 A library for simulating dice, intended for constructing a variety of dice systems as used in
 role-playing and board games.
 
+## Description
+
+GamesDice is a gem to automate or simulate a variety of dice rolling systems found in board games and
+role-playing games.
+
+GamesDice is designed for systems used to generate integer results, and that do not require the
+player to make decisions or apply other rules from the game. There are no game mechanics implemented
+in GamesDice (such as the chance to hit in a combat game).
+
+The main features of GamesDice are
+
+ * Uses string dice descriptions, the basics of which are familiar to many game players e.g. '2d6 + 3'
+ * Supports common features of dice systems automatically:
+   * Re-rolls that replace or modify the previous roll
+   * Counting number of "successes" from a set of dice
+   * Keeping the best, or worst, results from a set of dice
+ * Can explain how a result was achieved in terms of the individual die rolls
+ * Can calculate probabilities and expected values (experimental feature)
+
 ## Special Note on Versions Prior to 1.0.0
 
 The author is using this code as an exercise in gem "best practice". As such, the gem
 will have a deliberately limited set of functionality prior to version 1.0.0, and there should be
 many small release increments before then.
 
-The functionality should expand to cover dice systems seen in many role-playing systems, as it
-progresses through 0.x.y versions (in fact much of this code is already written and working, so if
-you have a burning need to simulate dice rolls for a specific game, feel free to get in touch).
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -33,11 +48,58 @@ Or install it yourself as:
 
     require 'games_dice'
 
-    # Simple 6-sided die, more to follow
-    d = GamesDice::Die.new( 6 )
-    d.roll         # => 4
-    d.result       # => 4
-    d.explain_roll # => "4"
+    dice = GamesDice.create '4d6+3'
+    dice.roll  #  => 17 (e.g.)
+
+## Library API
+
+Although you can refer to the documentation for the contained classes, and use it if needed to
+build some exotic dice systems, the recommended way to use GamesDice is to create GamesDice::Dice
+objects via the factory methods from the GamesDice module, and then use those objects to simulate
+dice rolls, explain the results or calculate probabilties as required.
+
+### GamesDice factory methods
+
+#### GamesDice.create dice_description, prng
+
+Converts a string such as '3d6+6' into a GamesDice::Dice object
+
+Parameters:
+
+ * dice_description is a string such as '3d6' or '2d4-1'. See String Dice Descriptions below for possibilities.
+ * prng is optional, if provided it should be an object that has a method 'rand( integer )' that works like Ruby's built-in rand method
+
+Returns a GamesDice::Dice object.
+
+### GamesDice::Dice instance methods
+
+#### dice.roll
+
+Simulates rolling the dice as they were described in the constructor, and keeps a record of how the
+simulation result was achieved.
+
+Takes no parameters.
+
+Returns the integer result of the roll.
+
+## String Dice Descriptions
+
+The dice descriptions are a mini-language. A simple six-sided die is described like this:
+
+    1d6
+
+where the first integer is the number of dice to add together, and the second number is the number
+of sides on each die. Spaces are allowed before the first number, and after the dice description, but
+not between either number and the "d".
+
+The dice mini-language allows for adding and subtracting integers and groups of dice in a list, e.g.
+
+    2d6 + 1d4
+    1d100 + 1d20 - 5
+
+That is the limit of combining dice and constants though, no multiplications, or bracketed constructs
+like "(1d8)d8" - you can still use games_dice to help simulate these, but you will need to add your own
+code to do so.
 
 ## Contributing
 

data/lib/games_dice.rb

@@ -8,7 +8,13 @@ require "games_dice/map_rule"
 require "games_dice/complex_die"
 require "games_dice/bunch"
 require "games_dice/dice"
+require "games_dice/parser"
 
 module GamesDice
-  # TODO: Factory methods for various dice schemes
+  @@parser = GamesDice::Parser.new
+
+  def self.create dice_description, prng = nil
+    parsed = @@parser.parse( dice_description )
+    GamesDice::Dice.new( parsed[:bunches], parsed[:offset], prng )
+  end
 end

data/lib/games_dice/dice.rb

@@ -1,8 +1,8 @@
 # models any combination of zero or more Bunches, plus a constant offset, summing them
 # to create a total result when rolled
 class GamesDice::Dice
-  # bunches is an Array of Hashes, each of which describes either a GamesDice::Bunch
-  # a Hash in the Array that describes a Bunch may contain any of the keys that can be used to initialize
+  # bunches is an Array of Hashes, each of which describes a GamesDice::Bunch
+  # and may contain any of the keys that can be used to initialize
   # the Bunch, plus the following optional key:
   #  :multiplier => any Integer, but typically 1 or -1 to describe whether the Bunch total is to be added or subtracted
   # offset is an Integer which will be added to the result when rolling all the bunches

data/lib/games_dice/parser.rb

@@ -0,0 +1,79 @@
+require 'parslet'
+
+# converts string dice descriptions to data usable for the GamesDice::Dice constructor
+class GamesDice::Parser < Parslet::Parser
+
+  # Descriptive language examples (capital letters stand in for integers)
+  #  NdX               -  a roll of N dice, with X sides each, values summed to total
+  #  NdX + C           -  a roll of N dice, with X sides each, values summed to total plus a constant C
+  #  NdX - C           -  a roll of N dice, with X sides each, values summed to total minus a constant C
+  #  NdX + MdY + C     -  any number of +C, -C, +NdX, -NdX etc sub-expressions can be combined
+  #  NdXkZ             -  a roll of N dice, sides X, keep best Z results and sum them
+  #  NdXk[Z,worst]     -  a roll of N dice, sides X, keep worst Z results and sum them
+  #  NdXrZ             -  a roll of N dice, sides X, re-roll and replace Zs
+  #  NdXr[Z,add]       -  a roll of N dice, sides X, re-roll and add on a result of Z
+  #  NdXr[Y..Z,add]    -  a roll of N dice, sides X, re-roll and add on a result of Y..Z
+  #  NdXx              -  exploding dice, synonym for NdXr[X,add]
+  #  NdXmZ             -  mapped dice, values below Z score 0, values above Z score 1
+  #  NdXm[>=Z,A]       -  mapped dice, values greater than or equal to Z score A (unmapped values score 0 by default)
+
+  # These are the Parslet rules that define the dice grammar
+  rule(:integer) { match('[0-9]').repeat(1) }
+  rule(:dlabel) { match('[d]') }
+  rule(:bunch_start) { integer.as(:ndice) >> dlabel >> integer.as(:sides) }
+  rule(:space) { match('\s').repeat(1) }
+  rule(:space?) { space.maybe }
+  rule(:operator) { match('[+-]').as(:op) >> space? }
+  rule(:add_bunch) { operator >> bunch_start >> space? }
+  rule(:add_constant) { operator >> integer.as(:constant) >> space? }
+  rule(:dice_expression) { add_bunch | add_constant }
+  rule(:expressions) { dice_expression.repeat.as(:bunches) }
+  root :expressions
+
+  def parse dice_description, dice_name = nil
+    dice_description = dice_description.to_s.strip
+    dice_name ||= dice_description
+    # Force first item to start '+' for simpler parse rules
+    dice_description = '+' + dice_description unless dice_description =~ /\A[+-]/
+    dice_expressions = super( dice_description )
+
+    { :bunches => collect_bunches( dice_expressions ), :offset => collect_offset( dice_expressions ) }
+  end
+
+  private
+
+  def collect_bunches dice_expressions
+    dice_expressions[:bunches].select {|h| h[:ndice] }.map do |in_hash|
+      out_hash = {}
+      # Convert integers
+      [:ndice, :sides].each do |s|
+        next unless in_hash[s]
+        out_hash[s] = in_hash[s].to_i
+      end
+
+      # Multiplier
+      if in_hash[:op]
+        optype = in_hash[:op].to_s
+        out_hash[:multiplier] = case optype
+          when '+' then 1
+          when '-' then -1
+        end
+      end
+      out_hash
+    end
+  end
+
+  def collect_offset dice_expressions
+    dice_expressions[:bunches].select {|h| h[:constant] }.inject(0) do |total, in_hash|
+      c = in_hash[:constant].to_i
+      optype = in_hash[:op].to_s
+      if optype == '+'
+        total += c
+      else
+        total -= c
+      end
+      total
+    end
+  end
+
+end # class Parser

data/lib/games_dice/version.rb

@@ -1,3 +1,3 @@
 module GamesDice
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/spec/parser_spec.rb

@@ -0,0 +1,26 @@
+require 'games_dice'
+
+describe GamesDice::Parser do
+
+  describe "#parse" do
+    let(:parser) { GamesDice::Parser.new }
+
+    it "should convert descriptive strings to data usable in the GamesDice::Dice constructor" do
+      variations = {
+        '1d6' => { :bunches => [{:ndice=>1, :sides=>6, :multiplier=>1}], :offset => 0 },
+        '2d8-1d4' => { :bunches => [{:ndice=>2, :sides=>8, :multiplier=>1},{:ndice=>1, :sides=>4, :multiplier=>-1}], :offset => 0 },
+        '+ 2d10 - 1d4 ' => { :bunches => [{:ndice=>2, :sides=>10, :multiplier=>1},{:ndice=>1, :sides=>4, :multiplier=>-1}], :offset => 0 },
+        ' + 3d6 + 12 ' => { :bunches => [{:ndice=>3, :sides=>6, :multiplier=>1}], :offset => 12 },
+        '-7 + 2d4 + 1 ' => { :bunches => [{:ndice=>2, :sides=>4, :multiplier=>1}], :offset => -6 },
+        '- 3 + 7d20 - 1 ' => { :bunches => [{:ndice=>7, :sides=>20, :multiplier=>1}], :offset => -4 },
+        ' -   2d4' => { :bunches => [{:ndice=>2, :sides=>4, :multiplier=>-1}], :offset => 0 },
+        '3d12+5+2d8+1d6' => { :bunches => [{:ndice=>3, :sides=>12, :multiplier=>1},{:ndice=>2, :sides=>8, :multiplier=>1},{:ndice=>1, :sides=>6, :multiplier=>1}], :offset => 5 },
+      }
+
+      variations.each do |input,expected_output|
+        parser.parse( input ).should ==  expected_output
+      end
+    end
+
+  end # describe "#parse"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: games_dice
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-15 00:00:00.000000000 Z
+date: 2013-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -82,6 +82,7 @@ files:
 - lib/games_dice/die.rb
 - lib/games_dice/die_result.rb
 - lib/games_dice/map_rule.rb
+- lib/games_dice/parser.rb
 - lib/games_dice/probabilities.rb
 - lib/games_dice/reroll_rule.rb
 - lib/games_dice/version.rb
@@ -91,6 +92,7 @@ files:
 - spec/die_result_spec.rb
 - spec/die_spec.rb
 - spec/map_rule_spec.rb
+- spec/parser_spec.rb
 - spec/probability_spec.rb
 - spec/reroll_rule_spec.rb
 - travis.yml
@@ -108,7 +110,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2463166365146025536
+      hash: 384639309274746311
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -117,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2463166365146025536
+      hash: 384639309274746311
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -131,5 +133,6 @@ test_files:
 - spec/die_result_spec.rb
 - spec/die_spec.rb
 - spec/map_rule_spec.rb
+- spec/parser_spec.rb
 - spec/probability_spec.rb
 - spec/reroll_rule_spec.rb