calyx 0.17.1 → 0.18.0

data/docs/content/introduction/contributing.md

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

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

data/docs/content/styleguide.html

@@ -0,0 +1,71 @@
+---
+layout: default
+title: Styleguide
+permalink: /styleguide/
+---
+
+<h2>Logo</h2>
+
+<div class="card">
+  <img src="/assets/calyx-flower.svg" width="200" height="200">
+</div>
+
+<h2>Colors</h2>
+
+<div class="columns">
+
+<div class="column">
+<div class="card">
+  <div class="card-header">
+    <div class="color-chip color-aquamarine"></div>
+  </div>
+  <div class="card-body">
+    <p>Aquamarine</p>
+  </div>
+</div>
+</div>
+
+<div class="column">
+<div class="card">
+  <div class="card-header">
+    <div class="color-chip color-meadow"></div>
+  </div>
+  <div class="card-body">
+    <p>Meadow</p>
+  </div>
+</div>
+</div>
+
+<div class="column">
+<div class="card">
+  <div class="card-header">
+    <div class="color-chip color-eucalyptus"></div>
+  </div>
+  <div class="card-body">
+    <p>Eucalyptus</p>
+  </div>
+</div>
+</div>
+
+<div class="column">
+<div class="card">
+  <div class="card-header">
+    <div class="color-chip color-stromboli"></div>
+  </div>
+  <div class="card-body">
+    <p>Stromboli</p>
+  </div>
+</div>
+</div>
+
+</div>
+
+<h2>Scale</h2>
+
+<div class="content">
+  <p class="p0">Wavering Plywood Handgloves</p>
+  <p class="p1">Wavering Plywood Handgloves</p>
+  <p class="p2">Wavering Plywood Handgloves</p>
+  <p class="p3">Wavering Plywood Handgloves</p>
+  <p class="p4">Wavering Plywood Handgloves</p>
+</div>

data/docs/docs.scss

@@ -0,0 +1,94 @@
+@import "_styles/reset";
+@import "_styles/media";
+@import "_styles/colors";
+@import "_styles/typography";
+@import "_styles/modifiers";
+@import "_styles/grid";
+@import "_styles/menu";
+@import "_styles/styleguide";
+@import "_styles/navbar";
+@import "_styles/pagebar";
+@import "_styles/syntax";
+@import "_styles/spread";
+@import "_styles/cta";
+@import "_styles/yard";
+@import "_styles/card";
+@import "_styles/content";
+
+.container {
+  width: 60%;
+  margin: $scale-p2 auto;
+  color: $color-dark;
+  line-height: 1.5;
+
+  h1 {
+    color: $color-eucalyptus;
+  }
+
+  a {
+    color: $color-dark;
+    border-bottom: 1px solid $color-meadow;
+    padding-left: $scale-m2;
+
+    &:before {
+      padding-right: $scale-m2;
+      content: "→";
+    }
+  }
+}
+
+.page {
+  background-color: $color-page-background;
+  min-height: calc(100vh - #{$navbar-height} - #{$pagebar-height} - #{$scale-p1});
+}
+
+.docs-sidebar {
+  background-color: $color-sidebar-background;
+
+  @include at-least-tablet {
+    .menu-label,
+    .menu-list li {
+      font-size: $scale-m1;
+    }
+  }
+
+  @include until-tablet {
+    .menu-label,
+    .menu-list li {
+      a {
+        padding-left: $scale-p3;
+      }
+    }
+  }
+
+  @include tablet {
+    width: $scale-p0 * 10;
+  }
+
+  @include desktop {
+    width: $scale-p0 * 10;
+  }
+}
+
+.docs-content {
+  order: 2;
+  min-width: 83.3333333%;
+}
+
+
+
+.content-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+
+  .content-footer-col {
+    border: 1px solid red;
+    //padding: $scale-p3;
+  }
+}
+
+.navbar.is-fixed + .spread,
+.navbar.is-fixed + .page {
+  margin-top: ($scale-p0 + $scale-m3) * 3;
+}

data/docs/index.html

@@ -2,31 +2,9 @@
 layout: home
 ---
 
