whirled_peas 0.1.0 → 0.4.1

data/lib/whirled_peas/ui.rb

@@ -1,7 +1,5 @@
-require_relative 'ui/element'
-require_relative 'ui/screen'
-
 module WhirledPeas
   module UI
   end
+  private_constant :UI
 end

data/lib/whirled_peas/ui/canvas.rb

@@ -1,8 +1,39 @@
-require_relative 'stroke'
+require_relative '../utils/ansi'
 
 module WhirledPeas
   module UI
+    # Canvas represent the area of the screen a painter can paint on.
     class Canvas
+      # A Stroke is a single line, formatted string of characters that is painted at
+      # a given position on a Canvas. This class is not meant to be instantiated
+      # directly. Instead, use Canvas#stroke to create a new Stroke.
+      class Stroke
+        attr_reader :left, :top, :chars
+
+        def initialize(left, top, chars)
+          @left = left
+          @top = top
+          @chars = chars
+        end
+
+        def hash
+          [left, top, chars].hash
+        end
+
+        def ==(other)
+          other.is_a?(self.class) && self.hash == other.hash
+        end
+
+        def inspect
+          "Stroke(left=#{left}, top=#{top}, chars=#{chars})"
+        end
+
+        alias_method :eq?, :==
+      end
+      private_constant :Stroke
+
+      EMPTY_STROKE = Stroke.new(nil, nil, nil)
+
       attr_reader :left, :top, :width, :height
 
       def initialize(left, top, width, height)
@@ -12,18 +43,20 @@ module WhirledPeas
         @height = height
       end
 
+      # Return a new Stroke instance, verifying only characters within the canvas
+      # are included in the stroke.
       def stroke(left, top, chars)
         if left >= self.left + self.width || left + chars.length <= self.left
-          Stroke::EMPTY
+          EMPTY_STROKE
         elsif top < self.top || top >= self.top + self.height
-          Stroke::EMPTY
+          EMPTY_STROKE
         else
           if left < self.left
             chars = chars[self.left - left..-1]
             left = self.left
           end
           num_chars = [self.left + self.width, left + chars.length].min - left
-          Stroke.new(left, top, Ansi.first(chars, num_chars))
+          Stroke.new(left, top, Ansi.substring(chars, 0, num_chars))
         end
       end
 

data/lib/whirled_peas/ui/painter.rb

@@ -1,6 +1,8 @@
-require_relative 'ansi'
+require_relative '../template/element'
+require_relative '../template/settings'
+require_relative '../utils/ansi'
+
 require_relative 'canvas'
-require_relative 'settings'
 
 module WhirledPeas
   module UI
@@ -15,43 +17,45 @@ module WhirledPeas
       end
 
       def paint(&block)
-        yield canvas.stroke(canvas.left, canvas.top, justified)
+        text.lines.each.with_index do |line, index|
+          yield canvas.stroke(canvas.left, canvas.top + index, justified(line))
+        end
       end
 
       private
 
       attr_reader :text, :canvas
 
-      def visible
-        if text.value.length <= text.preferred_width
-          text.value
+      def visible(line)
+        if line.length <= text.preferred_width
+          line
         elsif text.settings.align == TextAlign::LEFT
-          text.value[0..text.preferred_width - 1]
+          line[0..text.preferred_width - 1]
         elsif text.settings.align == TextAlign::CENTER
-          left_chop = (text.value.length - text.preferred_width) / 2
-          right_chop = text.value.length - text.preferred_width - left_chop
-          text.value[left_chop..-right_chop - 1]
+          left_chop = (line.length - text.preferred_width) / 2
+          right_chop = line.length - text.preferred_width - left_chop
+          line[left_chop..-right_chop - 1]
         else
-          text.value[-text.preferred_width..-1]
+          line[-text.preferred_width..-1]
         end
       end
 
-      def justified
+      def justified(line)
         format_settings = [*text.settings.color, *text.settings.bg_color]
-        format_settings << TextFormat::BOLD if text.settings.bold?
-        format_settings << TextFormat::UNDERLINE if text.settings.underline?
+        format_settings << Ansi::BOLD if text.settings.bold?
+        format_settings << Ansi::UNDERLINE if text.settings.underline?
 
         ljust = case text.settings.align
         when TextAlign::LEFT
           0
         when TextAlign::CENTER
-          [0, (text.preferred_width - text.value.length) / 2].max
+          [0, (text.preferred_width - line.length) / 2].max
         when TextAlign::RIGHT
-          [0, text.preferred_width - text.value.length].max
+          [0, text.preferred_width - line.length].max
         end
-        rjust = [0, text.preferred_width - text.value.length - ljust].max
+        rjust = [0, text.preferred_width - line.length - ljust].max
         Ansi.format(JUSTIFICATION * ljust, [*text.settings.bg_color]) +
