whirled_peas 0.7.1 → 0.8.0

data/lib/whirled_peas/config.rb

@@ -1,13 +1,47 @@
+require 'logger'
+
 module WhirledPeas
   class Config
-    attr_writer :driver, :template_factory
-    attr_accessor :loading_template_factory
+    # Refreshed rate measured in frames per second
+    DEFAULT_REFRESH_RATE = 30
+
+    DEFAULT_LOG_LEVEL = Logger::INFO
+    DEFAULT_LOG_FILE = 'whirled_peas.log'
 
-    def driver
-      unless @driver
-        raise ConfigurationError, 'driver must be configured'
+    # This formatter expects a loggers to send `progname` in each log call. This value
+    # should be an all uppercase version of the module or class that is invoking the
+    # logger. Ruby's logger supports setting this value on a per-log statement basis
+    # when the log message is passed in through a block:
+    #
+    #   logger.<level>(progname, &block)
+    #
+    # E.g.
+    #
+    #   class Foo
+    #     def bar
+    #       logger.warn('FOO') { 'Something fishy happened in #bar' }
+    #     end
+    #   end
+    #
+    # The block format also has the advantage that the evaluation of the block only
+    # occurs if the message gets logged. So expensive to calculate debug statements
+    # will not impact the performance of the application if the log level is INFO or
+    # higher.
+    DEFAULT_FORMATTER = proc do |severity, datetime, progname, msg|
+      # Convert an instance of an exception into a nicely formatted message string
+      if msg.is_a?(Exception)
+        msg = %Q(#{msg.class}: #{msg.to_s}\n    #{msg.backtrace.join("\n    ")})
       end
-      @driver
+      "[#{severity}] #{datetime.strftime('%Y-%m-%dT%H:%M:%S.%L')} (#{progname}) - #{msg}\n"
+    end
+
+    attr_writer :application, :template_factory, :refresh_rate, :log_level, :log_formatter, :log_file
+
+    def application
+      unless @application
+        raise ConfigurationError, 'application must be configured'
+      end
+      @application
     end
 
     def template_factory
@@ -16,6 +50,22 @@ module WhirledPeas
       end
       @template_factory
     end
+
+    def refresh_rate
+      @refresh_rate || DEFAULT_REFRESH_RATE
+    end
+
+    def log_level
+      @log_level || DEFAULT_LOG_LEVEL
+    end
+
+    def log_formatter
+      @log_formatter || DEFAULT_FORMATTER
+    end
+
+    def log_file
+      @log_file || DEFAULT_LOG_FILE
+    end
   end
   private_constant :Config
 end

data/lib/whirled_peas/device.rb

@@ -0,0 +1,5 @@
+module WhirledPeas
+  module Device
+  end
+  private_constant :Device
+end

data/lib/whirled_peas/device/null_device.rb

@@ -0,0 +1,8 @@
+module WhirledPeas
+  module Device
+    class NullDevice
+      def handle_renders(*)
+      end
+    end
+  end
+end

data/lib/whirled_peas/device/output_file.rb

@@ -0,0 +1,19 @@
+require 'whirled_peas/utils/file_handler'
+
+module WhirledPeas
+  module Device
+    class OutputFile
+      def initialize(file)
+        @file = file
+      end
+
+      def handle_renders(renders)
+        Utils::FileHandler.write(file, renders)
+      end
+
+      private
+
+      attr_reader :file
+    end
+  end
+end

data/lib/whirled_peas/device/screen.rb

@@ -0,0 +1,26 @@
+require 'highline'
+
+module WhirledPeas
+  module Device
+    class Screen
+      def initialize(refresh_rate, output: STDOUT)
+        @refresh_rate = refresh_rate
+        @output = output
+      end
+
+      def handle_renders(renders)
+        renders.each do |strokes|
+          frame_at = Time.now
+          output.print(strokes)
+          output.flush
+          next_frame_at = frame_at + 1.0 / refresh_rate
+          sleep([0, next_frame_at - Time.now].max)
+        end
+      end
+
+      private
+
+      attr_reader :refresh_rate, :output
+    end
+  end
+end

data/lib/whirled_peas/graphics/container_painter.rb

@@ -5,6 +5,8 @@ require_relative 'painter'
 
 module WhirledPeas
   module Graphics
+    # Abstract Painter for containers. Containers (as the name implies) contain other child
+    # elements and must delegate painting of the children to the children themselves.
     class ContainerPainter < Painter
       PADDING = ' '
 
@@ -13,38 +15,65 @@ module WhirledPeas
         @children = []
       end
 
+      # Paint the common attributes of containers (e.g. border and background color). Any
+      # class that inherits from this one should call `super` at the start of its #paint
+      # method, before painting its children.
       def paint(canvas, left, top, &block)
         return unless canvas.writable?
         return unless needs_printing?
         canvas_coords = coords(left, top)
+
+        # Paint the border, background color, and scrollbar starting from the top left
+        # border position, moving down row by row until we reach the bottom border
+        # position
         stroke_left = canvas_coords.border_left
         stroke_top = canvas_coords.border_top
+
+        # All strokes will have the same formatting options
         formatting = [*settings.border.color, *settings.bg_color]
+
+        # Paint the top border if the settings call for it
         if settings.border.top?
           canvas.stroke(stroke_left, stroke_top, top_border_stroke(canvas_coords), formatting, &block)
           stroke_top += 1
         end
+        # Precalculate the middle border container grids with more than 1 row
         middle_border = dimensions.num_rows > 1 ? middle_border_stroke(canvas_coords) : ''
+
+        # Paint each grid row by row
         dimensions.num_rows.times do |row_num|
+          # In a grid with N rows, we will need to paint N - 1 inner horizontal borders.
+          # This code treats the inner horizontal border as the top of each row except for
+          # the first one.
           if row_num > 0 && settings.border.inner_horiz?
             canvas.stroke(stroke_left, stroke_top, middle_border, formatting, &block)
             stroke_top += 1
           end
+
+          # Paint the interior of each row (horizontal borders, veritical scroll bar and
+          # background color for the padding and content area)
           canvas_coords.inner_grid_height.times do |row_within_cell|
             canvas.stroke(stroke_left, stroke_top, content_line_stroke(canvas_coords, row_within_cell), formatting, &block)
             stroke_top += 1
           end
+
+          # Paint the horizontal scroll bar is the settings call for it
           if settings.scrollbar.horiz?
             canvas.stroke(stroke_left, stroke_top, bottom_scroll_stroke(canvas_coords), formatting, &block)
             stroke_top += 1
           end
         end
+
+        # Paint the bottom border if the settings call for it
         if settings.border.bottom?
           canvas.stroke(stroke_left, stroke_top, bottom_border_stroke(canvas_coords), formatting, &block)
           stroke_top += 1
         end
       end
 
+      # Tightly manage access to the children (rather than simply exposing the underlying
+      # array). This allows subclasses to easily modify behavior based on that element's
+      # specific settings.
       def add_child(child)
         children << child
       end
@@ -65,6 +94,8 @@ module WhirledPeas
 
       attr_reader :children
 
+      # Determine if there is anything to print for the container (this does not accont for
+      # children, just the border, scrollbar, and background color)
       def needs_printing?
         return true if settings.bg_color
         return true if settings.border.outer?
@@ -73,10 +104,15 @@ module WhirledPeas
         settings.scrollbar.horiz? || settings.scrollbar.vert?
       end
 
+      # Return an object that allows easy access to important coordinates within the container,
+      # e.g. the left position where the left border is printed
       def coords(left, top)
         ContainerCoords.new(dimensions, settings, left, top)
       end
 
+      # @return [Array<Integer>] a two-item array, the first being the amount of horizontal
+      #   spacing to paint *before the first* child and the second being the amount of spacing
+      #   to paint *between each* child
       def horiz_justify_offset(containing_width)
         if settings.align_center?
           [(dimensions.content_width - containing_width) / 2, 0]
@@ -96,6 +132,9 @@ module WhirledPeas
         end
       end
 
+      # @return [Array<Integer>] a two-item array, the first being the amount of vertical
+      #   spacing to paint *above the first* child and the second being the amount of spacing
+      #   to paint *between each* child
       def vert_justify_offset(containing_height)
         if settings.valign_middle?
           [(dimensions.content_height - containing_height) / 2, 0]
@@ -115,6 +154,16 @@ module WhirledPeas
         end
       end
 
+      # Return a stroke for one line of the container
+      #
+      # @param left_border [String] the character to print as the first character if there
+      #   is a left border
+      # @param junc_border [String] the character to print as the junction between two grid
+      #   columns if there is an inner vertical border
+      # @param right_border [String] the character to print as the last character if there
+      #   is a right border
+      # @block [String] the block should yield a string that represents the interior
+      #   (including padding) of a grid cell
       def line_stroke(left_border, junc_border, right_border, &block)
         stroke = ''
         stroke += left_border if settings.border.left?
@@ -126,6 +175,7 @@ module WhirledPeas
         stroke
       end
 
+      # Return the stroke for the top border
       def top_border_stroke(canvas_coords)
         line_stroke(
           settings.border.style.top_left,
@@ -136,6 +186,7 @@ module WhirledPeas
         end
       end
 
+      # Return the stroke for an inner horizontal border
       def middle_border_stroke(canvas_coords)
         line_stroke(
           settings.border.style.left_junc,
@@ -146,6 +197,7 @@ module WhirledPeas
         end
       end
 
+      # Return the stroke for the bottom border
       def bottom_border_stroke(canvas_coords)
         line_stroke(
           settings.border.style.bottom_left,
@@ -156,6 +208,7 @@ module WhirledPeas
         end
       end
 
+      # Return the stroke for a grid row between any borders
       def content_line_stroke(canvas_coords, row_within_cell)
         line_stroke(
           settings.border.style.left_vert,
@@ -180,6 +233,7 @@ module WhirledPeas
         end
       end
 
+      # Return the stroke for the horizontal scroll bar
       def bottom_scroll_stroke(canvas_coords)
         line_stroke(
           settings.border.style.left_vert,
@@ -197,6 +251,7 @@ module WhirledPeas
         end
       end
 
+      # Contants to paint scrollbars
       GUTTER = ' '
       HORIZONTAL = %w[▗ ▄ ▖]
       VERTICAL = %w[
@@ -205,16 +260,33 @@ module WhirledPeas
         ▝
       ]
 
+      # Determine the character to paint the horizontal scroll bar with for the given column
+      #
+      # @see #scroll_char for more details
       def horiz_scroll_char(col_count, viewable_col_count, first_visible_col, curr_col)
         scroll_char(col_count, viewable_col_count, first_visible_col, curr_col, HORIZONTAL)
       end
 
+      # Determine the character to paint the vertical scroll bar with for the given row
+      #
+      # @see #scroll_char for more details
       def vert_scroll_char(row_count, viewable_row_count, first_visible_row, curr_row)
         scroll_char(row_count, viewable_row_count, first_visible_row, curr_row, VERTICAL)
       end
 
       private
 
+      # Determine which character to paint a for a scrollbar
+      #
+      # @param total_count [Integer] total number of rows/columns in the content
+      # @param viewable_count [Integer] number of rows/columns visible in the viewport
+      # @param first_visible [Integer] zero-based index of the first row/column that is visible
+      #   in the viewport
+      # @param curr [Integer] zero-based index of the row/column (relative to the first visible
+      #   row/column) that the painted character is being requested for
+      # @param chars [Array<String>] an array with three 1-character strings, the frist is the
+      #   "second half" scrollbar character, the second is the "full" scrollbar character, and
+      #   the third is the "first half" scrollbar character.
       def scroll_char(total_count, viewable_count, first_visible, curr, chars)
         return GUTTER unless total_count > 0 && viewable_count > 0
         # The scroll handle has the exact same relative size and position in the scroll gutter
@@ -239,6 +311,25 @@ module WhirledPeas
         #    |                             *                   *
         #    +---------1---------2---------3*********4*********+
         #                                  |...........********|
+        #
+        # Returning to the first example, we can match up the arguments to this method to the
+        # diagram
+        #
+        #                       total_count = 50
+        #    |<----------------------------------------------->|
+        #    |                                                 |
+        #    |                veiwable_count = 20              |
+        #    |               |<----------------->|             |
+        #    ↓               ↓                   ↓             ↓
+        #    +---------1-----****2*********3******---4---------+
+        #    |               *                   *             |
+        #    |   hidden      *     viewable      *   hidden    |
+        #    |               *                   *             |
+        #    +---------1-----****2*********3******---4---------+
+        #                    |......****?***.....|
+        #                    ↑          ↑
+        #      first_visible = 16       |
+        #                             curr = 11
 
         # The first task of determining how much of the handle is visible in a row/column is to
         # calculate the range (as a precentage of the total) of viewable items

data/lib/whirled_peas/graphics/painter.rb

@@ -1,5 +1,7 @@
 module WhirledPeas
   module Graphics
+    # Abstract base Painter class. Given a canvas and start coordinates (left, top), a painter
+    # is responsible for generating the "strokes" that display the element.
     class Painter
       attr_reader :name, :settings
 
@@ -8,9 +10,17 @@ module WhirledPeas
         @name = name
       end
 
+      # Paint the element onto the canvas by yielding strokes to the block. A stroke is composed
+      # of a left, top, and chars. E.g.
+      #
+      #   yield 10, 3, 'Hello World!'
+      #
+      # paints the string "Hello World!" in the 10th column from the left, 3rd row down.
       def paint(canvas, left, top, &block)
       end
 
+      # Return a dimension object that provider the `outer_width` and `outer_height` of the
+      # element being painted.
       def dimensions
       end
 

data/lib/whirled_peas/graphics/renderer.rb

@@ -9,13 +9,19 @@ module WhirledPeas
         @height = height
       end
 
-      def paint(&block)
+      def paint
         # Modify the template's settings so that it fills the entire screen
         template.settings.width = width
         template.settings.height = height
         template.settings.sizing = :border
         template.settings.set_margin(left: 0, top: 0, right: 0, bottom: 0)
-        template.paint(Canvas.new(0, 0, width, height), 0, 0, &block)
+        strokes = [Utils::Ansi.cursor_visible(false), Utils::Ansi.cursor_pos, Utils::Ansi.clear_down]
+        template.paint(Canvas.new(0, 0, width, height), 0, 0) do |left, top, fstring|
+          next unless fstring.length > 0
+          strokes << Utils::Ansi.cursor_pos(left: left, top: top)
+          strokes << fstring
+        end
+        strokes.join
       end
 
       private

data/lib/whirled_peas/utils/ansi.rb

@@ -28,6 +28,19 @@ module WhirledPeas
       BRIGHT_OFFSET = 60
 
       class << self
+        def with_screen(output, width: nil, height: nil, &block)
+          require 'highline'
+          unless width && height
+            width, height = HighLine.new.terminal.terminal_size
+          end
+          yield width, height
+        ensure
+          output.print clear
+          output.print cursor_pos(top: height - 1)
+          output.print cursor_visible(true)
+          output.flush
+        end
+
         def cursor_pos(top: 0, left: 0)
           "#{ESC}[#{top + 1};#{left + 1}H"
         end

data/lib/whirled_peas/utils/file_handler.rb

@@ -0,0 +1,57 @@
+require 'base64'
+require 'zlib'
+
+module WhirledPeas
+  module Utils
+    module FileHandler
+      module FileWriter
+        VERSION = '1'
+
+        def self.write(fp, renders)
+          fp.puts renders.count
+          renders.each do |strokes|
+            encoded = Base64.encode64(strokes)
+            fp.puts encoded.count("\n")
+            fp.puts encoded
+          end
+        end
+      end
+      private_constant :FileWriter
+
+      class FileReaderV1
+        def self.read(fp)
+          num_renders = Integer(fp.readline.chomp, 10)
+          num_renders.times.map do
+            num_strokes = Integer(fp.readline.chomp, 10)
+            Base64.decode64(num_strokes.times.map { fp.readline }.join)
+          end
+        end
+
+        private
+
+        attr_reader :file
+      end
+      private_constant :FileReaderV1
+
+      READERS = {
+        '1' => FileReaderV1
+      }
+      private_constant :READERS
+
+      def self.write(file, renders)
+        Zlib::GzipWriter.open(file, Zlib::BEST_COMPRESSION) do |gz|
+          gz.puts FileWriter::VERSION
+          FileWriter.write(gz, renders)
+        end
+      end
+
+      def self.read(file)
+        Zlib::GzipReader.open(file) do |gz|
+          version = gz.gets.chomp
+          raise ArgumentError, "Invalid file: #{file}" unless READERS.key?(version)
+          READERS[version].read(gz)
+        end
+      end
+    end
+  end
+end