cli-ui 1.5.0 → 2.0.0

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

@@ -1,34 +1,48 @@
 # coding: utf-8
+
+# typed: true
+
 require 'io/console'
 
 module CLI
   module UI
     module Prompt
       class InteractiveOptions
+        extend T::Sig
+
         DONE = 'Done'
         CHECKBOX_ICON = { false => '☐', true => '☑' }
 
-        # Prompts the user with options
-        # Uses an interactive session to allow the user to pick an answer
-        # Can use arrows, y/n, numbers (1/2), and vim bindings to control
-        # For more than 9 options, hitting 'e', ':', or 'G' will enter select
-        # mode allowing the user to type in longer numbers
-        # Pressing 'f' or '/' will allow the user to filter the results
-        #
-        # https://user-images.githubusercontent.com/3074765/33797984-0ebb5e64-dcdf-11e7-9e7e-7204f279cece.gif
-        #
-        # ==== Example Usage:
-        #
-        # Ask an interactive question
-        #   CLI::UI::Prompt::InteractiveOptions.call(%w(rails go python))
-        #
-        def self.call(options, multiple: false, default: nil)
-          list = new(options, multiple: multiple, default: default)
-          selected = list.call
-          if multiple
-            selected.map { |s| options[s - 1] }
-          else
-            options[selected - 1]
+        class << self
+          extend T::Sig
+
+          # Prompts the user with options
+          # Uses an interactive session to allow the user to pick an answer
+          # Can use arrows, y/n, numbers (1/2), and vim bindings to control
+          # For more than 9 options, hitting 'e', ':', or 'G' will enter select
+          # mode allowing the user to type in longer numbers
+          # Pressing 'f' or '/' will allow the user to filter the results
+          #
+          # https://user-images.githubusercontent.com/3074765/33797984-0ebb5e64-dcdf-11e7-9e7e-7204f279cece.gif
+          #
+          # ==== Example Usage:
+          #
+          # Ask an interactive question
+          #   CLI::UI::Prompt::InteractiveOptions.call(%w(rails go python))
+          #
+          sig do
+            params(options: T::Array[String], multiple: T::Boolean, default: T.nilable(T.any(String, T::Array[String])))
+              .returns(T.any(String, T::Array[String]))
+          end
+          def call(options, multiple: false, default: nil)
+            list = new(options, multiple: multiple, default: default)
+            selected = list.call
+            case selected
+            when Array
+              selected.map { |s| T.must(options[s - 1]) }
+            else
+              T.must(options[selected - 1])
+            end
           end
         end
 
@@ -39,6 +53,10 @@ module CLI
         #
         #   CLI::UI::Prompt::InteractiveOptions.new(%w(rails go python))
         #
+        sig do
+          params(options: T::Array[String], multiple: T::Boolean, default: T.nilable(T.any(String, T::Array[String])))
+            .void
+        end
         def initialize(options, multiple: false, default: nil)
           @options = options
           @active = 1
@@ -60,12 +78,13 @@ module CLI
             end
           end
           @redraw = true
-          @presented_options = []
+          @presented_options = T.let([], T::Array[[String, T.nilable(Integer)]])
         end
 
         # Calls the +InteractiveOptions+ and asks the question
         # Usually used from +self.call+
         #
+        sig { returns(T.any(Integer, T::Array[Integer])) }
         def call
           calculate_option_line_lengths
           CLI::UI.raw { print(ANSI.hide_cursor) }
@@ -85,6 +104,7 @@ module CLI
 
         private
 
+        sig { void }
         def calculate_option_line_lengths
           @terminal_width_at_calculation_time = CLI::UI::Terminal.width
           # options will be an array of questions but each option can be multi-line
@@ -103,13 +123,13 @@ module CLI
             width ||= text
               .split("\n")
               .reject(&:empty?)
-              .map { |l| (CLI::UI.fmt(l, enable_color: false).length / max_width).ceil }
-              .reduce(&:+)
+              .sum { |l| (CLI::UI.fmt(l, enable_color: false).length / max_width).ceil }
 
             width
           end
         end
 
+        sig { params(number_of_lines: Integer).void }
         def reset_position(number_of_lines = num_lines)
           # This will put us back at the beginning of the options
           # When we redraw the options, they will be overwritten
@@ -118,6 +138,7 @@ module CLI
           end
         end
 
+        sig { params(number_of_lines: Integer).void }
         def clear_output(number_of_lines = num_lines)
           CLI::UI.raw do
             # Write over all lines with whitespace
@@ -133,22 +154,26 @@ module CLI
 
         # Don't use this in place of +@displaying_metadata+, this updates too
         # quickly to be useful when drawing to the screen.
+        sig { returns(T::Boolean) }
         def display_metadata?
           filtering? || selecting? || has_filter?
         end
 
