cli-ui 1.2.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71e70e5d4866f5af664b7fe2393ae41e74e4995a3e9514b42cccaae9bdf5e62a
-  data.tar.gz: 30742fe01d001bb0b876c874efb2e2878e120b13334d15d2cc964e0bb0b0ac83
+  metadata.gz: 48913d44cb2cdae4f699a6f456cce15ca8b50b450317e4734f4bcd8062982d39
+  data.tar.gz: ae1d337eb7b280001153a25a5e92ee9b2e534b47d5e95c79a2b9a20371bdadf0
 SHA512:
-  metadata.gz: ba955e4dab0ddc389e1f878f2ddc689a4cb5581aafe7e96f4eacaf7cf7cc79b23081bd2fbf21a85c648b679f265d6f442e0ac1b8abde62c14d4f1dc5c258c90c
-  data.tar.gz: 1de7e63523615f6a39e756e106fb78000b05be0fa1ad00d70e471ba6b0b39fcfa702e624fa58d36d3d49da58526899337f33a5395b8f74513b726b84b04584d4
+  metadata.gz: 1e87d0b821c5911d1e10680619522b5f36a19213042e187cc54097850dd2ccb986db4a6dbf800234c43102377d168d6a5dda573f577763dff754e4cee58fc50b
+  data.tar.gz: 2cfb1d76a7b6f49f1f14eadf7237c644a2c2f1896dfff8dcaff9c5b68d354194df0da34339817d8153ef6815ff2898d15b6bb7bd6bb68198bdc614505072aaf3

data/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Shopify/dev-infra

data/README.md

@@ -115,6 +115,19 @@ puts CLI::UI.fmt "{{*}} {{x}} {{?}} {{v}}"
 
 ---
 
+### Status Widget
+
+```ruby
+CLI::UI::Spinner.spin("building packages: {{@widget/status:1:2:3:4}}") do |spinner|
+  # spinner.update_title(...)
+  sleep(3)
+end
+```
+
+![Status Widget](https://user-images.githubusercontent.com/1284/61405142-11042580-a8a7-11e9-9885-46ba44c46358.gif)
+
+---
+
 ### Progress Bar
 
 Show progress of a process or operation.

data/lib/cli/ui.rb

@@ -11,6 +11,7 @@ module CLI
     autoload :Truncater,          'cli/ui/truncater'
     autoload :Formatter,          'cli/ui/formatter'
     autoload :Spinner,            'cli/ui/spinner'
+    autoload :Widgets,            'cli/ui/widgets'
 
     # Convenience accessor to +CLI::UI::Spinner::SpinGroup+
     SpinGroup = Spinner::SpinGroup

data/lib/cli/ui/color.rb

@@ -31,6 +31,9 @@ module CLI
       BOLD    = new('1',  :bold)
       WHITE   = new('97', :white)
 
+      # 240 is very dark gray; 255 is very light gray. 244 is somewhat dark.
+      GRAY = new('38;5;244', :grey)
+
       MAP = {
         red:     RED,
         green:   GREEN,
@@ -40,6 +43,7 @@ module CLI
         cyan:    CYAN,
         reset:   RESET,
         bold:    BOLD,
+        gray:    GRAY,
       }.freeze
 
       class InvalidColorName < ArgumentError

data/lib/cli/ui/formatter.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
-
-require 'cli/ui'
-require 'strscan'
+require('cli/ui')
+require('strscan')
 
 module CLI
   module UI
@@ -16,7 +15,7 @@ module CLI
         'red'       => '31',
         'green'     => '32',
         'yellow'    => '33',
-         # default blue is low-contrast against black in some default terminal color scheme
+        # default blue is low-contrast against black in some default terminal color scheme
         'blue'      => '94', # 9x = high-intensity fg color x
         'magenta'   => '35',
         'cyan'      => '36',
@@ -36,16 +35,17 @@ module CLI
       BEGIN_EXPR = '{{'
       END_EXPR   = '}}'
 
+      SCAN_WIDGET   = %r[@widget/(?<handle>\w+):(?<args>.*?)}}]
       SCAN_FUNCNAME = /\w+:/
       SCAN_GLYPH    = /.}}/
-      SCAN_BODY     = /
+      SCAN_BODY     = %r{
         .*?
         (
           #{BEGIN_EXPR} |
           #{END_EXPR}   |
           \z
         )
-      /mx
+      }mx
 
       DISCARD_BRACES = 0..-3
 
@@ -123,7 +123,7 @@ module CLI
       end
 
       def parse_expr(sc, stack)
-        if match = sc.scan(SCAN_GLYPH)
+        if (match = sc.scan(SCAN_GLYPH))
           glyph_handle = match[0]
           begin
             glyph = Glyph.lookup(glyph_handle)
@@ -136,7 +136,20 @@ module CLI
               index
             )
           end
-        elsif match = sc.scan(SCAN_FUNCNAME)
+        elsif (match = sc.scan(SCAN_WIDGET))
+          match_data = SCAN_WIDGET.match(match) # Regexp.last_match doesn't work here
+          widget_handle = match_data['handle']
+          begin
+            widget = Widgets.lookup(widget_handle)
+            emit(widget.call(match_data['args']), stack)
+          rescue Widgets::InvalidWidgetHandle
+            index = sc.pos - 2 # rewind past '}}'
+            raise(FormatError.new(
+              "invalid widget handle at index #{index}: '#{widget_handle}'",
+              @text, index,
+            ))
+          end
+        elsif (match = sc.scan(SCAN_FUNCNAME))
           funcname = match.chop
           stack.push(funcname)
         else

data/lib/cli/ui/frame.rb

@@ -249,26 +249,32 @@ module CLI
 
           o = +''
 
-          is_ci = ![0, '', nil].include?(ENV['CI'])
+          # 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.
+          if (is_ci = ![0, '', nil].include?(ENV['CI']))
+            linewidth = [0, termwidth - (prefix_width + suffix_width)].max
+
+            o << color.code << prefix
+            o << color.code << (CLI::UI::Box::Heavy::HORZ * 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
 
-          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
+          # reset to column 1 so that things like ^C don't ruin formatting
+          o << "\r"
 
           o << color.code
           o << CLI::UI::Box::Heavy::HORZ * termwidth # draw a full line
-          o << print_at_x(prefix_start, prefix, is_ci)
+          o << print_at_x(prefix_start, prefix)
           o << color.code
-          o << print_at_x(suffix_start, suffix, is_ci)
+          o << print_at_x(suffix_start, suffix)
           o << CLI::UI::Color::RESET.code
           o << CLI::UI::ANSI.show_cursor
           o << "\n"
@@ -276,12 +282,8 @@ module CLI
           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
+        def print_at_x(x, str)
+          CLI::UI::ANSI.cursor_horizontal_absolute(1 + x) + str
         end
 
         module FrameStack

data/lib/cli/ui/glyph.rb

@@ -29,7 +29,7 @@ module CLI
         @handle    = handle
         @codepoint = codepoint
         @color     = color
-        @char      = [codepoint].pack('U')
+        @char      = Array(codepoint).pack('U*')
         @to_s      = color.code + char + Color::RESET.code
         @fmt       = "{{#{color.name}:#{char}}}"
 
@@ -38,20 +38,14 @@ module CLI
 
       # Mapping of glyphs to terminal output
       MAP = {}
-      # YELLOw SMALL STAR (⭑)
-      STAR     = new('*', 0x2b51,  Color::YELLOW)
-      # BLUE MATHEMATICAL SCRIPT SMALL i (𝒾)
-      INFO     = new('i', 0x1d4be, Color::BLUE)
-      # BLUE QUESTION MARK (?)
-      QUESTION = new('?', 0x003f,  Color::BLUE)
-      # GREEN CHECK MARK (✓)
-      CHECK    = new('v', 0x2713,  Color::GREEN)
-      # RED BALLOT X (✗)
-      X        = new('x', 0x2717,  Color::RED)
-      # Bug emoji (🐛)
-      BUG      = new('b', 0x1f41b, Color::WHITE)
-      # RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK (»)
-      CHEVRON  = new('>', 0xbb,    Color::YELLOW)
+      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 (⌛︎)
 
       # Looks up a glyph by name
       #

data/lib/cli/ui/prompt.rb

@@ -88,6 +88,33 @@ module CLI
           end
         end
 
+        # Asks the user for a single-line answer, without displaying the characters while typing.
+        # Typically used for password prompts
+        #
+        # ==== Return Value
+        #
+        # The password, without a trailing newline.
+        # If the user simply presses "Enter" without typing any password, this will return an empty string.
+        def ask_password(question)
+          require 'io/console'
+
+          CLI::UI.with_frame_color(:blue) do
+            STDOUT.print(CLI::UI.fmt('{{?}} ' + question)) # Do not use puts_question to avoid the new line.
+
+            # noecho interacts poorly with Readline under system Ruby, so do a manual `gets` here.
+            # No fancy Readline integration (like echoing back) is required for a password prompt anyway.
+            password = STDIN.noecho do
+              # Chomp will remove the one new line character added by `gets`, without touching potential extra spaces:
+              # " 123 \n".chomp => " 123 "
+              STDIN.gets.chomp
+            end
+
+            STDOUT.puts # Complete the line
+
+            password
+          end
+        end
+
         # Asks the user a yes/no question.
         # Can use arrows, y/n, numbers (1/2), and vim bindings to control
         #

data/lib/cli/ui/prompt/interactive_options.rb

@@ -288,6 +288,8 @@ module CLI
             case char
             when 'A'      ; up
             when 'B'      ; down
+            when 'C'      ; # Ignore right key
+            when 'D'      ; # Ignore left key
             else          ; raise Interrupt # unhandled escape sequence.
             end
           end

data/lib/cli/ui/spinner.rb

@@ -1,3 +1,4 @@
+# frozen-string-literal: true
 require 'cli/ui'
 
 module CLI
@@ -9,11 +10,30 @@ module CLI
       PERIOD = 0.1 # seconds
       TASK_FAILED = :task_failed
 
+      RUNES = %w(⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏).freeze
+
       begin
-        runes = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
         colors = [CLI::UI::Color::CYAN.code] * 5 + [CLI::UI::Color::MAGENTA.code] * 5
-        raise unless runes.size == colors.size
-        GLYPHS = colors.zip(runes).map(&:join)
+        raise unless RUNES.size == colors.size
+        GLYPHS = colors.zip(RUNES).map(&:join)
+      end
+
+      class << self
+        attr_accessor(:index)
+
+        # We use this from CLI::UI::Widgets::Status to render an additional
+        # spinner next to the "working" element. While this global state looks
+        # a bit repulsive at first, it's worth realizing that:
+        #
+        # * It's managed by the SpinGroup#wait method, not individual tasks; and
+        # * It would be complete insanity to run two separate but concurrent SpinGroups.
+        #
+        # While it would be possible to stitch through some connection between
+        # the SpinGroup and the Widgets included in its title, this is simpler
+        # in practice and seems unlikely to cause issues in practice.
+        def current_rune
+          RUNES[index || 0]
+        end
       end
 
       # Adds a single spinner

data/lib/cli/ui/spinner/spin_group.rb

@@ -40,6 +40,7 @@ module CLI
           #
           def initialize(title, &block)
             @title = title
+            @always_full_render = title =~ Formatter::SCAN_WIDGET
             @thread = Thread.new do
               cap = CLI::UI::StdoutRouter::Capture.new(self, with_frame_inset: false, &block)
               begin
@@ -75,7 +76,17 @@ module CLI
             @done
           end
 
-          # Re-renders the task if required
+          # Re-renders the task if required:
+          #
+          # We try to be as lazy as possible in re-rendering the full line. The
+          # spinner rune will change on each render for the most part, but the
+          # body text will rarely have changed. If the body text *has* changed,
+          # we set @force_full_render.
+          #
+          # Further, if the title string includes any CLI::UI::Widgets, we
+          # assume that it may change from render to render, since those
+          # evaluate more dynamically than the rest of our format codes, which
+          # are just text formatters. This is controlled by @always_full_render.
           #
           # ==== Attributes
           #
@@ -84,8 +95,11 @@ module CLI
           # * +width+ - current terminal width to format for
           #
           def render(index, force = true, width: CLI::UI::Terminal.width)
-            return full_render(index, width) if force || @force_full_render
-            partial_render(index)
+            if force || @always_full_render || @force_full_render
+              full_render(index, width)
+            else
+              partial_render(index)
+            end
           ensure
             @force_full_render = false
           end
@@ -97,6 +111,7 @@ module CLI
           # * +title+ - title to change the spinner to
           #
           def update_title(new_title)
+            @always_full_render = new_title =~ Formatter::SCAN_WIDGET
             @title = new_title
             @force_full_render = true
           end
@@ -194,6 +209,7 @@ module CLI
             break if all_done
 
             idx = (idx + 1) % GLYPHS.size
+            Spinner.index = idx
             sleep(PERIOD)
           end
 

data/lib/cli/ui/version.rb

@@ -1,5 +1,5 @@
 module CLI
   module UI
-    VERSION = "1.2.3"
+    VERSION = "1.3.0"
   end
 end

data/lib/cli/ui/widgets.rb

@@ -0,0 +1,75 @@
+require('cli/ui')
+
+module CLI
+  module UI
+    # Widgets are formatter objects with more custom implementations than the
+    # other features, which all center around formatting text with colours,
+    # etc.
+    #
+    # If you want to extend CLI::UI with your own widgets, you may want to do
+    # something like this:
+    #
+    #   require('cli/ui')
+    #   class MyWidget < CLI::UI::Widgets::Base
+    #     # ...
+    #   end
+    #   CLI::UI::Widgets.register('my-widget') { MyWidget }
+    #   puts(CLI::UI.fmt("{{@widget/my-widget:args}}"))
+    module Widgets
+      MAP = {}
+
+      autoload(:Base, 'cli/ui/widgets/base')
+
+      def self.register(name, &cb)
+        MAP[name] = cb
+      end
+
+      autoload(:Status, 'cli/ui/widgets/status')
+      register('status') { Widgets::Status }
+
+      # Looks up a widget by handle
+      #
+      # ==== Raises
+      # Raises InvalidWidgetHandle if the widget is not available.
+      #
+      # ==== Returns
+      # A callable widget, to be invoked like `.call(argstring)`
+      #
+      def self.lookup(handle)
+        MAP.fetch(handle.to_s).call
+      rescue KeyError, NameError
+        raise(InvalidWidgetHandle, handle)
+      end
+
+      # All available widgets by name
+      #
+      def self.available
+        MAP.keys
+      end
+
+      class InvalidWidgetHandle < ArgumentError
+        def initialize(handle)
+          @handle = handle
+        end
+
+        def message
+          keys = Widget.available.join(',')
+          "invalid widget handle: #{@handle} " \
+            "-- must be one of CLI::UI::Widgets.available (#{keys})"
+        end
+      end
+
+      class InvalidWidgetArguments < ArgumentError
+        def initialize(argstring, pattern)
+          @argstring = argstring
+          @pattern   = pattern
+        end
+
+        def message
+          "invalid widget arguments: #{@argstring} " \
+            "-- must match pattern: #{@pattern.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/cli/ui/widgets/base.rb

@@ -0,0 +1,27 @@
+require('cli/ui')
+
+module CLI
+  module UI
+    module Widgets
+      class Base
+        def self.call(argstring)
+          new(argstring).render
+        end
+
+        def initialize(argstring)
+          pat = self.class.argparse_pattern
+          unless (@match_data = pat.match(argstring))
+            raise(Widgets::InvalidWidgetArguments.new(argstring, pat))
+          end
+          @match_data.names.each do |name|
+            instance_variable_set(:"@#{name}", @match_data[name])
+          end
+        end
+
+        def self.argparse_pattern
+          const_get(:ARGPARSE_PATTERN)
+        end
+      end
+    end
+  end
+end

data/lib/cli/ui/widgets/status.rb

@@ -0,0 +1,61 @@
+# frozen-string-literal: true
+require('cli/ui')
+
+module CLI
+  module UI
+    module Widgets
+      class Status < Widgets::Base
+        ARGPARSE_PATTERN = %r{
+          \A (?<succeeded> \d+)
+          :  (?<failed>    \d+)
+          :  (?<working>   \d+)
+          :  (?<pending>   \d+) \z
+        }x # e.g. "1:23:3:404"
+        OPEN  = Color::RESET.code + Color::BOLD.code + '[' + Color::RESET.code
+        CLOSE = Color::RESET.code + Color::BOLD.code + ']' + Color::RESET.code
+        ARROW = Color::RESET.code + Color::GRAY.code + '◂' + Color::RESET.code
+        COMMA = Color::RESET.code + Color::GRAY.code + ',' + Color::RESET.code
+
+        SPINNER_STOPPED = '⠿'
+        EMPTY_SET = '∅'
+
+        def render
+          if zero?(@succeeded) && zero?(@failed) && zero?(@working) && zero?(@pending)
+            Color::RESET.code + Color::BOLD.code + EMPTY_SET + Color::RESET.code
+          else
+            #   [          0✓            ,         2✗          ◂         3⠼           ◂         4⌛︎           ]
+            "#{OPEN}#{succeeded_part}#{COMMA}#{failed_part}#{ARROW}#{working_part}#{ARROW}#{pending_part}#{CLOSE}"
+          end
+        end
+
+        private
+
+        def zero?(num_str)
+          num_str == '0'
+        end
+
+        def colorize_if_nonzero(num_str, rune, color)
+          color = Color::GRAY if zero?(num_str)
+          color.code + num_str + rune
+        end
+
+        def succeeded_part
+          colorize_if_nonzero(@succeeded, Glyph::CHECK.char, Color::GREEN)
+        end
+
+        def failed_part
+          colorize_if_nonzero(@failed, Glyph::X.char, Color::RED)
+        end
+
+        def working_part
+          rune = zero?(@working) ? SPINNER_STOPPED : Spinner.current_rune
+          colorize_if_nonzero(@working, rune, Color::BLUE)
+        end
+
+        def pending_part
+          colorize_if_nonzero(@pending, Glyph::HOURGLASS.char, Color::WHITE)
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cli-ui
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.3.0
 platform: ruby
 authors:
 - Burke Libbey
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-25 00:00:00.000000000 Z
+date: 2019-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -49,6 +49,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/CODEOWNERS"
 - ".github/probots.yml"
 - ".gitignore"
 - ".rubocop.yml"
@@ -78,6 +79,9 @@ files:
 - lib/cli/ui/terminal.rb
 - lib/cli/ui/truncater.rb
 - lib/cli/ui/version.rb
+- lib/cli/ui/widgets.rb
+- lib/cli/ui/widgets/base.rb
+- lib/cli/ui/widgets/status.rb
 homepage: https://github.com/shopify/cli-ui
 licenses:
 - MIT
@@ -97,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Terminal UI framework