whirled_peas 0.11.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f73ce3a27741b9c790785fe5aad7179c6db66e045ca1c2e43af33887c1fd4d9
-  data.tar.gz: bd19233e2d81a2d4e985bc4c8b0ec3ec07b8fe4691f0c70c5a2374add780bc9b
+  metadata.gz: 16dc58df5e4b6dbb2bdf51d95841d02bc9172f1e116efd8afd0633df592a7c8e
+  data.tar.gz: 0a2a14b167b502954a9ec2e58d762b32b60a2ab62e136d976b7d1d70e5630189
 SHA512:
-  metadata.gz: 9c2a41a72c30eb2c96161c23bb4f47a37dd9052ca1206cdec2d714d3266b0a6e3eb58bc8dab0dea0517eaf1fe7c5743323a8a7579319e81fdce80b9d65992504
-  data.tar.gz: 1b120aa9b5327880dcdcffbb37cfb77b63a06be55089f77efe7c4da104ce36e65893412178b5efcc31d6f7a3b9aed8353bbe076ea0131f52a142910d251bc61f
+  metadata.gz: 94d96284d6b3201496456fad7b464f3b71ab02c51878817e81856331fa3cb763a36383198ffe2be31f2e9747580656cb13a587b630f4f5866cd40340c1617744
+  data.tar.gz: 51e6271630fda2450af38f59f9c8d888b2b9338efacb6f8c7664393b1fdea8e616f00e20eec47b8bba59c25db510cade9a359119e06d02f8ac9c8de79f372664

data/.gitignore

@@ -2,7 +2,6 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/
@@ -12,4 +11,3 @@ Gemfile.lock
 # rspec failure tracking
 .rspec_status
 *.wpz
