whirled_peas 0.7.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ddf23151c866304cbe5213073c9ac9bd3c7b17139737acf1fe2f6678e6248f
-  data.tar.gz: 31d26322b45af3d06c2f64c019fde32cebfe87638852c87857fa0113dc3bdc11
+  metadata.gz: 7f73ce3a27741b9c790785fe5aad7179c6db66e045ca1c2e43af33887c1fd4d9
+  data.tar.gz: bd19233e2d81a2d4e985bc4c8b0ec3ec07b8fe4691f0c70c5a2374add780bc9b
 SHA512:
-  metadata.gz: 7be414e153881ff228f8780e11887be61844d1f719c1b19d50888cf7c2caf3d2171dd992c6694604672209f5e7457b35eebba7498dd60bb1d21e717c467f0a6c
-  data.tar.gz: d27958378cfd0fe6728ef547559f07258ecafb2481df0d1994d3cf13802ae14ad414c212d2186f8e36ecb00be608d8abc3c6ccb918109a0114cc9585ed431735
+  metadata.gz: 9c2a41a72c30eb2c96161c23bb4f47a37dd9052ca1206cdec2d714d3266b0a6e3eb58bc8dab0dea0517eaf1fe7c5743323a8a7579319e81fdce80b9d65992504
+  data.tar.gz: 1b120aa9b5327880dcdcffbb37cfb77b63a06be55089f77efe7c4da104ce36e65893412178b5efcc31d6f7a3b9aed8353bbe076ea0131f52a142910d251bc61f

data/.gitignore

@@ -11,4 +11,5 @@ Gemfile.lock
 
 # rspec failure tracking
 .rspec_status
