calyx 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c0d95f945e56c8dd61240e8868b62dfae5f4ac3
-  data.tar.gz: 4ced529a55be7f48c54875caa37b896ae40bdc2c
+  metadata.gz: f131c3c4d9ce8acaa598a0f6e32b92f13da5c566
+  data.tar.gz: c4e81bf0f753c605946c77c4943c28f1358632b2
 SHA512:
-  metadata.gz: 52ce90165a9e98c61f3a32849ef53d18af8c23772e5c31025a40c9edc6e3482ea896d188d56fd091485af6d22eb79fb2b58cd48096ec4c900ee802eb3402afac
-  data.tar.gz: d25eba6f569b69261d6eb77caeae011febfbc3177e29fb66614cc6721f799dcdd0237ead1190d87fd0ae25d8df095a754a07f948a9772a931554a5a1bb4a4f88
+  metadata.gz: 12a3d0964f80866aae48ae67036b6e97afb1ef3d89ca005bfbcbd6a8df7f55d2400cb8774ded7f2fbefd6b64b0e8da3b9201ade2c3599670918a2fba0f9c6f29
+  data.tar.gz: 6bd0062c621e001f28322484dd4dd7f9762a5e12de07fbbe26500a1b9fd03655099b22ec036046c96163b479f381c37be5fb711e5eacb9efd511a983538e982e

data/.travis.yml

@@ -4,7 +4,6 @@ rvm:
   - 2.2
   - rbx-2
   - jruby-9
-  - ruby-head
   - jruby-head
 before_install: gem install bundler -v 1.10.6
 script: bundle exec rspec

data/README.md

@@ -1,5 +1,8 @@
 # Calyx
 
