README.md in whirled_peas-0.7.1 vs README.md in whirled_peas-0.8.0

- old
+ new

@@ -16,11 +16,11 @@ ██║███╗██║██╔══██║██║██╔══██╗██║ ██╔══╝ ██║ ██║ ██╔═══╝ ██╔══╝ ██╔══██║╚════██║ ╚███╔███╔╝██║ ██║██║██║ ██║███████╗███████╗██████╔╝ ██║ ███████╗██║ ██║███████║ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝╚═╝ ╚═╝╚══════╝╚══════╝╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═╝╚══════╝ ``` -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 Add this line to your application's Gemfile: @@ -38,13 +38,12 @@ ## 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 +- 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 ```ruby # visualize.rb @@ -60,55 +59,33 @@ # ... end 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 ``` 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 -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. - ```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) @@ -122,11 +99,11 @@ # Send frame events to the UI # # @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 ``` **IMPORTANT**: the keys in the `args` hash must be symbols! @@ -134,44 +111,40 @@ #### Example 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. +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. -#### 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. - #### Building Blocks A template is created with `WhirledPeas.template`, which yields a `Composer` object for a `Box` and `BoxSettings`. The composer allows for attaching child elements and the settings for setting layout options. The following attributes of the template's settings will be overridden before it is rendered to ensure that it fills the screen exactly - `margin` - all margin will be set to 0 @@ -256,11 +229,11 @@ | `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 | +| `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 | | `valign` | Justifies the content in the vertical direction | `:top` | `Box`, `Grid` | No | @@ -744,92 +717,143 @@ end end end ``` -### Debugging +### Full usage -The `whirled_peas` executable provides some commands that are helpful for debugging. +``` +Usage: whirled_peas <command> [command options] -#### list_frames +Available commands: -List the frames sent by the driver + 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 +``` +#### `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 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. To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). ### Testing -In addition to standard RSpec tests, WhirledPeas has custom tests for rendered templates. These files live in `screen_test/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 +``` -- `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 +Usage: screen_test [file] [options] +If not file or options are provide, all tests are run + +If no file is provided, the supported options are +--help print this usage statement and exit +--view-pending interactively display and optionally save rendered output for each pending test +--view-failed interactively display and optionally save rendered output for each faiing test + +If 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 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). ## License @@ -837,5 +861,9 @@ The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). ## 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). + +``` + +```