[![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! ## Installation Add this line to your application's Gemfile: ```ruby gem 'whirled_peas' ``` And then execute: $ bundle install Or install it yourself as: $ gem install whirled_peas ## 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('Title') do |_, settings| settings.underline = true "Hello #{args[:name]}" end # ... end end end class Driver def start(producer) producer.send_frame('starting', args: { name: 'World' }) # ... end end WhirledPeas.configure do |config| config.driver = Driver.new config.template_factory = TemplateFactory.new end ``` 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 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) # application code here end ``` The producer provides a single method ```ruby # 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] 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 ```ruby class Driver def start(producer) numbers = File.readlines('/path/to/numbers.txt').map(&:to_i) producer.send_frame('load-numbers', duration: 3, args: { numbers: numbers }) numbers.sort! 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_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 }) low += 1 else producer.send_frame('too-high', args: { low: low, high: high, sum: sum }) high -= 1 end end producer.send_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 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, 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 } end end template.add_grid do |g| 100.times.map(&:itself) end ``` Similarly, if no child element is explicilty added to a `BoxElement`, but the block returns a string or number, that value will be converted to a `TextElement` and added as a child. For example, these are identical ways to create a box with string content ```ruby template.add_box do |b| b.add_text { "Hello!" } end template.add_box do |b| "Hello!" end ``` #### Settings Each element type has an associated settings type, which provide a custom set of options to format the output. Parent settings may be merged into child settings (assuming the child supports those settings) The available settigs are | Setting | Description | Default | Availability | Merged? | | ------------- | ------------------------------------------------------------------ | ------- | --------------------------------- | ------- | | `align` | Justifies the text (allowed values: `:left`, `:center`, `:right`) | `:left` | `Box`, `Grid`, `Text` | Yes | | `auto_margin` | Evenly distribute side margin (overrides left/right in `margin`) | `false` | `Box`, `Grid` | Yes | | `bg_color` | Background color (see [Colors](#colors)) | | `Box`, `Grid`, `Template`, `Text` | Yes | | `bold` | `true` makes the font bold | `false` | `Box`, `Grid`, `Template`, `Text` | Yes | | `border` | Set the border for the lements | none | `Box`, `Grid`, | Yes | | `color` | Foreground text color (see [Colors](#colors)) | | `Box`, `Grid`, `Template`, `Text` | Yes | | `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 | ##### Margin and Padding 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:)` ##### 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 - `:bold` (default) ``` ┏━━┳━━┓ ┃ ┃ ┃ ┣━━╋━━┫ ┃ ┃ ┃ ┗━━┻━━┛ ``` - `:double` ``` ╔══╦══╗ ║ ║ ║ ╠══╬══╣ ║ ║ ║ ╚══╩══╝ ``` - `:soft` ``` ╭──┬──╮ │ │ │ ├──┼──┤ │ │ │ ╰──┴──╯ ``` ##### Display Flow Child elements can flow in one of 4 directions - `:l2r` left-to-right ``` [child 1] [child 2] ... [child N] ``` - `:r2l` right-to-left ``` [child N] [child N - 1] ... [child 1] ``` - `:t2b` top-to-bottom ``` [child 1] [child 2] ... [child N] ``` - `:b2t` bottom-to-top ``` [child N] [child N - 1] ... [child 1] ``` ##### Colors Below is the list of available colors (for both foreground and background) - `:black` - `:blue` - `:cyan` - `:gray` - `:green` - `:magenta` - `:red` - `:white` - `:yellow` Many of these also have a "bright" option: - `:bright_blue` - `:bright_cyan` - `:bright_green` - `:bright_magenta` - `: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 build(frame, args) set_state(frame, args) WhirledPeas.template do |t| t.add_box('Body', &method(:body)) end end private 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 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 play_frame move '{"direction":"N"}' ``` Adding the `--debug` flag will result in just printing out the template's debug information, e.g. ``` $ whirled_peas play_frame move '{"direction":"N"}' --debug + TEMPLATE [WhirledPeas::UI::Template] - Settings WhirledPeas::UI::TemplateSettings - Children + TitleContainer [WhirledPeas::UI::BoxElement] ... ``` #### loading Displays the configured loading screen for several seconds ``` $ whirled_peas loading ``` Adding the `--debug` flag will result in just printing out the loading template's debug information, e.g. ``` $ whirled_peas loading --debug + TEMPLATE [WhirledPeas::UI::Template] - Settings WhirledPeas::UI::TemplateSettings - 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. 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). ## 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 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).