cli-ui 1.5.1 → 2.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e28f7cb02b8647ee32e91b11f2b25b450c33a245514a520783d50cc6d5f7d84
-  data.tar.gz: 894e2a52591d18c5210efa36beab81d761c18734a42f8362d8af0c97e3bd4ae2
+  metadata.gz: 140781de33cc19ef1c5bc946a0a887b3707e54475823affad8f5568e98fbc0dd
+  data.tar.gz: b754caad8da6b0d37ea17d807aef78351518c4f17d511a39decbfb29b0512791
 SHA512:
-  metadata.gz: af8bd2b36c0d4c65e93aa966062e040109f5a10347404b112331975f04eb9cfe2a8601a9a9d1d4c1787f92f5a306b81f68e21d1e4f6728705fdfc81dd58fc25c
-  data.tar.gz: a94fa31ff9991a26202f8c4d4d85f87d9efdd23489ed47c5f719b0389a6106be4eee4ee86075fcddafe367d847b8299f69e6fe014fdffce629b0c9df43e156d1
+  metadata.gz: 8d841fb206c3de7427c4903aa5bb350241c5fe10bbf39c04cb1980eada288deda4b235bf1d5d99a293ebaa6cd78482dd2f49849d65ddd3e7929d63d2f35894bc
+  data.tar.gz: 6a99dc71d996abbff3fccdda8ce9ede069a7868ba467d86296bed3575e5726f50f76b65d4d427757f5ddaea211b7926d25045402ae5304e1593ae2fb6bc656fb

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.
 
 ---
 
@@ -52,6 +52,11 @@ For large numbers of options, using `e`, `:`, or `G` will toggle "line select" m
 CLI::UI.ask('What language/framework do you use?', options: %w(rails go ruby python))
 ```
 
+To set the color of instruction text:
+```ruby
+CLI::UI::Prompt.instructions_color = CLI::UI::Color::GRAY
+```
+
 Can also assign callbacks to each option
 
 ```ruby
@@ -83,10 +88,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)
@@ -175,6 +180,12 @@ end
 
 ---
 
+## Sorbet
+
+We make use of [Sorbet](https://sorbet.org/) in cli-ui. We provide stubs for Sorbet so that you can use this gem even
+if you aren't using Sorbet. We activate these stubs if `T` is undefined when the gem is loaded. For this reason, if you
+would like to use this gem and your project _does_ use Sorbet, ensure you load Sorbet _before_ loading cli-ui.
+
 ## Example Usage
 
 The following code makes use of nested-framing, multi-threaded spinners, formatted text, and more.
@@ -187,22 +198,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,199 @@
+# 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
+        sig { returns(String) }
+        def enter_alternate_screen
+          control('?1049', 'h')
+        end
 
-      # Restore the saved cursor position
-      #
-      def self.cursor_restore
-        control('', 'u')
-      end
+        sig { returns(String) }
+        def exit_alternate_screen
+          control('?1049', 'l')
+        end
 
-      # Move to the next line
-      #
-      def self.next_line
-        cursor_down + cursor_horizontal_absolute
-      end
+        sig { returns(Regexp) }
+        def match_alternate_screen
+          /#{Regexp.escape(control('?1049', ''))}[hl]/
+        end
 
-      # Move to the previous line
-      #
-      def self.previous_line
-        cursor_up + cursor_horizontal_absolute
-      end
+        # Show the cursor
+        #
+        sig { returns(String) }
+        def show_cursor
+          control('', '?25h')
+        end
+
+        # Hide the cursor
+        #
+        sig { returns(String) }
+        def hide_cursor
+          control('', '?25l')
+        end
+
+        # Save the cursor position
+        #
+        sig { returns(String) }
+        def cursor_save
+          control('', 's')
+        end
+
+        # Restore the saved cursor position
+        #
+        sig { returns(String) }
+        def cursor_restore
+          control('', 'u')
+        end
 
-      def self.clear_to_end_of_line
-        control('', 'K')
+        # 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
+
+        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.to_sym
+        end
+
+        # All available colors by name
+        #
+        sig { returns(T::Array[Symbol]) }
+        def available
+          MAP.keys
+        end
       end
     end
   end