whirled_peas 0.7.1 → 0.11.0

data/lib/whirled_peas/component/list_with_active.rb

@@ -0,0 +1,88 @@
+module WhirledPeas
+  module Component
+    class ListWithActive
+      attr_accessor :active_index, :active_color, :active_bg_color, :separator
+
+      attr_reader :items
+
+      attr_writer :flow, :viewport_size
+
+      def items=(value)
+        @items = value.map(&:to_s)
+      end
+
+      def flow
+        @flow || :l2r
+      end
+
+      def total_size
+        @total_size ||= if flow == :l2r
+          size = separator.nil? ? 0 : (items.count - 1) * separator.length
+          items.each { |item| size += item.length }
+          size
+        else
+          items.count + (separator.nil? ? 0 : items.count - 1)
+        end
+      end
+
+      def viewport_size
+        @viewport_size || total_size
+      end
+
+      def compose(composer, settings)
+        %i[items active_index].each do |required_attr|
+          if send(required_attr).nil?
+            raise ArugmentError, "Require field #{required_attr} missing"
+          end
+        end
+
+        composer.add_box('ListWithActive') do |composer, settings|
+          settings.flow = flow
+          settings.align = :left
+          settings.full_border
+          if flow == :l2r
+            settings.width = viewport_size
+            active_start = separator.nil? ? 0 : active_index * separator.length
+            items.first(active_index).each do |item|
+              active_start += item.length
+            end
+            active_size = items[active_index].length
+          else
+            settings.height = viewport_size
+            active_start = active_index + (separator.nil? ? 0 : active_index)
+            active_size = 1
+          end
+
+          if viewport_size < total_size
+            front_padding = (viewport_size - active_size) * 0.667
+            offset = (active_start - front_padding).round
+            if offset < 0
+              offset = 0
+            elsif offset > total_size - viewport_size
+              offset = total_size - viewport_size
+            end
+
+            if flow == :l2r
+              settings.content_start.left = -offset
+              settings.scrollbar.horiz = true
+            else
+              settings.content_start.top = -offset
+              settings.scrollbar.vert = true
+            end
+          end
+
+          items.each.with_index do |item, index|
+            composer.add_text { separator } if !separator.nil? && index > 0
+            composer.add_text do |_, settings|
+              if index == active_index
+                settings.bg_color = active_bg_color
+                settings.color = active_color
+              end
+              item
+            end
+          end
+        end
+      end
+    end
+  end
+end

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/box_painter.rb

@@ -55,8 +55,8 @@ module WhirledPeas
       private
 
       def paint_horizontally(canvas, canvas_coords, &block)
-        stroke_left = canvas_coords.content_left
-        stroke_top = canvas_coords.content_top
+        stroke_left = canvas_coords.offset_content_left
+        stroke_top = canvas_coords.offset_content_top
         children_width = 0
         each_child { |c| children_width += c.dimensions.outer_width }
         left_offset, spacing_offset = horiz_justify_offset(children_width)
@@ -76,8 +76,8 @@ module WhirledPeas
       end
 
       def paint_vertically(canvas, canvas_coords, &block)
-        stroke_left = canvas_coords.content_left
-        stroke_top = canvas_coords.content_top
+        stroke_left = canvas_coords.offset_content_left
+        stroke_top = canvas_coords.offset_content_top
         children_height = 0
         each_child { |c| children_height += c.dimensions.outer_height }
         top_offset, spacing_offset = vert_justify_offset(children_height)

data/lib/whirled_peas/graphics/composer.rb

@@ -1,8 +1,11 @@
 require 'whirled_peas/settings/box_settings'
+require 'whirled_peas/settings/graph_settings'
 require 'whirled_peas/settings/grid_settings'
 require 'whirled_peas/settings/text_settings'
+require 'whirled_peas/settings/theme_library'
 
 require_relative 'box_painter'
+require_relative 'graph_painter'
 require_relative 'grid_painter'
 require_relative 'text_painter'
 
@@ -23,8 +26,10 @@ module WhirledPeas
         "Element-#{@counter}"
       end
 
-      def self.build
-        settings = Settings::BoxSettings.new
+      def self.build(theme_name=nil, &block)
+        theme_name ||= Settings::ThemeLibrary.default_name
+        theme = Settings::ThemeLibrary.get(theme_name)
+        settings = Settings::BoxSettings.new(theme)
         template = BoxPainter.new('TEMPLATE', settings)
         composer = Composer.new(template)
         value = yield composer, settings
@@ -45,6 +50,7 @@ module WhirledPeas
         child = TextPainter.new(name, child_settings)
         # TextPainters are not composable, so yield nil
         content = yield nil, child_settings
+        child_settings.validate!
         unless self.class.stringable?(content)
           raise ArgumentError, "Unsupported type for text: #{content.class}"
         end
@@ -52,11 +58,29 @@ module WhirledPeas
         painter.add_child(child)
       end
 
+      def add_graph(name=self.class.next_name, &block)
+        child_settings = Settings::GraphSettings.inherit(painter.settings)
+        child = GraphPainter.new(name, child_settings)
+        # GraphPainters are not composable, so yield nil
+        content = yield nil, child_settings
+        child_settings.validate!
+        unless content.is_a?(Array) && content.length > 0
+          raise ArgumentError, 'Graphs require a non-empty array as the content'
+        end
+        child.content = content
+        painter.add_child(child)
+      end
+
+      def add_component(component)
+        component.compose(self, settings)
+      end
+
       def add_box(name=self.class.next_name, &block)
         child_settings = Settings::BoxSettings.inherit(painter.settings)
         child = BoxPainter.new(name, child_settings)
         composer = self.class.new(child)
         value = yield composer, child.settings