-{% 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 generative grammar 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>
+  <p>Calyx provides a simple Ruby API for generating text with template expansion 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>

data/docs/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "main": "index.html",
   "scripts": {
-    "build": "node-sass --include-path node_modules/bulma calyx-docs.scss assets/calyx-docs.css",
+    "build": "node-sass --include-path node_modules/bulma docs.scss assets/calyx-docs.css",
     "watch": "node-sass --watch --include-path node_modules/bulma docs.scss assets/calyx-docs.css",
     "help": "node-sass --help"
   },

data/lib/calyx/production/choices.rb

@@ -34,6 +34,13 @@ module Calyx
         @collection = collection
       end
 
+      # The number of possible choices available for this rule.
+      #
+      # @return [Integer]
+      def size
+        @collection.size
+      end
+
       # Evaluate the choice by randomly picking one of its possible options.
       #
       # @param [Calyx::Options] options

data/lib/calyx/production/unique.rb

@@ -4,8 +4,6 @@ module Calyx
     # returns values that have not previously been selected. The probability
     # that a given rule will be selected increases as more selections are made
     # and the list grows smaller.
-    #
-    # TODO: handle wraparound
     class Unique
       SIGIL = '$'.freeze
 

data/lib/calyx/registry.rb

@@ -128,6 +128,11 @@ module Calyx
       uniques[symbol] = [] if uniques[symbol].nil?
 
       while pending
+        if uniques[symbol].size == @rules[symbol].size
+          uniques[symbol] = []
+          pending = false
+        end
+
         result = expand(symbol).evaluate(@options)
 
         unless uniques[symbol].include?(result)

data/lib/calyx/rule.rb

@@ -10,6 +10,10 @@ module Calyx
       @trace = trace
     end
 
+    def size
+      productions.size
+    end
+
     def evaluate(options)
       productions.evaluate(options)
     end

data/lib/calyx/version.rb

@@ -1,3 +1,3 @@
 module Calyx
-  VERSION = '0.17.1'.freeze
+  VERSION = '0.18.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calyx
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.18.0
 platform: ruby
 authors:
 - Mark Rickerby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-08 00:00:00.000000000 Z
+date: 2018-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -72,19 +72,65 @@ files:
 - docs/404.html
 - docs/CNAME
 - docs/_config.yml
+- docs/_data/breadcrumbs.yml
+- docs/_data/docs.yml
+- docs/_data/examples.yml
+- docs/_includes/breadcrumbs.html
+- docs/_includes/contents.html
+- docs/_includes/icon-github.html
+- docs/_includes/icon-rubygems.html
+- docs/_includes/navbar.html
+- docs/_includes/pagebar.html
 - docs/_layouts/default.html
+- docs/_layouts/docs.html
+- docs/_layouts/home.html
+- docs/_layouts/page.html
 - docs/_posts/2017-09-14-welcome-to-jekyll.markdown
-- docs/about.md
+- docs/_posts/2017-09-21-0.17.0-released.md
+- docs/_styles/card.scss
+- docs/_styles/colors.scss
+- docs/_styles/content.scss
+- docs/_styles/cta.scss
+- docs/_styles/grid.scss
+- docs/_styles/media.scss
+- docs/_styles/menu.scss
+- docs/_styles/modifiers.scss
+- docs/_styles/navbar.scss
+- docs/_styles/pagebar.scss
+- docs/_styles/reset.scss
+- docs/_styles/scale.scss
+- docs/_styles/spread.scss
+- docs/_styles/styleguide.scss
+- docs/_styles/syntax.scss
+- docs/_styles/typography.scss
+- docs/_styles/yard.scss
+- docs/api.html
 - docs/assets/calyx-docs.css
-- docs/calyx-docs.scss
-- docs/guide/context.md
-- docs/guide/examples.md
-- docs/guide/expressions.md
-- docs/guide/formats.md
-- docs/guide/getting-started.md
-- docs/guide/installation.md
-- docs/guide/random.md
-- docs/guide/results.md
+- docs/assets/calyx-flower-outline.svg
+- docs/assets/calyx-flower-reverse.svg
+- docs/assets/calyx-flower.svg
+- docs/assets/logo-small.png
+- docs/assets/logos/calyx-flower-1.svg
+- docs/assets/logos/calyx-flower-2.svg
+- docs/content/documentation.html
+- docs/content/examples.html
+- docs/content/examples/any-gradient.md
+- docs/content/examples/faker.md
+- docs/content/examples/tiny-woodland-bot.md
+- docs/content/guides/context.md
+- docs/content/guides/expressions.md
+- docs/content/guides/features.md
+- docs/content/guides/formats.md
+- docs/content/guides/installation.md
+- docs/content/guides/random.md
+- docs/content/guides/results.md
+- docs/content/index.html
+- docs/content/introduction.md
+- docs/content/introduction/concepts.md
+- docs/content/introduction/contributing.md
+- docs/content/introduction/tutorial.md
+- docs/content/styleguide.html
+- docs/docs.scss
 - docs/index.html
 - docs/package-lock.json
 - docs/package.json
@@ -130,7 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Generate text with declarative recursive grammars