+*.wpz
 

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## v0.11.0 - 2021-01-30
+
+- [c1f3d94](https://github.com/tcollier/whirled_peas/tree/c1f3d944a35305c3032681db13ffd6142a7e19e4): Add component support
+
+## v0.10.0 - 2021-01-29
+
+- [3063a2b](https://github.com/tcollier/whirled_peas/tree/3063a2becb7680b5e320a1733b3da933e6c65210): Add built-in and user-defined themes
+
+## v0.9.1 - 2021-01-29
+
+- [c35b134](https://github.com/tcollier/whirled_peas/tree/c35b134e1340b8b5f1d1fb0e6e56dc2a99b52e94): Improve graph plots
+
+## v0.9.0 - 2021-01-29
+
+BREAKING: `Frameset#add_frame` signature changed
+
+- [1c28947](https://github.com/tcollier/whirled_peas/tree/1c28947980eedce034d2596732ee4860717904c5): Add graph support
+
+## v0.8.0 - 2021-01-29
+
+BREAKING: `Producer` now responds to `#add_frame` instead of `#send_frame`
+
+- [67fdc17](https://github.com/tcollier/whirled_peas/tree/67fdc172434cb97f31ca20a674f28aefec6babb3): Add easing functions for frame transitions
+- [b888f2e](https://github.com/tcollier/whirled_peas/tree/b888f2e7a3b7c3341300326b417641cc8cf2e89b): Add record and playback functionality to command line tool
+
 ## v0.7.1 - 2021-01-27
 
 - [b98781d](https://github.com/tcollier/whirled_peas/tree/b98781de23a24b596955f25cfc48936c0cc1efac): Fix num_cols bug for vertical grid flow

data/README.md

@@ -18,7 +18,7 @@
      ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝╚══════╝╚══════╝╚═════╝    ╚═╝     ╚══════╝╚═╝  ╚═╝╚══════╝
 ```
 
-Easily create terminal-based graphics to visual the execution of your code. Whirled Peas offers templating inspired by HTML and CSS and provides a lightweight tie-in for your code to produce visual animations with these templates.
+Easily create terminal-based graphics to visualize the execution of your code. Whirled Peas offers templating inspired by HTML and CSS and provides a lightweight tie-in for your code to produce visual animations with these templates.
 
 ## Installation
 
@@ -40,9 +40,8 @@ Or install it yourself as:
 
 A Whirled Peas application consists of the following pieces
 
-- The driver (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 driver into terminal graphics
-- A loading screen template factory (optional) - builds templates to display while content is loading
+- 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
 
 These pieces are configured as following
 
@@ -62,15 +61,15 @@ class TemplateFactory
   end
 end
 
-class Driver
+class Application
   def start(producer)
-    producer.send_frame('starting', args: { name: 'World' })
+    producer.add_frame('starting', args: { name: 'World' })
     # ...
   end
 end
 
 WhirledPeas.configure do |config|
-  config.driver = Driver.new
+  config.application = Application.new
   config.template_factory = TemplateFactory.new
 end
 ```
@@ -78,54 +77,64 @@ end
 Then the visualizer is started on the command line with
 
 ```
-$ whirled_peas start visualize.rb
+$ whirled_peas play visualize.rb
 ```
 
-The optional loading screen can be configured like
+### Application
 
-```ruby
-class LoadingTemplateFactory
-  def build
-    WhirledPeas.template do |composer|
-      composer.add_box('Loading') do |_, settings|
-        settings.set_margin(top: 15)
-        settings.align = :center
-        settings.full_border(color: :blue, style: :double)
-        "Loading..."
-      end
-    end
-  end
-end
+The application is code to be visualized that integrates with Whirled Peas by providing the signature below
 
-WhirledPeas.configure do |config|
-  # ...
-  config.loading_template_factory = LoadingTemplateFactory.new
+```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
 ```
 
-### Driver
-
-The driver is the application code to be visualized. This is typically a lightweight wrapper around an existing application that conforms to the signature below.
+The producer provides the following methods
 
 ```ruby
-# Start the application and pass frame events to the producer to be rendered by the UI
+# Add a frame to be displayed
 #
-# @param producer [Producer] frame producer that sends events to the UI
-def start(producer)
-  # application code here
+# @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
 ```
 
-The producer provides a single method
+A frameset instance provides one method
 
 ```ruby
-# Send frame events to the UI
+# 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] application defined name for the frame. The template factory will be provided this name
-# @param duration [Number] time in seconds this frame should be displayed for (defaults to 1 frame)
-# @param args [Hash<Symbol, Object>] key value pairs to send as arguments to the template factory
-def send_frame(name, duration:, args:)
-  # implementation
+# @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
 ```
 
@@ -136,39 +145,35 @@ end
 Simple application that loads a set of numbers and looks for a pair that adds up to 1,000
 
 ```ruby
-class Driver
+class Application
   def start(producer)
     numbers = File.readlines('/path/to/numbers.txt').map(&:to_i)
-    producer.send_frame('load-numbers', duration: 3, args: { numbers: numbers })
+    producer.add_frame('load-numbers', duration: 3, args: { numbers: numbers })
     numbers.sort!
-    producer.send_frame('sort-numbers', duration: 3, args: { numbers: numbers })
+    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.send_frame('found-pair', duration: 5, args: { low: low, high: high, sum: sum })
+        producer.add_frame('found-pair', duration: 5, args: { low: low, high: high, sum: sum })
         return
       elsif sum < 1000
-        producer.send_frame('too-low', args: { low: low, high: high, sum: sum })
+        producer.add_frame('too-low', args: { low: low, high: high, sum: sum })
         low += 1
       else
-        producer.send_frame('too-high', args: { low: low, high: high, sum: sum })
+        producer.add_frame('too-high', args: { low: low, high: high, sum: sum })
         high -= 1
       end
     end
-    producer.send_frame('no-solution', duration: 5)
+    producer.add_frame('no-solution', duration: 5)
   end
 end
 ```
 
 ### Template Factory
 
-To render the frame events sent by the driver, 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 driver. 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.
-
-#### Loading Template Factory
-
-`WhirledPeas.configure` takes an optional template factory to build a loading screen. This instance must implement `#build` (taking no arguments). The template returned by that method will be painted while the event loop is waiting for frames. The factory method will be called once per refresh cycle, so it's possible to implement animation.
+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
 
@@ -182,6 +187,7 @@ A template is created with `WhirledPeas.template`, which yields a `Composer` obj
 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
 
@@ -239,30 +245,103 @@ template.add_box do
 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 available settigs are
-
-| Setting      | Description                                                                      | Default    | Availability          | Inherited            |
-| ------------ | -------------------------------------------------------------------------------- | ---------- | --------------------- | -------------------- |
-| `align`      | Justifies the content in the horizontal direction                                | `:left`    | `Box`, `Grid`         | No                   |
-| `bg_color`   | Background color (see [Colors](#colors))                                         |            | `Box`, `Grid`, `Text` | Yes                  |
-| `bold`       | `true` makes the font bold                                                       | `false`    | `Box`, `Grid`, `Text` | Yes                  |
-| `border`     | Set the border for the lements                                                   | none       | `Box`, `Grid`,        | Only style and color |
-| `color`      | Foreground text color (see [Colors](#colors))                                    |            | `Box`, `Grid`, `Text` | Yes                  |
-| `flow`       | Flow to display child elements (see [Display Flow](#display-flow))               | `:l2r`     | `Box`, `Grid`         | No                   |
-| `height`     | Override the calculated height of an element's content area                      |            | `Box`, `Grid`         | No                   |
-| `margin`     | Set the (left, top, right, bottom) margin of the element                         | `0`        | `Box`, `Grid`         | 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`        | `Box`, `Grid`         | No                   |
-| `position`   | Set the (left, top) position of the element relative to parent content area      | `0`        | `Box`, `Grid`         | No                   |
-| `scrollbar`  | Display a scroll bar for vertical or horizontal scrolling                        |            | `Box`                 | No                   |
-| `sizing`     | Sizing model (`:content` or `:border`) used in conjunction with `width`/`hieght` | `: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`    | `Box`, `Grid`, `Text` | Yes                  |
-| `width`      | Override the calculated width of an element's content area                       |            | `Box`, `Grid`         | No                   |
-| `valign`     | Justifies the content in the vertical direction                                  | `:top`     | `Box`, `Grid`         | No                   |
+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
 
@@ -450,11 +529,19 @@ The `valign` setting takes one of several values
 ┗━━━━━━━━━┛
 ```
 
-##### Position
+##### 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.
 
-Position settings dictate the relative position from where the painter would have preferred to place the container. Negative numbers move the container left/up and positive numbers move it right/down. To set these values, use
+To set these values, use
 
-- `set_position(left:, top:)`
+- `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
 
@@ -698,7 +785,265 @@ $ 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.
 
-### Example
+#### 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
@@ -746,64 +1091,120 @@ class TemplateFactory
 end
 ```
 
-### Debugging
+### Full usage
+
+```
+Usage: whirled_peas <command> [command options]
+
+Available commands:
 
-The `whirled_peas` executable provides some commands that are helpful for debugging.
+    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
+```
 
-#### list_frames
+#### `debug`
 
-List the frames sent by the driver
+Print the template tree for specified frame.
 
 ```
-$ whirled_peas <config file> list_frames
-Frame 'start' displayed for 5 second(s)
-Frame 'move' displayed for 1 frame ({:direction=>'N'})
-...
-EOF frame detected
+# 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)
 ```
 
-#### play_frame
+#### `fonts`
 
-Displays a single frame for several seconds
+List all installed title fonts with sample text.
 
 ```
-$ whirled_peas <config file> play_frame move '{"direction":"N"}'
+# Usage: whirled_peas fonts
 ```
 
-Adding the `--template` flag will result in printing out debug information for the template, e.g.
+#### `frames`
+
+Print out list of frames generated by application.
 
 ```
-$ whirled_peas <config file> play_frame move '{"direction":"N"}' --template
-+ TEMPLATE [WhirledPeas::Graphics::BoxPainter]
-  - Settings
-    WhirledPeas::Settings::BoxSettings
-      <default>
-  - Children
-    + TitleContainer [WhirledPeas::Graphics::BoxPainter]
+# 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)
 ...
 ```
 
-Note: the `list_frames` command will print out frame names and arguments formatted for this command
+#### `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
+```
 
-#### loading
+#### `record`
 
-Displays the configured loading screen for several seconds
+Record animation to a file
 
 ```
-$ whirled_peas <config file> loading
+# Usage: whirled_peas record <config file> <output file>
+% whirled_peas record my_app.rb my_animation.wpz
+# Record animation to my_animation.wpz
 ```
 
-Adding the `--template` flag will result in just printing out the loading template's debug information, e.g.
+#### `still`
+
+Show the specified still frame
 
 ```
-$ whirled_peas <config file> loading --template
-+ TEMPLATE [WhirledPeas::Graphics::BoxPainter]
-  - Settings
-    WhirledPeas::Settings::BoxSettings
-      <default>
-  - Children
-    + TitleContainer [WhirledPeas::Graphics::BoxPainter]
-...
+# 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
@@ -814,23 +1215,31 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ### Testing
 
-In addition to standard RSpec tests, WhirledPeas has custom tests for rendered templates. These files live in `screen_test/rendered`. 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.
+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.
 
-The following rake tasks are provided to interact with the screen tests
+```
+
+Usage: screen_test [file] [options]
+
+If not file or options are provide, all tests are run
 
-- `screen_test` runs all screen tests in the `screen_test/rendered` directory
-- `screen_test:debug[path/to/file.rb]` render the screen without printing it, this allows for debug print statments in the code to appear in the terminal
-- `screen_test:template[path/to/file.rb]` print the rendered template debug tree
-- `screen_test:run[path/to/file.rb]` runs a single screen test
-- `screen_test:save[path/to/file.rb]` saves the output generated by the template in the `.frame` file, overwriting any existing file
-- `screen_test:view[path/to/file.rb]` views the output generated by the template
-- `screen_test:update_all[path/to/file.rb]` interactively step through each pending or failed screen test to compare/set the expected output
+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
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/whirled_peas. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/whirled_peas/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/tcollier/whirled_peas. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/tcollier/whirled_peas/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -838,4 +1247,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the WhirledPeas project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/whirled_peas/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the WhirledPeas project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/tcollier/whirled_peas/blob/master/CODE_OF_CONDUCT.md).