+        sig { returns(Integer) }
         def num_lines
           calculate_option_line_lengths if terminal_width_changed?
 
           option_length = presented_options.reduce(0) do |total_length, (_, option_number)|
             # Handle continuation markers and "Done" option when multiple is true
             next total_length + 1 if option_number.nil? || option_number.zero?
+
             total_length + @option_lengths[option_number - 1]
           end
 
           option_length + (@displaying_metadata ? 1 : 0)
         end
 
+        sig { returns(T::Boolean) }
         def terminal_width_changed?
           @terminal_width_at_calculation_time != CLI::UI::Terminal.width
         end
@@ -158,6 +183,7 @@ module CLI
         CTRL_C = "\u0003"
         CTRL_D = "\u0004"
 
+        sig { void }
         def up
           active_index = @filtered_options.index { |_, num| num == @active } || 0
 
@@ -168,6 +194,7 @@ module CLI
           @redraw = true
         end
 
+        sig { void }
         def down
           active_index = @filtered_options.index { |_, num| num == @active } || 0
 
@@ -180,6 +207,7 @@ module CLI
 
         # n is 1-indexed selection
         # n == 0 if "Done" was selected in @multiple mode
+        sig { params(n: Integer).void }
         def select_n(n)
           if @multiple
             if n == 0
@@ -200,24 +228,29 @@ module CLI
           @redraw = true
         end
 
+        sig { params(char: String).void }
         def select_bool(char)
-          return unless (@options - %w(yes no)).empty?
-          opt = @options.detect { |o| o.start_with?(char) }
-          @active = @options.index(opt) + 1
-          @answer = @options.index(opt) + 1
+          return unless (@options - ['yes', 'no']).empty?
+
+          index = T.must(@options.index { |o| o.start_with?(char) })
+          @active = index + 1
+          @answer = index + 1
           @redraw = true
         end
 
+        sig { params(char: String).void }
         def build_selection(char)
           @active = (@active.to_s + char).to_i
           @redraw = true
         end
 
+        sig { void }
         def chop_selection
           @active = @active.to_s.chop.to_i
           @redraw = true
         end
 
+        sig { params(char: String).void }
         def update_search(char)
           @redraw = true
 
@@ -235,25 +268,28 @@ module CLI
           end
         end
 
+        sig { void }
         def select_current
           # Prevent selection of invisible options
           return unless presented_options.any? { |_, num| num == @active }
+
           select_n(@active)
         end
 
+        sig { void }
         def process_input_until_redraw_required
           @redraw = false
           wait_for_user_input until @redraw
         end
 
         # rubocop:disable Style/WhenThen,Layout/SpaceBeforeSemicolon,Style/Semicolon
+        sig { void }
         def wait_for_user_input
           char = read_char
           @last_char = char
 
           case char
-          when :timeout ; raise Interrupt # Timeout, use interrupt to simulate
-          when CTRL_C   ; raise Interrupt
+          when CTRL_C, nil ; raise Interrupt
           end
 
           max_digit = [@options.size, 9].min.to_s
@@ -302,51 +338,59 @@ module CLI
             end
           end
         end
-        # rubocop:enable Style/WhenThen,Layout/SpaceBeforeSemicolon
+        # rubocop:enable Style/WhenThen,Layout/SpaceBeforeSemicolon,Style/Semicolon
 
+        sig { returns(T::Boolean) }
         def selecting?
           @state == :line_select
         end
 
+        sig { returns(T::Boolean) }
         def filtering?
           @state == :filter
         end
 
+        sig { returns(T::Boolean) }
         def has_filter?
           !@filter.empty?
         end
 
+        sig { void }
         def start_filter
           @state = :filter
           @redraw = true
         end
 
+        sig { void }
         def start_line_select
           @state  = :line_select
           @active = 0
           @redraw = true
         end
 
+        sig { void }
         def stop_line_select
           @state = :root
           @active = 1 if @active.zero?
           @redraw = true
         end
 
+        sig { returns(T.nilable(String)) }
         def read_char
           if $stdin.tty? && !ENV['TEST']
             $stdin.getch # raw mode for tty
           else
-            $stdin.getc
+            $stdin.getc # returns nil at end of input
           end
-        rescue IOError
+        rescue Errno::EIO, Errno::EPIPE, IOError
           "\e"
         end
 
+        sig { params(recalculate: T::Boolean).returns(T::Array[[String, T.nilable(Integer)]]) }
         def presented_options(recalculate: false)
           return @presented_options unless recalculate
 
-          @presented_options = @options.zip(1..Float::INFINITY)
+          @presented_options = @options.zip(1..)
           if has_filter?
             @presented_options.select! { |option, _| option.downcase.include?(@filter.downcase) }
           end
@@ -385,36 +429,44 @@ module CLI
           @presented_options
         end
 
