calyx 0.17.1 → 0.18.0

data/docs/assets/logos/calyx-flower-1.svg

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+    <svg width="400px"
+         height="400px"
+         version="1.1"
+         xmlns="http://www.w3.org/2000/svg"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+      <defs>
+        <symbol id="petals">
+          <ellipse cx="200" cy="120" rx="37" ry="80" /><ellipse cx="200" cy="280" rx="37" ry="80" /><ellipse cx="280" cy="200" rx="80" ry="37" /><ellipse cx="120" cy="200" rx="80" ry="37" />
+        </symbol>
+        <symbol id="corolla">
+          <use xlink:href="#petals" />
+          <use xlink:href="#petals" transform="rotate(22.5 200 200)" />
+          <use xlink:href="#petals" transform="rotate(45 200 200)" />
+          <use xlink:href="#petals" transform="rotate(-22.5 200 200)" />
+        </symbol>
+      </defs>
+      <use xlink:href="#corolla" fill="#1BDE81" stroke="#2F5E52" stroke-width="16"/>
+      <use xlink:href="#corolla" fill="#76FABB" stroke="#2F5E52" stroke-width="18" transform="scale(0.80 0.80) translate(50 50)" />
+      <use xlink:href="#corolla" fill="#218764" stroke="#2F5E52" stroke-width="5" transform="scale(0.40 0.40) translate(300 300)" />
+    </svg>
+  

data/docs/assets/logos/calyx-flower-2.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+    <svg width="400px"
+         height="400px"
+         version="1.1"
+         xmlns="http://www.w3.org/2000/svg"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+      <defs>
+        <symbol id="petals">
+          <ellipse cx="200" cy="120" rx="25" ry="80" /><ellipse cx="200" cy="280" rx="25" ry="80" /><ellipse cx="280" cy="200" rx="80" ry="25" /><ellipse cx="120" cy="200" rx="80" ry="25" />
+        </symbol>
+        <symbol id="corolla">
+          <use xlink:href="#petals" />
+          <use xlink:href="#petals" transform="rotate(22.5 200 200)" />
+          <use xlink:href="#petals" transform="rotate(45 200 200)" />
+          <use xlink:href="#petals" transform="rotate(-22.5 200 200)" />
+        </symbol>
+      </defs>
+      <use xlink:href="#corolla" fill="#1BDE81" stroke="#218764" stroke-width="10"/>
+      <use xlink:href="#corolla" fill="#76FABB" stroke="#1BDE81" stroke-width="18" transform="scale(0.80 0.80) translate(50 50)" />
+      <use xlink:href="#corolla" fill="#218764" stroke="#76FABB" stroke-width="15" transform="scale(0.40 0.40) translate(300 300)" />
+    </svg>

data/docs/content/documentation.html

@@ -0,0 +1,20 @@
+---
+title: Documentation
+layout: page
+permalink: /docs/
+---
+
+<div class="row">
+{% for section in site.data.docs %}
+  <div class="col">
+    <div class="menu">
+      <h2 class="menu-label"><a href="{{ section.permalink }}">{{ section.title }}</a></h2>
+      <ul class="menu-list">
+      {% for doc_page in section.pages %}
+        <li><a href="{{ doc_page.permalink }}">{{ doc_page.title }}</a></li>
+      {% endfor %}
+      </ul>
+    </div>
+  </div>
+{% endfor %}
+</div>

data/docs/content/examples.html

@@ -0,0 +1,12 @@
+---
+title: Examples
+layout: page
+permalink: /examples/
+---
+
+{% for example in site.data.examples %}
+<div class="card">
+  <h2><a href="{{ example.permalink }}">{{ example.title }}</a></h2>
+  <p>{{ example.description }}</p>
+</div>
+{% endfor %}

data/docs/content/examples/any-gradient.md

@@ -0,0 +1,32 @@
+---
+layout: default
+title: Examples
+layout: page
+permalink: /examples/any-gradient
+---
+
+# 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
+```

data/docs/content/examples/faker.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: Examples
+layout: page
+permalink: /examples/faker
+---
+
+## 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
+```

data/docs/content/examples/tiny-woodland-bot.md

@@ -0,0 +1,24 @@
+---
+layout: default
+title: Examples
+layout: page
+permalink: /examples/tiny-woodland-bot
+---
+
+## 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
+```

data/docs/{guide → content/guides}/context.md

@@ -1,7 +1,7 @@
 ---
-layout: default
+layout: page
 title: Context
-permalink: /context/
+permalink: /guides/context
 ---
 
 j,jnnnnnnjjj

data/docs/{guide → content/guides}/expressions.md

@@ -1,7 +1,7 @@
 ---
-layout: default
+layout: page
 title: Template Expressions
-permalink: /expressions/
+permalink: /guides/expressions
 ---
 
 # Template Expressions

data/docs/content/guides/features.md

@@ -0,0 +1,50 @@
+---
+layout: docs
+title: Features documented in README
+---
+
+## Template Expressions
+
+Basic rule substitution uses single curly brackets as delimiters for template expressions:
+
+```ruby
+fruit = Calyx::Grammar.new do
+  start '{colour} {fruit}'
+  colour 'red', 'green', 'yellow'
+  fruit 'apple', 'pear', 'tomato'
+end
+
+6.times { fruit.generate }
+# => "yellow pear"
+# => "red apple"
+# => "green tomato"
+# => "red pear"
+# => "yellow tomato"
+# => "green apple"
+```
+
+## The start symbol
+
+By convention, the `start` rule specifies the default starting point for generating the final text. You can start from any other named rule by passing it explicitly to the generate method.
+
+```ruby
+class HelloWorld < Calyx::Grammar
+  hello 'Hello world!'
+end
+
+hello = HelloWorld.new
+hello.generate(:hello)
+```
+
+## 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.'
+  greeting 'Hello', 'Hi', 'Hey', 'Yo'
+end
+
+hello.generate
+```

data/docs/{guide → content/guides}/formats.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: File Formats
-permalink: /formats/
+permalink: /guides/formats
 ---
 
 # File Formats

data/docs/content/guides/installation.md

@@ -0,0 +1,51 @@
+---
+title: Installation
+layout: docs
+permalink: /guides/installation
+---
+
+## System requirements
+
+The following prerequisites are needed to install Calyx:
+
+- macOS, Windows, GNU/Linux or Unix
+- Ruby 2.3 or above (MRI 2.3+, JRuby 9+, Rubinius 3+)
+- RubyGems
+
+Calyx has no external Gem dependencies.
+
+## For command line use
+
+Install the Calyx gem using the [RubyGems](https://rubygems.org) package manager:
+
+```
+gem install calyx
+```
+
+## For applications
+
+Add the `calyx` dependency to your app’s `Gemfile`:
+
+```ruby
+gem 'calyx'
+```
+
+Run [Bundler](https://bundler.io/) to install it:
+
+```
+bundle install
+```
+
+## For local development
+
+To contribute code back to Calyx or fork it in a new direction, clone the repo from GitHub:
+
+```
+git clone git@github.com:maetl/calyx
+```
+
+You can also download the latest build of the project as a ZIP archive:
+
+```
+wget https://github.com/maetl/calyx/archive/master.zip
+```

data/docs/{guide → content/guides}/random.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Random Sampling
-permalink: /random/
+permalink: /guides/random/
 ---
 
 # Random Sampling

data/docs/{guide → content/guides}/results.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Results
-permalink: /results/
+permalink: /guides/results/
 ---
 
 # Generating Results

data/docs/content/index.html

@@ -0,0 +1,44 @@
+---
+title: Calyx
+layout: home
+permanlink: /
+---
+
+{% include navbar.html %}
+
+<div class="spread spread-hero">
+  <figure class="identity">
+    <img src="/assets/logos/calyx-flower-2.svg" width="80%" height="80%">
+  </figure>
+  <div class="lede">
+    <h2>Create writing machines with generative grammars</h2>
+
+    <ul class="cta-list">
+      <li><a class="cta-button" href="#">Download</a></li>
+      <li><a class="cta-button" href="#">Learn more</a></li>
+    </ul>
+  </div>
+</div>
+
+<div class="spread spread-intro">
+  <p>Calyx is a simple and powerful tool for creating writing machines using the Ruby programming language.</p>
+</div>
+
+<div class="content">
+  <h1>Calyx</h1>
+  <p>Calyx provides a simple and powerful generative grammar format for creating writing machines using the Ruby programming language.</p>
+  <p>Although the primary use case is procedurally generating text, Calyx grammars can be used to make anything where the output format is a string.</p>
+  <p>Calyx provides a simple Ruby API for creating writing machines of all shapes and sizes using generative grammars.</p>
+  <ul>
+    <li><a href="https://github.com/maetl/calyx">Source code on GitHub</a></li>
+    <li><a href="https://rubygems.org/gems/calyx">Package on Rubygems</a></li>
+  </ul>
+</div>
+
+<div class="features">
+<p>An intuitive syntax for constructing text generators in native Ruby or JSON.</p>
+
+<p>Randomly select desired output from multiple choices.</p>
+
+<p>Use weighted probabilities to shape the odds of choices occurring.</p>
+</div>

data/docs/content/introduction.md

@@ -0,0 +1,23 @@
+---
+layout: docs
+title: Introduction
+permalink: /introduction/
+---
+
+## What is Calyx?
+
+Calyx is a simple and powerful software library for creating writing machines using the Ruby programming language. It provides tools for producing randomized sequences of text using a syntax inspired by generative grammars.
+
+Its primary affordances are for creating bots and weird combinatorial prose and poetry but you can use it to generate anything that has a textual or tree-based representation, including SVG graphics, narrative graphs and fake data schemas.
+
+## Why grammars?
+
+There are many useful and interesting methods for generative writing. The grammar-based approach is popular, widely studied and practiced, and easy to get started with.
+
+Grammars offer direct authorial control over the fragments that combine to produce an output text. This involves more effort and structure than other more random approaches, but leads to carefully crafted and expressive results which still have a capacity to surprise, delight, and confound—as any good text generation method should.
+
+## Getting Started
+
+Get started with a [simple tutorial](/introduction/tutorial/) or learn more about the [underlying concepts](/introduction/concepts/). If you’re new to Ruby and generative art in general, the [documentation for beginners](/introduction/beginners/) is a good place to start.
+
+Use the [guides](/docs/guides/) to learn how to use the various features and capabilities of the library. For more direct and structured information, the [reference](/docs/reference/) contains a full breakdown of everything that Calyx supports.

data/docs/content/introduction/concepts.md

@@ -0,0 +1,82 @@
+---
+title: Key Concepts
+layout: docs
+permalink: /introduction/concepts/
+---
+
+## What are grammars?
+
+A grammar is a set of interconnected rules that describe the syntax of a language. The grammar rules describe how to form strings in that language based on an alphabet.
+
+## A dash of theory
+
+Traditionally, generative grammars are often described as recognizers. Given a particular string as input, the grammar defines whether or not that string is recognized.
+
+For example, let’s imagine what a pseudocode grammar representing whole numbers greater than zero might look like.
+
+```
+start := leading_digit *digit
+leading_digit := 1..9
+digit := 0..9
+```
+
+If we could turn this pseudocode grammar into a recognizer function and run it on a range of possible strings, we’d see the following results.
+
+```ruby
+grammar.parse("1")      # => true
+grammar.parse("2")      # => true
+grammar.parse("99")     # => true
+grammar.parse("111")    # => true
+grammar.parse("134534") # => true
+grammar.parse("0")      # => false
+grammar.parse("055")    # => false
+grammar.parse("abc")    # => false
+grammar.parse("1.5")    # => false
+```
+
+How does it work?
+
+The grammar here is made up of ‘production rules’, which in turn are made up of named symbols called ‘nonterminals’ and literal patterns called ‘terminals’ which match a range of possible strings.
+
+In this case, `start`, `leading_digit` and `digit` are nonterminals whereas `1..9` and `0..9` are terminals. By convention, `*` means ‘zero or more’, which specifies that the production can match repeating characters over and over until an unmatched character is found (formally, this is known as the [Kleene star](https://en.wikipedia.org/wiki/Kleene_star)).
+
+To recognize a string with the grammar, we start with a left hand side nonterminal (by convention, this is known as the start symbol, often named `start`) and substitute it with its right hand side production. We then do the same for the next set of nonterminals we find in the production, until we bottom out at a set of terminals matching the literal string.
+
+If we walk through
+
+```
+grammar.parse("1")
+```
+
+1. Replace `start` with `leading_digit` then `*digit`
+2. `leading_digit` is a terminal `1..9`, so check that the first character matches
+3. `*digit`
+
+
+
+If you’re familiar with regular expressions, you’ll notice that this grammar seems to do exactly the same thing as the following regular expression.
+
+```ruby
+/^[1-9][0-9]*$/
+```
+
+Remarkably, this isn’t a coincidence or example of TMTOWTDI. It turns out that there’s a deep symmetry between grammars and regular expressions. Every regular grammar can be transformed into an equivalent regular expression and vice versa.
+
+```
+Number := Zero | Integer | Decimal | Real
+Integer := LeadingDigit *Digit
+LeadingDigit := [1-9]
+Digit := [0-9]
+Decimal := Integer "." *Digit
+Real := Integer "/" Integer
+Zero := "0"
+```
+
+The following sequences are recognised as valid by the number grammar:
+
+- `1`
+- `23.424`
+- `30000`
+- `1/7`
+
+Template expansion grammars