-

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.11.1 - 2021-01-31
+
+- [36e48cf](https://github.com/tcollier/whirled_peas/tree/36e48cf6731706539c6c41ce0ef66e86c62380a5): Add highlight colors and border style to theme
+- [93b1034](https://github.com/tcollier/whirled_peas/tree/93b1034b9401fe9e31cd3199a5e2426d7a893ed6): Better handling of non-ascending graphs
+
 ## v0.11.0 - 2021-01-30
 
 - [c1f3d94](https://github.com/tcollier/whirled_peas/tree/c1f3d944a35305c3032681db13ffd6142a7e19e4): Add component support

data/README.md

@@ -38,10 +38,10 @@ Or install it yourself as:
 
 ## Usage
 
-A Whirled Peas application consists of the following pieces
+A Whirled Peas application consists of the following required pieces
 
-- The application (required) - the code that is to be visualized, it emits lightweight frame events through a producer
-- The main template factory (required) - builds templates to convert frame events from the application into terminal graphics
+- [The application](doc/application.md) - the code that is to be visualized, it dictates the frame contents and playback speed
+- [The template factory](doc/template_factory.md) - builds templates to convert frame from the application into terminal graphics
 
 These pieces are configured as following
 
@@ -74,1168 +74,19 @@ WhirledPeas.configure do |config|
 end
 ```
 
-Then the visualizer is started on the command line with
+Then the visualizer is started on the [command line](doc/cli.md) with
 
 ```
 $ whirled_peas play visualize.rb
 ```
 
-### Application
-
-The application is code to be visualized that integrates with Whirled Peas by providing the signature below
-
-```ruby
-# Start the application and pass frame events to the producer to be rendered
-# by the UI
-#
-# @param producer [Producer] frame producer that sends events to the UI
-def start(producer)
-  # application code here
-end
-```
-
-The producer provides the following methods
-
-```ruby
-# Add a frame to be displayed
-#
-# @param name [String] (required) application defined name for the frame. The
-#    template factory will be provided this name
-# @param duration [Number] (optional) time in seconds this frame should be
-#   displayed for (defaults to 1 frame)
-# @param args [Hash<Symbol, Object>] (optional) key/value pairs to send as
-#   arguments to the template factory
-def add_frame(name, duration:, args:)
-end
-
-# Create and yield a frameset instance that allows applications to add multiple
-# frames to play over the given duration. Adding frames to the yielded frameset
-# will result in playback that is eased by the given `easing` and `effect`
-# arguments (default is `:linear` easing)
-#
-# @param duration [Number] (required) total duration for which all frames in
-#   frameset will be displayed
-# @param easing [Symbol] (optional) easing function to be used to transition
-#   through all frames (defaults to `:linear`)
-# @param effect [Symbol] (optional) how to apply the easing function (defaults
-#   to `:in_out`, also available are `:in` and `:out`)
-# @yield [Frameset] instance that provides `#add_frame(name, args:)`
-def frameset(duration, easing:, effect:, &block)
-end
-```
-
-A frameset instance provides one method
-
-```ruby
-# Add a frame to be displayed, the duration will be determine by the number of
-# frames in the frameset along with the duration and easing of the frameset
-#
-# @param name [String] (required) application defined name for the frame. The
-#   template factory will be provided this name
-# @param args [Hash<Symbol, Object>] (optional) key/value pairs to send as
-#   arguments to the template factory
-def add_frame(name, args:)
-end
-```
-
-**IMPORTANT**: the keys in the `args` hash must be symbols!
-
-#### Example
-
-Simple application that loads a set of numbers and looks for a pair that adds up to 1,000
-
-```ruby
-class Application
-  def start(producer)
-    numbers = File.readlines('/path/to/numbers.txt').map(&:to_i)
-    producer.add_frame('load-numbers', duration: 3, args: { numbers: numbers })
-    numbers.sort!
-    producer.add_frame('sort-numbers', duration: 3, args: { numbers: numbers })
-    low = 0
-    high = numbers.length - 1
-    while low < high
-      sum = numbers[low] + numbers[high]
-      if sum == 1000
-        producer.add_frame('found-pair', duration: 5, args: { low: low, high: high, sum: sum })
-        return
-      elsif sum < 1000
-        producer.add_frame('too-low', args: { low: low, high: high, sum: sum })
-        low += 1
-      else
-        producer.add_frame('too-high', args: { low: low, high: high, sum: sum })
-        high -= 1
-      end
-    end
-    producer.add_frame('no-solution', duration: 5)
-  end
-end
-```
-
-### Template Factory
-
-To render the frame events sent by the application, the application requires a template factory. This factory will be called for each frame event, with the frame name and the arguments supplied by the application. A template factory can be an instance of ruby class and thus can maintain state. Whirled Peas provides a few basic building blocks to make simple, yet elegant terminal-based UIs.
-
-#### Building Blocks
-
-A template is created with `WhirledPeas.template`, which yields a `Composer` object for a `Box` and `BoxSettings`. The composer allows for attaching child elements and the settings for setting layout options. The following attributes of the template's settings will be overridden before it is rendered to ensure that it fills the screen exactly
-
-- `margin` - all margin will be set to 0
-- `width` - will be set to the screen's width
-- `height` - will be set to the screen's height
-- `sizing` - will be set `:border` to ensure the entire box fits on the screen and fills it entirely.
-
-A `Composer` provides the following methods to add child elements, each of these takes an optional string argument that is set as the name of the element (which can be useful when debugging).
-
-- `add_box` - yields a `Composer` for a `Box` and a `BoxSettings`, which will be added to the parent's children
-- `add_graph` - yields a `nil` and a `GraphSettings`, which will be added to the parent's children, the block should return an array of numbers
-- `add_grid` - yields a `Composer` for a `Grid` and a `GridSettings`, which will be added to the parent's children
-- `add_text` - yields `nil` and a `TextSettings`, which will be added to the parent's children
-
-E.g.
-
-```ruby
-WhirledPeas.template do |composer, settings|
-  settings.bg_color = :blue
-  composer.add_grid do |composer, settings|
-    settings.num_cols = 10
-    100.times do |i|
-      composer.add_text { i }
-    end
-  end
-end
-```
-
-The above template can also be broken down into more manageable methods, e.g.
-
-```ruby
-def number_grid(_composer, settings)
-  settings.num_cols = 10
-  100.times.map(&:itself)
-end
-
-WhirledPeas.template do |composer, settings|
-  settings.bg_color = :blue
-  composer.add_grid(&method(:number_grid))
-end
-```
-
-Additionally, if no child element is explicitly added to a `Grid`, but the block returns an array of strings or numbers, those will be converted to `Text` elements and added as children to the `Grid`. For example, these are identical ways to create a grid of strings
-
-```ruby
-template.add_grid do |composer|
-  100.times do |i|
-    composer.add_text { i }
-  end
-end
-
-template.add_grid do
-  100.times.map(&:itself)
-end
-```
-
-Similarly, if no child element is explicilty added to a `Box`, but the block returns a string or number, that value will be converted to a `Text` and added as a child. For example, these are identical ways to create a box with string content
-
-```ruby
-template.add_box do |composer|
-  composer.add_text { "Hello!" }
-end
-
-template.add_box do
-  "Hello!"
-end
-```
-
-#### Components
-
-A component is a composition of the core building blocks. This gem includes a handful of components and third parties can also add components using `WhirledPeas.register_component(name, component_class)` (the convention for `name` is a snake cased symbol). A component class must be constructed with no arguments, though can supply basic setters to allow for customizations. A component must also implement `#compose(composer, settings)`, which should attach elements to the composer. Thus a template can integrate with the component like
-
-```ruby
-WhirledPeas.template do |composer, settings|
-  # Attach the component registered with the name `:my_component` to the template
-  WhirledPeas.component(composer, settings, :my_component) do |component|
-    # Configure the component
-  end
-end
-```
-
-##### `:list_with_active`
-
-This component presents a list of content (either horizontally of vertically) and places the item specified by `active_index` in the preferred position.
-
-```
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ green, blue, *indigo*, viole┃
-┃           ▗▄▄▄▄▄▄▄▄▄▄▄▄▄▄▖  ┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-
-Note: in the diagram above, the item specified by the active index is highlighted with `*`s, these are for illustration onlhy. The component can highlight the item with a color and/or background color, but will _not_ add the `*`s.
-
-This component takes the following options
-
-**Required**
-
-- `active_index` - the index of the active item
-- `items` - the array of items to be displayed in the box
-
-**Optional**
-
-- `active_bg_color` - background color of the active item
-- `active_color` - text color of the active item
-- `flow` - `:l2r` or `:t2b`
-- `separator` - string used to separate items in the list, e.g. `", "` for a horizontal list or `"----"` for a vertical list
-- `viewport_size` - number of characters of the viewport in the flow direction
-
-**Example**
-
-```ruby
-WhirledPeas.template do |composer, settings|
-  WhirledPeas.component(composer, settings, :list_with_active) do |component|
-    component.items = %w[red orange yellow green blue indigo violet]
-    component.separator = ', '
-    component.active_index = active
-    component.viewport_size = 27
-    component.active_color = :blue
-    component.active_bg_color = :bright_yellow
-  end
-end
-```
-
-#### Settings
-
-Each element type has an associated settings type, which provide a custom set of options to format the output. Child settings will inherit from the parent, where applicable. The table below lists all settings along with which element types the settings can be applied to (`Grid` and `Box` are containers)
-
-| Setting         | Description                                                                      | Default    | Availability | Inherited            |
-| --------------- | -------------------------------------------------------------------------------- | ---------- | ------------ | -------------------- |
-| `align`         | Justifies the content in the horizontal direction                                | `:left`    | containers   | No                   |
-| `axis_color`    | Color used to paint the axes of the graph (see [Colors](#colors))                |            | `Graph`      | No                   |
-| `bg_color`      | Background color (see [Colors](#colors))                                         |            | all          | Yes                  |
-| `bold`          | `true` makes the font bold                                                       | `false`    | all          | Yes                  |
-| `border`        | Set the border for the lements                                                   | none       | containers,  | Only style and color |
-| `color`         | Foreground text color (see [Colors](#colors))                                    |            | all          | Yes                  |
-| `flow`          | Flow to display child elements (see [Display Flow](#display-flow))               | `:l2r`     | containers   | No                   |
-| `height`        | Override the calculated height of an element's content area                      |            | all          | No                   |
-| `margin`        | Set the (left, top, right, bottom) margin of the element                         | `0`        | containers   | No                   |
-| `num_cols`      | Number of columns in the grid (must be set!)                                     |            | `Grid`       | No                   |
-| `padding`       | Set the (left, top, right, bottom) padding of the element                        | `0`        | containers   | No                   |
-| `content_start` | Set the (left, top, right, bottom) position of children                          | `0`        | containers   | No                   |
-| `scrollbar`     | Display a scroll bar for vertical or horizontal scrolling                        |            | `Box`        | No                   |
-| `sizing`        | Sizing model (`:content` or `:border`) used in conjunction with `width`/`height` | `:content` | `Box`        | No                   |
-| `title_font`    | Font used for "large" text (see [Large Text](#large-text), ignores `underline`)  |            | `Text`       | No                   |
-| `underline`     | `true` underlines the font                                                       | `false`    | all          | Yes                  |
-| `width`         | Override the calculated width of an element's content area                       |            | all          | No                   |
-| `valign`        | Justifies the content in the vertical direction                                  | `:top`     | containers   | No                   |
-
-##### Themes
-
-The template builder (`WhirledPeas.template`) takes an optional `theme` argument. You can provide the name of a predefined theme (run `whirled_peas themes` to see a list with samples) or define you own with the following
-You can define your own theme
-
-```ruby
-WhirledPeas.register_theme(:my_theme) do |theme|
-  theme.bg_color = :bright_white
-  theme.color = :blue
-  theme.border_color = :bright_green
-  theme.axis_color = :bright_red
-  theme.title_font = :default
-end
-```
-
-Theme settings will be used as default settings throughout the template, however theme settings can be overridden on any element.
-
-##### Alignment
-
-The `align` setting takes one of several values
-
-- `:left` - align content starting at the leftmost edge of the container's content area
-
-```
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃[child 1][child 2][child 3]            ┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-
-- `:right` - align content starting at the rightmost edge of the container's content area
-
-```
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃            [child 1][child 2][child 3]┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-
-- `:center` - align content starting in the horizontal center of the container's content area
-
-```
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃      [child 1][child 2][child 3]      ┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-
-- `:between` - distribute children so there is equal space between children no space outside of the children
-
-```
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃[child 1]      [child 2]      [child 3]┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-
-- `:around` - distribute children so that they have equal spacing around them, space between two children is twice the space between an edge and a child.
-
-```
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃  [child 1]    [child 2]    [child 3]  ┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-
-- `:evenly` - distribute children so there is even spacing between any two children (or space to the edge)
-
-```
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃   [child 1]   [child 2]   [child 3]   ┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-```
-
-The `valign` setting takes one of several values
-
-- `:top` - align content starting at the top of the container's content area
-
-```
-┏━━━━━━━━━┓
-┃[child 1]┃
-┃[child 2]┃
-┃[child 3]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┗━━━━━━━━━┛
-```
-
-- `:bottom` - align content starting at the bottom of the container's content area
-
-```
-┏━━━━━━━━━┓
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 1]┃
-┃[child 2]┃
-┃[child 3]┃
-┗━━━━━━━━━┛
-```
-
-- `:middle` - align content starting in the vertical middle of the container's content area
-
-```
-┏━━━━━━━━━┓
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 1]┃
-┃[child 2]┃
-┃[child 3]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┗━━━━━━━━━┛
-```
-
-- `:between` - distribute children so there is equal space between children no space outside of the children
-
-```
-┏━━━━━━━━━┓
-┃[child 1]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 2]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 3]┃
-┗━━━━━━━━━┛
-```
-
-- `:around` - distribute children so that they have equal spacing around them, space between two children is twice the space between an edge and a child.
-
-```
-┏━━━━━━━━━┓
-┃         ┃
-┃         ┃
-┃[child 1]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 2]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 3]┃
-┃         ┃
-┃         ┃
-┗━━━━━━━━━┛
-```
-
-- `:evenly` - distribute children so there is even spacing between any two children (or space to the edge)
-
-```
-┏━━━━━━━━━┓
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 1]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 2]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┃[child 3]┃
-┃         ┃
-┃         ┃
-┃         ┃
-┗━━━━━━━━━┛
-```
-
-##### Content Start
-
-Content start settings dictate the relative position from the content area where the children will get painted. Positive values for `left`/`top` result in moving the children leftward/downward, negative values shift children rightward/upward. Setting `right` or `bototm` will result in the end of the children to be painted relative to the right/bottom of the content area.
-
-To set these values, use
-
-- `set_content_start(left:, top:, right:, bottom:)`
-- `content_start.left=`
-- `content_start.top=`
-- `content_start.right=`
-- `content_start.bottom=`
-
-Note: setting `left` and `right` or `top` and `bottom` is not supported
-
-##### Sizing Model
-
-The sizing model determines how to interpret the `width` and `height` settings. The default sizing model is `:content`, which sets the width and height of the cotent area, whereas `:border` sets the width and height of the element inlcuding the padding and border and scroll bars.
-
-###### Examples
-
-In the examples below, the `~` character represents padding and would not be displayed in the acutal rendered screen.
-
-```ruby
-settings.width = 10
-settings.height = 3
-settings.set_padding(left: 3, top: 1, right: 3, bottom: 1)
-settings.full_border
-
-## Content sizing
-settings.sizing = :content
-
-# Results in the box
-#
-#   ┏━━━━━━━━━━━━━━━━┓
-#   ┃~~~~~~~~~~~~~~~~┃
-#   ┃~~~1234567890~~~┃
-#   ┃~~~1234567890~~~┃
-#   ┃~~~1234567890~~~┃
-#   ┃~~~~~~~~~~~~~~~~┃
-#   ┗━━━━━━━━━━━━━━━━┛
-
-## Border sizing
-settings.sizing = :border
-
-# Results in the box
-#
-#   ┏━━━━━━━━┓
-#   ┃~~~12~~~┃
-#   ┗━━━━━━━━┛
-```
-
-Notice that a box rendered with `:border` sizing would fit exactly in the content area of a box with the same `width` and `height` that is rendered with `:content` sizing. For containers with no padding and no border, the resulting size is the same for either sizing model.
-
-##### Margin
-
-Margin settings dictate the spacing on the outside (i.e. outside of the border) of each of the 4 sides of the container independently. To set these values, use
-
-- `set_margin(left:, top:, right:, bottom:, horiz:, vert:)` - set any combination of margin (note: setting `horiz` and `left`/`right` or setting `vert` and `top`/`bottom` is not allowed)
-- `margin.left=(value)` - set left margin
-- `margin.top=(value)` - set top margin
-- `margin.right=(value)` - set right margin
-- `margin.bottom=(value)` - set bottom margin
-- `margin.horiz=(value)` - set left and right margin to the same value
-- `margin.vert=(value)` - set top and bottom margin to the same value
-
-Note: values cannot be negative
-
-##### Padding
-
-Padding settings dictate the spacing on the inside (i.e. inside of the border) of each of the 4 sides of the container independently. To set these values, use
-
-- `set_padding(left:, top:, right:, bottom:, horiz:, vert:)` - set any combination of padding (note: setting `horiz` and `left`/`right` or setting `vert` and `top`/`bottom` is not allowed)
-- `padding.left=(value)` - set left padding
-- `padding.top=(value)` - set top padding
-- `padding.right=(value)` - set right padding
-- `padding.bottom=(value)` - set bottom padding
-- `padding.horiz=(value)` - set left and right padding to the same value
-- `padding.vert=(value)` - set top and bottom padding to the same value
-
-Note: values cannot be negative
-
-##### Scrollbar
-
-Scroll settings dictate whether the scrollbar will be shown when child content is larger the the container's viewport. A scrollbar adds a unit to the dimensions of a container (as opposed to overwriting the leftmost/bottommost padding)
-
-- `set_scrollbar(horiz:, vert:)` - set both scrollbar settings
-- `scrollbar.horiz=(flag)` - show/hide the horizontal scrollbar
-- `scrollbar.vert=(flag)` - show/hide the vertical scrollbar
-
-Note: there is a know bug with scrollbars and `center`/`right` alignments. Using `left` alignment is the supported workaround
-
-##### Border
-
-The border settings consist of 6 boolean values (border are either width 1 or not shown), the 4 obvious values (`left`, `top`, `right`, and `bottom`) along with 2 other values for inner borders (`inner_horiz` and `inner_vert`) in a grid. A border also has a foreground color (defaults to `:white`) and a style. The background color is determined by the `bg_color` of the element. Border values can be set with
-
-- `set_border(left:, top:, right:, bottom:, inner_horiz:, inner_vert:, color:, style:)` - set any combination of border settings
-- `full_border(style:, color:)` - set all borders to true and optionally set the style or color
-- `border.left=(flag)` - show/hide left border
-- `border.top=(flag)` - show/hide top border
-- `border.right=(flag)` - show/hide right border
-- `border.bottom=(flag)` - show/hide bottom border
-- `border.inner_horiz=(flag)` - show/hide inner horizontal border (dividing grid rows)
-- `border.inner_vert=(flag)` - show/hide inner vertical border (dividing grid columns)
-- `border.color=(text_color)` - set the border color
-- `border.style=(style)` - set the border style
-
-Available border styles are
-
-- `:bold` (default)
-
-```
-┏━━┳━━┓
-┃  ┃  ┃
-┣━━╋━━┫
-┃  ┃  ┃
-┗━━┻━━┛
-```
-
-- `:double`
-
-```
-╔══╦══╗
-║  ║  ║
-╠══╬══╣
-║  ║  ║
-╚══╩══╝
-```
-
-- `:soft`
-
-```
-╭──┬──╮
-│  │  │
-├──┼──┤
-│  │  │
-╰──┴──╯
-```
-
-##### Display Flow
-
-Child elements can flow in one of 4 directions
-
-- `:l2r` left-to-right
-
-```
-# In a Box
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃[child 1] [child 2] ... [child N]┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-
-# In a Grid
-┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
-┃[child 1]┃[child 2]┃[child 3]┃
-┣━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━┫
-┃[chiid 4]┃[child 5]┃         ┃
-┗━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━┛
-```
-
-- `:r2l` right-to-left
-
-```
-# In a Box
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃[child N] [child N - 1] ... [child 1]┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
-
-# In a Grid
-┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
-┃[child 3]┃[child 2]┃[child 1]┃
-┣━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━┫
-┃         ┃[chiid 5]┃[child 4]┃
-┗━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━┛
-```
-
-- `:t2b` top-to-bottom
-
-```
-# In a Box
-┏━━━━━━━━━┓
-┃[child 1]┃
-┃[child 2]┃
-┃ ...     ┃
-┃[child N]┃
-┗━━━━━━━━━┛
-
-# In a Grid
-┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
-┃[child 1]┃[child 3]┃[child 5]┃
-┣━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━┫
-┃[child 2]┃[child 4]┃         ┃
-┗━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━┛
-```
-
-- `:b2t` bottom-to-top
-
-```
-# In a Box
-┏━━━━━━━━━━━━━┓
-┃[child N]    ┃
-┃[child N - 1]┃
-┃ ...         ┃
-┃[child 1]    ┃
-┗━━━━━━━━━━━━━┛
-
-# In a Grid
-┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
-┃[child 2]┃[child 4]┃         ┃
-┣━━━━━━━━━╋━━━━━━━━━╋━━━━━━━━━┫
-┃[child 1]┃[child 3]┃[child 5]┃
-┗━━━━━━━━━┻━━━━━━━━━┻━━━━━━━━━┛
-```
-
-##### Colors
-
-Below is the list of available colors (for both foreground and background)
-
-- `:black`
-- `:blue`
-- `:cyan`
-- `:gray`
-- `:green`
-- `:magenta`
-- `:red`
-- `:white`
-- `:yellow`
-
-Many of these also have a "bright" option:
-
-- `:bright_blue`
-- `:bright_cyan`
-- `:bright_green`
-- `:bright_magenta`
-- `:bright_red`
-- `:bright_yellow`
-
-##### Large Text
-
-The `title_font` setting for `Text`s converts the standard terminal font into a large block font. The available fonts vary from system to system. Every system will have a `:default` font available, this font could look like
-
-```
-██████╗ ███████╗███████╗ █████╗ ██╗   ██╗██╗     ████████╗
-██╔══██╗██╔════╝██╔════╝██╔══██╗██║   ██║██║     ╚══██╔══╝
-██║  ██║█████╗  █████╗  ███████║██║   ██║██║        ██║
-██║  ██║██╔══╝  ██╔══╝  ██╔══██║██║   ██║██║        ██║
-██████╔╝███████╗██║     ██║  ██║╚██████╔╝███████╗   ██║
-╚═════╝ ╚══════╝╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝
-```
-
-To print out a list of all available fonts as well as sample text in that font, run
-
-```
-$ whirled_peas title_fonts
-```
-
-Note: when using a title font with WhirledPeas for the first time on a system, the gem loads all fonts to check which ones are available. This can be a slow process and may cause a noticeable delay when running a visualization. Running the command above will cache the results and thus when a WhirledPeas visualization is run, there will be no lag from loading fonts.
-
-#### Easing
-
-The play duration of a frame within a frameset is determined by the easing function and effect along with the frames relative position within the frameset. The three effects are
-
-- `:in` - apply easing only to the start of the frameset
-- `:out` - apply easing only to the end of the frameset
-- `:in_out` - apply easing to the start and end of the frameset
-
-The available easing functions are
-
-- `:bezier`
-
-```
-# bezier (in)
-┃                                                         ▄▀
-┃                                                      ▄▄▀
-┃                                                    ▄▀
-┃                                                 ▄▀▀
-┃                                              ▄▄▀
-┃                                           ▄▄▀
-┃                                        ▄▄▀
-┃                                      ▄▀
-┃                                  ▄▄▀▀
-┃                               ▄▄▀
-┃                            ▄▀▀
-┃                        ▄▄▀▀
-┃                   ▄▄▀▀▀
-┃             ▄▄▄▀▀▀
-┃▄▄▄▄▄▄▄▄▄▄▀▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-# bezier (out)
-┃                                               ▄▄▄▀▀▀▀▀▀▀▀▀
-┃                                         ▄▄▄▀▀▀
-┃                                    ▄▄▄▀▀
-┃                                ▄▄▀▀
-┃                             ▄▄▀
-┃                          ▄▀▀
-┃                      ▄▄▀▀
-┃                    ▄▀
-┃                 ▄▀▀
-┃              ▄▀▀
-┃           ▄▀▀
-┃        ▄▄▀
-┃      ▄▀
-┃   ▄▀▀
-┃▄▄▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-# bezier (in_out)
-┃                                                  ▄▄▄▀▀▀▀▀▀
-┃                                              ▄▄▀▀
-┃                                           ▄▀▀
-┃                                        ▄▀▀
-┃                                     ▄▀▀
-┃                                  ▄▀▀
-┃                               ▄▄▀
-┃                             ▄▀
-┃                          ▄▀▀
-┃                       ▄▄▀
-┃                    ▄▄▀
-┃                 ▄▄▀
-┃              ▄▄▀
-┃          ▄▄▀▀
-┃▄▄▄▄▄▄▄▀▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-`:linear`
-
-```
-# linear (in)
-┃                                                        ▄▄▀
-┃                                                    ▄▄▀▀
-┃                                                ▄▄▀▀
-┃                                            ▄▄▀▀
-┃                                        ▄▄▀▀
-┃                                    ▄▄▀▀
-┃                                ▄▄▀▀
-┃                            ▄▄▀▀
-┃                        ▄▄▀▀
-┃                    ▄▄▀▀
-┃                ▄▄▀▀
-┃            ▄▄▀▀
-┃        ▄▄▀▀
-┃    ▄▄▀▀
-┃▄▄▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-# linear (out)
-┃                                                        ▄▄▀
-┃                                                    ▄▄▀▀
-┃                                                ▄▄▀▀
-┃                                            ▄▄▀▀
-┃                                        ▄▄▀▀
-┃                                    ▄▄▀▀
-┃                                ▄▄▀▀
-┃                            ▄▄▀▀
-┃                        ▄▄▀▀
-┃                    ▄▄▀▀
-┃                ▄▄▀▀
-┃            ▄▄▀▀
-┃        ▄▄▀▀
-┃    ▄▄▀▀
-┃▄▄▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-# linear (in_out)
-┃                                                        ▄▄▀
-┃                                                    ▄▄▀▀
-┃                                                ▄▄▀▀
-┃                                            ▄▄▀▀
-┃                                        ▄▄▀▀
-┃                                    ▄▄▀▀
-┃                                ▄▄▀▀
-┃                            ▄▄▀▀
-┃                        ▄▄▀▀
-┃                    ▄▄▀▀
-┃                ▄▄▀▀
-┃            ▄▄▀▀
-┃        ▄▄▀▀
-┃    ▄▄▀▀
-┃▄▄▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-`:parametric`
-
-```
-# parametric (in)
-┃                                                          ▄
-┃                                                        ▄▀
-┃                                                      ▄▀
-┃                                                   ▄▄▀
-┃                                                 ▄▀
-┃                                               ▄▀
-┃                                             ▄▀
-┃                                          ▄▄▀
-┃                                        ▄▀
-┃                                     ▄▀▀
-┃                                  ▄▀▀
-┃                              ▄▄▀▀
-┃                         ▄▄▄▀▀
-┃                   ▄▄▄▄▀▀
-┃▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀▀▀▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-# parametric (out)
-┃                                         ▄▄▄▄▄▀▀▀▀▀▀▀▀▀▀▀▀▀
-┃                                   ▄▄▀▀▀▀
-┃                              ▄▄▀▀▀
-┃                          ▄▄▀▀
-┃                       ▄▄▀
-┃                    ▄▄▀
-┃                  ▄▀
-┃               ▄▀▀
-┃             ▄▀
-┃           ▄▀
-┃         ▄▀
-┃      ▄▀▀
-┃    ▄▀
-┃  ▄▀
-┃▄▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-# parametric (in_out)
-┃                                               ▄▄▄▀▀▀▀▀▀▀▀▀
-┃                                           ▄▄▀▀
-┃                                        ▄▀▀
-┃                                     ▄▄▀
-┃                                   ▄▀
-┃                                 ▄▀
-┃                               ▄▀
-┃                             ▄▀
-┃                           ▄▀
-┃                         ▄▀
-┃                       ▄▀
-┃                    ▄▀▀
-┃                 ▄▄▀
-┃             ▄▄▀▀
-┃▄▄▄▄▄▄▄▄▄▄▀▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-`:quadratic`
-
-```
-# quadratic (in)
-┃                                                         ▄▄
-┃                                                       ▄▀
-┃                                                     ▄▀
-┃                                                   ▄▀
-┃                                                 ▄▀
-┃                                              ▄▀▀
-┃                                            ▄▀
-┃                                         ▄▀▀
-┃                                      ▄▀▀
-┃                                   ▄▀▀
-┃                               ▄▄▀▀
-┃                           ▄▄▀▀
-┃                      ▄▄▄▀▀
-┃                ▄▄▄▀▀▀
-┃▄▄▄▄▄▄▄▄▄▄▄▀▀▀▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-# quadratic (out)
-┃                                            ▄▄▄▄▄▀▀▀▀▀▀▀▀▀▀
-┃                                      ▄▄▄▀▀▀
-┃                                 ▄▄▀▀▀
-┃                             ▄▄▀▀
-┃                         ▄▄▀▀
-┃                      ▄▄▀
-┃                   ▄▄▀
-┃                ▄▄▀
-┃              ▄▀
-┃           ▄▄▀
-┃         ▄▀
-┃       ▄▀
-┃     ▄▀
-┃   ▄▀
-┃▄▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-# quadratic (in_out)
-┃                                                 ▄▄▄▀▀▀▀▀▀▀
-┃                                            ▄▄▀▀▀
-┃                                         ▄▀▀
-┃                                      ▄▀▀
-┃                                   ▄▄▀
-┃                                 ▄▀
-┃                               ▄▀
-┃                             ▄▀
-┃                           ▄▀
-┃                         ▄▀
-┃                      ▄▀▀
-┃                   ▄▄▀
-┃                ▄▄▀
-┃           ▄▄▄▀▀
-┃▄▄▄▄▄▄▄▄▀▀▀
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Full template example
-
-```ruby
-class TemplateFactory
-  def build(frame, args)
-    set_state(frame, args)
-    WhirledPeas.template do |composer, settings|
-      settings.flow = :l2r
-      settings.align = :center
-
-      composer.add_box('Title', &method(:title))
-      composer.add_box('Sum', &method(:sum))
-      composer.add_grid('NumberGrid', &method(:number_grid))
-    end
-  end
-
-  private
-
-  def set_state(frame, args)
-    @frame = frame
-    @numbers = args.key?(:numbers) ? args[:numbers] || []
-    @sum = args[:sum] if args.key?(:sum)
-    @low = args[:low] if args.key?(:low)
-    @high = args[:high] if args.key?(:high)
-  end
-
-  def title(_composer, settings)
-    settings.underline = true
-    "Pair Finder"
-  end
-
-  def sum(_composer, settings)
-    settings.color = @frame == 'found-pair' ? :green : :red
-    @sum ? "Sum: #{@sum}" : 'N/A'
-  end
-
-  def number_grid(composer, settings)
-    settings.full_border
-    @numbers.each.with_index do |num, index|
-      composer.add_text do |_, settings|
-        settings.bg_color = (@low == index || @high == index) ? :cyan : :white
-        num
-      end
-    end
-  end
-end
-```
-
-### Full usage
-
-```
-Usage: whirled_peas <command> [command options]
-
-Available commands:
-
-    debug     Print template tree for specified frame
-    fonts     List installed title fonts with sample text
-    frames    Print out list of frames generated by application
-    help      Show detailed help for a command
-    play      Play an animation from an application or prerecorded file
-    record    Record animation to a file
-    still     Show the specified still frame
-    themes    List all themes with sample template rendered in the theme
-```
-
-#### `debug`
-
-Print the template tree for specified frame.
-
-```
-# Usage: whirled_peas debug <config file> <frame> [args as a JSON string]
-% whirled_peas debug my_app.rb greeting '{"name":"World"}'
-* WhirledPeas::Graphics::BoxPainter(TEMPLATE)
-  - Dimensions(outer=140x27, content=120x15, grid=1x1)
-  - Settings
-    WhirledPeas::Settings::BoxSettings
-      padding: Padding(left: 10, top: 6, right: 10, bottom: 6)
-      align: :center
-      width: 120
-      flow: :t2b
-      bold: true
-      bg_color: BgColor(code=107, bright=true)
-  - Children
-    * WhirledPeas::Graphics::BoxPainter(Element-1)
-      - Dimensions(outer=64x6, content=64x6, grid=1x1)
-```
-
-#### `fonts`
-
-List all installed title fonts with sample text.
-
-```
-# Usage: whirled_peas fonts
-```
-
-#### `frames`
-
-Print out list of frames generated by application.
-
-```
-# Usage: whirled_peas frames <config file>
-% whirled_peas frames my_app.rb
-Frame 'intro' displayed for 3 second(s) '{"title":"Foo"}'
-Frame 'greet' displayed for 0.3 second(s)
-...
-```
-
-#### `help`
-
-Print out command-specific help message
-
-```
-Usage: whirled_peas help <command>
-```
-
-#### `play`
-
-Play an animation from an application or prerecorded file
-
-```
-# Usage: whirled_peas play <config/wpz file>
-
-# Play animation directly from app
-% whirled_peas play my_app.rb
-# Animation plays
-
-# Play animation from previously recorded file
-% whirled_peas play my_animation.wpz
-# Animation plays
-```
-
-#### `record`
-
-Record animation to a file
-
-```
-# Usage: whirled_peas record <config file> <output file>
-% whirled_peas record my_app.rb my_animation.wpz
-# Record animation to my_animation.wpz
-```
-
-#### `still`
-
-Show the specified still frame
-
-```
-# Usage: whirled_peas still <config file> <frame> [args as a JSON string]
-% whirled_peas still my_app.rb greeting '{"name":"World"}'
-# Still frame is displayed
-```
-
-#### `themes`
-
-List all themes and display a small sample screen in each. Running this with no extra command line arguments will display all the built-in themes. Adding the path to a Whirled Peas configuration file will inlcude any themes defined in that configuration.
-
-```
-# Usage: whirled_peas themes [config file]
-% whirled_peas themes
-# Display all system themes
-
-% whirled_peas themes my_app.rb
-# Display app-defined themes and all system themes
-```
-
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-### Testing
-
-In addition to standard RSpec tests, WhirledPeas has custom tests for rendered templates. These files live in `screen_test/`. Each ruby file is expected to define a class named `TemplateFactory` that responds to `#build(name, args)` returning a template (the standard template factory role). Each file should also be accompanied by a `.frame` file with the same base name. This file will contain the output of the rendered screen and is considered the correct output when running tests.
-
-Note: viewing `.frame` files with `cat` works better than most other text editors.
-
-```
+Tests inclued standard RSpec tests for application logic as well as custom [screen tests](doc/screen_test.md) to validate the rendered graphics.
 
-Usage: screen_test [file] [options]
-
-If not file or options are provide, all tests are run
-
-If no file is provided, the supported options are
-    --help             print this usage statement and exit
-    --view-pending     interactively display and optionally save rendered output for each pending test
-    --view-failed      interactively display and optionally save rendered output for each faiing test
-
-If a screen test file is provided as the first argument, the supported options are
-    --run        run screen test for given file
-    --view       interactively display and optionally save the file's test output
-    --template   print out template tree for the test template
-    --debug      render the test template without displying it, printing out debug information
-```
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing