cli-ui 1.2.1 → 1.5.0

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

@@ -0,0 +1,98 @@
+module CLI
+  module UI
+    module Frame
+      module FrameStack
+        COLOR_ENVVAR = 'CLI_FRAME_STACK'
+        STYLE_ENVVAR = 'CLI_STYLE_STACK'
+
+        class StackItem
+          attr_reader :color, :frame_style
+
+          def initialize(color_name, style_name)
+            @color = CLI::UI.resolve_color(color_name)
+            @frame_style = CLI::UI.resolve_style(style_name)
+          end
+        end
+
+        class << self
+          # Fetch all items off the frame stack
+          def items
+            colors = ENV.fetch(COLOR_ENVVAR, '').split(':').map(&:to_sym)
+            styles = ENV.fetch(STYLE_ENVVAR, '').split(':').map(&:to_sym)
+
+            colors.length.times.map do |i|
+              StackItem.new(colors[i], styles[i] || Frame.frame_style)
+            end
+          end
+
+          # Push a new item onto the frame stack.
+          #
+          # Either an item or a :color/:style pair should be pushed onto the stack.
+          #
+          # ==== Attributes
+          #
+          # * +item+ a +StackItem+ to push onto the stack. Defaults to nil
+          #
+          # ==== Options
+          #
+          # * +:color+ the color of the new stack item. Defaults to nil
+          # * +:style+ the style of the new stack item. Defaults to nil
+          #
+          # ==== Raises
+          #
+          # If both an item and a color/style pair are given, raises an +ArgumentError+
+          # If the given item is not a +StackItem+, raises an +ArgumentError+
+          #
+          def push(item = nil, color: nil, style: nil)
+            unless item.nil?
+              unless item.is_a?(StackItem)
+                raise ArgumentError, 'item must be a StackItem'
+              end
+
+              unless color.nil? && style.nil?
+                raise ArgumentError, 'Must give one of item or color: and style:'
+              end
+            end
+
+            item ||= StackItem.new(color, style)
+
+            curr = items
+            curr << item
+
+            serialize(curr)
+          end
+
+          # Removes and returns the last stack item off the stack
+          def pop
+            curr = items
+            ret = curr.pop
+
+            serialize(curr)
+
+            ret.nil? ? nil : ret
+          end
+
+          private
+
+          # Serializes the item stack into two ENV variables.
+          #
+          # This is done to preserve backward compatibility with earlier versions of cli/ui.
+          # This ensures that any code that relied upon previous stack behavior should continue
+          # to work.
+          def serialize(items)
+            colors = []
+            styles = []
+
+            items.each do |item|
+              colors << item.color.name
+              styles << item.frame_style.name
+            end
+
+            ENV[COLOR_ENVVAR] = colors.join(':')
+            ENV[STYLE_ENVVAR] = styles.join(':')
+          end
+        end
+      end
+    end
+  end
+end

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