cli-ui 1.2.1 → 1.5.0

data/lib/cli/ui/glyph.rb

@@ -5,6 +5,7 @@ module CLI
     class Glyph
       class InvalidGlyphHandle < ArgumentError
         def initialize(handle)
+          super
           @handle = handle
         end
 
@@ -15,7 +16,7 @@ module CLI
         end
       end
 
-      attr_reader :handle, :codepoint, :color, :char, :to_s, :fmt
+      attr_reader :handle, :codepoint, :color, :to_s, :fmt
 
       # Creates a new glyph
       #
@@ -23,35 +24,40 @@ module CLI
       #
       # * +handle+ - The handle in the +MAP+ constant
       # * +codepoint+ - The codepoint used to create the glyph (e.g. +0x2717+ for a ballot X)
+      # * +plain+ - A fallback plain string to be used in case glyphs are disabled
       # * +color+ - What color to output the glyph. Check +CLI::UI::Color+ for options.
       #
-      def initialize(handle, codepoint, color)
+      def initialize(handle, codepoint, plain, color)
         @handle    = handle
         @codepoint = codepoint
         @color     = color
-        @char      = [codepoint].pack('U')
+        @plain     = plain
+        @char      = Array(codepoint).pack('U*')
         @to_s      = color.code + char + Color::RESET.code
         @fmt       = "{{#{color.name}:#{char}}}"
 
         MAP[handle] = self
       end
 
+      # Fetches the actual character(s) to be displayed for a glyph, based on the current OS support
+      #
+      # ==== Returns
+      # Returns the glyph string
+      def char
+        CLI::UI::OS.current.supports_emoji? ? @char : @plain
+      end
+
       # 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,          'i', 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,           'X', 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], 'H', Color::BLUE)   # HOURGLASS + VARIATION SELECTOR 15 (⌛︎)
+      WARNING   = new('!', [0x26a0, 0xfe0f], '!', Color::YELLOW) # WARNING SIGN + VARIATION SELECTOR 16 (⚠️ )
 
       # Looks up a glyph by name
       #

data/lib/cli/ui/os.rb

@@ -0,0 +1,67 @@
+require 'rbconfig'
+
+module CLI
+  module UI
+    module OS
+      # Determines which OS is currently running the UI, to make it easier to
+      # adapt its behaviour to the features of the OS.
+      def self.current
+        @current_os ||= case RbConfig::CONFIG['host_os']
+        when /darwin/
+          Mac
+        when /linux/
+          Linux
+        else
+          if RUBY_PLATFORM !~ /cygwin/ && ENV['OS'] == 'Windows_NT'
+            Windows
+          else
+            raise "Could not determine OS from host_os #{RbConfig::CONFIG["host_os"]}"
+          end
+        end
+      end
+
+      class Mac
+        class << self
+          def supports_emoji?
+            true
+          end
+
+          def supports_color_prompt?
+            true
+          end
+
+          def supports_arrow_keys?
+            true
+          end
+
+          def shift_cursor_on_line_reset?
+            false
+          end
+        end
+      end
+
+      class Linux < Mac
+      end
+
+      class Windows
+        class << self
+          def supports_emoji?
+            false
+          end
+
+          def supports_color_prompt?
+            false
+          end
+
+          def supports_arrow_keys?
+            false
+          end
+
+          def shift_cursor_on_line_reset?
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cli/ui/printer.rb

@@ -0,0 +1,59 @@
+require 'cli/ui'
+
+module CLI
+  module UI
+    class Printer
+      # Print a message to a stream with common utilities.
+      # Allows overriding the color, encoding, and target stream.
+      # By default, it formats the string using CLI:UI and rescues common stream errors.
+      #
+      # ==== Attributes
+      #
+      # * +msg+ - (required) the string to output. Can be frozen.
+      #
+      # ==== Options
+      #
+      # * +:frame_color+ - Override the frame color. Defaults to nil.
+      # * +:to+ - Target stream, like $stdout or $stderr. Can be anything with a puts method. Defaults to $stdout.
+      # * +:encoding+ - Force the output to be in a certain encoding. Defaults to UTF-8.
+      # * +:format+ - Whether to format the string using CLI::UI.fmt. Defaults to true.
+      # * +:graceful+ - Whether to gracefully ignore common I/O errors. Defaults to true.
+      # * +:wrap+ - Whether to wrap text at word boundaries to terminal width. Defaults to true.
+      #
+      # ==== Returns
+      # Returns whether the message was successfully printed,
+      # which can be useful if +:graceful+ is set to true.
+      #
+      # ==== Example
+      #
+      #   CLI::UI::Printer.puts('{{x}} Ouch', to: $stderr)
+      #
+      def self.puts(
+        msg,
+        frame_color:
+        nil,
+        to:
+        $stdout,
+        encoding: Encoding::UTF_8,
+        format: true,
+        graceful: true,
+        wrap: true
+      )
+        msg = (+msg).force_encoding(encoding) if encoding
+        msg = CLI::UI.fmt(msg) if format
+        msg = CLI::UI.wrap(msg) if wrap
+
+        if frame_color
+          CLI::UI::Frame.with_frame_color_override(frame_color) { to.puts(msg) }
+        else
+          to.puts(msg)
+        end
+
+        true
+      rescue Errno::EIO, Errno::EPIPE, IOError => e
+        raise(e) unless graceful
+        false
+      end
+    end
+  end
+end