+        child_settings.validate!
         painter.add_child(child)
         if !child.children? && self.class.stringable?(value)
           composer.add_text("#{name}-Text") { value.to_s }
@@ -68,6 +92,7 @@ module WhirledPeas
         child = GridPainter.new(name, child_settings)
         composer = self.class.new(child)
         values = yield composer, child.settings
+        child_settings.validate!
         painter.add_child(child)
         if !child.children? && values.is_a?(Array)
           values.each.with_index do |value, index|

data/lib/whirled_peas/graphics/container_coords.rb

@@ -9,11 +9,11 @@ module WhirledPeas
       end
 
       def left
-        start_left + settings.position.left
+        start_left
       end
 
       def top
-        start_top + settings.position.top
+        start_top
       end
 
       def border_left
@@ -36,10 +36,32 @@ module WhirledPeas
         padding_left + settings.padding.left + col_index * grid_width
       end
 
+      def offset_content_left(col_index=0)
+        if settings.content_start.left
+          content_left(col_index) + settings.content_start.left
+        elsif settings.content_start.right
+          left_offset = dimensions.content_width - dimensions.children_width
+          content_left(col_index) + left_offset - settings.content_start.right
+        else
+          content_left(col_index)
+        end
+      end
+
       def content_top(row_index=0)
         padding_top + settings.padding.top + row_index * grid_height
       end
 
+      def offset_content_top(row_index=0)
+        if settings.content_start.top
+          content_top(row_index) + settings.content_start.top
+        elsif settings.content_start.bottom
+          top_offset = dimensions.content_height - dimensions.children_height
+          content_top(row_index) + top_offset - settings.content_start.bottom
+        else
+          content_top(row_index)
+        end
+      end
+
       def inner_grid_width
         settings.padding.left +
           dimensions.content_width +

data/lib/whirled_peas/graphics/container_painter.rb

@@ -2,9 +2,12 @@ require 'whirled_peas/utils/formatted_string'
 
 require_relative 'container_coords'
 require_relative 'painter'
+require_relative 'scrollbar_helper'
 
 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 +16,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 +95,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 +105,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 +133,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 +155,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 +176,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 +187,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 +198,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 +209,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,
@@ -163,16 +217,12 @@ module WhirledPeas
           settings.border.style.right_vert,
         ) do
           if settings.scrollbar.vert?
-            if dimensions.children_height <= canvas_coords.grid_height || children.first.settings.position.top > 0
-              scrollbar_char = GUTTER
-            else
-              scrollbar_char = vert_scroll_char(
-                dimensions.children_height + dimensions.padding_height,
-                canvas_coords.inner_grid_height,
-                -children.first.settings.position.top,
-                row_within_cell
-              )
-            end
+            scrollbar_char = ScrollbarHelper.vert_char(
+              dimensions.children_height + dimensions.padding_height,
+              canvas_coords.inner_grid_height,
+              canvas_coords.top - canvas_coords.offset_content_top,
+              row_within_cell
+            )
             PADDING * canvas_coords.inner_grid_width + scrollbar_char
           else
             PADDING * canvas_coords.inner_grid_width
@@ -180,6 +230,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,
@@ -187,85 +238,15 @@ module WhirledPeas
           settings.border.style.right_vert,
         ) do
           canvas_coords.inner_grid_width.times.map do |col_within_cell|
-            horiz_scroll_char(
+            ScrollbarHelper.horiz_char(
               dimensions.children_width + dimensions.padding_width,
               canvas_coords.inner_grid_width,
-              -children.first.settings.position.left,
+              canvas_coords.left - canvas_coords.offset_content_left,
               col_within_cell
             )
           end.join
         end
       end
-
-      GUTTER = ' '
-      HORIZONTAL = %w[▗ ▄ ▖]
-      VERTICAL = %w[
-        ▗
-        ▐
-        ▝
-      ]
-
-      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
-
-      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
-
-      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
-        # that the viewable content has in the total content area. For example, a content area
-        # that is 50 columns wide with a view port that is 20 columns wide might look like
-        #
-        #    +---------1-----****2*********3******---4---------+
-        #    |               *                   *             |
-        #    |   hidden      *     viewable      *   hidden    |
-        #    |               *                   *             |
-        #    +---------1-----****2*********3******---4---------+
-        #
-        # The scoll gutter, would look like
-        #
-        #                    |......********.....|
-        #
-        # Scrolling all the way to the right results in
-        #
-        #    +---------1---------2---------3*********4*********+
-        #    |                             *                   *
-        #    |            hidden           *     viewable      *
-        #    |                             *                   *
-        #    +---------1---------2---------3*********4*********+
-        #                                  |...........********|
-
-        # 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
-        viewable_start = first_visible.to_f / total_count
-        viewable_end = (first_visible + viewable_count).to_f / total_count
-
-        # Always use the same length for the scroll bar so it does not give an inchworm effect
-        # as it scrolls along.
-        #
-        # Also, double the value now to get granularity for half width
-        # scrollbar characters.
-        scrollbar_length = ((2 * viewable_count ** 2).to_f / total_count).ceil
-        scrollbar_start = ((2 * first_visible * viewable_count).to_f / total_count).floor
-
-        first_half = (scrollbar_start...scrollbar_start + scrollbar_length).include?(2 * curr)
-        second_half = (scrollbar_start...scrollbar_start + scrollbar_length).include?(2 * curr + 1)
-
-        if first_half && second_half
-          chars[1]
-        elsif first_half
-          chars[2]
-        elsif second_half
-          chars[0]
-        else
-          GUTTER
-        end
-      end
     end
     private_constant :ContainerPainter
   end