whirled_peas 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85262725d00d4055dceb88c2672afc6a7f5027626a3038998706b5d8e2d1a3aa
+  data.tar.gz: 15bc9278fd2945d0ea5cf6a5436ba11e00724e71f128ec487f5569c3689bfaeb
+SHA512:
+  metadata.gz: 7270704f5ff2adc5d225dd7c612f489a968c9d5efc2fef399b65a8ad7320fcad2920ec355645f961744577df740efbfcf4947f477e13224702764bf64931a52b
+  data.tar.gz: a46f83016c3038275fccc907894c0ea7fc3ce0553c5da343d77fbfbbdf9f619ca169346e11b5862cf502e7785372a750a0ab668bfffb3198b1d529a75cd198a5

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+Gemfile.lock
+
+# rspec failure tracking
+.rspec_status
+

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.6
+before_install: gem install bundler -v 2.1.4

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at collier@apartmentlist.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in whirled_peas.gemspec
+gemspec
+
+gem 'rake', '~> 12.0'
+gem 'rspec', '~> 3.0'
+gem 'pry-byebug'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Tom Collier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,331 @@
+# 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
+
+```ruby
+require 'whirled_peas'
+
+class TemplateFactory
+  def build(frame, args)
+    WhirledPeas.template do |body|
+      body.add_box do |_, settings|
+        settings.underline = true
+        "Hello #{args['name']}"
+      end
+      # ...
+    end
+  end
+end
+
+class Driver
+  def start(producer)
+    producer.send('starting', args: { 'name' => 'World' })
+    # ...
+  end
+end
+
+WhirledPeas.start(Driver.new, TemplateFactory.new)
+```
+
+A Whirled Peas application consists of two pieces
+
+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
+
+### 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, these values will be
+#   serialized/deserialized
+def send(name, duration:, args:)
+  # implementation
+end
+```
+
+#### 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('load-numbers', duration: 3, args: { numbers: numbers })
+    numbers.sort!
+    producer.send('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 })
+        return
+      elsif sum < 1000
+        producer.send('too-low', args: { low: low, high: high, sum: sum })
+        low += 1
+      else
+        producer.send('too-high', args: { low: low, high: high, sum: sum })
+        high -= 1
+      end
+    end
+    producer.send('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.
+
+#### 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
+
+- `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
+
+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 }
+  end
+end
+
+template.add_grid do |g|
+  100.times.map(&:to_s)
+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     |
+| `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
+
+- `set_margin(left:, top:, right:, bottom:)`
+- `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
+
+- `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`
+
+### Example
+
+```ruby
+class TemplateFactory
+  def initialize
+    @numbers = []
+  end
+
+  def build(name, args)
+    @numbers = args['numbers'] if args.key?('numbers')
+
+    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
+      end
+    end
+  end
+end
+```
+
+## 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).