calyx 0.11.3 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b5a355ab937e5afbf5ab76be107bee0f4e0b53a9
-  data.tar.gz: be8ab43657f9a57fac3644fcb11a7f4c184433aa
+  metadata.gz: 19046d53109e4dfe958d0e9e4fd3a3ff2d446109
+  data.tar.gz: 4a41b45d945bcb44ea7359db7398d0bdb6c366e8
 SHA512:
-  metadata.gz: 30858f8a309bf24795679caaae1f43558e5c4ecc8e356747c35745ecf6a680b18127183814f4cd0b0b8c4c96a6e8ba151b14fec506f56e806f184e037d98c5cc
-  data.tar.gz: 166bcc17f2e120a8e0cc6b2b95f42696e032c51bcbdfc73d86d0645feefc403a442ddd50f34972f6c1ac3d7a622bb33073e42bf11b2aa0bd52024f169910c707
+  metadata.gz: 38527d602bf96335cef8c504612c0d4bfb1fbf17dd459420123ceeb2c088207921e0d68580ec1777cf822476ab4e3a935f8f2b02d2d7834642806a3593f4170c
+  data.tar.gz: e49e3d348caaec3290e6412317f31e29054f4dbecce4dbf35c264c2a952fc36c442e1adeb7af2d6444ca7429f82d59f1b2bf504f15dc6967641a383fa09ca18c

data/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to Calyx
+
+Calyx is an open source project and contributions are welcome with the caveat that this is very much a personal creative project by Mark Rickerby, so keep that context in mind if you’re considering drastic code changes.
+
+Changes that fix bugs and improve test coverage will generally be merged on-the-spot. Larger changes that introduce new features should harmonise with the vision, goals and style of the project. If in doubt, just ask in advance.
+
+Should Calyx become more popular, these guidelines are likely to become more community-oriented, and I’ll look at handing project stewardship over to the community with a more formal project charter and structure.
+
+## General Contributions
+
+The best way to contribute is to use the Gem. Install it on a local project and try things out. Does it work? Does it do what you expect? Is there anything missing?
+
+It’s really helpful to contribute to discussion on open issues, reporting bugs or suggest new features. Any feedback and criticism is received with gratitude.
+
+## Code Contributions
+
+### Submitting Changes
+
+Changes to the source code and documentation should be submitted as a pull request on GitHub, corresponding to the following process:
+
+- Fork the repo and make a new branch for your changes
+- Submit your branch as a pull request against the master branch
+
+If any aspects of your changes are ambiguous or unclear, use the pull request description to explain and provide further context (including code samples as necessary).
+
+Please don’t bump the version as part of your changes (this happens separately).
+
+### Pull Request Checklist
+
+- Extraneous and trivial small commits should be squashed into larger descriptive commits
+- Commits should include concise and clear messages using standard formatting conventions
+- The test suite must be passing
+- Newly introduced code branches should be covered by tests
+-- Introduce new tests if existing tests don’t support your changes
+- Changes to method signatures and class organisation should be annotated by doc comments
+
+## Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behaviour by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+The maintainer has the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct.
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported by opening an issue or contacting the maintainer.
+
+*From the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/).*

data/README.md

@@ -1,7 +1,7 @@
 # Calyx
 
 [![Gem Version](http://img.shields.io/gem/v/calyx.svg)](https://rubygems.org/gems/calyx)
-[![Build Status](https://travis-ci.org/maetl/calyx.svg?branch=master)](https://travis-ci.org/maetl/calyx)
+[![Build Status](https://img.shields.io/travis/maetl/calyx.svg)](https://travis-ci.org/maetl/calyx)
 
 Calyx provides a simple API for generating text with declarative recursive grammars.
 
@@ -19,6 +19,60 @@ gem install calyx
 gem 'calyx'
 ```
 
+## Examples
+
+The best way to get started quickly is to install the gem and run the examples locally.
+
+## Any Gradient
+
+Requires Roda and Rack to be available.
+
+```
+gem install roda
+```
+
+Demonstrates how to use Calyx to construct SVG graphics. **Any Gradient** generates a rectangle with a linear gradient of random colours.
+
+Run as a web server and preview the output in a browser (`http://localhost:9292`):
+
+```
+ruby examples/any_gradient.rb
+```
+
+Or generate SVG files via a command line pipe:
+
+```
+ruby examples/any_gradient > gradient1.xml
+```
+
+## Tiny Woodland Bot
+
+Requires the Twitter client gem and API access configured for a specific Twitter handle.
+
+```
+gem install twitter
+```
+
+Demonstrates how to use Calyx to make a minimal Twitter bot that periodically posts unique tweets. See [@tiny_woodland on Twitter](https://twitter.com/tiny_woodland) and the [writeup here](http://maetl.net/notes/storyboard/tiny-woodlands).
+
+```
+TWITTER_CONSUMER_KEY=XXX-XXX
+TWITTER_CONSUMER_SECRET=XXX-XXX
+TWITTER_ACCESS_TOKEN=XXX-XXX
+TWITTER_CONSUMER_SECRET=XXX-XXX
+ruby examples/tiny_woodland_bot.rb
+```
+
+## Faker
+
+[Faker](https://github.com/stympy/faker) is a popular library for generating fake names and associated sample data like internet addresses, company names and locations.
+
+This example demonstrates how to use Calyx to reproduce the same functionality using custom lists defined in a YAML configuration file.
+
+```
+ruby examples/faker.rb
+```
+
 ## Usage
 
 Require the library and inherit from `Calyx::Grammar` to construct a set of rules to generate a text.
@@ -231,11 +285,13 @@ Dot-notation is supported in template expressions, allowing you to call any avai
 ```ruby
 class Greeting < Calyx::Grammar
   start '{hello.capitalize} there.', 'Why, {hello} there.'
-  hello 'hello'
+  hello 'hello', 'hi'
 end
 
 # => "Hello there."
+# => "Hi there."
 # => "Why, hello there."
+# => "Why, hi there."
 ```
 
 You can also extend the grammar with custom modifiers that provide useful formatting functions.
@@ -251,11 +307,13 @@ class Greeting < Calyx::Grammar
   end
 
   start '{hello.shoutycaps} there.', 'Why, {hello} there.'
-  hello 'hello'
+  hello 'hello', 'hi'
 end
 
 # => "HELLO there."
+# => "HI there."
 # => "Why, HELLO there."
+# => "Why, HI there."
 ```
 
 ### Mappings

data/examples/any_gradient.rb

@@ -0,0 +1,60 @@
+require 'roda'
+require 'calyx'
+
+class AnyGradient < Calyx::Grammar
+  html '<body style="margin:0; padding:0">{svg}</body>'
+  xml '<?xml version="1.0" encoding="utf-8"?>{svg}'
+  svg '
+    <svg width="100%"
+         height="100%"
+         version="1.1"
+         xmlns="http://www.w3.org/2000/svg"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+      {defs}
+      {rect}
+    </svg>
+  '
+  defs '
+    <defs>
+      {linear_gradient}
+    </defs>
+  '
+  linear_gradient '
+    <linearGradient id="linearGradient-1">
+      {stop_fixed}
+      {stop_offset}
+    </linearGradient>
+  '
+  stop_fixed '<stop stop-color="{stop_color}" offset="0%"></stop>'
+  stop_offset '<stop stop-color="{stop_color}" offset="{offset}"></stop>'
+  stop_color '#{hex_num}{hex_num}{hex_num}'
+  hex_num '{hex_val}{hex_val}'
+  hex_val '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F'
+  offset '{tens}{ones}%'
+  tens 3,4,5,6
+  ones 1,2,3,4,5,6,7,8,9,0
+  rect '
+    <rect id="gradient"
+          stroke="none"
+          fill="url(#linearGradient-1)"
+          fill-rule="evenodd"
+          x="0"
+          y="0"
+          width="100%"
+          height="100%"></rect>
+  '
+end
+
+class Server < Roda
+  route do |r|
+    r.root do
+      AnyGradient.new.generate(:html)
+    end
+  end
+end
+
+if STDOUT.tty?
+  Rack::Server.start :app => Server
+else
+  STDOUT.puts AnyGradient.new.generate(:xml)
+end

data/examples/tiny_woodland_bot.rb

@@ -0,0 +1,31 @@
+require "calyx"
+require "twitter"
+require "logger"
+
+tiny_woodland = Calyx::Grammar.new do
+  start :field
+  field (0..7).map { "{row}{br}" }.join
+  row (0..12).map { "{point}" }.join
+  point trees: 0.6, foliage: 0.35, flowers: 0.05
+  trees "🌲", "🌳"
+  foliage "🌿", "🌱"
+  flowers "🌷", "🌻", "🌼"
+  creatures "🐗", "🐻", "🐝", "🐦"
+  br "\n"
+end
+
+twitter_client = Twitter::REST::Client.new do |config|
+  config.consumer_key = ENV["TWITTER_CONSUMER_KEY"]
+  config.consumer_secret = ENV["TWITTER_CONSUMER_SECRET"]
+  config.access_token = ENV["TWITTER_ACCESS_TOKEN"]
+  config.access_token_secret = ENV["TWITTER_CONSUMER_SECRET"]
+end
+
+logger = Logger.new(STDOUT)
+
+begin
+  tweet = twitter_client.update(tiny_woodland.generate)
+  logger.info("Posted tweet: https://twitter.com/#{tweet.user.name}/status/#{tweet.id}")
+rescue Exception => e
+  logger.error(e)
+end

data/lib/calyx/grammar.rb

@@ -98,10 +98,13 @@ module Calyx
     # Grammar rules can be constructed on the fly when the passed-in block is
     # evaluated.
     #
-    # @param [Number] seed
-    def initialize(seed=nil, &block)
-      @seed = seed || Random.new_seed
-      srand(@seed)
+    # @param [Number, Random] seed
+    def initialize(seed=Random.new, &block)
+      if seed.is_a?(Numeric)
+        @rng = Random.new(seed)
+      else
+        @rng = seed
+      end
 
       if block_given?
         @registry = Registry.new
@@ -120,7 +123,7 @@ module Calyx
     def generate(*args)
       start_symbol, rules_map = map_default_args(*args)
 
-      @registry.evaluate(start_symbol, rules_map).flatten.reject do |obj|
+      @registry.evaluate(start_symbol, @rng, rules_map).flatten.reject do |obj|
         obj.is_a?(Symbol)
       end.join(''.freeze)
     end
@@ -134,7 +137,7 @@ module Calyx
     def evaluate(*args)
       start_symbol, rules_map = map_default_args(*args)
 
-      @registry.evaluate(start_symbol, rules_map)
+      @registry.evaluate(start_symbol, @rng, rules_map)
     end
 
     private

data/lib/calyx/production/choices.rb

@@ -35,8 +35,8 @@ module Calyx
       # Evaluate the choice by randomly picking one of its possible options.
       #
       # @return [Array]
-      def evaluate
-        [:choice, @collection.sample.evaluate]
+      def evaluate(rng)
+        [:choice, @collection.sample(random: rng).evaluate(rng)]
       end
     end
   end

data/lib/calyx/production/concat.rb

@@ -51,9 +51,9 @@ module Calyx
       # into a single result.
       #
       # @return [Array]
-      def evaluate
+      def evaluate(rng)
         concat = @expansion.reduce([]) do |exp, atom|
-          exp << atom.evaluate
+          exp << atom.evaluate(rng)
         end
 
         [:concat, concat]

data/lib/calyx/production/expression.rb

@@ -18,8 +18,8 @@ module Calyx
       # returning the transformed result.
       #
       # @return [Array]
-      def evaluate
-        terminal = @production.evaluate.flatten.reject { |o| o.is_a?(Symbol) }.join(''.freeze)
+      def evaluate(rng)
+        terminal = @production.evaluate(rng).flatten.reject { |o| o.is_a?(Symbol) }.join(''.freeze)
         expression = @methods.reduce(terminal) do |value, method|
           @registry.transform(method, value)
         end

data/lib/calyx/production/memo.rb

@@ -18,7 +18,7 @@ module Calyx
       # Evaluate the memo, using the registry to handle the expansion.
       #
       # @return [Array]
-      def evaluate
+      def evaluate(rng)
         [@symbol, @registry.memoize_expansion(@symbol)]
       end
     end

data/lib/calyx/production/non_terminal.rb

@@ -16,8 +16,8 @@ module Calyx
       # Evaluate the non-terminal, using the registry to handle the expansion.
       #
       # @return [Array]
-      def evaluate
-        [@symbol, @registry.expand(@symbol).evaluate]
+      def evaluate(rng)
+        [@symbol, @registry.expand(@symbol).evaluate(rng)]
       end
     end
   end

data/lib/calyx/production/terminal.rb

@@ -12,7 +12,7 @@ module Calyx
       # Evaluate the terminal by returning its identity directly.
       #
       # @return [Array]
-      def evaluate
+      def evaluate(rng)
         [:atom, @atom]
       end
     end

data/lib/calyx/production/weighted_choices.rb

@@ -30,6 +30,7 @@ module Calyx
       # Initialize a new choice with a list of child nodes.
       #
       # @param [Array] collection
+      # @param [Random] rng
       def initialize(collection)
         @collection = collection
       end
@@ -41,12 +42,12 @@ module Calyx
       # of code recommended in the Ruby standard library documentation.
       #
       # @return [Array]
-      def evaluate
+      def evaluate(rng)
         choice = @collection.max_by do |_, weight|
-          rand ** (1.0 / weight)
+          rng.rand ** (1.0 / weight)
         end.first
 
-        [:weighted_choice, choice.evaluate]
+        [:weighted_choice, choice.evaluate(rng)]
       end
     end
   end

data/lib/calyx/registry.rb

@@ -1,7 +1,7 @@
 module Calyx
   # Lookup table of all the available rules in the grammar.
   class Registry
-    attr_reader :rules, :transforms, :modifiers
+    attr_reader :rng, :rules, :transforms, :modifiers
 
     # Construct an empty registry.
     def initialize
@@ -78,7 +78,7 @@ module Calyx
     #
     # @param [Symbol] symbol
     def memoize_expansion(symbol)
-      memos[symbol] ||= expand(symbol).evaluate
+      memos[symbol] ||= expand(symbol).evaluate(@rng)
     end
 
     # Merges the given registry instance with the target registry.
@@ -99,8 +99,8 @@ module Calyx
     # @param [Symbol] start_symbol
     # @param [Hash] rules_map
     # @return [Array]
-    def evaluate(start_symbol=:start, rules_map={})
-      reset_evaluation_context
+    def evaluate(start_symbol=:start, rng=Random.new, rules_map={})
+      reset_evaluation_context(rng)
 
       rules_map.each do |key, value|
         if rules.key?(key.to_sym)
@@ -117,7 +117,7 @@ module Calyx
       expansion = expand(start_symbol)
 
       if expansion.respond_to?(:evaluate)
-        [start_symbol, expansion.evaluate]
+        [start_symbol, expansion.evaluate(rng)]
       else
         raise Errors::MissingRule.new(start_symbol)
       end
@@ -125,9 +125,10 @@ module Calyx
 
     private
 
-    attr_reader :memos, :context
+    attr_reader :rng, :memos, :context
 
-    def reset_evaluation_context
+    def reset_evaluation_context(rng)
+      @rng = rng
       @context = {}
       @memos = {}
     end

data/lib/calyx/version.rb

@@ -1,3 +1,3 @@
 module Calyx
-  VERSION = '0.11.3'.freeze
+  VERSION = '0.12.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calyx
 version: !ruby/object:Gem::Version
-  version: 0.11.3
+  version: 0.12.0
 platform: ruby
 authors:
 - Mark Rickerby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-07 00:00:00.000000000 Z
+date: 2016-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -62,13 +62,15 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE
 - README.md
 - calyx.gemspec
+- examples/any_gradient.rb
 - examples/faker.rb
 - examples/faker.yml
-- examples/tiny_woodland.rb
+- examples/tiny_woodland_bot.rb
 - lib/calyx.rb
 - lib/calyx/errors.rb
 - lib/calyx/format.rb
@@ -103,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Generate text with declarative recursive grammars

data/examples/tiny_woodland.rb

@@ -1,15 +0,0 @@
-require "calyx"
-
-tiny_woodland = Calyx::Grammar.new do
-  start :field
-  field (0..7).map { "{row}{br}" }.join
-  row (0..18).map { "{point}" }.join
-  point [:trees, 0.2], [:foliage, 0.25], [:flowers, 0.05], [:space, 0.5]
-  trees "🌲", "🌳"
-  foliage "🌿", "🌱"
-  flowers "🌷", "🌻", "🌼"
-  space " "
-  br "\n"
-end
-
-puts tiny_woodland.generate