tra38-calyx 0.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 85ba5ec4d74873b85ad9e7aafd4694191717b00b
+  data.tar.gz: 93e6e5cc487f09443953e46d334e746aff12d919
+SHA512:
+  metadata.gz: 88d7fd63cdf3e7cd491cd001093d5762e5a0b8dff5716d493bafb0afde2d2ffef82014f5fb68a5bdfdcd94b19fd24b8ac215f1e18a4aa77f4f41ffca9b7e33f8
+  data.tar.gz: 0c407e12b96da714500fb2827bf62c2f28ab9e6ae5fd97fea4535f672672e6f685cfede0d5f2e36ea64e104c07f9bf0aa74650b7a7d7ffa91a6c5a7a88335976

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 2.1
+  - 2.2
+  - rbx-2
+  - jruby-9
+  - jruby-head
+before_install: gem install bundler -v 1.10.6
+script: bundle exec rspec

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Mark Rickerby
+Copyright (c) 2016 Tariq Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,282 @@
+# Calyx
+
+Calyx provides a simple API for generating text with declarative recursive grammars.
+
+## Install
+
+### Command Line
+
+```
+gem install calyx
+```
+
+## Gemfile
+
+```
+gem 'calyx'
+```
+
+## Usage
+
+Calyx support two types of classes.
+
+Classes that inherit from `Calyx::Grammar` are used to construct a set of rules that can generate a text. All grammars require a `start` rule, which specifies the starting point for generating the text structure.
+
+Classes that inherit from `Calyx::DataTemplate` are used to construct a set of "meta-rules" that will invoke Grammar rules for you. All templates require a `write_narrative` method which specifies what "meta-rules" are being called.
+
+```ruby
+require 'calyx'
+
+class HelloWorld < Calyx::Grammar
+ start "Hello World."
+end
+
+class Greeting < Calyx::DataTemplate
+ def write_narrative
+  write HelloWorld
+ end
+end
+```
+
+There are two ways to generate text. You can generate text using Calyx::Grammar by initializing the object and calling the `generate` method.
+
+```ruby
+hello = HelloWorld.new
+hello.generate
+# > "Hello World."
+```
+
+Or, you can generate text by initializing the Calyx::DataTemplate class and calling the `result` method.
+```ruby
+greeting = Greeting.new
+greeting.result
+# > "Hello World."
+```
+
+### Calyx::Grammar
+Obviously, "Hello World" isn’t very interesting by itself. Possible variations can be added to the text using the `rule` constructor to provide a named set of text strings and the rule delimiter syntax (`{}`) within the text strings to substitute the generated content of the rule.
+
+```ruby
+class HelloWorld < Calyx::Grammar
+  start '{greeting} world.'
+  rule :greeting, 'Hello', 'Hi', 'Hey', 'Yo'
+end
+
+hello = HelloWorld.new
+
+hello.generate
+# > "Hi world."
+
+hello.generate
+# > "Hello world."
+
+hello.generate
+# > "Yo world."
+```
+
+Rules are recursive. They can be arbitrarily nested and connected to generate larger and more complex texts.
+
+```ruby
+class HelloWorld < Calyx::Grammar
+  start '{greeting} {world_phrase}.'
+  rule :greeting, 'Hello', 'Hi', 'Hey', 'Yo'
+  rule :world_phrase, '{happy_adj} world', '{sad_adj} world', 'world'
+  rule :happy_adj, 'wonderful', 'amazing', 'bright', 'beautiful'
+  rule :sad_adj, 'cruel', 'miserable'
+end
+```
+
+Nesting and hierarchy can be manipulated to balance consistency with variation. The exact same word atoms can be combined in different ways to produce strikingly different resulting texts.
+
+```ruby
+module HelloWorld
+  Sentiment < Calyx::Grammar
+    start '{happy_phrase}', '{sad_phrase}'
+    rule :happy_phrase, '{happy_greeting} {happy_adj} world.'
+    rule :happy_greeting, 'Hello', 'Hi', 'Hey', 'Yo'
+    rule :happy_adj, 'wonderful', 'amazing', 'bright', 'beautiful'
+    rule :sad_phrase, '{sad_greeting} {sad_adj} world.'
+    rule :sad_greeting, 'Goodbye', 'So long', 'Farewell'
+    rule :sad_adj, 'cruel', 'miserable'
+  end
+
+  Mixed < Calyx::Grammar
+    start '{greeting} {adj} world.'
+    rule :greeting, 'Hello', 'Hi', 'Hey', 'Yo', 'Goodbye', 'So long', 'Farewell'
+    rule :adj, 'wonderful', 'amazing', 'bright', 'beautiful', 'cruel', 'miserable'
+  end
+end
+```
+
+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
+```
+
+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."
+```
+
+### Calyx::DataTemplate
+Calyx::DataTemplate is useful for allowing a computer to write stories based on data stored within a Hash. The data can be plugged instantly into generated content, so long as you use erb syntax (to distingush from the rule delimiter syntax).
+
+```ruby
+class StockReport < Calyx::Grammar
+ start "The price of one share of <%= name %> on <%= date %> is <%= price %> Yen."
+end
+
+class StockWriter < Calyx::DataTemplate
+ def write_narrative
+  write StockReport
+ end
+end
+
+cyberdyne = { :name => "Cyberdyne", :price => 1897.0, :date => Date.new(2015,1,14) }
+
+stock_writer = StockWriter.new(cyberdyne)
+stock_writer.result
+# => "The price of one share of Cyberdyne on 2015-01-14 is 1897.0 Yen."
+```
+
+`conditional_write` allows Calyx::DataTemplate to choose what grammar rule to invoke. If the condition is true, use the first grammar; otherwise, use the second grammar.
+```ruby
+class GoodStock < Calyx::Grammar
+ start "You should buy stock in <%= name %> because this company has a low EPS."
+end
+
+class BadStock < Calyx:Grammar
+ start "You should sell stock in <%= name %> because this company has a high EPS."
+end
+
+class StockWriter < Calyx::DataTemplate
+ def write_narrative
+  conditional_write eps <= 20, GoodStock, BadStock
+ end
+end
+
+mitsui = { :name => "Mitsui", :eps => 15.8}
+mitsui_writer = StockWriter.new(mitsui)
+mitsui_writer.result
+# => "You should buy stock in Mitsui because this company has a low EPS."
+
+tokoyo_electric = { :name => "Tokyo Electric Power", :eps => 275.2 }
+tokoyo_electric_writer = StockWriter.new(tokoyo_electric)
+tokoyo_electric_writer.result
+# => "You should sell stock in Tokoyo Electric Power because this company has a high EPS."
+```
+
+You may also only provide only one grammar for `conditional_write`. If the condition is false, then nothing will be written.
+```ruby
+class StockWriter < Calyx::DataTemplate
+ def write_narrative
+  conditional_write eps <= 20, GoodStock
+ end
+end
+
+tokoyo_electric = { :name => "Tokyo Electric Power", :eps => 275.2 }
+tokoyo_electric_writer = StockWriter.new(tokoyo_electric)
+tokoyo_electric_writer.result
+# => ""
+```
+
+By simply specifying a few "meta-rules" with conditionals and Grammars, you can generate unique, readable narratives based on your data.
+```ruby
+class StockWriter < Calyx::DataTemplate
+ def write_narrative
+   write StockReport
+   conditional_write eps <= 20, GoodStock, BadStock
+   conditional_write eps <= 10, WonderfulStock
+   conditional_write eps >= 50, AbsolutelyHorribleStock
+   write ThanksForReading
+  end
+end
+```
+
+###
+
+## License
+
+Calyx is open source and provided under the terms of the MIT license. Copyright (c) 2015 Mark Rickerby, (c) 2016 Tariq Ali
+
+See the `LICENSE` file [included with the project distribution](https://github.com/tra38/calyx/blob/master/LICENSE) for more information.
+
+## History
+In November 2015, Mark Rickerby created Calyx and used that gem to create [choose-your-own adventure gamebooks](https://github.com/dariusk/NaNoGenMo-2015/issues/189). He later on wrote a [blog post](http://maetl.net/notes/storyboard/gamebook-of-dungeon-tropes) explaining his thought process.
+
+In January 2016, Tariq Ali forked Calyx and started adding in new features to turn Calyx into a useful tool for generating data-driven narratives (robojournalism).
+
+## Disclaimer
+In the real world, you would probably not want to buy or sell Japanese stock based solely on EPS. [The MIT Encyclopedia of the Japanese Economy](https://books.google.com/books?id=0RS0CGUaef8C&pg=PA423&lpg=PA423&dq=high+earnings+per+share+in+japan&source=bl&ots=sR8KV0fBTk&sig=qHspeX72SmpsU25wz9AZnhaAxyU&hl=en&sa=X&ved=0ahUKEwjcnqqctrLKAhWKRiYKHdKACaoQ6AEIHDAA#v=onepage&q=high%20earnings%20per%20share%20in%20japan&f=false) can provide some reasons why.

data/calyx.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'calyx/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'tra38-calyx'
+  spec.version       = Calyx::VERSION
+  spec.authors       = ['Mark Rickerby','Tariq Ali']
+  spec.email         = ['me@maetl.net','tra38@nau.edu']
+
+  spec.summary       = %q{Generate text with declarative recursive grammars}
+  spec.description   = %q{Calyx provides a simple API for generating text with declarative recursive grammars.}
+  spec.homepage      = 'https://github.com/tra38/calyx'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec)/}) }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec'
+end

data/lib/calyx.rb

@@ -0,0 +1,217 @@
+require 'erb'
+
+module Calyx
+  #The Grammar class and the Production module was written by Mark Rickerby in 2015, and licensed under the MIT license.
+  class Grammar
+    class << self
+      attr_accessor :registry
+
+      def start(*productions, &production)
+        registry[:start] = construct_rule(productions)
+      end
+
+      def rule(name, *productions, &production)
+        registry[name.to_sym] = construct_rule(productions)
+      end
+
+      def inherit_registry(rules)
+        @registry ||= {}
+        @registry.merge!(rules || {})
+      end
+
+      def inherited(subclass)
+        subclass.inherit_registry(@registry)
+      end
+
+      private
+
+      def construct_rule(productions)
+        if productions.first.is_a?(Enumerable)
+          Production::WeightedChoices.parse(productions, registry)
+        else
+          Production::Choices.parse(productions, registry)
+        end
+      end
+    end
+
+    module Production
+      class NonTerminal
+        def initialize(expansion, registry)
+          @expansion = expansion.to_sym
+          @registry = registry
+        end
+
+        def evaluate
+          @registry[@expansion].evaluate
+        end
+      end
+
+      class Terminal
+        def initialize(atom)
+          @atom = atom
+        end
+
+        def evaluate
+          @atom
+        end
+      end
+
+      class Expression
+        def initialize(production, methods)
+          @production = production
+          @methods = methods.map { |m| m.to_sym }
+        end
+
+        def evaluate
+          @methods.reduce(@production.evaluate) do |value,method|
+            value.send(method)
+          end
+        end
+      end
+
+      class Concat
+        EXPRESSION = /(\{[A-Za-z0-9_\.]+\})/.freeze
+        START_TOKEN = '{'.freeze
+        END_TOKEN = '}'.freeze
+        DEREF_TOKEN = '.'.freeze
+
+        def self.parse(production, registry)
+          expansion = production.split(EXPRESSION).map do |atom|
+            if atom.is_a?(String)
+              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)
+                else
+                  rule
+                end
+              else
+                Terminal.new(atom)
+              end
+            elsif atom.is_a?(Symbol)
+              NonTerminal.new(atom, registry)
+            end
+          end
+
+          self.new(expansion)
+        end
+
+        def initialize(expansion)
+          @expansion = expansion
+        end
+
+        def evaluate
+          @expansion.reduce('') do |exp, atom|
+            exp << atom.evaluate
+          end
+        end
+      end
+
+      class WeightedChoices
+        def self.parse(productions, registry)
+          weights_sum = productions.reduce(0) do |memo, choice|
+            memo += choice.last
+          end
+
+          raise 'Weights must sum to 1' if weights_sum != 1.0
+
+          choices = productions.map do |choice, weight|
+            if choice.is_a?(String)
+              [Concat.parse(choice, registry), weight]
+            elsif choice.is_a?(Symbol)
+              [NonTerminal.new(choice, registry), weight]
+            end
+          end
+
+          self.new(choices)
+        end
+
+        def initialize(collection)
+          @collection = collection
+        end
+
+        def evaluate
+          choice = @collection.max_by do |_, weight|
+            rand ** (1.0 / weight)
+          end.first
+
+          choice.evaluate
+        end
+      end
+
+      class Choices
+        def self.parse(productions, registry)
+          choices = productions.map do |choice|
+            if choice.is_a?(String)
+              Concat.parse(choice, registry)
+            elsif choice.is_a?(Symbol)
+              NonTerminal.new(choice, registry)
+            end
+          end
+          self.new(choices)
+        end
+
+        def initialize(collection)
+          @collection = collection
+        end
+
+        def evaluate
+          @collection.sample.evaluate
+        end
+      end
+    end
+
+    def initialize(seed=nil)
+      @seed = seed
+      @seed = Time.new.to_i unless @seed
+      srand(@seed)
+    end
+
+    def registry
+      self.class.registry
+    end
+
+    def generate
+      registry[:start].evaluate
+    end
+  end
+
+  #The DataTemplate class was written by Tariq Ali in 2016, and licensed under the MIT License.
+  class DataTemplate
+    attr_reader :narrative
+
+    def initialize(data_hash = {})
+      data_hash.each do |key, value|
+        self.define_singleton_method(:"#{key}") do
+          value
+        end
+      end
+      @narrative = []
+      write_narrative
+    end
+
+    def write_narrative
+      #user writes in what should happened next
+      raise "There is no 'write_narrative' method present in your class."
+    end
+
+    def write(klass)
+      @narrative << klass.new.generate
+    end
+
+    def conditional_write(condition, klass_a, klass_b = nil)
+      if condition
+        @narrative << klass_a.new.generate
+      elsif klass_b
+        @narrative << klass_b.new.generate
+      else
+      end
+    end
+
+    def result
+      ERB.new(@narrative.join(" ")).result(binding)
+    end
+
+  end
+end

data/lib/calyx/version.rb

@@ -0,0 +1,3 @@
+module Calyx
+  VERSION = '0.6.2'.freeze
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: tra38-calyx
+version: !ruby/object:Gem::Version
+  version: 0.6.2
+platform: ruby
+authors:
+- Mark Rickerby
+- Tariq Ali
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-01-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Calyx provides a simple API for generating text with declarative recursive
+  grammars.
+email:
+- me@maetl.net
+- tra38@nau.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE
+- README.md
+- calyx.gemspec
+- lib/calyx.rb
+- lib/calyx/version.rb
+homepage: https://github.com/tra38/calyx
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Generate text with declarative recursive grammars
+test_files: []