whirled_peas 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 563cc06007d90aa0599b61c5366a5d9b2c5224ec2973367b6c358cad95ddaedc
-  data.tar.gz: fa798abdfb8a8e4fd229f08b964c8ee4f4d480939ece9ddaeb5731c171985504
+  metadata.gz: 1b374c9d4250b281d3f87284f446e82c01ece7ff2fe196687be50502b2e42960
+  data.tar.gz: 0ebd7b96a154277121767eb8c33d63b831db37770ff0172b76f28fcf89c5dec9
 SHA512:
-  metadata.gz: 1be24e74d75f87a001b26f216e320d4a4680c48513e48c42047d2c2168a9404471704731df97ced5954facdc4ca7316580f6078db5670e45067c7e8ed3ee4cd3
-  data.tar.gz: 86f3b995575fc7ff8b6bb83adf368182a684faece1584cffb7b1150bd47ce082adaba5b0d4ce0b83d19d2ec2d795bd31db19d35c990e6d0065698c050161bcd0
+  metadata.gz: f6dcc7dc00852a343f55056646db886903bc5735a21bd9af71a885e28ff70aa85bb3f26ff4f97c23dc4292fa401c1c624284c347b17fb957fb8e0069301b7ef9
+  data.tar.gz: 1f0ae0e07baf45703dff90396be7b6c705f17f8c9cb4fcd4e0b4b433513efc94dd8c3a056f50f1d3f47f7e3179c308d36264ef4e4be0c179815e650a6136a11a

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.5.0 - 2021-01-25
+
+BREAKING: there was a significant amount of structural refactoring in this release. While that aspect did not add or remove any features, it fixed several layout bugs (some known and some unknown), so most template with moderate complexity will now be laid out slightly differently.
+
+- [3ddfede](https://github.com/tcollier/whirled_peas/tree/3ddfedee4ab2fadeecbe82c7c9caf25c2988f095): Allow relative positioning of containers
+- [507e77c](https://github.com/tcollier/whirled_peas/tree/507e77c551bcb9cc832d5c24e2f24eb1afe4eddc): Add height attribute for container settings
+- [af8ef19](https://github.com/tcollier/whirled_peas/tree/af8ef1950edebcd23a57a04982b22a56296ee09b): Add automated screen testing
+
+## v0.4.1 - 2021-01-22
+
+- [0f7aa6c](https://github.com/tcollier/whirled_peas/tree/0f7aa6ccc07323230dd602cb43e0341de5a69ad8): Allow relative path for config files
+
 ## v0.4.0 - 2021-01-22
 
 - [7fd6712](https://github.com/tcollier/whirled_peas/tree/7fd6712818c94cdbfd81828277ca67c705e01793): BREAKING: replace `WhirledPeas.start` with command line executable

data/README.md

@@ -36,8 +36,8 @@ require 'whirled_peas'
 
 class TemplateFactory
   def build(frame, args)
-    WhirledPeas.template do |body|
-      body.add_box('Title') do |_, settings|
+    WhirledPeas.template do |composer|
+      composer.add_box('Title') do |_, settings|
         settings.underline = true
         "Hello #{args[:name]}"
       end
@@ -70,10 +70,10 @@ The optional loading screen can be configured like
 ```ruby
 class LoadingTemplateFactory
   def build
-    WhirledPeas.template do |t|
-      t.add_box('Loading') do |box, settings|
+    WhirledPeas.template do |composer|
+      composer.add_box('Loading') do |_, settings|
         settings.set_margin(top: 15)
-        settings.auto_margin = true
+        settings.align = :center
         settings.full_border(color: :blue, style: :double)
         "Loading..."
       end
@@ -113,7 +113,7 @@ def send_frame(name, duration:, args:)
 end
 ```
 
-**IMPORTANT**: the keys for arguments must be symbols.
+**IMPORTANT**: the keys in the `args` hash must be symbols!
 
 #### Example
 
@@ -148,31 +148,31 @@ 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.
+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.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.
+`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 `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 template is created with `WhirledPeas.template`, which yields a `Composer` object for a `BoxElement` and `BoxSettings`. The composer allows for attaching child elements and the settings for setting layout options.
 
-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).
+A `Composer` 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_box` - yields a `Composer` and a `BoxSettings`, which will be added to the parent's children
+- `add_grid` - yields a `Composer` 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
+WhirledPeas.template do |composer, settings|
+  settings.bg_color = :blue
+  composer.add_grid do |composer, settings|
+    settings.num_cols = 10
     100.times do |i|
-      grid.add_text { i }
+      composer.add_text { i }
     end
   end
 end
@@ -181,29 +181,27 @@ end
 The above template can also be broken down into more manageable methods, e.g.
 
 ```ruby
-def number_grid(grid, settings)
+def number_grid(_composer, settings)
   settings.num_cols = 10
-  100.times do |i|
-    grid.add_text { i }
-  end
+  100.times.map(&:itself)
 end
 
-WhirledPeas.template do |template, settings|
+WhirledPeas.template do |composer, settings|
   settings.bg_color = :blue
-  template.add_grid(&method(:number_grid))
+  composer.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|
+template.add_grid do |composer|
   100.times do |i|
-    g.add_text { i }
+    composer.add_text { i }
   end
 end
 
-template.add_grid do |g|
+template.add_grid do
   100.times.map(&:itself)
 end
 ```
@@ -211,51 +209,65 @@ 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!" }
+template.add_box do |composer|
+  composer.add_text { "Hello!" }
 end
 
-template.add_box do |b|
+template.add_box do
   "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)
+Each element type has an associated settings type, which provide a custom set of options to format the output. Child settings will inherit from the parent, where applicable
 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
+| Setting      | Description                                                                     | Default | Availability          | Inherited            |
+| ------------ | ------------------------------------------------------------------------------- | ------- | --------------------- | -------------------- |
+| `align`      | Justifies the content (allowed values: `:left`, `:center`, `:right`)            | `:left` | `Box`, `Grid`         | Yes                  |
+| `bg_color`   | Background color (see [Colors](#colors))                                        |         | `Box`, `Grid`, `Text` | Yes                  |
+| `bold`       | `true` makes the font bold                                                      | `false` | `Box`, `Grid`, `Text` | Yes                  |
+| `border`     | Set the border for the lements                                                  | none    | `Box`, `Grid`,        | Only style and color |
+| `color`      | Foreground text color (see [Colors](#colors))                                   |         | `Box`, `Grid`, `Text` | Yes                  |
+| `flow`       | Flow to display child elements (see [Display Flow](#display-flow))              | `:l2r`  | `Box`, `Grid`         | Yes                  |
+| `height`     | Override the calculated height of an element's content area                     |         | `Box`, `Grid`         | No                   |
+| `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                   |
+| `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                   |
+
+##### Position
+
+Position settings dictate the relative position from where the painter would have preferred to place the container. Negative numbers move the container left/up and positive numbers move it right/down. To set these values, use
+
+- `set_position(left:, top:)`
+
+##### Margin
+
+Margin settings dictate the spacing on the outside (i.e. outside of the border) of each of the 4 sides of the container independently. To set these values, use
+
 - `set_margin(left:, top:, right:, bottom:)`
-- `clear_padding` - sets all margin values to 0
+
+Note: values cannot be negative
+
+##### Padding
+
+Padding settings dictate the spacing on the inside (i.e. inside of the border) of each of the 4 sides of the container independently. To set these values, use
+
 - `set_padding(left:, top:, right:, bottom:)`
 
+Note: values cannot be negative
+
 ##### 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:)`
+- `full_border(style:, color:)`
 
 Available border styles are
 
@@ -373,8 +385,13 @@ Note: when using a title font with WhirledPeas for the first time on a system, t
 class TemplateFactory
   def build(frame, args)
     set_state(frame, args)
-    WhirledPeas.template do |t|
-      t.add_box('Body', &method(:body))
+    WhirledPeas.template do |composer, settings|
+      settings.flow = :l2r
+      settings.align = :center
+
+      composer.add_box('Title', &method(:title))
+      composer.add_box('Sum', &method(:sum))
+      composer.add_grid('NumberGrid', &method(:number_grid))
     end
   end
 
@@ -388,34 +405,25 @@ class TemplateFactory
     @high = args[:high] if args.key?(:high)
   end
 
-  def title(_elem, settings)
+  def title(_composer, settings)
     settings.underline = true
     "Pair Finder"
   end
 
-  def sum(_elem, settings)
+  def sum(_composer, settings)
     settings.color = @frame == 'found-pair' ? :green : :red
     @sum ? "Sum: #{@sum}" : 'N/A'
   end
 
-  def number_grid(elem, settings)
+  def number_grid(composer, settings)
     settings.full_border
     @numbers.each.with_index do |num, index|
-      g.add_text do |_, settings|
+      composer.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
 ```
 
@@ -443,16 +451,31 @@ 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.
+Adding the `--template` flag will result in printing out debug information for the template, e.g.
 
 ```
-$ whirled_peas <config file> play_frame move '{"direction":"N"}' --debug
-+ TEMPLATE [WhirledPeas::UI::Template]
+$ whirled_peas <config file> play_frame move '{"direction":"N"}' --template
++ TEMPLATE [WhirledPeas::Template::BoxElement]
   - Settings
-    WhirledPeas::UI::TemplateSettings
+    WhirledPeas::Settings::BoxSettings
       <default>
   - Children
-    + TitleContainer [WhirledPeas::UI::BoxElement]
+    + TitleContainer [WhirledPeas::Template::BoxElement]
+...
+```
+
+Adding the `--painter` flag will result in printing out debug information the painter (the rendered template), e.g.
+
+```
+$ whirled_peas <config file> play_frame move '{"direction":"N"}' --painter
++ TEMPLATE [WhirledPeas::Graphics::BoxPainter]
+  - Settings
+    WhirledPeas::Settings::BoxSettings
+      <default>
+  - Dimensions
+  - Canvas:
+  - Children
+    + TitleContainer [WhirledPeas::Graphics::BoxPainter]
 ...
 ```
 
@@ -483,6 +506,21 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 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.
+
+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]` 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
+
 ## 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).

data/Rakefile

@@ -1,6 +1,40 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+def screen_test(file, method)
+  raise ArgumentError, 'Missing argument: file' unless file
+
+  require 'bundler/setup'
+  require 'whirled_peas'
+  require_relative 'screen_test/screen_tester'
+
+  WhirledPeas::ScreenTester.new(file).send(method)
+end
+
+namespace :screen_test do
+  %i[debug run save view].each do |t|
+    task t, [:file] do |_, args|
+      screen_test(args[:file], t)
+    end
+  end
+
+  task :update_all do
+    require 'bundler/setup'
+    require 'whirled_peas'
+    require_relative 'screen_test/screen_tester'
+
+    WhirledPeas::ScreenTester.update_all
+  end
+end
+
+task :screen_test do
+  require 'bundler/setup'
+  require 'whirled_peas'
+  require_relative 'screen_test/screen_tester'
+
+  WhirledPeas::ScreenTester.run_all
+end
+
+task default: [:screen_test, :spec]

data/bin/debug

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+def print_usage
+  puts "Usage: #{$0} <config file> [options]"
+  puts
+  puts 'options include'
+  puts '    --disable-screen  Disable the screen (useful when printing debug statements)'
+  puts '    --painter         Print the painter debug tree and exit'
+  puts '    --template        Print the template debug tree and exit'
+end
+
+if !(1..2).include?(ARGV.length)
+  print_usage
+  exit(1)
+elsif !File.exist?(ARGV.first)
+  puts "File not found: #{ARGV.first}"
+  print_usage
+  exit(1)
+elsif ARGV.length == 2 && !%w[--disable-screen --template --painter].include?(ARGV[1])
+  puts "Unrecognized option: #{ARGV[1]}"
+  print_usage
+  exit(1)
+end
+
+require 'bundler/setup'
+require 'whirled_peas'
+
+if ARGV.length == 1
+  option = nil
+else
+  option = ARGV[1].sub(/^--/, '').gsub(/-/, '_').to_sym
+end
+
+template_file = ARGV.first[0] == '/' ? ARGV.first : File.join(Dir.pwd, ARGV.first)
+WhirledPeas.debug(template_file, option)

data/lib/whirled_peas.rb

@@ -1,11 +1,12 @@
 require 'logger'
 
 require 'whirled_peas/errors'
-
 require 'whirled_peas/config'
+require 'whirled_peas/debugger'
 require 'whirled_peas/frame'
+require 'whirled_peas/graphics'
+require 'whirled_peas/settings'
 require 'whirled_peas/template'
-require 'whirled_peas/ui'
 require 'whirled_peas/utils'
 require 'whirled_peas/version'
 
@@ -18,11 +19,12 @@ module WhirledPeas
     yield config
   end
 
-  def self.template(&block)
-    require 'whirled_peas/template/element'
+  def self.debug(config_file, option=nil)
+    Debugger.new(config_file, option).debug
+  end
 
-    template = UI::Template.new
-    yield template, template.settings
-    template
+  def self.template(&block)
+    require 'whirled_peas/template/composer'
+    Template::Composer.build(&block)
   end
 end