cli-ui 1.3.0 → 1.4.0

data/lib/cli/ui/frame/frame_style.rb

@@ -0,0 +1,120 @@
+require 'cli/ui/frame'
+
+module CLI
+  module UI
+    module Frame
+      module FrameStyle
+        class << self
+          # rubocop:disable Style/ClassVars
+          @@loaded_styles = []
+
+          def loaded_styles
+            @@loaded_styles.map(&:name)
+          end
+
+          # Lookup a frame style via its name
+          #
+          # ==== Attributes
+          #
+          # * +symbol+ - frame style name to lookup
+          def lookup(name)
+            @@loaded_styles
+              .find { |style| style.name.to_sym == name }
+              .tap  { |style| raise InvalidFrameStyleName, name if style.nil? }
+          end
+
+          def extended(base)
+            @@loaded_styles << base
+            base.extend(Interface)
+          end
+          # rubocop:enable Style/ClassVars
+        end
+
+        class InvalidFrameStyleName < ArgumentError
+          def initialize(name)
+            super
+            @name = name
+          end
+
+          def message
+            keys = FrameStyle.loaded_styles.map(&:inspect).join(',')
+            "invalid frame style: #{@name.inspect}" \
+              " -- must be one of CLI::UI::Frame::FrameStyle.loaded_styles " \
+              "(#{keys})"
+          end
+        end
+
+        # Public interface for FrameStyles
+        # Applied by extending FrameStyle
+        module Interface
+          def name
+            raise NotImplementedError
+          end
+
+          # Returns the character(s) that should be printed at the beginning
+          # of lines inside this frame
+          def prefix
+            raise NotImplementedError
+          end
+
+          # Returns the printing width of the prefix
+          def prefix_width
+            CLI::UI::ANSI.printing_width(prefix)
+          end
+
+          # Draws the "Open" line for this frame style
+          #
+          # ==== Attributes
+          #
+          # * +text+ - (required) the text/title to output in the frame
+          #
+          # ==== Options
+          #
+          # * +:color+ - (required) The color of the frame.
+          #
+          def open(text, color:)
+            raise NotImplementedError
+          end
+
+          # Draws the "Close" line for this frame style
+          #
+          # ==== Attributes
+          #
+          # * +text+ - (required) the text/title to output in the frame
+          #
+          # ==== Options
+          #
+          # * +:color+ - (required) The color of the frame.
+          # * +:right_text+ - Text to print at the right of the line. Defaults to nil
+          #
+          def close(text, color:, right_text: nil)
+            raise NotImplementedError
+          end
+
+          # Draws a "divider" line for the current frame style
+          #
+          # ==== Attributes
+          #
+          # * +text+ - (required) the text/title to output in the frame
+          #
+          # ==== Options
+          #
+          # * +:color+ - (required) The color of the frame.
+          #
+          def divider(text, color: nil)
+            raise NotImplementedError
+          end
+
+          private
+
+          def print_at_x(x, str)
+            CLI::UI::ANSI.cursor_horizontal_absolute(1 + x) + str
+          end
+        end
+      end
+    end
+  end
+end
+
+require 'cli/ui/frame/frame_style/box'
+require 'cli/ui/frame/frame_style/bracket'

data/lib/cli/ui/frame/frame_style/box.rb

