cli-ui 1.5.1 → 2.2.3

data/lib/cli/ui/prompt.rb

@@ -1,4 +1,7 @@
 # coding: utf-8
+
+# typed: true
+
 require 'cli/ui'
 require 'readline'
 
@@ -22,9 +25,26 @@ module CLI
     module Prompt
       autoload :InteractiveOptions,  'cli/ui/prompt/interactive_options'
       autoload :OptionsHandler,      'cli/ui/prompt/options_handler'
-      private_constant :InteractiveOptions, :OptionsHandler
 
       class << self
+        extend T::Sig
+
+        sig { returns(Color) }
+        def instructions_color
+          @instructions_color ||= Color::YELLOW
+        end
+
+        # Set the instructions color.
+        #
+        # ==== Attributes
+        #
+        # * +color+ - the color to use for prompt instructions
+        #
+        sig { params(color: Colorable).void }
+        def instructions_color=(color)
+          @instructions_color = CLI::UI.resolve_color(color)
+        end
+
         # Ask a user a question with either free form answer or a set of answers (multiple choice)
         # Can use arrows, y/n, numbers (1/2), and vim bindings to control multiple choice selection
         # Do not use this method for yes/no questions. Use +confirm+
@@ -92,26 +112,52 @@ module CLI
         #     handler.option('python') { |selection| selection }
         #   end
         #
+        sig do
+          params(
+            question: String,
+            options: T.nilable(T::Array[String]),
+            default: T.nilable(T.any(String, T::Array[String])),
+            is_file: T::Boolean,
+            allow_empty: T::Boolean,
+            multiple: T::Boolean,
+            filter_ui: T::Boolean,
+            select_ui: T::Boolean,
+            options_proc: T.nilable(T.proc.params(handler: OptionsHandler).void),
+          ).returns(T.any(String, T::Array[String]))
+        end
         def ask(
           question,
           options: nil,
           default: nil,
-          is_file: nil,
+          is_file: false,
           allow_empty: true,
           multiple: false,
           filter_ui: true,
           select_ui: true,
           &options_proc
         )
-          if (options || block_given?) && ((default && !multiple) || is_file)
-            raise(ArgumentError, 'conflicting arguments: options provided with default or is_file')
+          has_options = !!(options || block_given?)
+          if has_options && default && !multiple
+            raise(ArgumentError, 'conflicting arguments: default may not be provided with options when not multiple')
           end
 
-          if options && multiple && default && !(default - options).empty?
+          if has_options && is_file
+            raise(ArgumentError, 'conflicting arguments: is_file is only useful when options are not provided')
+          end
+
+          if options && multiple && default && !(Array(default) - options).empty?
             raise(ArgumentError, 'conflicting arguments: default should only include elements present in options')
           end
 
-          if options || block_given?
+          if multiple && !has_options
+            raise(ArgumentError, 'conflicting arguments: options must be provided when multiple is true')
+          end
+
+          if !multiple && default.is_a?(Array)
+            raise(ArgumentError, 'conflicting arguments: multiple defaults may only be provided when multiple is true')
+          end
+
+          if has_options
             ask_interactive(
               question,
               options,
@@ -122,7 +168,7 @@ module CLI
               &options_proc
             )
           else
-            ask_free_form(question, default, is_file, allow_empty)
+            ask_free_form(question, T.cast(default, T.nilable(String)), is_file, allow_empty)
           end
         end
 
@@ -133,21 +179,22 @@ module CLI
         #
         # The password, without a trailing newline.
         # If the user simply presses "Enter" without typing any password, this will return an empty string.
+        sig { params(question: String).returns(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.
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen 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
+            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
+              $stdin.gets.to_s.chomp
             end
 
-            STDOUT.puts # Complete the line
+            $stdout.puts # Complete the line
 
             password
           end
@@ -163,38 +210,85 @@ module CLI
         #
         #   CLI::UI::Prompt.confirm('Do a dangerous thing?', default: false)
         #
+        sig { params(question: String, default: T::Boolean).returns(T::Boolean) }
         def confirm(question, default: true)
-          ask_interactive(question, default ? %w(yes no) : %w(no yes), filter_ui: false) == 'yes'
+          ask_interactive(question, default ? ['yes', 'no'] : ['no', 'yes'], filter_ui: false) == 'yes'
+        end
+
+        # Present the user with a message and wait for any key to be pressed, returning the pressed key.
+        #
+        # ==== Example Usage:
+        #
+        #   CLI::UI::Prompt.any_key # Press any key to continue...
+        #
+        #   CLI::UI::Prompt.any_key('Press RETURN to continue...') # Then check if that's what they pressed
+        sig { params(prompt: String).returns(T.nilable(String)) }
+        def any_key(prompt = 'Press any key to continue...')
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            puts_question(prompt)
+            read_char
+          end
+        end
+
+        # Wait for any key to be pressed, returning the pressed key.
+        sig { returns(T.nilable(String)) }
+        def read_char
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            if $stdin.tty? && !ENV['TEST']
+              require 'io/console'
+              $stdin.getch # raw mode for tty
+            else
+              $stdin.getc # returns nil at end of input
+            end
+          end
+        rescue Errno::EIO, Errno::EPIPE, IOError
+          "\e"
         end
 
         private
 
+        sig do
+          params(question: String, default: T.nilable(String), is_file: T::Boolean, allow_empty: T::Boolean)
+            .returns(String)
+        end
         def ask_free_form(question, default, is_file, allow_empty)
           if default && !allow_empty
             raise(ArgumentError, 'conflicting arguments: default enabled but allow_empty is false')
           end
 
-          if default
-            puts_question("#{question} (empty = #{default})")
-          else
-            puts_question(question)
-          end
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            if default
+              puts_question("#{question} (empty = #{default})")
+            else
+              puts_question(question)
+            end
 
-          # Ask a free form question
-          loop do
-            line = readline(is_file: is_file)
+            # Ask a free form question
+            loop do
+              line = readline(is_file: is_file)
 
-            if line.empty? && default
-              write_default_over_empty_input(default)
-              return default
-            end
+              if line.empty? && default
+                write_default_over_empty_input(default)
+                return default
+              end
 
-            if !line.empty? || allow_empty
-              return line
+              if !line.empty? || allow_empty
+                return line
+              end
             end
           end
         end
 
+        sig do
+          params(
+            question: String,
+            options: T.nilable(T::Array[String]),
+            multiple: T::Boolean,
+            default: T.nilable(T.any(String, T::Array[String])),
+            filter_ui: T::Boolean,
+            select_ui: T::Boolean,
+          ).returns(T.any(String, T::Array[String]))
+        end
         def ask_interactive(question, options = nil, multiple: false, default: nil, filter_ui: true, select_ui: true)
           raise(ArgumentError, 'conflicting arguments: options and block given') if options && block_given?
 
@@ -205,7 +299,8 @@ module CLI
           end
 
           raise(ArgumentError, 'insufficient options') if options.nil? || options.empty?
-          navigate_text = if CLI::UI::OS.current.supports_arrow_keys?
+
+          navigate_text = if CLI::UI::OS.current.suggest_arrow_keys?
             'Choose with ↑ ↓ ⏎'
           else
             "Navigate up with 'k' and down with 'j', press Enter to select"
@@ -214,55 +309,70 @@ module CLI
           instructions = (multiple ? 'Toggle options. ' : '') + navigate_text
           instructions += ", filter with 'f'" if filter_ui
           instructions += ", enter option with 'e'" if select_ui && (options.size > 9)
-          puts_question("#{question} {{yellow:(#{instructions})}}")
-          resp = interactive_prompt(options, multiple: multiple, default: default)
-
-          # Clear the line
-          print(ANSI.previous_line + ANSI.clear_to_end_of_line)
-          # Force StdoutRouter to prefix
-          print(ANSI.previous_line + "\n")
-
-          # reset the question to include the answer
-          resp_text = resp
-          if multiple
-            resp_text = case resp.size
-            when 0
-              '<nothing>'
-            when 1..2
-              resp.join(' and ')
+
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            puts_question("#{question} " + instructions_color.code + "(#{instructions})" + Color::RESET.code)
+            resp = interactive_prompt(options, multiple: multiple, default: default)
+
+            # Clear the line
+            print(ANSI.previous_line + ANSI.clear_to_end_of_line)
+            # Force StdoutRouter to prefix
+            print(ANSI.previous_line + "\n")
+
+            # reset the question to include the answer
+            resp_text = case resp
+            when Array
+              case resp.size
+              when 0
+                '<nothing>'
+              when 1..2
+                resp.join(' and ')
+              else
+                "#{resp.size} items"
+              end
             else
-              "#{resp.size} items"
+              resp
             end
-          end
-          puts_question("#{question} (You chose: {{italic:#{resp_text}}})")
+            puts_question("#{question} (You chose: {{italic:#{resp_text}}})")
 
-          return handler.call(resp) if block_given?
-          resp
+            if block_given?
+              T.must(handler).call(resp)
+            else
+              resp
+            end
+          end
         end
 
         # Useful for stubbing in tests
+        sig do
+          params(options: T::Array[String], multiple: T::Boolean, default: T.nilable(T.any(T::Array[String], String)))
+            .returns(T.any(T::Array[String], String))
+        end
         def interactive_prompt(options, multiple: false, default: nil)
-          InteractiveOptions.call(options, multiple: multiple, default: default)
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            InteractiveOptions.call(options, multiple: multiple, default: default)
+          end
         end
 
+        sig { params(default: String).void }
         def write_default_over_empty_input(default)
           CLI::UI.raw do
-            STDERR.puts(
+            $stderr.puts(
               CLI::UI::ANSI.cursor_up(1) +
               "\r" +
               CLI::UI::ANSI.cursor_forward(4) + # TODO: width
               default +
-              CLI::UI::Color::RESET.code
+              CLI::UI::Color::RESET.code,
             )
           end
         end
 
+        sig { params(str: String).void }
         def puts_question(str)
-          CLI::UI.with_frame_color(:blue) do
-            STDOUT.puts(CLI::UI.fmt('{{?}} ' + str))
-          end
+          $stdout.puts(CLI::UI.fmt('{{?}} ' + str))
         end
 
+        sig { params(is_file: T::Boolean).returns(String) }
         def readline(is_file: false)
           if is_file
             Readline.completion_proc = Readline::FILENAME_COMPLETION_PROC
@@ -276,18 +386,18 @@ module CLI
           # work. We could work around this by having CLI::UI use a pipe and a
           # thread to manage output, but the current strategy feels like a
           # better tradeoff.
-          prefix = CLI::UI.with_frame_color(:blue) { CLI::UI::Frame.prefix }
+          prefix = CLI::UI::Frame.prefix
           # If a prompt is interrupted on Windows it locks the colour of the terminal from that point on, so we should
           # not change the colour here.
           prompt = prefix + CLI::UI.fmt('{{blue:> }}')
-          prompt += CLI::UI::Color::YELLOW.code if CLI::UI::OS.current.supports_color_prompt?
+          prompt += CLI::UI::Color::YELLOW.code if CLI::UI::OS.current.use_color_prompt?
 
           begin
             line = Readline.readline(prompt, true)
             print(CLI::UI::Color::RESET.code)
             line.to_s.chomp
           rescue Interrupt
-            CLI::UI.raw { STDERR.puts('^C' + CLI::UI::Color::RESET.code) }
+            CLI::UI.raw { $stderr.puts('^C' + CLI::UI::Color::RESET.code) }
             raise
           end
         end

data/lib/cli/ui/sorbet_runtime_stub.rb

@@ -0,0 +1,169 @@
+# typed: ignore
+# frozen_string_literal: true
+
+module T
+  class << self
+    def absurd(value); end
+    def all(type_a, type_b, *types); end
+    def any(type_a, type_b, *types); end
+    def attached_class; end
+    def class_of(klass); end
+    def enum(values); end
+    def nilable(type); end
+    def noreturn; end
+    def self_type; end
+    def type_alias(type = nil, &_blk); end
+    def type_parameter(name); end
+    def untyped; end
+
+    def assert_type!(value, _type, _checked: true)
+      value
+    end
+
+    def cast(value, _type, _checked: true)
+      value
+    end
+
+    def let(value, _type, _checked: true)
+      value
+    end
+
+    def must(arg, _msg = nil)
+      arg
+    end
+
+    def proc
+      T::Proc.new
+    end
+
+    def reveal_type(value)
+      value
+    end
+
+    def unsafe(value)
+      value
+    end
+  end
+
+  module Sig
+    def sig(arg0 = nil, &blk); end
+  end
+
+  module Helpers
+    def abstract!;  end
+    def interface!; end
+    def final!; end
+    def sealed!; end
+    def mixes_in_class_methods(mod); end
+  end
+
+  module Generic
+    include(T::Helpers)
+
+    def type_parameters(*params); end
+    def type_member(variance = :invariant, fixed: nil, lower: nil, upper: BasicObject); end
+    def type_template(variance = :invariant, fixed: nil, lower: nil, upper: BasicObject); end
+
+    def [](*types)
+      self
+    end
+  end
+
+  module Array
+    class << self
+      def [](type); end
+    end
+  end
+
+  Boolean = Object.new.freeze
+
+  module Configuration
+    class << self
+      def call_validation_error_handler(signature, opts); end
+      def call_validation_error_handler=(value); end
+      def default_checked_level=(default_checked_level); end
+      def enable_checking_for_sigs_marked_checked_tests; end
+      def enable_final_checks_on_hooks; end
+      def enable_legacy_t_enum_migration_mode; end
+      def reset_final_checks_on_hooks; end
+      def hard_assert_handler(str, extra); end
+      def hard_assert_handler=(value); end
+      def inline_type_error_handler(error); end
+      def inline_type_error_handler=(value); end
+      def log_info_handler(str, extra); end
+      def log_info_handler=(value); end
+      def scalar_types; end
+      def scalar_types=(values); end
+      # rubocop:disable Naming/InclusiveLanguage
+      def sealed_violation_whitelist; end
+      def sealed_violation_whitelist=(sealed_violation_whitelist); end
+      # rubocop:enable Naming/InclusiveLanguage
+      def sig_builder_error_handler(error, location); end
+      def sig_builder_error_handler=(value); end
+      def sig_validation_error_handler(error, opts); end
+      def sig_validation_error_handler=(value); end
+      def soft_assert_handler(str, extra); end
+      def soft_assert_handler=(value); end
+    end
+  end
+
+  module Enumerable
+    class << self
+      def [](type); end
+    end
+  end
+
+  module Enumerator
+    class << self
+      def [](type); end
+    end
+  end
+
+  module Hash
+    class << self
+      def [](keys, values); end
+    end
+  end
+
+  class Proc
+    def bind(*_)
+      self
+    end
+
+    def params(*_param)
+      self
+    end
+
+    def void
+      self
+    end
+
+    def returns(_type)
+      self
+    end
+  end
+
+  module Range
+    class << self
+      def [](type); end
+    end
+  end
+
+  module Set
+    class << self
+      def [](type); end
+    end
+  end
+
+  class << self
+    def const_added(name)
+      super
+      raise 'When using both cli-ui and sorbet, you must require sorbet before cli-ui'
+    end
+
+    def method_added(name)
+      super
+      raise 'When using both cli-ui and sorbet, you must require sorbet before cli-ui'
+    end
+  end
+end

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

@@ -1,11 +1,20 @@
+# typed: true
+
 module CLI
   module UI
     module Spinner
       class Async
-        # Convenience method for +initialize+
-        #
-        def self.start(title)
-          new(title)
+        extend T::Sig
+
+        class << self
+          extend T::Sig
+
+          # Convenience method for +initialize+
+          #
+          sig { params(title: String).returns(Async) }
+          def start(title)
+            new(title)
+          end
         end
 
         # Initializes a new asynchronous spinner with no specific end.
@@ -19,6 +28,7 @@ module CLI
         #
         #   CLI::UI::Spinner::Async.new('Title')
         #
+        sig { params(title: String).void }
         def initialize(title)
           require 'thread'
           sg = CLI::UI::Spinner::SpinGroup.new
@@ -30,6 +40,7 @@ module CLI
 
         # Stops an asynchronous spinner
         #
+        sig { returns(T::Boolean) }
         def stop
           @m.synchronize { @cv.signal }
           @t.value