whirled_peas 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3cb7aa7af0bf74f8818eb5796f310e3b65a73851b7cbab35834e14fe0262ac1
-  data.tar.gz: 6ae73d252d69d3730c1e1814d441800fca08177a4401abc3e4dcbe6edcd34548
+  metadata.gz: 740b5ae88bfdd0f6dfbf4b1ef9e220a4298ddd8f4d8b01d62e904e3bfb4e109b
+  data.tar.gz: 1e78f0bf1664187825441258909a750c74455017266d01b4b64d5cdd7c609572
 SHA512:
-  metadata.gz: 2b0965214a99209e4830ed68da162cc83d249188e197d8b9fe11b61356f797e2172a648aef2b23f83f9ac45db40d9f4e7daee9471f67069e61998e5f24a8d0ba
-  data.tar.gz: e0d546f8a60606a918aadf1743848b9839703328bf14a05dcb67f680886ee2eef2c4ae542d89055daf822f74200f64a719e77f1223520266aa7d6703b18ccb03
+  metadata.gz: '0960008e3b09aae39cf0655ff57d6dde8859bd3437844b68b37fd72b49bc04199dae2fa5544ba219f795d87f5b5ada80d56f0e96f005eaffddbd74de67d4037c'
+  data.tar.gz: ce998b69ac1db491577cdfaaaa4b35fb79a0bd07d24c622f426e38b1ff3eb0851ff10c90d24b8b7f48dc1b97dd01c11f93960a011c2611df201f3d86c45ce65a

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.3.0 - 2021-01-21
+
+- [617f802](https://github.com/tcollier/whirled_peas/tree/617f8027d6688a2ec81a3e594e529c94485cee85): BREAKING: send frames directly to EventLoop (`Producer#send` renamed to `Producer#send_frame`)
+
 ## v0.2.0 - 2021-01-20
 
 - [73eb326](https://github.com/tcollier/whirled_peas/tree/73eb326426f9814e91e3bc7a60dfd87be3d69f7e): Convert "primitive" data types to strings

data/README.md

@@ -22,13 +22,22 @@ Or install it yourself as:
 
 ## Usage
 
+A Whirled Peas application consists of the following pieces
+
+1. [REQUIRED] The driver, which emits lightweight frame events
+1. [REQUIRED] The main template factory, which builds templates to convert frame events from the driver into terminal graphics
+1. [OPTIONAL] A loading screen template factory, which is used 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 do |_, settings|
+      body.add_box('Title') do |_, settings|
         settings.underline = true
         "Hello #{args['name']}"
       end
@@ -44,13 +53,39 @@ class Driver
   end
 end
 
-WhirledPeas.start(Driver.new, TemplateFactory.new)
+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
 ```
 
-A Whirled Peas application consists of two pieces
+The optional loading screen can be configured like
 
-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
+````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
 
@@ -63,7 +98,7 @@ The driver is the application code to be visualized. This is typically a lightwe
 def start(producer)
   # application code here
 end
-```
+````
 
 The producer provides a single method
 
@@ -113,6 +148,10 @@ end
 
 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.
@@ -195,6 +234,7 @@ The available settigs are
 | `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      |
@@ -304,6 +344,27 @@ Many of these also have a "bright" option:
 - `: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
@@ -356,6 +417,64 @@ class TemplateFactory
 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 <config file> 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 <config file> play_frame move '{"direction":"N"}'
+```
+
+Adding the `--debug` flag will result in just printing out the template's debug information, e.g.
+
+```
+$ whirled_peas <config file> play_frame move '{"direction":"N"}' --debug
++ TEMPLATE [WhirledPeas::UI::Template]
+  - Settings
+    WhirledPeas::UI::TemplateSettings
+      <default>
+  - Children
+    + TitleContainer [WhirledPeas::UI::BoxElement]
+...
+```
+
+#### loading
+
+Displays the configured loading screen for several seconds
+
+```
+$ whirled_peas <config file> loading
+```
+
+Adding the `--debug` flag will result in just printing out the loading template's debug information, e.g.
+
+```
+$ whirled_peas <config file> loading --debug
++ TEMPLATE [WhirledPeas::UI::Template]
+  - Settings
+    WhirledPeas::UI::TemplateSettings
+      <default>
+  - 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.

data/bin/title_fonts

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'whirled_peas'
+
+WhirledPeas.print_title_fonts

data/exe/whirled_peas

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'whirled_peas'
+require 'whirled_peas/command_line'
+
+WhirledPeas::CommandLine.new(ARGV).start

data/lib/whirled_peas.rb

@@ -1,46 +1,26 @@
 require 'logger'
 
+require 'whirled_peas/errors'
+
+require 'whirled_peas/config'
 require 'whirled_peas/frame'
+require 'whirled_peas/template'
 require 'whirled_peas/ui'
+require 'whirled_peas/utils'
 require 'whirled_peas/version'
 
 module WhirledPeas
-  class Error < StandardError; end
-
-  DEFAULT_REFRESH_RATE = 30
-
-  LOGGER_ID = 'MAIN'
-
-  def self.start(driver, template_factory, log_level: Logger::INFO, refresh_rate: DEFAULT_REFRESH_RATE)
-    logger = Logger.new(File.open('whirled_peas.log', 'a'))
-    logger.level = log_level
-    logger.formatter = proc do |severity, datetime, progname, msg|
-      if msg.is_a?(Exception)
-        msg = %Q(#{msg.class}: #{msg.to_s}\n    #{msg.backtrace.join("\n    ")})
-      end
-      "[#{severity}] #{datetime.strftime('%Y-%m-%dT%H:%M:%S.%L')} (#{progname}) - #{msg}\n"
-    end
-
-    event_loop = Frame::EventLoop.new(template_factory, refresh_rate, logger)
-    event_loop_thread = Thread.new do
-      Thread.current.report_on_exception = false
-      event_loop.start
-    end
-
-    Frame::Producer.produce(event_loop: event_loop, logger: logger) do |producer|
-      begin
-        driver.start(producer)
-      rescue => e
-        logger.warn(LOGGER_ID) { 'Driver exited with error, terminating producer...' }
-        logger.error(LOGGER_ID) { e }
-        raise
-      end
-    end
+  def self.config
+    @config ||= Config.new
+  end
 
-    event_loop_thread.join
+  def self.configure(&block)
+    yield config
   end
 
   def self.template(&block)
+    require 'whirled_peas/template/element'
+
     template = UI::Template.new
     yield template, template.settings
     template

data/lib/whirled_peas/command_line.rb

@@ -0,0 +1,266 @@
+module WhirledPeas
+  class Command
+    DEFAULT_REFRESH_RATE = 30
+
+    DEFAULT_LOG_LEVEL = Logger::INFO
+    DEFAULT_FORMATTER = proc do |severity, datetime, progname, msg|
+      if msg.is_a?(Exception)
+        msg = %Q(#{msg.class}: #{msg.to_s}\n    #{msg.backtrace.join("\n    ")})
+      end
+      "[#{severity}] #{datetime.strftime('%Y-%m-%dT%H:%M:%S.%L')} (#{progname}) - #{msg}\n"
+    end
+
+    def self.command_name
+      self.name.split('::').last.sub(/Command$/, '').gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+    end
+
+    def self.build_logger(output, level=DEFAULT_LOG_LEVEL, formatter=DEFAULT_FORMATTER)
+      logger = Logger.new(output)
+      logger.level = level
+      logger.formatter = formatter
+      logger
+    end
+
+    attr_reader :args
+
+    def initialize(args)
+      @args = args
+    end
+
+    def valid?
+      @error_text = nil
+      validate!
+      @error_text.nil?
+    end
+
+    def print_error
+      puts @error_text if @error_text
+      print_usage
+    end
+
+    def start
+    end
+
+    private
+
+    def print_usage
+      puts "Usage: #{$0} #{self.class.command_name}"
+    end
+
+    def validate!
+      # Set @error_text if the options are not valid
+    end
+  end
+
+  class TitleFontsCommand < Command
+    def start
+      require 'whirled_peas/utils/title_font'
+
+      Utils::TitleFont.fonts.keys.each do |key|
+        puts Utils::TitleFont.to_s(key.to_s, key)
+        puts key.inspect
+        puts
+      end
+    end
+  end
+
+  class ConfigCommand < Command
+    def start
+      require args[0]
+    end
+
+    private
+
+    def validate!
+      if args.length == 0
+        @error_text = "#{self.class.command_name} requires a config file"
+      elsif !File.exist?(args[0])
+        @error_text = "File not found: #{args[0]}"
+      elsif args[0][-3..-1] != '.rb'
+        @error_text = 'Config file should be a .rb file'
+      end
+    end
+
+    def print_usage
+      puts "Usage: #{$0} #{self.class.command_name} <config file>"
+    end
+  end
+
+  class StartCommand < ConfigCommand
+    LOGGER_ID = 'MAIN'
+
+    def start
+      super
+      require 'whirled_peas/frame/event_loop'
+      require 'whirled_peas/frame/producer'
+
+      logger = self.class.build_logger(File.open('whirled_peas.log', 'a'))
+
+      consumer = Frame::EventLoop.new(
+        WhirledPeas.config.template_factory,
+        WhirledPeas.config.loading_template_factory,
+        DEFAULT_REFRESH_RATE,
+        logger
+      )
+      Frame::Producer.produce(consumer, logger) do |producer|
+        begin
+          WhirledPeas.config.driver.start(producer)
+        rescue => e
+          logger.warn(LOGGER_ID) { 'Driver exited with error, terminating producer...' }
+          logger.error(LOGGER_ID) { e }
+          raise
+        end
+      end
+    end
+  end
+
+  class ListFramesCommand < ConfigCommand
+    def start
+      super
+      require 'whirled_peas/frame/print_consumer'
+      require 'whirled_peas/frame/producer'
+
+      logger = self.class.build_logger(STDOUT)
+      Frame::Producer.produce(Frame::PrintConsumer.new, logger) do |producer|
+        begin
+          WhirledPeas.config.driver.start(producer)
+        rescue => e
+          logger.warn(LOGGER_ID) { 'Driver exited with error, terminating producer...' }
+          logger.error(LOGGER_ID) { e }
+          raise
+        end
+      end
+    end
+  end
+
+  class PlayFrameCommand < ConfigCommand
+    def start
+      super
+
+      if args.last == '--debug'
+        puts WhirledPeas.config.template_factory.build(frame, frame_args).inspect
+        exit
+      end
+
+      require 'whirled_peas/frame/event_loop'
+      require 'whirled_peas/frame/producer'
+
+      logger = self.class.build_logger(File.open('whirled_peas.log', 'a'))
+
+      consumer = Frame::EventLoop.new(
+        WhirledPeas.config.template_factory,
+        WhirledPeas.config.loading_template_factory,
+        DEFAULT_REFRESH_RATE,
+        logger
+      )
+      Frame::Producer.produce(consumer, logger) do |producer|
+        producer.send_frame(args[1], duration: 5, args: frame_args)
+      end
+    end
+
+    private
+
+    attr_reader :frame, :frame_args
+
+    def validate!
+      super
+      if !@error_text.nil?
+        return
+      elsif args.length < 2
+        @error_text = "#{self.class.command_name} requires a frame name"
+      else
+        require 'json'
+        @frame = args[1]
+        @frame_args = {}
+        JSON.parse(args[2] || '{}').each do |key, value|
+          @frame_args[key.to_sym] = value
+        end
+      end
+    end
+
+    def print_usage
+      puts "Usage: #{$0} #{self.class.command_name} <config file> <frame> [args as a JSON string] [--debug]"
+    end
+  end
+
+  class LoadingCommand < ConfigCommand
+    def start
+      super
+      unless WhirledPeas.config.loading_template_factory
+        puts 'No loading screen configured'
+        exit
+      end
+
+      if args.last == '--debug'
+        puts WhirledPeas.config.loading_template_factory.build.inspect
+        exit
+      end
+
+      require 'whirled_peas/frame/event_loop'
+      require 'whirled_peas/frame/producer'
+
+      logger = self.class.build_logger(File.open('whirled_peas.log', 'a'))
+      consumer = Frame::EventLoop.new(
+        WhirledPeas.config.template_factory,
+        WhirledPeas.config.loading_template_factory,
+        DEFAULT_REFRESH_RATE,
+        logger
+      )
+      Frame::Producer.produce(consumer, logger) { sleep(5) }
+    end
+
+    private
+
+    def print_usage
+      puts "Usage: #{$0} #{self.class.command_name} [--debug]"
+    end
+  end
+
+  class CommandLine
+    COMMANDS = [
+      StartCommand,
+      ListFramesCommand,
+      PlayFrameCommand,
+      LoadingCommand,
+      TitleFontsCommand
+    ].map.with_object({}) { |c, h| h[c.command_name] = c }
+
+    def initialize(args)
+      @args = args
+    end
+
+    def start
+      if args.length < 1
+        print_usage
+        exit(1)
+      end
+
+      command = args.shift
+
+      unless COMMANDS.key?(command)
+        puts "Unrecognized command: #{command}"
+        print_usage
+        exit(1)
+      end
+
+      cmd = COMMANDS[command].new(args)
+
+      unless cmd.valid?
+        cmd.print_error
+        exit(1)
+      end
+
+      cmd.start
+    end
+
+    private
+
+    attr_reader :args
+
+    def print_usage
+      puts "Usage: #{$0} <command> [command options]"
+      puts
+      puts "Available commands: #{COMMANDS.keys.join(', ')}"
+    end
+  end
+end