@@ -0,0 +1,166 @@
+module CLI
+  module UI
+    module Frame
+      module FrameStyle
+        module Box
+          extend FrameStyle
+
+          VERTICAL    = '┃'
+          HORIZONTAL  = '━'
+          DIVIDER     = '┣'
+          TOP_LEFT    = '┏'
+          BOTTOM_LEFT = '┗'
+
+          class << self
+            def name
+              'box'
+            end
+
+            def prefix
+              VERTICAL
+            end
+
+            # Draws the "Open" line for this frame style
+            #
+            # ==== Attributes
+            #
+            # * +text+ - (required) the text/title to output in the frame
+            #
+            # ==== Options
+            #
+            # * +:color+ - (required) The color of the frame.
+            #
+            # ==== Output:
+            #
+            #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+            #
+            def open(text, color:)
+              edge(text, color: color, first: TOP_LEFT)
+            end
+
+            # Draws a "divider" line for the current frame style
+            #
+            # ==== Attributes
+            #
+            # * +text+ - (required) the text/title to output in the frame
+            #
+            # ==== Options
+            #
+            # * +:color+ - (required) The color of the frame.
+            #
+            # ==== Output:
+            #
+            #   ┣━━ Divider ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+            #
+            def divider(text, color:)
+              edge(text, color: color, first: DIVIDER)
+            end
+
+            # Draws the "Close" line for this frame style
+            #
+            # ==== Attributes
+            #
+            # * +text+ - (required) the text/title to output in the frame
+            #
+            # ==== Options
+            #
+            # * +:color+ - (required) The color of the frame.
+            # * +:right_text+ - Text to print at the right of the line. Defaults to nil
+            #
+            # ==== Output:
+            #
+            #   ┗━━ Close ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+            #
+            def close(text, color:, right_text: nil)
+              edge(text, color: color, right_text: right_text, first: BOTTOM_LEFT)
+            end
+
+            private
+
+            def edge(text, color:, first:, right_text: nil)
+              color = CLI::UI.resolve_color(color)
+
+              preamble = +''
+
+              preamble << color.code << first << (HORIZONTAL * 2)
+
+              text ||= ''
+              unless text.empty?
+                preamble << ' ' << CLI::UI.resolve_text("{{#{color.name}:#{text}}}") << ' '
+              end
+
+              termwidth = CLI::UI::Terminal.width
+
+              suffix = +''
+
+              if right_text
+                suffix << ' ' << right_text << ' '
+              end
+
+              preamble_width = CLI::UI::ANSI.printing_width(preamble)
+              preamble_start = Frame.prefix_width
+              # If prefix_width is non-zero, we need to subtract the width of
+              # the final space, since we're going to write over it.
+              preamble_start -= 1 unless preamble_start.zero?
+              preamble_end = preamble_start + preamble_width
+
+              suffix_width = CLI::UI::ANSI.printing_width(suffix)
+              suffix_end   = termwidth - 2
+              suffix_start = suffix_end - suffix_width
+
+              if preamble_end > suffix_start
+                suffix = ''
+                # if preamble_end > termwidth
+                # we *could* truncate it, but let's just let it overflow to the
+                # next line and call it poor usage of this API.
+              end
+
+              o = +''
+
+              # Shopify's CI system supports terminal emulation, but not some of
+              # the fancier features that we normally use to draw frames
+              # extra-reliably, so we fall back to a less foolproof strategy. This
+              # is probably better in general for cases with impoverished terminal
+              # emulators and no active user.
+              unless [0, '', nil].include?(ENV['CI'])
+                linewidth = [0, termwidth - (preamble_end + suffix_width + 1)].max
+
+                o << color.code << preamble
+                o << color.code << (HORIZONTAL * linewidth)
+                o << color.code << suffix
+                o << CLI::UI::Color::RESET.code << "\n"
+                return o
+              end
+
+              # Jumping around the line can cause some unwanted flashes
+              o << CLI::UI::ANSI.hide_cursor
+
+              # reset to column 1 so that things like ^C don't ruin formatting
+              o << "\r"
+
+              # This code will print out a full line with the given preamble and
+              # suffix, as exemplified below.
+              #
+              # preamble_start                         suffix_start
+              # |                 preamble_end         |            suffix_end
+              # |                 |                    |            | termwidth
+              # |                 |                    |            | |
+              # V                 V                    V            V V
+              # --- Preamble text --------------------- suffix text --
+              o << color.code
+              o << print_at_x(preamble_start, HORIZONTAL * (termwidth - preamble_start)) # draw a full line
+              o << print_at_x(preamble_start, preamble)
+              o << color.code
+              o << print_at_x(suffix_start, suffix)
+              o << CLI::UI::Color::RESET.code
+              o << CLI::UI::ANSI.show_cursor
+              o << "\n"
+
+              o
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cli/ui/frame/frame_style/bracket.rb

@@ -0,0 +1,139 @@
+module CLI
+  module UI
+    module Frame
+      module FrameStyle
+        module Bracket
+          extend FrameStyle
+
+          VERTICAL    = '┃'
+          HORIZONTAL  = '━'
+          DIVIDER     = '┣'
+          TOP_LEFT    = '┏'
+          BOTTOM_LEFT = '┗'
+
+          class << self
+            def name
+              'bracket'
+            end
+
+            def prefix
+              VERTICAL
+            end
+
+            # Draws the "Open" line for this frame style
+            #
+            # ==== Attributes
+            #
+            # * +text+ - (required) the text/title to output in the frame
+            #
+            # ==== Options
+            #
+            # * +:color+ - (required) The color of the frame.
+            #
+            # ==== Output
+            #
+            #   ┏━━ Open
+            #
+            def open(text, color:)
+              edge(text, color: color, first: TOP_LEFT)
+            end
+
+            # Draws a "divider" line for the current frame style
+            #
+            # ==== Attributes
+            #
+            # * +text+ - (required) the text/title to output in the frame
+            #
+            # ==== Options
+            #
+            # * +:color+ - (required) The color of the frame.
+            #
+            # ==== Output:
+            #
+            #   ┣━━ Divider
+            #
+            def divider(text, color:)
+              edge(text, color: color, first: DIVIDER)
+            end
+
+            # Draws the "Close" line for this frame style
+            #
+            # ==== Attributes
+            #
+            # * +text+ - (required) the text/title to output in the frame
+            #
+            # ==== Options
+            #
+            # * +:color+ - (required) The color of the frame.
+            # * +:right_text+ - Text to print at the right of the line. Defaults to nil
+            #
+            # ==== Output:
+            #
+            #   ┗━━ Close
+            #
+            def close(text, color:, right_text: nil)
+              edge(text, color: color, right_text: right_text, first: BOTTOM_LEFT)
+            end
+
+            private
+
+            def edge(text, color:, first:, right_text: nil)
+              color = CLI::UI.resolve_color(color)
+
+              preamble = +''
+
+              preamble << color.code << first << (HORIZONTAL * 2)
+
+              text ||= ''
+              unless text.empty?
+                preamble << ' ' << CLI::UI.resolve_text("{{#{color.name}:#{text}}}") << ' '
+              end
+
+              suffix = +''
+
+              if right_text
+                suffix << ' ' << right_text << ' '
+              end
+
+              o = +''
+
+              # Shopify's CI system supports terminal emulation, but not some of
+              # the fancier features that we normally use to draw frames
+              # extra-reliably, so we fall back to a less foolproof strategy. This
+              # is probably better in general for cases with impoverished terminal
+              # emulators and no active user.
+              unless [0, '', nil].include?(ENV['CI'])
+                o << color.code << preamble
+                o << color.code << suffix
+                o << CLI::UI::Color::RESET.code
+                o << "\n"
+
+                return o
+              end
+
+              preamble_start = Frame.prefix_width
+
+              # If prefix_width is non-zero, we need to subtract the width of
+              # the final space, since we're going to write over it.
+              preamble_start -= 1 unless preamble_start.zero?
+
+              # Prefix_width includes the width of the terminal space, which we
+              # want to remove.  The clamping is done to avoid a negative
+              # preamble start which can occur for the first frame.
+              o << CLI::UI::ANSI.hide_cursor
+
+              # reset to column 1 so that things like ^C don't ruin formatting
+              o << "\r"
+              o << color.code
+              o << print_at_x(preamble_start, preamble + color.code + suffix)
+              o << CLI::UI::Color::RESET.code
+              o << "\n"
+
+              o
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cli/ui/glyph.rb