data/lib/cli/ui/progress.rb

@@ -26,11 +26,11 @@ module CLI
       #
       # Increase the percent by X
       #   CLI::UI::Progress.progress do |bar|
-      #     bar.tick(percent: 5)
+      #     bar.tick(percent: 0.05)
       #   end
       def self.progress(width: Terminal.width)
         bar = Progress.new(width: width)
-        print CLI::UI::ANSI.hide_cursor
+        print(CLI::UI::ANSI.hide_cursor)
         yield(bar)
       ensure
         puts bar.to_s
@@ -59,29 +59,31 @@ module CLI
       # * +:percent+ - Increment progress by a specific percent amount
       # * +:set_percent+ - Set progress to a specific percent
       #
+      # *Note:* The +:percent+ and +:set_percent must be between 0.00 and 1.0
+      #
       def tick(percent: 0.01, set_percent: nil)
         raise ArgumentError, 'percent and set_percent cannot both be specified' if percent != 0.01 && set_percent
         @percent_done += percent
         @percent_done = set_percent if set_percent
         @percent_done = [@percent_done, 1.0].min # Make sure we can't go above 1.0
 
-        print to_s
-        print CLI::UI::ANSI.previous_line + "\n"
+        print(to_s)
+        print(CLI::UI::ANSI.previous_line + "\n")
       end
 
       # Format the progress bar to be printed to terminal
       #
       def to_s
-        suffix = " #{(@percent_done * 100).round(2)}%"
+        suffix = " #{(@percent_done * 100).floor}%".ljust(5)
         workable_width = @max_width - Frame.prefix_width - suffix.size
         filled = [(@percent_done * workable_width.to_f).ceil, 0].max
         unfilled = [workable_width - filled, 0].max
 
-        CLI::UI.resolve_text [
+        CLI::UI.resolve_text([
           FILLED_BAR + ' ' * filled,
           UNFILLED_BAR + ' ' * unfilled,
-          CLI::UI::Color::RESET.code + suffix
-        ].join
+          CLI::UI::Color::RESET.code + suffix,
+        ].join)
       end
     end
   end

data/lib/cli/ui/prompt.rb

@@ -1,6 +1,22 @@
+# coding: utf-8
 require 'cli/ui'
 require 'readline'
 
+module Readline
+  unless const_defined?(:FILENAME_COMPLETION_PROC)
+    FILENAME_COMPLETION_PROC = proc do |input|
+      directory = input[-1] == '/' ? input : File.dirname(input)
+      filename = input[-1] == '/' ? '' : File.basename(input)
+
+      (Dir.entries(directory).select do |fp|
+        fp.start_with?(filename)
+      end - (input[-1] == '.' ? [] : ['.', '..'])).map do |fp|
+        File.join(directory, fp).gsub(/\A\.\//, '')
+      end
+    end
+  end
+end
+
 module CLI
   module UI
     module Prompt
@@ -30,11 +46,16 @@ module CLI
         # * +:default+ - The default answer to the question (e.g. they just press enter and don't input anything)
         # * +:is_file+ - Tells the input to use file auto-completion (tab completion)
         # * +:allow_empty+ - Allows the answer to be empty
+        # * +:multiple+ - Allow multiple options to be selected
+        # * +:filter_ui+ - Enable option filtering (default: true)
+        # * +:select_ui+ - Enable long-form option selection (default: true)
         #
         # Note:
-        # * +:options+ or providing a +Block+ conflicts with +:default+ and +:is_file+, you cannot set options with either of these keywords
+        # * +:options+ or providing a +Block+ conflicts with +:default+ and +:is_file+,
+        #              you cannot set options with either of these keywords
         # * +:default+ conflicts with +:allow_empty:, you cannot set these together
         # * +:options+ conflicts with providing a +Block+ , you may only set one
+        # * +:multiple+ can only be used with +:options+ or a +Block+; it is ignored, otherwise.
         #
         # ==== Block (optional)
         #
@@ -44,7 +65,7 @@ module CLI
         # ==== Return Value
         #
         # * If a +Block+ was not provided, the selected option or response to the free form question will be returned
-        # * If a +Block+ was provided, the evaluted value of the +Block+ will be returned
+        # * If a +Block+ was provided, the evaluated value of the +Block+ will be returned
         #
         # ==== Example Usage:
         #
@@ -71,18 +92,67 @@ module CLI
         #     handler.option('python') { |selection| selection }
         #   end
         #
-        def ask(question, options: nil, default: nil, is_file: nil, allow_empty: true, multiple: false, &options_proc)
-          if ((options || block_given?) && (default || is_file))
+        def ask(
+          question,
+          options: nil,
+          default: nil,
+          is_file: nil,
+          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')
           end
 
+          if options && multiple && default && !(default - options).empty?
+            raise(ArgumentError, 'conflicting arguments: default should only include elements present in options')
+          end
+
           if options || block_given?
-            ask_interactive(question, options, multiple: multiple, &options_proc)
+            ask_interactive(
+              question,
+              options,
+              multiple: multiple,
+              default: default,
+              filter_ui: filter_ui,
+              select_ui: select_ui,
+              &options_proc
+            )
           else
             ask_free_form(question, default, is_file, allow_empty)
           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
         #
@@ -91,14 +161,18 @@ module CLI
         # Confirmation question
         #   CLI::UI::Prompt.confirm('Is the sky blue?')
         #
-        def confirm(question)
-          ask_interactive(question, %w(yes no)) == 'yes'
+        #   CLI::UI::Prompt.confirm('Do a dangerous thing?', default: false)
+        #
+        def confirm(question, default: true)
+          ask_interactive(question, default ? %w(yes no) : %w(no yes), filter_ui: false) == 'yes'
         end
 
         private
 
         def ask_free_form(question, default, is_file, allow_empty)
-          raise(ArgumentError, 'conflicting arguments: default enabled but allow_empty is false') if (default && !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})")
@@ -121,7 +195,7 @@ module CLI
           end
         end
 
-        def ask_interactive(question, options = nil, multiple: false)
+        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?
 
           options ||= if block_given?
@@ -130,24 +204,32 @@ module CLI
             handler.options
           end
 
-          raise(ArgumentError, 'insufficient options') if options.nil? || options.size < 2
-          instructions = (multiple ? "Toggle options. " : "") + "Choose with ↑ ↓ ⏎"
+          raise(ArgumentError, 'insufficient options') if options.nil? || options.empty?
+          navigate_text = if CLI::UI::OS.current.supports_arrow_keys?
+            'Choose with ↑ ↓ ⏎'
+          else
+            "Navigate up with 'k' and down with 'j', press Enter to select"
+          end
+
+          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)
+          resp = interactive_prompt(options, multiple: multiple, default: default)
 
           # Clear the line
-          print ANSI.previous_line + ANSI.clear_to_end_of_line
+          print(ANSI.previous_line + ANSI.clear_to_end_of_line)
           # Force StdoutRouter to prefix
-          print ANSI.previous_line + "\n"
+          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>"
+              '<nothing>'
             when 1..2
-              resp.join(" and ")
+              resp.join(' and ')
             else
               "#{resp.size} items"
             end
@@ -159,8 +241,8 @@ module CLI
         end
 
         # Useful for stubbing in tests
-        def interactive_prompt(options, multiple: false)
-          InteractiveOptions.call(options, multiple: multiple)
+        def interactive_prompt(options, multiple: false, default: nil)
+          InteractiveOptions.call(options, multiple: multiple, default: default)
         end
 
         def write_default_over_empty_input(default)
@@ -184,10 +266,10 @@ module CLI
         def readline(is_file: false)
           if is_file
             Readline.completion_proc = Readline::FILENAME_COMPLETION_PROC
-            Readline.completion_append_character = ""
+            Readline.completion_append_character = ''
           else
             Readline.completion_proc = proc { |*| nil }
-            Readline.completion_append_character = " "
+            Readline.completion_append_character = ' '
           end
 
           # because Readline is a C library, CLI::UI's hooks into $stdout don't
@@ -195,10 +277,14 @@ module CLI
           # thread to manage output, but the current strategy feels like a
           # better tradeoff.
           prefix = CLI::UI.with_frame_color(:blue) { CLI::UI::Frame.prefix }
-          prompt = prefix + CLI::UI.fmt('{{blue:> }}{{yellow:')
+          # 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?
 
           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) }