-          Ansi.format(visible, format_settings) +
+          Ansi.format(visible(line), format_settings) +
           Ansi.format(JUSTIFICATION * rjust, [*text.settings.bg_color])
       end
     end

data/lib/whirled_peas/ui/screen.rb

@@ -1,7 +1,7 @@
 require 'highline'
-require 'tty-cursor'
 
-require_relative 'ansi'
+require_relative '../utils/ansi'
+
 require_relative 'painter'
 
 module WhirledPeas
@@ -10,7 +10,6 @@ module WhirledPeas
       def initialize(print_output=true)
         @print_output = print_output
         @terminal = HighLine.new.terminal
-        @cursor = TTY::Cursor
         @strokes = []
         refresh_size!
         Signal.trap('SIGWINCH', proc { self.refresh_size! })
@@ -18,33 +17,20 @@ module WhirledPeas
 
       def paint(template)
         @template = template
-        refresh
-      end
-
-      def needs_refresh?
-        @refreshed_width != width || @refreshed_height != height
+        draw
       end
 
       def refresh
-        strokes = [cursor.hide, cursor.move_to(0, 0), cursor.clear_screen_down]
-        Painter.paint(@template, Canvas.new(0, 0, width, height)) do |stroke|
-          unless stroke.chars.nil?
-            strokes << cursor.move_to(stroke.left, stroke.top)
-            strokes << stroke.chars
-          end
-        end
-        return unless @print_output
-        strokes.each(&method(:print))
-        STDOUT.flush
-        @refreshed_width = width
-        @refreshed_height = height
+        # No need to refresh if the screen dimensions have not changed
+        return if @refreshed_width == width || @refreshed_height == height
+        draw
       end
 
       def finalize
         return unless @print_output
-        print UI::Ansi.clear
-        print cursor.move_to(0, height - 1)
-        print cursor.show
+        print Ansi.clear
+        print Ansi.cursor_pos(top: height - 1)
+        print Ansi.cursor_visible(true)
         STDOUT.flush
       end
 
@@ -57,6 +43,21 @@ module WhirledPeas
       private
 
       attr_reader :cursor, :terminal, :width, :height
+
+      def draw
+        strokes = [Ansi.cursor_visible(false), Ansi.cursor_pos, Ansi.clear_down]
+        Painter.paint(@template, Canvas.new(0, 0, width, height)) do |stroke|
+          unless stroke.chars.nil?
+            strokes << Ansi.cursor_pos(left: stroke.left, top: stroke.top)
+            strokes << stroke.chars
+          end
+        end
+        return unless @print_output
+        strokes.each(&method(:print))
+        STDOUT.flush
+        @refreshed_width = width
+        @refreshed_height = height
+      end
     end
   end
 end

data/lib/whirled_peas/utils.rb

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

data/lib/whirled_peas/utils/ansi.rb

@@ -0,0 +1,103 @@
+module WhirledPeas
+  module UI
+    # Helper module for working with ANSI escape codes. The most useful ANSI escape codes
+    # relate to text formatting.
+    #
+    # @see https://en.wikipedia.org/wiki/ANSI_escape_code
+    module Ansi
+      ESC = "\033"
+
+      # Text formatting constants
+      BOLD = 1
+      UNDERLINE = 4
+
+      # Text and background color constants
+      BLACK = 30
+      RED = 31
+      GREEN = 32
+      YELLOW = 33
+      BLUE = 34
+      MAGENTA = 35
+      CYAN = 36
+      WHITE = 37
+
+      END_FORMATTING = 0
+      private_constant :END_FORMATTING
+
+      class << self
+        def cursor_pos(top: 0, left: 0)
+          "#{ESC}[#{top + 1};#{left + 1}H"
+        end
+
+        def cursor_visible(visible)
+          visible ? "#{ESC}[?25h" : "#{ESC}[?25l"
+        end
+
+        def clear_down
+          "#{ESC}[J"
+        end
+
+        # Format the string with the ANSI escapes codes for the given integer codes
+        #
+        # @param str [String] the string to format
+        # @param codes [Array<Integer>] the integer part of the ANSI escape code (see
+        #   constants in this module for codes and meanings)
+        def format(str, codes)
+          if str.empty? || codes.length == 0
+            str
+          else
+            start_formatting = codes.map(&method(:esc_seq)).join
+            "#{start_formatting}#{str}#{esc_seq(END_FORMATTING)}"
+          end
+        end
+
+        def clear
+          esc_seq(END_FORMATTING)
+        end
+
+        # If the string has unclosed formatting, add the end formatting characters to
+        # the end of the string
+        def close_formatting(str)
+          codes = str.scan(/#{ESC}\[(\d+)m/)
+          if codes.length > 0 && codes.last[0] != END_FORMATTING.to_s
+            "#{str}#{esc_seq(END_FORMATTING)}"
+          else
+            str
+          end
+        end
+
+        # Return a substring of the input string that preservse the formatting
+        #
+        # @param str [String] the (possibly formatted) string
+        # @param first_visible_character [Integer] the index of the first character to
+        #   include in the substring (ignoring all hidden formatting characters)
+        # @param num_visible_chars [Integer] the maximum number of visible characters to
+        #   include in the substring (ignoring all hidden formatting characters)
+        def substring(str, first_visible_character, num_visible_chars)
+          substr = ''
+          is_visible = true
+          visible_index = 0
+          substr_visible_len = 0
+          str.chars.each do |char|
+            in_substring = (visible_index >= first_visible_character)
+            is_visible = false if is_visible && char == ESC
+            visible_index += 1 if is_visible
+            if !is_visible || in_substring
+              substr += char
+              substr_visible_len += 1 if is_visible
+            end
+            is_visible = true if !is_visible && char == 'm'
+            break if substr_visible_len == num_visible_chars
+          end
+          close_formatting(substr)
+        end
+
+        private
+
+        def esc_seq(code)
+          "#{ESC}[#{code}m"
+        end
+      end
+    end
+  end
+end

data/lib/whirled_peas/{ui/ansi.rb → utils/color.rb}

@@ -1,83 +1,26 @@
+require_relative 'ansi'
+
 module WhirledPeas
   module UI
-    DEBUG_COLOR = ARGV.include?('--debug-color')
-
-    module Ansi
-      BOLD = 1
-      UNDERLINE = 4
-
-      BLACK = 30
-      RED = 31
-      GREEN = 32
-      YELLOW = 33
-      BLUE = 34
-      MAGENTA = 35
-      CYAN = 36
-      WHITE = 37
-
-      END_FORMATTING = 0
-
-      class << self
-        def format(str, codes)
-          if str.empty? || codes.length == 0
-            str
-          else
-            start_formatting = codes.map(&method(:esc_seq)).join
-            "#{start_formatting}#{str}#{esc_seq(END_FORMATTING)}"
-          end
-        end
-
-        def clear
-          esc_seq(END_FORMATTING)
-        end
-
-        def hidden_width(line)
-          return 0 if DEBUG_COLOR
-          width = 0
-          line.scan(/\033\[\d+m/).each { |f| width += f.length }
-          width
-        end
-
-        def close_formatting(line)
-          codes = line.scan(DEBUG_COLOR ? /<(\d+)>/ : /\033\[(\d+)m/)
-          if codes.length > 0 && codes.last[0] != END_FORMATTING.to_s
-            "#{line}#{esc_seq(END_FORMATTING)}"
-          else
-            line
-          end
-        end
-
-        def first(str, num_visible_chars)
-          return str if str.length <= num_visible_chars + hidden_width(str)
-          result = ''
-          in_format = false
-          visible_len = 0
-          str.chars.each do |char|
-            in_format = true if !in_format && char == "\033"
-            result += char
-            visible_len += 1 if !in_format
-            in_format = false if in_format && char == 'm'
-            break if visible_len == num_visible_chars
-          end
-          close_formatting(result)
-        end
-
-        private
-
-        def esc_seq(code)
-          DEBUG_COLOR ? "<#{code}>" : "\033[#{code}m"
-        end
-      end
-    end
-
+    # An abstract class that encapsulates colors for a specific use case
     class Color
+      # The ANSI codes for bright colors are offset by this much from their
+      # standard versions
       BRIGHT_OFFSET = 60
       private_constant :BRIGHT_OFFSET
 
+      # Validate the `color` argument is either (1) nil, (2) a valid Color constant in
+      # this class or (3) a symbol that maps to valid Color constant. E.g. if there
+      # is a RED constant in an implementing class, then :red or :bright_red are
+      # valid values for `color`
+      #
+      # @param color [Color|Symbol]
+      # @return [Color|Symbol] the value passed in if valid, otherwise an ArgumentError
+      #   is raised.
       def self.validate!(color)
         return unless color
         if color.is_a?(Symbol)
-          error_message = "Unsupported #{self.name.split('::').last}: #{color}"
+          error_message = "Unsupported #{self.name.split('::').last}: #{color.inspect}"
           match = color.to_s.match(/^(bright_)?(\w+)$/)
           begin
             color = self.const_get(match[2].upcase)
@@ -109,6 +52,15 @@ module WhirledPeas
         bright? ? self : self.class.new(@code + BRIGHT_OFFSET, true)
       end
 
+      def hash
+        [@code, @bright].hash
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && self.hash == other.hash
+      end
+      alias_method :eq?, :==
+
       def to_s
         @code.to_s
       end
@@ -145,10 +97,5 @@ module WhirledPeas
       WHITE = new(Ansi::WHITE)
       GRAY = BLACK.bright
     end
-
-    module TextFormat
-      BOLD = Ansi::BOLD
-      UNDERLINE = Ansi::UNDERLINE
-    end
   end
 end