cli-ui 1.5.0 → 2.0.0

data/lib/cli/ui/glyph.rb

@@ -1,14 +1,22 @@
+# typed: true
+
 require 'cli/ui'
 
 module CLI
   module UI
     class Glyph
+      extend T::Sig
+
       class InvalidGlyphHandle < ArgumentError
+        extend T::Sig
+
+        sig { params(handle: String).void }
         def initialize(handle)
           super
           @handle = handle
         end
 
+        sig { returns(String) }
         def message
           keys = Glyph.available.join(',')
           "invalid glyph handle: #{@handle} " \
@@ -16,7 +24,14 @@ module CLI
         end
       end
 
-      attr_reader :handle, :codepoint, :color, :to_s, :fmt
+      sig { returns(String) }
+      attr_reader :handle, :to_s, :fmt, :char
+
+      sig { returns(T.any(Integer, T::Array[Integer])) }
+      attr_reader :codepoint
+
+      sig { returns(Color) }
+      attr_reader :color
 
       # Creates a new glyph
       #
@@ -27,26 +42,18 @@ module CLI
       # * +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.
       #
+      sig { params(handle: String, codepoint: T.any(Integer, T::Array[Integer]), plain: String, color: Color).void }
       def initialize(handle, codepoint, plain, color)
         @handle    = handle
         @codepoint = codepoint
         @color     = color
-        @plain     = plain
-        @char      = Array(codepoint).pack('U*')
-        @to_s      = color.code + char + Color::RESET.code
-        @fmt       = "{{#{color.name}:#{char}}}"
+        @char      = CLI::UI::OS.current.use_emoji? ? Array(codepoint).pack('U*') : plain
+        @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 = {}
       STAR      = new('*', 0x2b51,           '*', Color::YELLOW) # YELLOW SMALL STAR (⭑)
@@ -59,25 +66,31 @@ module CLI
       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
-      #
-      # ==== Raises
-      # Raises a InvalidGlyphHandle if the glyph is not available
-      # You likely need to create it with +.new+ or you made a typo
-      #
-      # ==== Returns
-      # Returns a terminal output-capable string
-      #
-      def self.lookup(name)
-        MAP.fetch(name.to_s)
-      rescue KeyError
-        raise InvalidGlyphHandle, name
-      end
+      class << self
+        extend T::Sig
 
-      # All available glyphs by name
-      #
-      def self.available
-        MAP.keys
+        # Looks up a glyph by name
+        #
+        # ==== Raises
+        # Raises a InvalidGlyphHandle if the glyph is not available
+        # You likely need to create it with +.new+ or you made a typo
+        #
+        # ==== Returns
+        # Returns a terminal output-capable string
+        #
+        sig { params(name: String).returns(Glyph) }
+        def lookup(name)
+          MAP.fetch(name.to_s)
+        rescue KeyError
+          raise InvalidGlyphHandle, name
+        end
+
+        # All available glyphs by name
+        #
+        sig { returns(T::Array[String]) }
+        def available
+          MAP.keys
+        end
       end
     end
   end

data/lib/cli/ui/os.rb

@@ -1,67 +1,63 @@
+# typed: true
+
 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
+    class OS
+      extend T::Sig
+
+      sig { params(emoji: T::Boolean, color_prompt: T::Boolean, arrow_keys: T::Boolean, shift_cursor: T::Boolean).void }
+      def initialize(emoji: true, color_prompt: true, arrow_keys: true, shift_cursor: false)
+        @emoji = emoji
+        @color_prompt = color_prompt
+        @arrow_keys = arrow_keys
+        @shift_cursor = shift_cursor
       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
+      sig { returns(T::Boolean) }
+      def use_emoji?
+        @emoji
       end
 
-      class Linux < Mac
+      sig { returns(T::Boolean) }
+      def use_color_prompt?
+        @color_prompt
       end
 
-      class Windows
-        class << self
-          def supports_emoji?
-            false
-          end
+      sig { returns(T::Boolean) }
+      def suggest_arrow_keys?
+        @arrow_keys
+      end
 
-          def supports_color_prompt?
-            false
-          end
+      sig { returns(T::Boolean) }
+      def shift_cursor_back_on_horizontal_absolute?
+        @shift_cursor
+      end
 
-          def supports_arrow_keys?
-            false
-          end
+      class << self
+        extend T::Sig
 
-          def shift_cursor_on_line_reset?
-            true
+        sig { returns(OS) }
+        def 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
       end
+
+      MAC = OS.new
+      LINUX = OS.new
+      WINDOWS = OS.new(emoji: false, color_prompt: false, arrow_keys: false, shift_cursor: true)
     end
   end
 end