+[![Gem Version](http://img.shields.io/gem/v/yarrow.svg)](https://rubygems.org/gems/calyx)
+[![Build Status](https://travis-ci.org/maetl/calyx.svg?branch=master)](https://travis-ci.org/maetl/calyx)
+
 Calyx provides a simple API for generating text with declarative recursive grammars.
 
 ## Install
@@ -56,6 +59,21 @@ hello.generate
 # > "Yo world."
 ```
 
+### Block Constructors
+
+As an alternative to subclassing, you can also construct rules unique to an instance by passing a block when initializing the class:
+
+```ruby
+hello = Calyx::Grammar.new do
+  start '{greeting} world.'
+  rule :greeting, 'Hello', 'Hi', 'Hey', 'Yo'
+end
+
+hello.generate
+```
+
+### Nesting and Substitution
+
 Rules are recursive. They can be arbitrarily nested and connected to generate larger and more complex texts.
 
 ```ruby
@@ -90,6 +108,116 @@ module HelloWorld
 end
 ```
 
+### Random Sampling
+
+By default, the outcomes of generated rules are selected with Ruby’s built-in random number generator (as seen in methods like `Kernel.rand` and `Array.sample`). 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.
+
+For example, you can model the triangular distribution produced by rolling 2d6:
+
+```ruby
+class Roll2D6 < Calyx::Grammar
+  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]
+  )
+end
+```
+
+Or reproduce Gary Gygax’s famous generation table from the original Dungeon Master’s Guide (page 171):
+
+```ruby
+class ChamberOrRoomContents < Calyx::Grammar
+  start(
+    [:empty, 0.6],
+    [:monster, 0.1],
+    [:monster_treasure, 0.15],
+    [:special, 0.05],
+    [:trick_trap, 0.05],
+    [:treasure, 0.05]
+  )
+
+  rule :empty, 'Empty'
+  rule :monster, 'Monster Only'
+  rule :monster_treasure, 'Monster and Treasure'
+  rule :special, 'Special'
+  rule :trick_trap, 'Trick/Trap.'
+  rule :treasure, 'Treasure'
+end
+```
+
+### Template Expressions
+
+Basic rule substitution uses single curly brackets as delimiters for template expressions:
+
+```ruby
+class Fruit < Calyx::Grammar
+  start '{colour} {fruit}'
+  rule :colour, 'red', 'green', 'yellow'
+  rule :fruit, 'apple', 'pear', 'tomato'
+end
+```
+
+Dot-notation is supported in template expressions, allowing you to call any available method on the `String` object returned from a rule. Formatting methods can be chained arbitrarily and will execute in the same way as they would in native Ruby code.
+
+```ruby
+class Greeting < Calyx::Grammar
+  start '{hello.capitalize} there.', 'Why, {hello} there.'
+  rule :hello, 'hello'
+end
+
+# => "Hello there."
+# => "Why, hello there."
+```
+
+In order to use more intricate natural language processing capabilities, you can embed additional methods onto the `String` class yourself, as well as use methods from existing Gems that monkeypatch `String`.
+
+```ruby
+require 'indefinite_article'
+
+module FullStop
+  def full_stop
+    self << '.'
+  end
+end
+
+class String
+  include FullStop
+end
+
+class NounsWithArticles < Calyx::Grammar
+  start '{fruit.with_indefinite_article.capitalize.full_stop}'
+  rule :fruit, 'apple', 'orange', 'banana', 'pear'
+end
+
+# => "An apple."
+# => "An orange."
+# => "A banana."
+# => "A pear."
+```
+
+## Roadmap
+
+Rough plan for stabilising the API and features for a `1.0` release.
+
+| Version | Features planned |
+|---------|------------------|
+| `0.6`   | block constructor |
+| `0.7`   | support for template context map passed to generate |
+| `0.8`   | return grammar tree from evaluate/generate, with to_s being separate |
+| `0.9`   | support mixin/composition of rule sets rather than inheritance |
+| `0.10`  | support YAML format (and JSON?) |
+| `0.11`  | method missing metaclass API |
+| `1.0`   | API documentation |
+
 ## License
 
 Calyx is open source and provided under the terms of the MIT license. Copyright (c) 2015 Mark Rickerby

data/lib/calyx.rb

@@ -1,34 +1,67 @@
 module Calyx
   class Grammar
-    class << self
-      attr_accessor :registry
+    class Registry
+      def initialize
+        @rules = {}
+      end
 
       def start(*productions, &production)
-        registry[:start] = construct_rule(productions)
+        @rules[:start] = construct_rule(productions)
       end
 
       def rule(name, *productions, &production)
-        registry[name.to_sym] = construct_rule(productions)
+        @rules[name.to_sym] = construct_rule(productions)
       end
 
-      def inherit_registry(rules)
-        @registry ||= {}
-        @registry.merge!(rules || {})
+      def []=(symbol, production)
+        @rules[symbol] = production
       end
 
-      def inherited(subclass)
-        subclass.inherit_registry(@registry)
+      def [](symbol)
+        @rules[symbol]
+      end
+
+      def combine(rules)
+        @rules.merge!(rules.to_h)
+      end
+
+      def to_h
+        @rules
       end
 
+      private
+
       def construct_rule(productions)
         if productions.first.is_a?(Enumerable)
-          Production::WeightedChoices.parse(productions, registry)
+          Production::WeightedChoices.parse(productions, self)
         else
-          Production::Choices.parse(productions, registry)
+          Production::Choices.parse(productions, self)
         end
       end
     end
 
+    class << self
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def start(*productions, &production)
+        registry.start(*productions)
+      end
+
+      def rule(name, *productions, &production)
+        registry.rule(name, *productions)
+      end
+
+      def inherit_registry(rules)
+        registry.combine(rules) unless rules.nil?
+      end
+
+      def inherited(subclass)
+        subclass.inherit_registry(registry)
+      end
+    end
+
     module Production
       class NonTerminal
         def initialize(expansion, registry)
@@ -65,14 +98,16 @@ module Calyx
       end
 
       class Concat
-        DELIMITER = /(\{[A-Za-z0-9_\.]+\})/.freeze
-        DEREF = '.'.freeze
+        EXPRESSION = /(\{[A-Za-z0-9_\.]+\})/.freeze
+        START_TOKEN = '{'.freeze
+        END_TOKEN = '}'.freeze
+        DEREF_TOKEN = '.'.freeze
 
         def self.parse(production, registry)
-          expansion = production.split(DELIMITER).map do |atom|
+          expansion = production.split(EXPRESSION).map do |atom|
             if atom.is_a?(String)
-              if atom.chars.first == '{' && atom.chars.last == '}'
-                head, *tail = atom.slice(1, atom.length-2).split(DEREF)
+              if atom.chars.first == START_TOKEN && atom.chars.last == END_TOKEN
+                head, *tail = atom.slice(1, atom.length-2).split(DEREF_TOKEN)
                 rule = NonTerminal.new(head, registry)
                 unless tail.empty?
                   Expression.new(rule, tail)
@@ -155,18 +190,21 @@ module Calyx
       end
     end
 
-    def initialize(seed=nil)
+    def initialize(seed=nil, &block)
       @seed = seed
       @seed = Time.new.to_i unless @seed
       srand(@seed)
-    end
 
-    def registry
-      self.class.registry
+      if block_given?
+        @registry = Registry.new
+        @registry.instance_eval(&block)
+      else
+        @registry = self.class.registry
+      end
     end
 
     def generate
-      registry[:start].evaluate
+      @registry[:start].evaluate
     end
   end
 end

data/lib/calyx/version.rb

@@ -1,3 +1,3 @@
 module Calyx
-  VERSION = '0.5.1'.freeze
+  VERSION = '0.6.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calyx
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Mark Rickerby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-28 00:00:00.000000000 Z
+date: 2016-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,3 +94,4 @@ signing_key:
 specification_version: 4
 summary: Generate text with declarative recursive grammars
 test_files: []
+has_rdoc: