cli-ui 0.1.2

data/lib/cli/ui/ansi.rb

@@ -0,0 +1,155 @@
+require 'cli/ui'
+
+module CLI
+  module UI
+    module ANSI
+      ESC = "\x1b"
+
+      # ANSI escape sequences (like \x1b[31m) have zero width.
+      # when calculating the padding width, we must exclude them.
+      # This also implements a basic version of utf8 character width calculation like
+      # we could get for real from something like utf8proc.
+      #
+      def self.printing_width(str)
+        zwj = false
+        strip_codes(str).codepoints.reduce(0) do |acc, cp|
+          if zwj
+            zwj = false
+            next acc
+          end
+          case cp
+          when 0x200d # zero-width joiner
+            zwj = true
+            acc
+          else
+            acc + 1
+          end
+        end
+      end
+
+      # Strips ANSI codes from a str
+      #
+      # ==== Attributes
+      #
+      # - +str+ - The string from which to strip codes
+      #
+      def self.strip_codes(str)
+        str.gsub(/\x1b\[[\d;]+[A-z]|\r/, '')
+      end
+
+      # Returns an ANSI control sequence
+      #
+      # ==== Attributes
+      #
+      # - +args+ - Argument to pass to the ANSI control sequence
+      # - +cmd+ - ANSI control sequence Command
+      #
+      def self.control(args, cmd)
+        ESC + "[" + args + cmd
+      end
+
+      # https://en.wikipedia.org/wiki/ANSI_escape_code#graphics
+      def self.sgr(params)
+        control(params.to_s, 'm')
+      end
+
+      # Cursor Movement
+
+      # Move the cursor up n lines
+      #
+      # ==== Attributes
+      #
+      # * +n+ - number of lines by which to move the cursor up
+      #
+      def self.cursor_up(n = 1)
+        return '' if n.zero?
+        control(n.to_s, 'A')
+      end
+
+      # Move the cursor down n lines
+      #
+      # ==== Attributes
+      #
+      # * +n+ - number of lines by which to move the cursor down
+      #
+      def self.cursor_down(n = 1)
+        return '' if n.zero?
+        control(n.to_s, 'B')
+      end
+
+      # Move the cursor forward n columns
+      #
+      # ==== Attributes
+      #
+      # * +n+ - number of columns by which to move the cursor forward
+      #
+      def self.cursor_forward(n = 1)
+        return '' if n.zero?
+        control(n.to_s, 'C')
+      end
+
+      # Move the cursor back n columns
+      #
+      # ==== Attributes
+      #
+      # * +n+ - number of columns by which to move the cursor back
+      #
+      def self.cursor_back(n = 1)
+        return '' if n.zero?
+        control(n.to_s, 'D')
+      end
+
+      # Move the cursor to a specific column
+      #
+      # ==== Attributes
+      #
+      # * +n+ - The column to move to
+      #
+      def self.cursor_horizontal_absolute(n = 1)
+        control(n.to_s, 'G')
+      end
+
+      # Show the cursor
+      #
+      def self.show_cursor
+        control('', "?25h")
+      end
+
+      # Hide the cursor
+      #
+      def self.hide_cursor
+        control('', "?25l")
+      end
+
+      # Save the cursor position
+      #
+      def self.cursor_save
+        control('', 's')
+      end
+
+      # Restore the saved cursor position
+      #
+      def self.cursor_restore
+        control('', 'u')
+      end
+
+      # Move to the next line
+      #
+      def self.next_line
+        cursor_down + control('1', 'G')
+      end
+
+      # Move to the previous line
+      #
+      def self.previous_line
+        cursor_up + control('1', 'G')
+      end
+
+      # Move to the end of the line
+      #
+      def self.end_of_line
+        control("\033[", 'C')
+      end
+    end
+  end
+end

data/lib/cli/ui/box.rb

@@ -0,0 +1,15 @@
+require 'cli/ui'
+
+module CLI
+  module UI
+    module Box
+      module Heavy
+        VERT = '┃'
+        HORZ = '━'
+        DIV  = "┣"
+        TL   = '┏'
+        BL   = '┗'
+      end
+    end
+  end
+end

data/lib/cli/ui/color.rb

@@ -0,0 +1,79 @@
+require 'cli/ui'
+
+module CLI
+  module UI
+    class Color
+      attr_reader :sgr, :name, :code
+
+      # Creates a new color mapping
+      # Signatures can be found here:
+      # https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+      #
+      # ==== Attributes
+      #
+      # * +sgr+ - The color signature
+      # * +name+ - The name of the color
+      #
+      def initialize(sgr, name)
+        @sgr  = sgr
+        @code = CLI::UI::ANSI.sgr(sgr)
+        @name = name
+      end
+
+      RED     = new('31', :red)
+      GREEN   = new('32', :green)
+      YELLOW  = new('33', :yellow)
+      # default blue is low-contrast against black in some default terminal color scheme
+      BLUE    = new('94', :blue) # 9x = high-intensity fg color x
+      MAGENTA = new('35', :magenta)
+      CYAN    = new('36', :cyan)
+      RESET   = new('0',  :reset)
+      BOLD    = new('1',  :bold)
+      WHITE   = new('97', :white)
+
+      MAP = {
+        red:     RED,
+        green:   GREEN,
+        yellow:  YELLOW,
+        blue:    BLUE,
+        magenta: MAGENTA,
+        cyan:    CYAN,
+        reset:   RESET,
+        bold:    BOLD,
+      }.freeze
+
+      class InvalidColorName < ArgumentError
+        def initialize(name)
+          @name = name
+        end
+
+        def message
+          keys = Color.available.map(&:inspect).join(',')
+          "invalid color: #{@name.inspect} " \
+            "-- must be one of CLI::UI::Color.available (#{keys})"
+        end
+      end
+
+      # Looks up a color code by name
+      #
+      # ==== Raises
+      # Raises a InvalidColorName if the color is not available
+      # You likely need to add it to the +MAP+ or you made a typo
+      #
+      # ==== Returns
+      # Returns a color code
+      #
+      def self.lookup(name)
+        MAP.fetch(name)
+      rescue KeyError
+        raise InvalidColorName, name
+      end
+
+      # All available colors by name
+      #
+      def self.available
+        MAP.keys
+      end
+    end
+  end
+end

data/lib/cli/ui/formatter.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'cli/ui'
+require 'strscan'
+
+module CLI
+  module UI
+    class Formatter
+      # Available mappings of formattings
+      # To use any of them, you can use {{<key>:<string>}}
+      # There are presentational (colours and formatters)
+      # and semantic (error, info, command) formatters available
+      #
+      SGR_MAP = {
+        # presentational
+        'red'       => '31',
+        'green'     => '32',
+        'yellow'    => '33',
+        'blue'      => '34',
+        'magenta'   => '35',
+        'cyan'      => '36',
+        'bold'      => '1',
+        'italic'    => '3',
+        'underline' => '4',
+        'reset'     => '0',
+
+        # semantic
+        'error'   => '31', # red
+        'success' => '32', # success
+        'warning' => '33', # yellow
+        'info'    => '34', # blue
+        'command' => '36', # cyan
+      }.freeze
+
+      BEGIN_EXPR = '{{'
+      END_EXPR   = '}}'
+
+      SCAN_FUNCNAME = /\w+:/
+      SCAN_GLYPH    = /.}}/
+      SCAN_BODY     = /
+        .*?
+        (
+          #{BEGIN_EXPR} |
+          #{END_EXPR}   |
+          \z
+        )
+      /mx
+
+      DISCARD_BRACES = 0..-3
+
+      LITERAL_BRACES = :__literal_braces__
+
+      class FormatError < StandardError
+        attr_accessor :input, :index
+
+        def initialize(message = nil, input = nil, index = nil)
+          super(message)
+          @input = input
+          @index = index
+        end
+      end
+
+      # Initialize a formatter with text.
+      #
+      # ===== Attributes
+      #
+      # * +text+ - the text to format
+      #
+      def initialize(text)
+        @text = text
+      end
+
+      # Format the text using a map.
+      #
+      # ===== Attributes
+      #
+      # * +sgr_map+ - the mapping of the formattings. Defaults to +SGR_MAP+
+      #
+      # ===== Options
+      #
+      # * +:enable_color+ - enable color output? Default is true
+      #
+      def format(sgr_map = SGR_MAP, enable_color: true)
+        @nodes = []
+        stack = parse_body(StringScanner.new(@text))
+        prev_fmt = nil
+        content = @nodes.each_with_object(String.new) do |(text, fmt), str|
+          if prev_fmt != fmt && enable_color
+            text = apply_format(text, fmt, sgr_map)
+          end
+          str << text
+          prev_fmt = fmt
+        end
+
+        stack.reject! { |e| e == LITERAL_BRACES }
+
+        return content unless enable_color
+        return content if stack == prev_fmt
+
+        unless stack.empty? && (@nodes.size.zero? || @nodes.last[1].empty?)
+          content << apply_format('', stack, sgr_map)
+        end
+        content
+      end
+
+      private
+
+      def apply_format(text, fmt, sgr_map)
+        sgr = fmt.each_with_object(String.new('0')) do |name, str|
+          next if name == LITERAL_BRACES
+          begin
+            str << ';' << sgr_map.fetch(name)
+          rescue KeyError
+            raise FormatError.new(
+              "invalid format specifier: #{name}",
+              @text,
+              -1
+            )
+          end
+        end
+        CLI::UI::ANSI.sgr(sgr) + text
+      end
+
+      def parse_expr(sc, stack)
+        if match = sc.scan(SCAN_GLYPH)
+          glyph_handle = match[0]
+          begin
+            glyph = Glyph.lookup(glyph_handle)
+            emit(glyph.char, [glyph.color.name.to_s])
+          rescue Glyph::InvalidGlyphHandle
+            index = sc.pos - 2 # rewind past '}}'
+            raise FormatError.new(
+              "invalid glyph handle at index #{index}: '#{glyph_handle}'",
+              @text,
+              index
+            )
+          end
+        elsif match = sc.scan(SCAN_FUNCNAME)
+          funcname = match.chop
+          stack.push(funcname)
+        else
+          # We read a {{ but it's not apparently Formatter syntax.
+          # We could error, but it's nicer to just pass through as text.
+          # We do kind of assume that the text will probably have balanced
+          # pairs of {{ }} at least.
+          emit('{{', stack)
+          stack.push(LITERAL_BRACES)
+        end
+        parse_body(sc, stack)
+        stack
+      end
+
+      def parse_body(sc, stack = [])
+        match = sc.scan(SCAN_BODY)
+        if match && match.end_with?(BEGIN_EXPR)
+          emit(match[DISCARD_BRACES], stack)
+          parse_expr(sc, stack)
+        elsif match && match.end_with?(END_EXPR)
+          emit(match[DISCARD_BRACES], stack)
+          if stack.pop == LITERAL_BRACES
+            emit('}}', stack)
+          end
+          parse_body(sc, stack)
+        elsif match
+          emit(match, stack)
+        else
+          emit(sc.rest, stack)
+        end
+        stack
+      end
+
+      def emit(text, stack)
+        return if text.nil? || text.empty?
+        @nodes << [text, stack.reject { |n| n == LITERAL_BRACES }]
+      end
+    end
+  end
+end

data/lib/cli/ui/frame.rb

@@ -0,0 +1,310 @@
+require 'cli/ui'
+
+module CLI
+  module UI
+    module Frame
+      class UnnestedFrameException < StandardError; end
+      class << self
+        DEFAULT_FRAME_COLOR = CLI::UI.resolve_color(:cyan)
+
+        # Opens a new frame. Can be nested
+        # Can be invoked in two ways: block and blockless
+        # * In block form, the frame is closed automatically when the block returns
+        # * In blockless form, caller MUST call +Frame.close+ when the frame is logically done
+        # * Blockless form is strongly discouraged in cases where block form can be made to work
+        #
+        # https://user-images.githubusercontent.com/3074765/33799861-cb5dcb5c-dd01-11e7-977e-6fad38cee08c.png
+        #
+        # The return value of the block determines if the block is a "success" or a "failure"
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - The color of the frame. Defaults to +DEFAULT_FRAME_COLOR+
+        # * +:failure_text+ - If the block failed, what do we output? Defaults to nil
+        # * +:success_text+ - If the block succeeds, what do we output? Defaults to nil
+        # * +:timing+ - How long did the frame content take? Invalid for blockless. Defaults to true for the block form
+        #
+        # ==== Example
+        #
+        # ===== Block Form (Assumes +CLI::UI::StdoutRouter.enable+ has been called)
+        #
+        #   CLI::UI::Frame.open('Open') { puts 'hi' }
+        #
+        # Output:
+        #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #   ┃ hi
+        #   ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ (0.0s) ━━
+        #
+        # ===== Blockless Form
+        #
+        #   CLI::UI::Frame.open('Open')
+        #
+        # Output:
+        #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #
+        #
+        def open(
+          text,
+          color: DEFAULT_FRAME_COLOR,
+          failure_text: nil,
+          success_text: nil,
+          timing:       nil
+        )
+          color = CLI::UI.resolve_color(color)
+
+          unless block_given?
+            if failure_text
+              raise ArgumentError, "failure_text is not compatible with blockless invocation"
+            elsif success_text
+              raise ArgumentError, "success_text is not compatible with blockless invocation"
+            elsif !timing.nil?
+              raise ArgumentError, "timing is not compatible with blockless invocation"
+            end
+          end
+
+          timing = true if timing.nil?
+
+          t_start = Time.now.to_f
+          CLI::UI.raw do
+            puts edge(text, color: color, first: CLI::UI::Box::Heavy::TL)
+          end
+          FrameStack.push(color)
+
+          return unless block_given?
+
+          closed = false
+          begin
+            success = false
+            success = yield
+          rescue
+            closed = true
+            t_diff = timing ? (Time.now.to_f - t_start) : nil
+            close(failure_text, color: :red, elapsed: t_diff)
+            raise
+          else
+            success
+          ensure
+            unless closed
+              t_diff = timing ? (Time.now.to_f - t_start) : nil
+              if success != false
+                close(success_text, color: color, elapsed: t_diff)
+              else
+                close(failure_text, color: :red, elapsed: t_diff)
+              end
+            end
+          end
+        end
+
+        # Closes a frame
+        # Automatically called for a block-form +open+
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - The color of the frame. Defaults to +DEFAULT_FRAME_COLOR+
+        # * +:elapsed+ - How long did the frame take? Defaults to nil
+        #
+        # ==== Example
+        #
+        #   CLI::UI::Frame.close('Close')
+        #
+        # Output:
+        #   ┗━━ Close ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #
+        #
+        def close(text, color: DEFAULT_FRAME_COLOR, elapsed: nil)
+          color = CLI::UI.resolve_color(color)
+
+          FrameStack.pop
+          kwargs = {}
+          if elapsed
+            kwargs[:right_text] = "(#{elapsed.round(2)}s)"
+          end
+          CLI::UI.raw do
+            puts edge(text, color: color, first: CLI::UI::Box::Heavy::BL, **kwargs)
+          end
+        end
+
+        # Adds a divider in a frame
+        # Used to separate information within a single frame
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - The color of the frame. Defaults to +DEFAULT_FRAME_COLOR+
+        #
+        # ==== Example
+        #
+        #   CLI::UI::Frame.open('Open') { CLI::UI::Frame.divider('Divider') }
+        #
+        # Output:
+        #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #   ┣━━ Divider ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #   ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #
+        # ==== Raises
+        #
+        # MUST be inside an open frame or it raises a +UnnestedFrameException+
+        #
+        def divider(text, color: nil)
+          fs_item = FrameStack.pop
+          raise UnnestedFrameException, "no frame nesting to unnest" unless fs_item
+          color = CLI::UI.resolve_color(color)
+          item  = CLI::UI.resolve_color(fs_item)
+
+          CLI::UI.raw do
+            puts edge(text, color: (color || item), first: CLI::UI::Box::Heavy::DIV)
+          end
+          FrameStack.push(item)
+        end
+
+        # Determines the prefix of a frame entry taking multi-nested frames into account
+        #
+        # ==== Options
+        #
+        # * +:color+ - The color of the prefix. Defaults to +Thread.current[:cliui_frame_color_override]+ or nil
+        #
+        def prefix(color: nil)
+          pfx = String.new
+          items = FrameStack.items
+          items[0..-2].each do |item|
+            pfx << CLI::UI.resolve_color(item).code << CLI::UI::Box::Heavy::VERT
+          end
+          if item = items.last
+            c = Thread.current[:cliui_frame_color_override] || color || item
+            pfx << CLI::UI.resolve_color(c).code \
+              << CLI::UI::Box::Heavy::VERT << ' ' << CLI::UI::Color::RESET.code
+          end
+          pfx
+        end
+
+        # Override a color for a given thread.
+        #
+        # ==== Attributes
+        #
+        # * +color+ - The color to override to
+        #
+        def with_frame_color_override(color)
+          prev = Thread.current[:cliui_frame_color_override]
+          Thread.current[:cliui_frame_color_override] = color
+          yield
+        ensure
+          Thread.current[:cliui_frame_color_override] = prev
+        end
+
+        # The width of a prefix given the number of Frames in the stack
+        #
+        def prefix_width
+          w = FrameStack.items.size
+          w.zero? ? 0 : w + 1
+        end
+
+        private
+
+        def edge(text, color: raise, first: raise, right_text: nil)
+          color = CLI::UI.resolve_color(color)
+          text  = CLI::UI.resolve_text("{{#{color.name}:#{text}}}")
+
+          prefix = String.new
+          FrameStack.items.each do |item|
+            prefix << CLI::UI.resolve_color(item).code << CLI::UI::Box::Heavy::VERT
+          end
+          prefix << color.code << first << (CLI::UI::Box::Heavy::HORZ * 2)
+          text ||= ''
+          unless text.empty?
+            prefix << ' ' << text << ' '
+          end
+
+          termwidth = CLI::UI::Terminal.width
+
+          suffix = String.new
+          if right_text
+            suffix << ' ' << right_text << ' '
+          end
+
+          suffix_width = CLI::UI::ANSI.printing_width(suffix)
+          suffix_end   = termwidth - 2
+          suffix_start = suffix_end - suffix_width
+
+          prefix_width = CLI::UI::ANSI.printing_width(prefix)
+          prefix_start = 0
+          prefix_end   = prefix_start + prefix_width
+
+          if prefix_end > suffix_start
+            suffix = ''
+            # if prefix_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 = String.new
+
+          is_ci = ![0, '', nil].include?(ENV['CI'])
+
+          # Jumping around the line can cause some unwanted flashes
+          o << CLI::UI::ANSI.hide_cursor
+
+          o << if is_ci
+                 # In CI, we can't use absolute horizontal positions because of timestamps.
+                 # So we move around the line by offset from this cursor position.
+                 CLI::UI::ANSI.cursor_save
+               else
+                 # Outside of CI, we reset to column 1 so that things like ^C don't
+                 # cause output misformatting.
+                 "\r"
+               end
+
+          o << color.code
+          o << CLI::UI::Box::Heavy::HORZ * termwidth # draw a full line
+          o << print_at_x(prefix_start, prefix, is_ci)
+          o << color.code
+          o << print_at_x(suffix_start, suffix, is_ci)
+          o << CLI::UI::Color::RESET.code
+          o << CLI::UI::ANSI.show_cursor
+          o << "\n"
+
+          o
+        end
+
+        def print_at_x(x, str, is_ci)
+          if is_ci
+            CLI::UI::ANSI.cursor_restore + CLI::UI::ANSI.cursor_forward(x) + str
+          else
+            CLI::UI::ANSI.cursor_horizontal_absolute(1 + x) + str
+          end
+        end
+
+        module FrameStack
+          ENVVAR = 'CLI_FRAME_STACK'
+
+          def self.items
+            ENV.fetch(ENVVAR, '').split(':').map(&:to_sym)
+          end
+
+          def self.push(item)
+            curr = items
+            curr << item.name
+            ENV[ENVVAR] = curr.join(':')
+          end
+
+          def self.pop
+            curr = items
+            ret = curr.pop
+            ENV[ENVVAR] = curr.join(':')
+            ret.nil? ? nil : ret.to_sym
+          end
+        end
+      end
+    end
+  end
+end