whirled_peas 0.1.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85262725d00d4055dceb88c2672afc6a7f5027626a3038998706b5d8e2d1a3aa
-  data.tar.gz: 15bc9278fd2945d0ea5cf6a5436ba11e00724e71f128ec487f5569c3689bfaeb
+  metadata.gz: 563cc06007d90aa0599b61c5366a5d9b2c5224ec2973367b6c358cad95ddaedc
+  data.tar.gz: fa798abdfb8a8e4fd229f08b964c8ee4f4d480939ece9ddaeb5731c171985504
 SHA512:
-  metadata.gz: 7270704f5ff2adc5d225dd7c612f489a968c9d5efc2fef399b65a8ad7320fcad2920ec355645f961744577df740efbfcf4947f477e13224702764bf64931a52b
-  data.tar.gz: a46f83016c3038275fccc907894c0ea7fc3ce0553c5da343d77fbfbbdf9f619ca169346e11b5862cf502e7785372a750a0ab668bfffb3198b1d529a75cd198a5
+  metadata.gz: 1be24e74d75f87a001b26f216e320d4a4680c48513e48c42047d2c2168a9404471704731df97ced5954facdc4ca7316580f6078db5670e45067c7e8ed3ee4cd3
+  data.tar.gz: 86f3b995575fc7ff8b6bb83adf368182a684faece1584cffb7b1150bd47ce082adaba5b0d4ce0b83d19d2ec2d795bd31db19d35c990e6d0065698c050161bcd0

data/.travis.yml

@@ -3,4 +3,6 @@ language: ruby
 cache: bundler
 rvm:
   - 2.6.6
