cli-ui 1.5.1 → 2.2.3

data/lib/cli/ui/frame.rb

@@ -1,4 +1,7 @@
 # coding: utf-8
+
+# typed: true
+
 require 'cli/ui'
 require 'cli/ui/frame/frame_stack'
 require 'cli/ui/frame/frame_style'
@@ -7,9 +10,12 @@ module CLI
   module UI
     module Frame
       class UnnestedFrameException < StandardError; end
+      DEFAULT_FRAME_COLOR = CLI::UI.resolve_color(:cyan)
+
       class << self
-        DEFAULT_FRAME_COLOR = CLI::UI.resolve_color(:cyan)
+        extend T::Sig
 
+        sig { returns(FrameStyle) }
         def frame_style
           @frame_style ||= FrameStyle::Box
         end
@@ -22,6 +28,7 @@ module CLI
         #
         # * +symbol+ or +FrameStyle+ - the default frame style to use for frames
         #
+        sig { params(frame_style: FrameStylable).void }
         def frame_style=(frame_style)
           @frame_style = CLI::UI.resolve_style(frame_style)
         end
@@ -47,6 +54,8 @@ module CLI
         # * +:success_text+ - If the block succeeds, what do we output? Defaults to nil
         # * +:timing+ - How long did the frame content take? Invalid for blockless. Defaults to true for the block form
         # * +frame_style+ - The frame style to use for this frame
+        # * +:to+ - Target stream, like $stdout or $stderr. Can be anything with print and puts methods,
+        #   or under Sorbet, IO or StringIO. Defaults to $stdout.
         #
         # ==== Example
         #
@@ -67,13 +76,27 @@ module CLI
         #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
         #
         #
+        sig do
+          type_parameters(:T).params(
+            text: String,
+            color: Colorable,
+            failure_text: T.nilable(String),
+            success_text: T.nilable(String),
+            timing: T.any(T::Boolean, Numeric),
+            frame_style: FrameStylable,
+            to: IOLike,
+            block: T.nilable(T.proc.returns(T.type_parameter(:T))),
+          ).returns(T.nilable(T.type_parameter(:T)))
+        end
         def open(
           text,
           color: DEFAULT_FRAME_COLOR,
           failure_text: nil,
           success_text: nil,
-          timing:       nil,
-          frame_style:  self.frame_style
+          timing: block_given?,
+          frame_style: self.frame_style,
+          to: $stdout,
+          &block
         )
           frame_style = CLI::UI.resolve_style(frame_style)
           color = CLI::UI.resolve_color(color)
@@ -90,8 +113,8 @@ module CLI
 
           t_start = Time.now
           CLI::UI.raw do
-            print(prefix.chop)
-            puts frame_style.open(text, color: color)
+            to.print(prefix.chop)
+            to.puts(frame_style.start(text, color: color))
           end
           FrameStack.push(color: color, style: frame_style)
 
@@ -103,18 +126,18 @@ module CLI
             success = yield
           rescue
             closed = true
-            t_diff = elasped(t_start, timing)
-            close(failure_text, color: :red, elapsed: t_diff)
+            t_diff = elapsed(t_start, timing)
+            close(failure_text, color: :red, elapsed: t_diff, to: to)
             raise
           else
             success
           ensure
             unless closed
-              t_diff = elasped(t_start, timing)
-              if success != false
-                close(success_text, color: color, elapsed: t_diff)
+              t_diff = elapsed(t_start, timing)
+              if T.unsafe(success) != false
+                close(success_text, color: color, elapsed: t_diff, to: to)
               else
-                close(failure_text, color: :red, elapsed: t_diff)
+                close(failure_text, color: :red, elapsed: t_diff, to: to)
               end
             end
           end
@@ -131,6 +154,8 @@ module CLI
         #
         # * +:color+ - The color of the frame. Defaults to +DEFAULT_FRAME_COLOR+
         # * +frame_style+ - The frame style to use for this frame
+        # * +:to+ - Target stream, like $stdout or $stderr. Can be anything with print and puts methods,
+        #   or under Sorbet, IO or StringIO. Defaults to $stdout.
         #
         # ==== Example
         #
@@ -145,16 +170,24 @@ module CLI
         #
         # MUST be inside an open frame or it raises a +UnnestedFrameException+
         #
-        def divider(text, color: nil, frame_style: nil)
+        sig do
+          params(
+            text: T.nilable(String),
+            color: T.nilable(Colorable),
+            frame_style: T.nilable(FrameStylable),
+            to: IOLike,
+          ).void
+        end
+        def divider(text, color: nil, frame_style: nil, to: $stdout)
           fs_item = FrameStack.pop
           raise UnnestedFrameException, 'No frame nesting to unnest' unless fs_item
 
