cli-ui 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8de8c1fd6c855f812125e71e85dbfc12163dfd504215fab462d56ad5f4d2cc7e
-  data.tar.gz: 404f164084fd9cf85aa382a5d5f93b77b08ea4bc529840ebfe230e1b5ea7c620
+  metadata.gz: d8dec5198cdbbb3a6060fc448a9a03b5bc6eca461b94a62ead0f128664bb0ee2
+  data.tar.gz: bed02e7e27771141c08859c11d7e01f690438bb46d4022f5225d8cb42e39efe4
 SHA512:
-  metadata.gz: 9f737c534e372589165a3263854d3a90f024181f632f6ae918fcb7aafea69abad27f50246d35c2957c238447a74871f4705add26d1bf272ad58f4fcc52d31ae6
-  data.tar.gz: 56c449900c817637b97d0e99b05ac01375bbde1458db3f2d5e7122027cdd525e0b8aaf9b9d5290cc2f1fa8cae314efb1365ac46ab277629f5cebf5d113e39b0d
+  metadata.gz: 6944f7c1b8492e69bd078b2ca0d9901d26694e4542976cb07729efff2cb59438cbc2ec61692b75ccf178ffcec896a297264be5734520695f9bc11779f2698ead
+  data.tar.gz: c9795b1749d3db7cb57bccca815495ed9b2e8ee02092fe95b46bf451f2993e65c33f8b48e9f6520b2984b7278db64cb9e92bb1fe58a761691a9b313dab6ef464

data/README.md

@@ -3,7 +3,7 @@ CLI UI
 
 CLI UI is a small framework for generating nice command-line user interfaces
 