+  - 2.7.2
+  - 3.0.0
 before_install: gem install bundler -v 2.1.4

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## v0.4.0 - 2021-01-22
+
+- [7fd6712](https://github.com/tcollier/whirled_peas/tree/7fd6712818c94cdbfd81828277ca67c705e01793): BREAKING: replace `WhirledPeas.start` with command line executable
+- [2535342](https://github.com/tcollier/whirled_peas/tree/25353424f1ab4af4880f44eb7ddd28afefbbb9b2): Add support for loading screen
+- [7388fc2](https://github.com/tcollier/whirled_peas/tree/7388fc2eacdc8045b725311c11d650d6b8654be8): Add support for title fonts
+- [b345155](https://github.com/tcollier/whirled_peas/tree/b345155b1c212cabe73f9a2562ac8dbbedbbb6df): Add command to list title fonts to executable
+- [d3a8324](https://github.com/tcollier/whirled_peas/tree/d3a832496c36985993217ff11b6d83dd4697c4ed): Add commands for debugging application to executable
+
+## v0.3.0 - 2021-01-21
+
+- [617f802](https://github.com/tcollier/whirled_peas/tree/617f8027d6688a2ec81a3e594e529c94485cee85): BREAKING: send frames directly to EventLoop (`Producer#send` renamed to `Producer#send_frame`)
+
+## v0.2.0 - 2021-01-20
+
+- [73eb326](https://github.com/tcollier/whirled_peas/tree/73eb326426f9814e91e3bc7a60dfd87be3d69f7e): Convert "primitive" data types to strings
+- [f28b69d](https://github.com/tcollier/whirled_peas/tree/f28b69df8b6cfc973da2ebc0b8da29b278f23433): Give elements names
+- [1ae1c929](https://github.com/tcollier/whirled_peas/tree/1ae1c929429c2f8520054d33a064c2b6d71955fe): Consistently format exceptions in logs
+- [4c2114f](https://github.com/tcollier/whirled_peas/tree/4c2114fd360fd98c65e6e32f905a377f09b919ee): Fix bug with negative sleep times
+- [627bf12](https://github.com/tcollier/whirled_peas/tree/627bf126dd7f9c845f65105e0826d14a35a0a953): Don't reraise pipe error
+
+## v0.1.1 - 2021-01-20
+
+- [3852c8c](https://github.com/tcollier/whirled_peas/tree/3852c8c700c2e8fb92e65bbca1c99be74304c6d0): Improve error handling
+
+## v0.1.0 - 2021-01-20
+
+- [f343434](https://github.com/tcollier/whirled_peas/tree/f34343458097da04d5846ab13533e8226ba04d75): Inaugural release

data/Gemfile

@@ -6,3 +6,4 @@ gemspec
 gem 'rake', '~> 12.0'
 gem 'rspec', '~> 3.0'
 gem 'pry-byebug'
+gem 'tty-cursor', '~> 0.7'

data/README.md

@@ -1,3 +1,5 @@
+[![Build Status](https://travis-ci.com/tcollier/whirled_peas.svg?branch=main)](https://travis-ci.com/tcollier/whirled_peas)
+
 # WhirledPeas
 
 Visualize your code's execution with Whirled Peas!
@@ -20,15 +22,24 @@ Or install it yourself as:
 
 ## Usage
 
+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
+
+These pieces are configured as following
+
 ```ruby
+# visualize.rb
 require 'whirled_peas'
 
 class TemplateFactory
   def build(frame, args)
     WhirledPeas.template do |body|
-      body.add_box do |_, settings|
+      body.add_box('Title') do |_, settings|
         settings.underline = true
-        "Hello #{args['name']}"
+        "Hello #{args[:name]}"
       end
       # ...
     end
@@ -37,18 +48,44 @@ end
 
 class Driver
   def start(producer)
-    producer.send('starting', args: { 'name' => 'World' })
+    producer.send_frame('starting', args: { name: 'World' })
     # ...
   end
 end
 
-WhirledPeas.start(Driver.new, TemplateFactory.new)
+WhirledPeas.configure do |config|
+  config.driver = Driver.new
+  config.template_factory = TemplateFactory.new
+end
 ```
 
-A Whirled Peas application consists of two pieces
+Then the visualizer is started on the command line with
+
+```
+$ whirled_peas start visualize.rb
+```
+
+The optional loading screen can be configured like
+
+```ruby
+class LoadingTemplateFactory
+  def build
+    WhirledPeas.template do |t|
+      t.add_box('Loading') do |box, settings|
+        settings.set_margin(top: 15)
+        settings.auto_margin = true
+        settings.full_border(color: :blue, style: :double)
+        "Loading..."
+      end
+    end
+  end
+end
 
-1. The driver, which emits lightweight frame events
-1. The template factory, which builds templates to convert frame events from the driver into terminal graphics
+WhirledPeas.configure do |config|
+  # ...
+  config.loading_template_factory = LoadingTemplateFactory.new
+end
+```
 
 ### Driver
 
@@ -70,13 +107,14 @@ The producer provides a single method
 #
 # @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] key value pairs to send as arguments to the template factory, these values will be
-#   serialized/deserialized
-def send(name, duration:, args:)
+# @param args [Hash<Symbol, Object>] key value pairs to send as arguments to the template factory
+def send_frame(name, duration:, args:)
   # implementation
 end
 ```
 
+**IMPORTANT**: the keys for arguments must be symbols.
+
 #### Example
 
 Simple application that loads a set of numbers and looks for a pair that adds up to 1,000
@@ -85,25 +123,25 @@ Simple application that loads a set of numbers and looks for a pair that adds up
 class Driver
   def start(producer)
     numbers = File.readlines('/path/to/numbers.txt').map(&:to_i)
-    producer.send('load-numbers', duration: 3, args: { numbers: numbers })
+    producer.send_frame('load-numbers', duration: 3, args: { numbers: numbers })
     numbers.sort!
-    producer.send('sort-numbers', duration: 3, args: { numbers: numbers })
+    producer.send_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('found-pair', duration: 5, args: { low: low, high: high, sum: sum })
+        producer.send_frame('found-pair', duration: 5, args: { low: low, high: high, sum: sum })
         return
       elsif sum < 1000
-        producer.send('too-low', args: { low: low, high: high, sum: sum })
+        producer.send_frame('too-low', args: { low: low, high: high, sum: sum })
         low += 1
       else
-        producer.send('too-high', args: { low: low, high: high, sum: sum })
+        producer.send_frame('too-high', args: { low: low, high: high, sum: sum })
         high -= 1
       end
     end
-    producer.send('no-solution', duration: 5)
+    producer.send_frame('no-solution', duration: 5)
   end
 end
 ```
@@ -112,27 +150,61 @@ end
 
 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 a simple 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.start` takes an optional template facotry 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.
+
 #### Building Blocks
 
 A template is created with `WhirledPeas.template`, which yields a `Template` object and `TemplateSettings`. This template object is a `ComposableElement`, which allows for attaching child elements and setting layout options. `GridElement` and `BoxElement` are two other composable elements and `TextElement` is a simple element that can hold a text/number value and has layout options, but cannot have any child elements.
 
-A `ComposableElement` provides the following methods to add child elements
+A `ComposableElement` 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 `ComposableElement` and a `BoxSettings`, which will be added to the parent's children
 - `add_grid` - yields a `ComposableElement` 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 |template, template_settings|
+  template_settings.bg_color = :blue
+  template.add_grid do |grid, grid_settings|
+    grid_settings.num_cols = 10
+    100.times do |i|
+      grid.add_text { i }
+    end
+  end
+end
+```
+
+The above template can also be broken down into more manageable methods, e.g.
+
+```ruby
+def number_grid(grid, settings)
+  settings.num_cols = 10
+  100.times do |i|
+    grid.add_text { i }
+  end
+end
+
+WhirledPeas.template do |template, settings|
+  settings.bg_color = :blue
+  template.add_grid(&method(:number_grid))
+end
+```
+
 Additionally, if no child element is explicitly added to a `GridElement`, but the block returns an array of strings or numbers, those will be converted to `TextElements` and added as children to the `GridElement`. For example, these are identical ways to create a grid of strings
 
 ```ruby
 template.add_grid do |g|
   100.times do |i|
-    g.add_text { i.to_s }
+    g.add_text { i }
   end
 end
 
 template.add_grid do |g|
-  100.times.map(&:to_s)
+  100.times.map(&:itself)
 end
 ```
 
@@ -164,6 +236,7 @@ The available settigs are
 | `flow`        | Flow to display child elements (see [Display Flow](#display-flow)) | `:l2r`  | `Box`                             | Yes     |
 | `margin`      | Set the (left, top, right, bottom) margin of the element           | `0`     | `Box`, `Grid`                     | Yes     |
 | `padding`     | Set the (left, top, right, bottom) padding of the element          | `0`     | `Box`, `Grid`                     | Yes     |
+| `title_font`  | Font used to create "large" text (see [Large Text](#large-text))   |         | `Text`                            |
 | `transpose`   | Display grid elements top-to-bottom, then left-to-right            | `false` | `Grid`                            | No      |
 | `underline`   | `true` underlines the font                                         | `false` | `Box`, `Grid`, `Template`, `Text` | Yes     |
 | `width`       | Override the calculated with of an element                         |         | `Box`, `Grid`, `Text`             | No      |
@@ -172,15 +245,16 @@ The available settigs are
 
 Margin and padding settings allow for setting the spacing on each of the 4 sides of the element independently. The set these values, use
 
+- `clear_margin` - sets all margin values to 0
 - `set_margin(left:, top:, right:, bottom:)`
+- `clear_padding` - sets all margin values to 0
 - `set_padding(left:, top:, right:, bottom:)`
 
-Any argument value not provided will result in that value being 0.
-
 ##### 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
 
+- `clear_border` - sets all border positions to `false`
 - `set_border(left:, top:, right:, bottom:, inner_horiz:, inner_vert:, color:, style:)`
 
 Available border styles are
@@ -272,46 +346,137 @@ Many of these also have a "bright" option:
 - `:bright_red`
 - `:bright_yellow`
 
+##### Large Text
+
+The `title_font` setting for `TextElement`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.
+
 ### Example
 
 ```ruby
 class TemplateFactory
-  def initialize
-    @numbers = []
+  def build(frame, args)
+    set_state(frame, args)
+    WhirledPeas.template do |t|
+      t.add_box('Body', &method(:body))
+    end
   end
 
-  def build(name, args)
-    @numbers = args['numbers'] if args.key?('numbers')
+  private
 
-    WhirledPeas.template do |t|
-      t.add_box do |body, settings|
-        settings.flow = :l2r
-        settings.auto_margin = true
-        body.add_box do |title, settings|
-          settings.underline = true
-          "Pair Finder"
-        end
-        body.add_box do |_, settings|
-          settings.color = name == 'found-pair' ? :green : :red
-          args.key?('sum') ? "Sum: #{args['sum']}" : 'N/A'
-        end
-        body.add_grid do |g, settings|
-          settings.full_border
-          @numbers.each.with_index do |num, index|
-            is_low = args.key?('low') && args['low'] == index
-            is_high = args.key?('high') && args['high'] == index
-            g.add_text do |_, settings|
-              settings.bg_color = (is_low || is_high) ? :cyan : :white
-              num.to_s
-            end
-          end
-        end
+  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(_elem, settings)
+    settings.underline = true
+    "Pair Finder"
+  end
+
+  def sum(_elem, settings)
+    settings.color = @frame == 'found-pair' ? :green : :red
+    @sum ? "Sum: #{@sum}" : 'N/A'
+  end
+
+  def number_grid(elem, settings)
+    settings.full_border
+    @numbers.each.with_index do |num, index|
+      g.add_text do |_, settings|
+        settings.bg_color = (@low == index || @high == index) ? :cyan : :white
+        num
       end
     end
   end
+
+  def body(elem, settings)
+    settings.flow = :l2r
+    settings.auto_margin = true
+
+    elem.add_box('Title', &method(:title))
+    elem.add_box('Sum', &method(:sum))
+    elem.add_grid('NumberGrid', &method(:number_grid))
+  end
 end
 ```
 
+### Debugging
+
+The `whirled_peas` executable provides some commands that are helpful for debugging.
+
+#### list_frames
+
+List the frames sent by the driver
+
+```
+$ whirled_peas <config file> list_frames
+Frame 'start' displayed for 5 second(s)
+Frame 'move' displayed for 1 frame ({:direction=>'N'})
+...
+EOF frame detected
+```
+
+#### play_frame
+
+Displays a single frame for several seconds
+
+```
+$ whirled_peas <config file> play_frame move '{"direction":"N"}'
+```
+
+Adding the `--debug` flag will result in just printing out the template's debug information, e.g.
+
+```
+$ whirled_peas <config file> play_frame move '{"direction":"N"}' --debug
++ TEMPLATE [WhirledPeas::UI::Template]
+  - Settings
+    WhirledPeas::UI::TemplateSettings
+      <default>
+  - Children
+    + TitleContainer [WhirledPeas::UI::BoxElement]
+...
+```
+
+#### loading
+
+Displays the configured loading screen for several seconds
+
+```
+$ whirled_peas <config file> loading
+```
+
+Adding the `--debug` flag will result in just printing out the loading template's debug information, e.g.
+
+```
+$ whirled_peas <config file> loading --debug
++ TEMPLATE [WhirledPeas::UI::Template]
+  - Settings
+    WhirledPeas::UI::TemplateSettings
+      <default>
+  - Children
+    + TitleContainer [WhirledPeas::UI::BoxElement]
+...
+```
+
 ## 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.

data/bin/title_fonts

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'whirled_peas'
+
+WhirledPeas.print_title_fonts

data/exe/whirled_peas

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'whirled_peas'
+require 'whirled_peas/command_line'
+
+WhirledPeas::CommandLine.new(ARGV).start