+        sig { void }
         def ensure_visible_is_active
           unless presented_options.any? { |_, num| num == @active }
             @active = presented_options.first&.last.to_i
           end
         end
 
+        sig { returns(Integer) }
         def distance_from_selection_to_end
           @presented_options.count - index_of_active_option
         end
 
+        sig { returns(Integer) }
         def distance_from_start_to_selection
           index_of_active_option
         end
 
+        sig { returns(Integer) }
         def index_of_active_option
           @presented_options.index { |_, num| num == @active }.to_i
         end
 
+        sig { void }
         def ensure_last_item_is_continuation_marker
-          @presented_options.push(['...', nil]) if @presented_options.last.last
+          @presented_options.push(['...', nil]) if @presented_options.last&.last
         end
 
+        sig { void }
         def ensure_first_item_is_continuation_marker
-          @presented_options.unshift(['...', nil]) if @presented_options.first.last
+          @presented_options.unshift(['...', nil]) if @presented_options.first&.last
         end
 
+        sig { returns(Integer) }
         def max_lines
           CLI::UI::Terminal.height - (@displaying_metadata ? 3 : 2) # Keeps a one line question visible
         end
 
+        sig { void }
         def render_options
           previously_displayed_lines = num_lines
 
@@ -436,11 +488,7 @@ module CLI
             "Filter: #{filter_text}"
           end
 
-          if metadata_text
-            CLI::UI.with_frame_color(:blue) do
-              puts CLI::UI.fmt("  {{green:#{metadata_text}}}#{ANSI.clear_to_end_of_line}")
-            end
-          end
+          puts CLI::UI.fmt("  {{green:#{metadata_text}}}#{ANSI.clear_to_end_of_line}") if metadata_text
 
           options.each do |choice, num|
             is_chosen = @multiple && num && @chosen[num - 1] && num != 0
@@ -463,12 +511,11 @@ module CLI
               message = message.split("\n").map { |l| "{{#{color}:> #{l.strip}}}" }.join("\n")
             end
 
-            CLI::UI.with_frame_color(:blue) do
-              puts CLI::UI.fmt(message)
-            end
+            puts CLI::UI.fmt(message)
           end
         end
 
+        sig { params(format: String, choice: String).returns(String) }
         def format_choice(format, choice)
           eol = CLI::UI::ANSI.clear_to_end_of_line
           lines = choice.split("\n")

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

@@ -1,20 +1,28 @@
+# typed: true
+
 module CLI
   module UI
     module Prompt
       # A class that handles the various options of an InteractivePrompt and their callbacks
       class OptionsHandler
+        extend T::Sig
+
+        sig { void }
         def initialize
           @options = {}
         end
 
+        sig { returns(T::Array[String]) }
         def options
           @options.keys
         end
 
+        sig { params(option: String, handler: T.proc.params(option: String).returns(String)).void }
         def option(option, &handler)
           @options[option] = handler
         end
 
+        sig { params(options: T.any(T::Array[String], String)).returns(String) }
         def call(options)
           case options
           when Array

data/lib/cli/ui/prompt.rb

@@ -1,4 +1,7 @@
 # coding: utf-8
+
+# typed: true
+
 require 'cli/ui'
 require 'readline'
 
@@ -22,9 +25,10 @@ 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
+
         # 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 +96,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 has_options && is_file
+            raise(ArgumentError, 'conflicting arguments: is_file is only useful when options are not provided')
           end
 
-          if options && multiple && default && !(default - options).empty?
+          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 +152,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,24 +163,23 @@ 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.
+          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
+          # 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.to_s.chomp
+          end
 
-            STDOUT.puts # Complete the line
+          STDOUT.puts # Complete the line
 
-            password
-          end
+          password
         end
 
         # Asks the user a yes/no question.
@@ -163,12 +192,17 @@ 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
 
         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')
@@ -195,6 +229,16 @@ module CLI
           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 +249,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"
@@ -223,9 +268,9 @@ module CLI
           print(ANSI.previous_line + "\n")
 
           # reset the question to include the answer
-          resp_text = resp
-          if multiple
-            resp_text = case resp.size
+          resp_text = case resp
+          when Array
+            case resp.size
             when 0
               '<nothing>'
             when 1..2
@@ -233,18 +278,26 @@ module CLI
             else
               "#{resp.size} items"
             end
+          else
+            resp
           end
           puts_question("#{question} (You chose: {{italic:#{resp_text}}})")
 
-          return handler.call(resp) if block_given?
+          return T.must(handler).call(resp) if block_given?
+
           resp
         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)
         end
 
+        sig { params(default: String).void }
         def write_default_over_empty_input(default)
           CLI::UI.raw do
             STDERR.puts(
@@ -252,17 +305,17 @@ module CLI
               "\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,11 +329,11 @@ 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)