-          color = CLI::UI.resolve_color(color) || fs_item.color
-          frame_style = CLI::UI.resolve_style(frame_style) || fs_item.frame_style
+          divider_color = CLI::UI.resolve_color(color || fs_item.color)
+          frame_style = CLI::UI.resolve_style(frame_style || fs_item.frame_style)
 
           CLI::UI.raw do
-            print(prefix.chop)
-            puts frame_style.divider(text, color: color)
+            to.print(prefix.chop)
+            to.puts(frame_style.divider(text.to_s, color: divider_color))
           end
 
           FrameStack.push(fs_item)
@@ -172,6 +205,8 @@ module CLI
         # * +:color+ - The color of the frame. Defaults to nil
         # * +:elapsed+ - How long did the frame take? Defaults to nil
         # * +frame_style+ - The frame style to use for this frame.  Defaults to nil
+        # * +:to+ - Target stream, like $stdout or $stderr. Can be anything with print and puts methods,
+        #   or under Sorbet, IO or StringIO. Defaults to $stdout.
         #
         # ==== Example
         #
@@ -184,21 +219,26 @@ module CLI
         #
         # MUST be inside an open frame or it raises a +UnnestedFrameException+
         #
-        def close(text, color: nil, elapsed: nil, frame_style: nil)
+        sig do
+          params(
+            text: T.nilable(String),
+            color: T.nilable(Colorable),
+            elapsed: T.nilable(Numeric),
+            frame_style: T.nilable(FrameStylable),
+            to: IOLike,
+          ).void
+        end
+        def close(text, color: nil, elapsed: nil, frame_style: nil, to: $stdout)
           fs_item = FrameStack.pop
           raise UnnestedFrameException, 'No frame nesting to unnest' unless fs_item
 
-          color = CLI::UI.resolve_color(color) || fs_item.color
-          frame_style = CLI::UI.resolve_style(frame_style) || fs_item.frame_style
-
-          kwargs = {}
-          if elapsed
-            kwargs[:right_text] = "(#{elapsed.round(2)}s)"
-          end
+          close_color = CLI::UI.resolve_color(color || fs_item.color)
+          frame_style = CLI::UI.resolve_style(frame_style || fs_item.frame_style)
+          elapsed_string = elapsed ? "(#{elapsed.round(2)}s)" : nil
 
           CLI::UI.raw do
-            print(prefix.chop)
-            puts frame_style.close(text, color: color, **kwargs)
+            to.print(prefix.chop)
+            to.puts(frame_style.close(text.to_s, color: close_color, right_text: elapsed_string))
           end
         end
 
@@ -208,11 +248,12 @@ module CLI
         #
         # * +:color+ - The color of the prefix. Defaults to +Thread.current[:cliui_frame_color_override]+
         #
+        sig { params(color: T.nilable(Colorable)).returns(String) }
         def prefix(color: Thread.current[:cliui_frame_color_override])
           +''.tap do |output|
             items = FrameStack.items
 
-            items[0..-2].each do |item|
+            items[0..-2].to_a.each do |item|
               output << item.color.code << item.frame_style.prefix
             end
 
@@ -227,6 +268,7 @@ module CLI
         end
 
         # The width of a prefix given the number of Frames in the stack
+        sig { returns(Integer) }
         def prefix_width
           w = FrameStack.items.reduce(0) do |width, item|
             width + item.frame_style.prefix_width
@@ -241,7 +283,12 @@ module CLI
         #
         # * +color+ - The color to override to
         #
-        def with_frame_color_override(color)
+        sig do
+          type_parameters(:T)
+            .params(color: Colorable, block: T.proc.returns(T.type_parameter(:T)))
+            .returns(T.type_parameter(:T))
+        end
+        def with_frame_color_override(color, &block)
           prev = Thread.current[:cliui_frame_color_override]
           Thread.current[:cliui_frame_color_override] = color
           yield
@@ -254,13 +301,13 @@ module CLI
         # If timing is:
         #   Numeric: return it
         #   false: return nil
-        #   true or nil: defaults to Time.new
-        #   Time: return the difference with start
-        def elasped(start, timing)
+        #   true: defaults to Time.new
+        sig { params(start: Time, timing: T.any(Numeric, T::Boolean)).returns(T.nilable(Numeric)) }
+        def elapsed(start, timing)
           return timing if timing.is_a?(Numeric)
           return if timing.is_a?(FalseClass)
 
-          timing = Time.new if timing.is_a?(TrueClass) || timing.nil?
+          timing = Time.new
           timing - start
         end
       end

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