calyx 0.16.0 → 0.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2dd4b07658e5e6d37f0b1c7a1f75afb08d61ae5f
-  data.tar.gz: 6cf84a9ef492e359ff297a84129abca738c4ca91
+  metadata.gz: 414d8c715cd98f914a199935c68c0b2a06b479c2
+  data.tar.gz: 71fb631f0746d89d96bc20d6897cc0c65201b2ab
 SHA512:
-  metadata.gz: c8bcd0a0eddc36040f008dc22de6d9df8b8f8e204e036c77f0efaceb226ab835888cfe997b4d9807f01e002b067de1f5b7750c1698711d3e0b05e92d3aac795f
-  data.tar.gz: fe055edd5d1062a6e55ab474ed9d923bc228ed276cb22dca3ce3c5c0cb218361208635bfeeff24112ca159f44d9914ac1ed535a1301f23c68bd73411f0b2fb5d
+  metadata.gz: 6aaaec468253bddaf2ac68e81e87fca1c4a3654a23c2a1ea3bf6e63cd276d466b74995695b15429b6e57bef930ef35e2d37aad0ea81c939b089353ad5b385d0e
+  data.tar.gz: b2180e9d495f6d1e08a02a28bbf50ad09bd29a60a6e9c47e8c4c649fc8c112c98602c921c60cf0f2039968a79b13bbfa3fdcce2ab33ab3f53be82b7e95fd2af9

data/README.md

@@ -231,26 +231,54 @@ end
 
 When a random seed isn’t supplied, `Time.new.to_i` is used as the default seed, which makes each run of the generator relatively unique.
 
-### Weighted Selection
+### Weighted Choices
 
-If you want to supply a weighted probability list, you can pass in arrays to the rule constructor, with the first argument being the template text string and the second argument being a float representing the probability between `0` and `1` of this choice being selected.
+Choices can be weighted so that some rules have a greater probability of expanding than others.
 
-For example, you can model the triangular distribution produced by rolling 2d6:
+Weights are defined by passing a hash instead of a list of rules where the keys are strings or symbols representing the grammar rules and the values are weights.
+
+Weights can be represented as floats, integers or ranges.
+
+- Floats must be in the interval 0..1 and the given weights for a production must sum to 1.
+- Ranges must be contiguous and cover the entire interval from 1 to the maximum value of the largest range.
+- Integers (Fixnums) will produce a distribution based on the sum of all given numbers, with each number being a fraction of that sum.
+
+The following definitions produce an equivalent weighting of choices:
 
 ```ruby
-class Roll2D6 < Calyx::Grammar
+Calyx::Grammar.new do
+  start 'heads' => 1, 'tails' => 1
+end
+
+Calyx::Grammar.new do
+  start 'heads' => 0.5, 'tails' => 0.5
+end
+
+Calyx::Grammar.new do
+  start 'heads' => 1..5, 'tails' => 6..10
+end
+
+Calyx::Grammar.new do
+  start 'heads' => 50, 'tails' => 50
+end
+```
+
+There’s a lot of interesting things you can do with this. For example, you can model the triangular distribution produced by rolling 2d6:
+
+```ruby
+Calyx::Grammar.new do
   start(
-    ['2', 0.0278],
-    ['3', 0.556],
-    ['4', 0.833],
-    ['5', 0.1111],
-    ['6', 0.1389],
-    ['7', 0.1667],
-    ['8', 0.1389],
-    ['9', 0.1111],
-    ['10', 0.833],
-    ['11', 0.556],
-    ['12', 0.278]
+    '2' => 1,
+    '3' => 2,
+    '4' => 3,
+    '5' => 4,
+    '6' => 5,
+    '7' => 6,
+    '8' => 5,
+    '9' => 4,
+    '10' => 3,
+    '11' => 2,
+    '12' => 1
   )
 end
 ```
@@ -258,16 +286,15 @@ end
 Or reproduce Gary Gygax’s famous generation table from the original [Dungeon Master’s Guide](https://en.wikipedia.org/wiki/Dungeon_Master%27s_Guide#Advanced_Dungeons_.26_Dragons) (page 171):
 
 ```ruby
-class ChamberOrRoomContents < Calyx::Grammar
+Calyx::Grammar.new do
   start(
-    [:empty, 0.6],
-    [:monster, 0.1],
-    [:monster_treasure, 0.15],
-    [:special, 0.05],
-    [:trick_trap, 0.05],
-    [:treasure, 0.05]
+    :empty => 0.6,
+    :monster => 0.1,
+    :monster_treasure => 0.15,
+    :special => 0.05,
+    :trick_trap => 0.05,
+    :treasure => 0.05
   )
-
   empty 'Empty'
   monster 'Monster Only'
   monster_treasure 'Monster and Treasure'
@@ -518,8 +545,8 @@ Rough plan for stabilising the API and features for a `1.0` release.
 | `0.12`   | ~~API documentation~~ |
 | `0.13`   | ~~Support for unique rules~~ |
 | `0.14`   | ~~Support for Ruby 2.4~~ |
-| `0.15`   | Options config and ‘strict mode’ error handling |
-| `0.16`   | Improve representation of weighted probability selection |
+| `0.15`   | ~~Options config and ‘strict mode’ error handling~~ |
+| `0.16`   | ~~Improve representation of weighted probability selection~~ |
 | `0.17`   | Introduce wildcard syntax for meta rules (rules returning rules) |
 
 ## Credits

data/lib/calyx/options.rb

@@ -20,6 +20,10 @@ module Calyx
       @options[:rng]
     end
 
+    def rand
+      rng.rand
+    end
+
     def strict?
       @options[:strict]
     end

data/lib/calyx/production/weighted_choices.rb

@@ -5,10 +5,14 @@ module Calyx
     # being chosen.
     class WeightedChoices
       # Parse a given list or hash of productions into a syntax tree of weighted
-      # choices.
+      # choices. Supports weights specified as Range, Fixnum and Float types.
+      #
+      # All weights get normalized to a set of values in the 0..1 interval that
+      # sum to 1.
       #
       # @param [Array<Array>, Hash<#to_s, Float>] productions
       # @param [Calyx::Registry] registry
+      # @return [Calyx::Production::WeightedChoices]
       def self.parse(productions, registry)
         if productions.first.last.is_a?(Range)
           range_max = productions.max { |a,b| a.last.max <=> b.last.max }.last.max
@@ -30,9 +34,15 @@ module Calyx
             memo += choice.last
           end
 
-          raise Errors::InvalidDefinition, 'Weights must sum to 1' if weights_sum != 1.0
-
-          normalized_productions = productions
+          if productions.first.last.is_a?(Float)
+            raise Errors::InvalidDefinition, 'Weights must sum to 1' if weights_sum != 1.0
+            normalized_productions = productions
+          else
+            normalized_productions = productions.map do |choice|
+              weight = choice.last.to_f / weights_sum.to_f * 1.0
+              [choice.first, weight]
+            end
+          end
         end
 
         choices = normalized_productions.map do |choice, weight|
@@ -63,7 +73,7 @@ module Calyx
       # @return [Array]
       def evaluate(options)
         choice = @collection.max_by do |_, weight|
-          options.rng.rand ** (1.0 / weight)
+          options.rand ** (1.0 / weight)
         end.first
 
         [:weighted_choice, choice.evaluate(options)]

data/lib/calyx/version.rb

@@ -1,3 +1,3 @@
 module Calyx
-  VERSION = '0.16.0'.freeze
+  VERSION = '0.16.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calyx
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.16.1
 platform: ruby
 authors:
 - Mark Rickerby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-31 00:00:00.000000000 Z
+date: 2017-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler