calyx 0.20.0 → 0.21.0

data/docs/content/guides/installation.md

@@ -1,51 +0,0 @@
----
-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/content/guides/random.md

@@ -1,100 +0,0 @@
----
-layout: default
-title: Random Sampling
-permalink: /guides/random/
----
-
-# Random Sampling
-
-By default, the outcomes of generated rules are selected with Ruby’s built-in pseudorandom number generator (as seen in methods like `Kernel.rand` and `Array.sample`). To seed the random number generator, pass in an integer seed value as the first argument to the constructor:
-
-```ruby
-grammar = Calyx::Grammar.new(seed: 12345) do
-  # rules...
-end
-```
-
-Alternatively, you can pass a preconfigured instance of Ruby’s stdlib `Random` class:
-
-```ruby
-random = Random.new(12345)
-
-grammar = Calyx::Grammar.new(rng: random) do
-  # rules...
-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 Choices
-
-Choices can be weighted so that some rules have a greater probability of expanding than others.
-
-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
-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' => 1,
-    '3' => 2,
-    '4' => 3,
-    '5' => 4,
-    '6' => 5,
-    '7' => 6,
-    '8' => 5,
-    '9' => 4,
-    '10' => 3,
-    '11' => 2,
-    '12' => 1
-  )
-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
-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 'Empty'
-  monster 'Monster Only'
-  monster_treasure 'Monster and Treasure'
-  special 'Special'
-  trick_trap 'Trick/Trap.'
-  treasure 'Treasure'
-end
-```

data/docs/content/guides/results.md

@@ -1,62 +0,0 @@
----
-layout: default
-title: Results
-permalink: /guides/results/
----
-
-# Generating Results
-
-## Result objects
-
-Results are generated by calling `#generate` on the grammar instance. Results are immutable objects representing the unique randomized output from evaluating the grammar.
-
-```ruby
-grammar = Calyx::Grammar.new do
-  start "Where is the green sheep?"
-end
-
-result = grammar.generate
-# => Calyx::Result
-```
-
-The core accessor methods on the result are:
-
-- `#text`
-- `#tree`
-
-Results can only be deterministically generated by seeding the random number generator.
-
-## Accessing the flattened text string
-
-The `#text` method of the result provides access to the flattened text string generated by the grammar.
-
-```ruby
-result = grammar.generate
-
-result.text
-# => "Where is the green sheep?"
-```
-
-`#text` is aliased to the `#to_s` method so result objects can be concatenated and interpolated within other strings directly.
-
-```ruby
-result = grammar.generate
-
-templated = "Q: #{result}"
-# => "Q: Where is the green sheep?"
-```
-
-## Accessing the generated tree
-
-The `#tree` method of the result provides access to the raw generated tree structure without being flattened into a string.
-
-The tree is encoded as an array of nested arrays, with the leading symbols labeling the choices and rules selected, and the trailing terminal leaves encoding string values.
-
-This is related to the concept of [s-expressions](https://en.wikipedia.org/wiki/S-expression). It’s a fairly speculative feature at this stage, but it leads to some interesting possibilities.
-
-```ruby
-result = grammar.generate
-
-result.tree
-# => [:start, [:choice, [:concat, [[:atom, "Where is the green sheep?"]]]]]
-```

data/docs/content/index.html

@@ -1,44 +0,0 @@
----
-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

@@ -1,23 +0,0 @@
----
-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

@@ -1,82 +0,0 @@
----
-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

data/docs/content/introduction/contributing.md

@@ -1,43 +0,0 @@
----
-title: Contributing to Calyx
-layout: docs
-permalink: /introduction/contributing/
----
-
-# Contributing to Calyx
-
-Calyx is an open source project and contributions are welcome.
-
-## 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
-
-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.
-
-### 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 need further explanation, use the pull request description to provide further detail and context (including code samples as necessary).
-
-Please don’t bump the version as part of your pull request (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
-
-Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

data/docs/content/introduction/tutorial.md

@@ -1,129 +0,0 @@
----
-title: Tutorial
-layout: docs
-permalink: /introduction/tutorial
----
-
-## Objective
-
-This tutorial introduces Calyx with a basic ‘hello world’ example. Following these steps will help you get Calyx up and running and provide you with a code skeleton to start adding more interesting and creative things.
-
-## Initial setup
-
-Before getting started, you’ll need to install Calyx from RubyGems and have it available in your local dev environment:
-
-```
-gem install calyx
-```
-
-If you’re not sure how to do this yet, there’s more information about setting up your Ruby environment in the [resources for beginners](/introduction/beginners/). The [installation guide](/docs/guide/installation/) contains further details about prerequisites and how to download and install the Gem.
-
-## Getting started
-
-Create a file named `hello.rb` and add the following contents:
-
-```ruby
-require "calyx"
-
-hello = Calyx::Grammar.new do
-  start "Hello world!"
-end
-```
-
-The first line imports the Calyx library and the lines following use the `Calyx::Grammar` class to define the rules for the generated text, in this case just ‘Hello world!’.
-
-To generate the text result, call the `#generate` method on the grammar object. Add this to the bottom of the `hello.rb` file:
-
-```ruby
-puts hello.generate
-```
-
-Run it on the command line by typing `ruby hello.rb`. You should see the following result:
-
-```
-Hello world!
-```
-
-## Adding random choices
-
-Obviously, this hardcoded sentence isn’t very interesting by itself. To add variety to the text, rules can be defined with multiple choices to pick from:
-
-```ruby
-hello = Calyx::Grammar.new do
-  start 'Hello world!', 'Hi world!', 'Hey world!'
-end
-```
-
-Each time `#generate` runs, Calyx evaluates the grammar and randomly selects a single choice from the list of possible choices. So if we run the grammar three times, we might see three different results:
-
-```ruby
-hello.generate
-# => Hi world!
-
-hello.generate
-# => Hello world!
-
-hello.generate
-# => Yo world!
-```
-
-## Nesting rules inside rules
-
-When you embed the name of a rule in curly brackets inside a text fragment, Calyx will expand the embedded rule and replace it with generated output each time the grammar runs.
-
-The following example nests the `greeting` rule within the `start` rule:
-
-```ruby
-hello = Calyx::Grammar.new do
-  start '{greeting} world!'
-  greeting 'Hello', 'Hi', 'Hey', 'Yo'
-end
-```
-
-This generates the exact same text as before, but listing the greeting words on their own is more flexible and eliminates the need to write each variation of the phrase out in full.
-
-This process of starting with a larger fragment of text and breaking it up into smaller phrases and single words is something you’ll do a lot when writing larger and more detailed grammars.
-
-## Using nesting to shape the text
-
-Rules can be arbitrarily nested and connected to generate larger and more complex texts. The way the rules branch out is going to define the shape and ‘flavor’ of the text.
-
-For example, to create more exaggerated variations of the phrase, we can branch out to pick from a list of happy adjectives or a list of sad adjectives:
-
-```ruby
-hello = Calyx::Grammar.new do
-  start '{greeting} {world_phrase}.'
-  greeting 'Hello', 'Hi', 'Hey', 'Yo'
-  world_phrase '{happy_adj} world', '{sad_adj} world', 'world'
-  happy_adj 'wonderful', 'amazing', 'bright', 'beautiful'
-  sad_adj 'cruel', 'miserable'
-end
-```
-
-Nesting and branching can be manipulated to balance consistency with novelty. The exact same text fragments can be combined in a variety of ways to produce strikingly different resulting texts.
-
-The following grammar branches out at the top level, with `happy_phrase` and `sad_phrase` being generated from completely separate trees that don’t overlap:
-
-```ruby
-hello = Calyx::Grammar.new do
-  start '{happy_phrase} world.', '{sad_phrase} world.'
-  happy_phrase '{happy_greeting} {happy_adj}'
-  happy_greeting 'Hello', 'Hi', 'Hey', 'Yo'
-  happy_adj 'wonderful', 'amazing', 'bright', 'beautiful'
-  sad_phrase '{sad_greeting} {sad_adj}'
-  sad_greeting 'Goodbye', 'So long', 'Farewell'
-  sad_adj 'cruel', 'miserable'
-end
-```
-
-Whereas this variation of the grammar uses the same content but generates everything from a single branch, resulting in a word salad with happy and sad fragments mashed together:
-
-```ruby
-hello = Calyx::Grammar.new do
-  start '{greeting} {adj} world.'
-  greeting 'Hello', 'Hi', 'Hey', 'Yo', 'Goodbye', 'So long', 'Farewell'
-  adj 'wonderful', 'amazing', 'bright', 'beautiful', 'cruel', 'miserable'
-end
-```
-
-That’s really all you need to know to get started.