@@ -5,6 +5,7 @@ module CLI
     class Glyph
       class InvalidGlyphHandle < ArgumentError
         def initialize(handle)
+          super
           @handle = handle
         end
 
@@ -15,7 +16,7 @@ module CLI
         end
       end
 
-      attr_reader :handle, :codepoint, :color, :char, :to_s, :fmt
+      attr_reader :handle, :codepoint, :color, :to_s, :fmt
 
       # Creates a new glyph
       #
@@ -23,12 +24,14 @@ module CLI
       #
       # * +handle+ - The handle in the +MAP+ constant
       # * +codepoint+ - The codepoint used to create the glyph (e.g. +0x2717+ for a ballot X)
+      # * +plain+ - A fallback plain string to be used in case glyphs are disabled
       # * +color+ - What color to output the glyph. Check +CLI::UI::Color+ for options.
       #
-      def initialize(handle, codepoint, color)
+      def initialize(handle, codepoint, plain, color)
         @handle    = handle
         @codepoint = codepoint
         @color     = color
+        @plain     = plain
         @char      = Array(codepoint).pack('U*')
         @to_s      = color.code + char + Color::RESET.code
         @fmt       = "{{#{color.name}:#{char}}}"
@@ -36,16 +39,24 @@ module CLI
         MAP[handle] = self
       end
 
+      # Fetches the actual character(s) to be displayed for a glyph, based on the current OS support
+      #
+      # ==== Returns
+      # Returns the glyph string
+      def char
+        CLI::UI::OS.current.supports_emoji? ? @char : @plain
+      end
+
       # Mapping of glyphs to terminal output
       MAP = {}
-      STAR      = new('*', 0x2b51,           Color::YELLOW) # YELLOW SMALL STAR (⭑)
-      INFO      = new('i', 0x1d4be,          Color::BLUE)   # BLUE MATHEMATICAL SCRIPT SMALL i (𝒾)
-      QUESTION  = new('?', 0x003f,           Color::BLUE)   # BLUE QUESTION MARK (?)
-      CHECK     = new('v', 0x2713,           Color::GREEN)  # GREEN CHECK MARK (✓)
-      X         = new('x', 0x2717,           Color::RED)    # RED BALLOT X (✗)
-      BUG       = new('b', 0x1f41b,          Color::WHITE)  # Bug emoji (🐛)
-      CHEVRON   = new('>', 0xbb,             Color::YELLOW) # RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK (»)
-      HOURGLASS = new('H', [0x231b, 0xfe0e], Color::BLUE)   # HOURGLASS + VARIATION SELECTOR 15 (⌛︎)
+      STAR      = new('*', 0x2b51,           '*', Color::YELLOW) # YELLOW SMALL STAR (⭑)
+      INFO      = new('i', 0x1d4be,          'i', Color::BLUE)   # BLUE MATHEMATICAL SCRIPT SMALL i (𝒾)
+      QUESTION  = new('?', 0x003f,           '?', Color::BLUE)   # BLUE QUESTION MARK (?)
+      CHECK     = new('v', 0x2713,           '√', Color::GREEN)  # GREEN CHECK MARK (✓)
+      X         = new('x', 0x2717,           'X', Color::RED)    # RED BALLOT X (✗)
+      BUG       = new('b', 0x1f41b,          '!', Color::WHITE)  # Bug emoji (🐛)
+      CHEVRON   = new('>', 0xbb,             '»', Color::YELLOW) # RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK (»)
+      HOURGLASS = new('H', [0x231b, 0xfe0e], 'H', Color::BLUE)   # HOURGLASS + VARIATION SELECTOR 15 (⌛︎)
 
       # Looks up a glyph by name
       #