-- [Master Documentation](http://www.rubydoc.info/github/Shopify/cli-ui/master/CLI/UI)
+- [Master Documentation](http://www.rubydoc.info/github/Shopify/cli-ui/main/CLI/UI)
 - [Documentation of the Rubygems version](http://www.rubydoc.info/gems/cli-ui/)
 - [Rubygems](https://rubygems.org/gems/cli-ui)
 
@@ -23,7 +23,7 @@ In your code, simply add a `require 'cli/ui'`. Most options assume `CLI::UI::Std
 
 ## Features
 
-This may not be an exhaustive list. Please check our [documentation](http://www.rubydoc.info/github/Shopify/cli-ui/master/CLI/UI) for more information.
+This may not be an exhaustive list. Please check our [documentation](http://www.rubydoc.info/github/Shopify/cli-ui/main/CLI/UI) for more information.
 
 ---
 
@@ -83,10 +83,10 @@ CLI::UI.ask('Is CLI UI Awesome?', default: 'It is great!')
 Handle many multi-threaded processes while suppressing output unless there is an issue. Can update title to show state.
 
 ```ruby
-spin_group = CLI::UI::SpinGroup.new
-spin_group.add('Title')   { |spinner| sleep 3.0 }
-spin_group.add('Title 2') { |spinner| sleep 3.0; spinner.update_title('New Title'); sleep 3.0 }
-spin_group.wait
+CLI::UI::SpinGroup.new do |spin_group|
+  spin_group.add('Title')   { |spinner| sleep 3.0 }
+  spin_group.add('Title 2') { |spinner| sleep 3.0; spinner.update_title('New Title'); sleep 3.0 }
+end
 ```
 
 ![Spinner Group](https://user-images.githubusercontent.com/3074765/33798295-d94fd822-dce3-11e7-819b-43e5502d490e.gif)
@@ -187,22 +187,22 @@ CLI::UI::StdoutRouter.enable
 CLI::UI::Frame.open('{{*}} {{bold:a}}', color: :green) do
   CLI::UI::Frame.open('{{i}} b', color: :magenta) do
     CLI::UI::Frame.open('{{?}} c', color: :cyan) do
-      sg = CLI::UI::SpinGroup.new
-      sg.add('wow') do |spinner|
-        sleep(2.5)
-        spinner.update_title('second round!')
-        sleep (1.0)
+      CLI::UI::SpinGroup.new do |sg|
+        sg.add('wow') do |spinner|
+          sleep(2.5)
+          spinner.update_title('second round!')
+          sleep (1.0)
+        end
+        sg.add('such spin') { sleep(1.6) }
+        sg.add('many glyph') { sleep(2.0) }
       end
-      sg.add('such spin') { sleep(1.6) }
-      sg.add('many glyph') { sleep(2.0) }
-      sg.wait
     end
   end
   CLI::UI::Frame.divider('{{v}} lol')
   puts CLI::UI.fmt '{{info:words}} {{red:oh no!}} {{green:success!}}'
-  sg = CLI::UI::SpinGroup.new
-  sg.add('more spins') { sleep(0.5) ; raise 'oh no' }
-  sg.wait
+  CLI::UI::SpinGroup.new do |sg|
+    sg.add('more spins') { sleep(0.5) ; raise 'oh no' }
+  end
 end
 ```
 

data/lib/cli/ui/ansi.rb

@@ -1,156 +1,184 @@
+# typed: true
+
 require 'cli/ui'
 
 module CLI
   module UI
     module ANSI
+      extend T::Sig
+
       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
-          when "\n"
-            acc
-          else
-            acc + 1
+      class << self
+        extend T::Sig
+
+        # 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.
+        #
+        sig { params(str: String).returns(Integer) }
+        def printing_width(str)
+          zwj = T.let(false, T::Boolean)
+          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
+            when "\n"
+              acc
+            else
+              acc + 1
+            end
           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
+        # Strips ANSI codes from a str
+        #
+        # ==== Attributes
+        #
+        # - +str+ - The string from which to strip codes
+        #
+        sig { params(str: String).returns(String) }
+        def 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
+        # Returns an ANSI control sequence
+        #
+        # ==== Attributes
+        #
+        # - +args+ - Argument to pass to the ANSI control sequence
+        # - +cmd+ - ANSI control sequence Command
+        #
+        sig { params(args: String, cmd: String).returns(String) }
+        def 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
+        # https://en.wikipedia.org/wiki/ANSI_escape_code#graphics
+        sig { params(params: String).returns(String) }
+        def sgr(params)
+          control(params, '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
+        # Cursor Movement
 
-      # 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 up n lines
+        #
+        # ==== Attributes
+        #
+        # * +n+ - number of lines by which to move the cursor up
+        #
+        sig { params(n: Integer).returns(String) }
+        def cursor_up(n = 1)
+          return '' if n.zero?
 
-      # 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
+          control(n.to_s, 'A')
+        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 down n lines
+        #
+        # ==== Attributes
+        #
+        # * +n+ - number of lines by which to move the cursor down
+        #
+        sig { params(n: Integer).returns(String) }
+        def cursor_down(n = 1)
+          return '' if n.zero?
+
+          control(n.to_s, 'B')
+        end
 
-      # Move the cursor to a specific column
-      #
-      # ==== Attributes
-      #
-      # * +n+ - The column to move to
-      #
-      def self.cursor_horizontal_absolute(n = 1)
-        cmd = control(n.to_s, 'G')
-        cmd += control('1', 'D') if CLI::UI::OS.current.shift_cursor_on_line_reset?
-        cmd
-      end
+        # Move the cursor forward n columns
+        #
+        # ==== Attributes
+        #
+        # * +n+ - number of columns by which to move the cursor forward
+        #
+        sig { params(n: Integer).returns(String) }
+        def cursor_forward(n = 1)
+          return '' if n.zero?
+
+          control(n.to_s, 'C')
+        end
 
-      # Show the cursor
-      #
-      def self.show_cursor
-        control('', '?25h')
-      end
+        # Move the cursor back n columns
+        #
+        # ==== Attributes
+        #
+        # * +n+ - number of columns by which to move the cursor back
+        #
+        sig { params(n: Integer).returns(String) }
+        def cursor_back(n = 1)
+          return '' if n.zero?
+
+          control(n.to_s, 'D')
+        end
 
-      # Hide the cursor
-      #
-      def self.hide_cursor
-        control('', '?25l')
-      end
+        # Move the cursor to a specific column
+        #
+        # ==== Attributes
+        #
+        # * +n+ - The column to move to
+        #
+        sig { params(n: Integer).returns(String) }
+        def cursor_horizontal_absolute(n = 1)
+          cmd = control(n.to_s, 'G')
+          cmd += cursor_back if CLI::UI::OS.current.shift_cursor_back_on_horizontal_absolute?
+          cmd
+        end
 
-      # Save the cursor position
-      #
-      def self.cursor_save
-        control('', 's')
-      end
+        # Show the cursor
+        #
+        sig { returns(String) }
+        def show_cursor
+          control('', '?25h')
+        end
 
-      # Restore the saved cursor position
-      #
-      def self.cursor_restore
-        control('', 'u')
-      end
+        # Hide the cursor
+        #
+        sig { returns(String) }
+        def hide_cursor
+          control('', '?25l')
+        end
 
-      # Move to the next line
-      #
-      def self.next_line
-        cursor_down + cursor_horizontal_absolute
-      end
+        # Save the cursor position
+        #
+        sig { returns(String) }
+        def cursor_save
+          control('', 's')
+        end
 
-      # Move to the previous line
-      #
-      def self.previous_line
-        cursor_up + cursor_horizontal_absolute
-      end
+        # Restore the saved cursor position
+        #
+        sig { returns(String) }
+        def cursor_restore
+          control('', 'u')
+        end
+
+        # Move to the next line
+        #
+        sig { returns(String) }
+        def next_line
+          cursor_down + cursor_horizontal_absolute
+        end
+
+        # Move to the previous line
+        #
+        sig { returns(String) }
+        def previous_line
+          cursor_up + cursor_horizontal_absolute
+        end
 
-      def self.clear_to_end_of_line
-        control('', 'K')
+        sig { returns(String) }
+        def clear_to_end_of_line
+          control('', 'K')
+        end
       end
     end
   end

data/lib/cli/ui/color.rb

@@ -1,9 +1,17 @@
+# typed: true
+
 require 'cli/ui'
 
 module CLI
   module UI
     class Color
-      attr_reader :sgr, :name, :code
+      extend T::Sig
+
+      sig { returns(String) }
+      attr_reader :sgr, :code
+
+      sig { returns(Symbol) }
+      attr_reader :name
 
       # Creates a new color mapping
       # Signatures can be found here:
@@ -14,6 +22,7 @@ module CLI
       # * +sgr+ - The color signature
       # * +name+ - The name of the color
       #
+      sig { params(sgr: String, name: Symbol).void }
       def initialize(sgr, name)
         @sgr  = sgr
         @code = CLI::UI::ANSI.sgr(sgr)
@@ -32,7 +41,7 @@ module CLI
       WHITE   = new('97', :white)
 
       # 240 is very dark gray; 255 is very light gray. 244 is somewhat dark.
-      GRAY = new('38;5;244', :grey)
+      GRAY = new('38;5;244', :gray)
 
       MAP = {
         red: RED,
@@ -47,11 +56,15 @@ module CLI
       }.freeze
 
       class InvalidColorName < ArgumentError
+        extend T::Sig
+
+        sig { params(name: Symbol).void }
         def initialize(name)
           super
           @name = name
         end
 
+        sig { returns(String) }
         def message
           keys = Color.available.map(&:inspect).join(',')
           "invalid color: #{@name.inspect} " \
@@ -59,25 +72,31 @@ module CLI
         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
+      class << self
+        extend T::Sig
 
-      # All available colors by name
-      #
-      def self.available
-        MAP.keys
+        # 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
+        #
+        sig { params(name: T.any(Symbol, String)).returns(Color) }
+        def lookup(name)
+          MAP.fetch(name.to_sym)
+        rescue KeyError
+          raise InvalidColorName, name
+        end
+
+        # All available colors by name
+        #
+        sig { returns(T::Array[Symbol]) }
+        def available
+          MAP.keys
+        end
       end
     end
   end

data/lib/cli/ui/formatter.rb

@@ -1,10 +1,14 @@
+# typed: true
 # frozen_string_literal: true
+
 require('cli/ui')
 require('strscan')
 
 module CLI
   module UI
     class Formatter
+      extend T::Sig
+
       # Available mappings of formattings
       # To use any of them, you can use {{<key>:<string>}}
       # There are presentational (colours and formatters)
@@ -19,6 +23,8 @@ module CLI
         'blue' => '94', # 9x = high-intensity fg color x
         'magenta' => '35',
         'cyan' => '36',
+        'gray' => '38;5;244',
+        'white' => '97',
         'bold' => '1',
         'italic' => '3',
         'underline' => '4',
@@ -49,12 +55,21 @@ module CLI
 
       DISCARD_BRACES = 0..-3
 
-      LITERAL_BRACES = :__literal_braces__
+      LITERAL_BRACES = Class.new
+
+      Stack = T.type_alias { T::Array[T.any(String, LITERAL_BRACES)] }
 
       class FormatError < StandardError
-        attr_accessor :input, :index
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_accessor :input
 
-        def initialize(message = nil, input = nil, index = nil)
+        sig { returns(Integer) }
+        attr_accessor :index
+
+        sig { params(message: String, input: String, index: Integer).void }
+        def initialize(message, input, index)
           super(message)
           @input = input
           @index = index
@@ -67,8 +82,10 @@ module CLI
       #
       # * +text+ - the text to format
       #
+      sig { params(text: String).void }
       def initialize(text)
         @text = text
+        @nodes = T.let([], T::Array[[String, Stack]])
       end
 
       # Format the text using a map.
@@ -81,10 +98,11 @@ module CLI
       #
       # * +:enable_color+ - enable color output? Default is true unless output is redirected
       #
+      sig { params(sgr_map: T::Hash[String, String], enable_color: T::Boolean).returns(String) }
       def format(sgr_map = SGR_MAP, enable_color: CLI::UI.enable_color?)
-        @nodes = []
+        @nodes.replace([])
         stack = parse_body(StringScanner.new(@text))
-        prev_fmt = nil
+        prev_fmt = T.let(nil, T.nilable(Stack))
         content = @nodes.each_with_object(+'') do |(text, fmt), str|
           if prev_fmt != fmt && enable_color
             text = apply_format(text, fmt, sgr_map)
@@ -93,12 +111,12 @@ module CLI
           prev_fmt = fmt
         end
 
-        stack.reject! { |e| e == LITERAL_BRACES }
+        stack.reject! { |e| e.is_a?(LITERAL_BRACES) }
 
         return content unless enable_color
         return content if stack == prev_fmt
 
-        unless stack.empty? && (@nodes.size.zero? || @nodes.last[1].empty?)
+        unless stack.empty? && (@nodes.size.zero? || T.must(@nodes.last)[1].empty?)
           content << apply_format('', stack, sgr_map)
         end
         content
@@ -106,25 +124,28 @@ module CLI
 
       private
 
+      sig { params(text: String, fmt: Stack, sgr_map: T::Hash[String, String]).returns(String) }
       def apply_format(text, fmt, sgr_map)
         sgr = fmt.each_with_object(+'0') do |name, str|
-          next if name == LITERAL_BRACES
+          next if name.is_a?(LITERAL_BRACES)
+
           begin
             str << ';' << sgr_map.fetch(name)
           rescue KeyError
             raise FormatError.new(
               "invalid format specifier: #{name}",
               @text,
-              -1
+              -1,
             )
           end
         end
         CLI::UI::ANSI.sgr(sgr) + text
       end
 
+      sig { params(sc: StringScanner, stack: Stack).returns(Stack) }
       def parse_expr(sc, stack)
         if (match = sc.scan(SCAN_GLYPH))
-          glyph_handle = match[0]
+          glyph_handle = T.must(match[0])
           begin
             glyph = Glyph.lookup(glyph_handle)
             emit(glyph.char, [glyph.color.name.to_s])
@@ -133,20 +154,20 @@ module CLI
             raise FormatError.new(
               "invalid glyph handle at index #{index}: '#{glyph_handle}'",
               @text,
-              index
+              index,
             )
           end
         elsif (match = sc.scan(SCAN_WIDGET))
-          match_data = SCAN_WIDGET.match(match) # Regexp.last_match doesn't work here
-          widget_handle = match_data['handle']
+          match_data = T.must(SCAN_WIDGET.match(match)) # Regexp.last_match doesn't work here
+          widget_handle = T.must(match_data['handle'])
           begin
             widget = Widgets.lookup(widget_handle)
-            emit(widget.call(match_data['args']), stack)
+            emit(widget.call(T.must(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,
+              @text, index
             ))
           end
         elsif (match = sc.scan(SCAN_FUNCNAME))
@@ -158,20 +179,21 @@ module CLI
           # We do kind of assume that the text will probably have balanced
           # pairs of {{ }} at least.
           emit('{{', stack)
-          stack.push(LITERAL_BRACES)
+          stack.push(LITERAL_BRACES.new)
         end
         parse_body(sc, stack)
         stack
       end
 
+      sig { params(sc: StringScanner, stack: Stack).returns(Stack) }
       def parse_body(sc, stack = [])
         match = sc.scan(SCAN_BODY)
         if match&.end_with?(BEGIN_EXPR)
-          emit(match[DISCARD_BRACES], stack)
+          emit(T.must(match[DISCARD_BRACES]), stack)
           parse_expr(sc, stack)
         elsif match&.end_with?(END_EXPR)
-          emit(match[DISCARD_BRACES], stack)
-          if stack.pop == LITERAL_BRACES
+          emit(T.must(match[DISCARD_BRACES]), stack)
+          if stack.pop.is_a?(LITERAL_BRACES)
             emit('}}', stack)
           end
           parse_body(sc, stack)
@@ -183,9 +205,11 @@ module CLI
         stack
       end
 
+      sig { params(text: String, stack: Stack).void }
       def emit(text, stack)
-        return if text.nil? || text.empty?
-        @nodes << [text, stack.reject { |n| n == LITERAL_BRACES }]
+        return if text.empty?
+
+        @nodes << [text, stack.reject { |n| n.is_a?(LITERAL_BRACES) }]
       end
     end
   end