whirled_peas 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ddf23151c866304cbe5213073c9ac9bd3c7b17139737acf1fe2f6678e6248f
-  data.tar.gz: 31d26322b45af3d06c2f64c019fde32cebfe87638852c87857fa0113dc3bdc11
+  metadata.gz: 9652a887fc6a68ba5367864a25b4a211674433eae86a2f68db3923e873ab49e8
+  data.tar.gz: 72926cd288adc3c30393990d88dcc0bca53e2fbfe79d56768e438ffaee2cf3ba
 SHA512:
-  metadata.gz: 7be414e153881ff228f8780e11887be61844d1f719c1b19d50888cf7c2caf3d2171dd992c6694604672209f5e7457b35eebba7498dd60bb1d21e717c467f0a6c
-  data.tar.gz: d27958378cfd0fe6728ef547559f07258ecafb2481df0d1994d3cf13802ae14ad414c212d2186f8e36ecb00be608d8abc3c6ccb918109a0114cc9585ed431735
+  metadata.gz: 9e0124bd724ece36b76e1d527ffb3ccd5a06e9cd7f00c1ae5d0c39445d0c4ed4804d8c2cdc0c3df250f0d927b9927efd97d118fd0fd76bbc42277fda68a674cb
+  data.tar.gz: '09edc4873598d1363d7d3ef2c548699bcbfa229a8821e458c201608ec9f7e3aba8cf2f081f559edc51c04244267f569e8444b7952b21ab41bfea8a7807c0432a'

data/.gitignore

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

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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,34 +77,12 @@ 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
-
-WhirledPeas.configure do |config|
-  # ...
-  config.loading_template_factory = LoadingTemplateFactory.new
-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 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
@@ -124,7 +101,7 @@ 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<Symbol, Object>] key value pairs to send as arguments to the template factory
-def send_frame(name, duration:, args:)
+def add_frame(name, duration:, args:)
   # implementation
 end
 ```
@@ -136,39 +113,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
 
@@ -258,7 +231,7 @@ The available settigs are
 | `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                   |
+| `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`    | `Box`, `Grid`, `Text` | Yes                  |
 | `width`      | Override the calculated width of an element's content area                       |            | `Box`, `Grid`         | No                   |
@@ -746,64 +719,106 @@ class TemplateFactory
 end
 ```
 
-### Debugging
+### Full usage
+
+```
+Usage: whirled_peas <command> [command options]
 
-The `whirled_peas` executable provides some commands that are helpful for debugging.
+Available commands:
 
-#### list_frames
+    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
+```
 
-List the frames sent by the driver
+#### `debug`
+
+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`
 
-#### loading
+Print out command-specific help message
 
-Displays the configured loading screen for several seconds
+```
+Usage: whirled_peas help <command>
+```
+
+#### `play`
+
+Play an animation from an application or prerecorded file
 
 ```
-$ whirled_peas <config file> loading
+# 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
 ```
 
-Adding the `--template` flag will result in just printing out the loading template's debug information, e.g.
+#### `record`
+
+Record animation to a file
 
 ```
-$ whirled_peas <config file> loading --template
-+ TEMPLATE [WhirledPeas::Graphics::BoxPainter]
-  - Settings
-    WhirledPeas::Settings::BoxSettings
-      <default>
-  - Children
-    + TitleContainer [WhirledPeas::Graphics::BoxPainter]
-...
+# 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
 ```
 
 ## Development
@@ -814,19 +829,28 @@ 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
+
+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
 
-- `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 the file provide is a screen test, 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
 
@@ -839,3 +863,7 @@ 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).
+
+```
+
+```

data/Rakefile

@@ -3,29 +3,10 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-def screen_test(file, method)
-  raise ArgumentError, 'Missing argument: file' unless file
-  require_relative 'tools/whirled_peas/tools/screen_tester'
-  WhirledPeas::Tools::ScreenTester.new(file).send(method)
-end
-
-namespace :screen_test do
-  %i[template view run save update debug].each do |t|
-    task t, [:file] do |_, args|
-      screen_test(args[:file], t)
-    end
-  end
-
-  task :update_all do
-    require_relative 'tools/whirled_peas/tools/screen_tester'
-    WhirledPeas::Tools::ScreenTester.update_all
-  end
-end
-
 task :screen_test do
   require_relative 'tools/whirled_peas/tools/screen_tester'
   WhirledPeas::Tools::ScreenTester.run_all
 end
 
-task default: :ci
 task ci: %i[spec screen_test]
+task default: :ci

data/bin/reset_cursor

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'whirled_peas'
+require 'whirled_peas/utils/ansi'
+
+module WhirledPeas
+  print Utils::Ansi.clear
+  print Utils::Ansi.cursor_visible(true)
+  STDOUT.flush
+end

data/bin/screen_test

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'whirled_peas'
+require 'whirled_peas/utils/formatted_string'
+
+require_relative '../tools/whirled_peas/tools/screen_tester'
+
+def print_usage(exit_code=0)
+  puts "Usage: #{$0} [file] [options]"
+  puts
+  puts 'If not file or options are provide, all tests are run'
+  puts
+  puts 'If no file is provided, the supported options are'
+  puts '    --help             print this usage statement and exit'
+  puts '    --view-pending     interactively display and optionally save rendered output for each pending test'
+  puts '    --view-failed      interactively display and optionally save rendered output for each faiing test'
+  puts
+  puts 'If a screen test file is provided as the first argument, the supported options are'
+  puts '    --run        run screen test for given file'
+  puts '    --view       interactively display and optionally save the file\'s test output'
+  puts '    --template   print out template tree for the test template'
+  puts '    --debug      render the test template without displying it, printing out debug information'
+  exit(exit_code)
+end
+
+module WhirledPeas
+  if ARGV.length == 0
+    Tools::ScreenTester.run_all
+  elsif ARGV.length == 1
+    option = ARGV[0]
+    case option
+    when '--help'
+      print_usage
+    when '--view-pending'
+      Tools::ScreenTester.view_pending
+    when '--view-failed'
+      Tools::ScreenTester.view_failed
+    else
+      print_usage(1)
+    end
+  elsif ARGV.length == 2
+    file, option = ARGV
+    case option
+    when '--run'
+      tester = Tools::ScreenTester.new(file)
+      if tester.pending?
+        puts Utils::FormattedString.new('Pending', Settings::TextColor::YELLOW)
+        puts "Run `#{$0} #{file} --view` to view and optionally save ouput."
+      elsif tester.failed?
+        puts Utils::FormattedString.new('Failed', Settings::TextColor::RED)
+        puts "Run `#{$0} #{file} --view` to compare and optionally save ouput."
+      else
+        puts Utils::FormattedString.new('Pass', Settings::TextColor::GREEN)
+      end
+    when '--view'
+      Tools::ScreenTester.new(file).view
+    when '--template'
+      Tools::ScreenTester.new(file).template
+    when '--debug'
+      Tools::ScreenTester.new(file).debug
+    else
+      print_usage(1)
+    end
+  else
+    print_usage(1)
+  end
+end