whirled_peas 0.9.1 → 0.13.0

data/doc/application.md

@@ -0,0 +1,92 @@
+## 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
+```
+
+See the [easing documentation](easing.md) for more details on the various easing functions.
+
+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
+```

data/doc/cli.md

@@ -0,0 +1,115 @@
+## 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
+```

data/doc/components.md

@@ -0,0 +1,51 @@
+## 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
+
+- `items` - the array of items to be displayed in the box
+
+#### Optional
+
+- `active_index` - the index of the active item, the item at the position will be highlighted and moved to the _preferred_ position. For items in the middle of a long list, the _preferred_ position is roughly 2/3rds to the way to the right in the viewport.
+- `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
+  end
+end
+```

data/doc/easing.md

@@ -0,0 +1,257 @@
+## Easing
+
+The duration that a frame within a frameset is displayed 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)
+┃                                                 ▄▄▄▀▀▀▀▀▀▀
+┃                                            ▄▄▀▀▀
+┃                                         ▄▀▀
+┃                                      ▄▀▀
+┃                                   ▄▄▀
+┃                                 ▄▀
+┃                               ▄▀
+┃                             ▄▀
+┃                           ▄▀
+┃                         ▄▀
+┃                      ▄▀▀
+┃                   ▄▄▀
+┃                ▄▄▀
+┃           ▄▄▄▀▀
+┃▄▄▄▄▄▄▄▄▀▀▀
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```