data/lib/cli/ui/printer.rb

@@ -1,58 +1,76 @@
+# typed: true
+
 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
+      extend T::Sig
+
+      class << self
+        extend T::Sig
 
-        if frame_color
-          CLI::UI::Frame.with_frame_color_override(frame_color) { to.puts(msg) }
-        else
-          to.puts(msg)
+        # 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)
+        #
+        sig do
+          params(
+            msg: String,
+            frame_color: T.nilable(Colorable),
+            to: IOLike,
+            encoding: T.nilable(Encoding),
+            format: T::Boolean,
+            graceful: T::Boolean,
+            wrap: T::Boolean,
+          ).returns(T::Boolean)
         end
+        def 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
+          true
+        rescue Errno::EIO, Errno::EPIPE, IOError => e
+          raise(e) unless graceful
+
+          false
+        end
       end
     end
   end

data/lib/cli/ui/progress.rb

@@ -1,41 +1,54 @@
+# typed: true
+
 require 'cli/ui'
 
 module CLI
   module UI
     class Progress
+      extend T::Sig
+
       # A Cyan filled block
       FILLED_BAR = "\e[46m"
       # A bright white block
       UNFILLED_BAR = "\e[1;47m"
 
-      # Add a progress bar to the terminal output
-      #
-      # https://user-images.githubusercontent.com/3074765/33799794-cc4c940e-dd00-11e7-9bdc-90f77ec9167c.gif
-      #
-      # ==== Example Usage:
-      #
-      # Set the percent to X
-      #   CLI::UI::Progress.progress do |bar|
-      #     bar.tick(set_percent: percent)
-      #   end
-      #
-      # Increase the percent by 1 percent
-      #   CLI::UI::Progress.progress do |bar|
-      #     bar.tick
-      #   end
-      #
-      # Increase the percent by X
-      #   CLI::UI::Progress.progress do |bar|
-      #     bar.tick(percent: 0.05)
-      #   end
-      def self.progress(width: Terminal.width)
-        bar = Progress.new(width: width)
-        print(CLI::UI::ANSI.hide_cursor)
-        yield(bar)
-      ensure
-        puts bar.to_s
-        CLI::UI.raw do
-          print(ANSI.show_cursor)
+      class << self
+        extend T::Sig
+
+        # Add a progress bar to the terminal output
+        #
+        # https://user-images.githubusercontent.com/3074765/33799794-cc4c940e-dd00-11e7-9bdc-90f77ec9167c.gif
+        #
+        # ==== Example Usage:
+        #
+        # Set the percent to X
+        #   CLI::UI::Progress.progress do |bar|
+        #     bar.tick(set_percent: percent)
+        #   end
+        #
+        # Increase the percent by 1 percent
+        #   CLI::UI::Progress.progress do |bar|
+        #     bar.tick
+        #   end
+        #
+        # Increase the percent by X
+        #   CLI::UI::Progress.progress do |bar|
+        #     bar.tick(percent: 0.05)
+        #   end
+        sig do
+          type_parameters(:T)
+            .params(width: Integer, block: T.proc.params(bar: Progress).returns(T.type_parameter(:T)))
+            .returns(T.type_parameter(:T))
+        end
+        def progress(width: Terminal.width, &block)
+          bar = Progress.new(width: width)
+          print(CLI::UI::ANSI.hide_cursor)
+          yield(bar)
+        ensure
+          puts bar.to_s
+          CLI::UI.raw do
+            print(ANSI.show_cursor)
+          end
         end
       end
 
@@ -46,8 +59,9 @@ module CLI
       #
       # * +:width+ - The width of the terminal
       #
+      sig { params(width: Integer).void }
       def initialize(width: Terminal.width)
-        @percent_done = 0
+        @percent_done = T.let(0, Numeric)
         @max_width = width
       end
 
@@ -61,9 +75,11 @@ module CLI
       #
       # *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
+      sig { params(percent: T.nilable(Numeric), set_percent: T.nilable(Numeric)).void }
+      def tick(percent: nil, set_percent: nil)
+        raise ArgumentError, 'percent and set_percent cannot both be specified' if percent && set_percent
+
+        @percent_done += percent || 0.01
         @percent_done = set_percent if set_percent
         @percent_done = [@percent_done, 1.0].min # Make sure we can't go above 1.0
 
@@ -73,6 +89,7 @@ module CLI
 
       # Format the progress bar to be printed to terminal
       #
+      sig { returns(String) }
       def to_s
         suffix = " #{(@percent_done * 100).floor}%".ljust(5)
         workable_width = @max_width - Frame.prefix_width - suffix.size