cli-ui 1.5.1 → 2.0.0

data/lib/cli/ui.rb

@@ -1,5 +1,13 @@
+# typed: true
+
+unless defined?(T)
+  require('cli/ui/sorbet_runtime_stub')
+end
+
 module CLI
   module UI
+    extend T::Sig
+
     autoload :ANSI,      'cli/ui/ansi'
     autoload :Glyph,     'cli/ui/glyph'
     autoload :Color,     'cli/ui/color'
@@ -18,215 +26,344 @@ module CLI
     # Convenience accessor to +CLI::UI::Spinner::SpinGroup+
     SpinGroup = Spinner::SpinGroup
 
-    # Glyph resolution using +CLI::UI::Glyph.lookup+
-    # Look at the method signature for +Glyph.lookup+ for more details
-    #
-    # ==== Attributes
-    #
-    # * +handle+ - handle of the glyph to resolve
-    #
-    def self.glyph(handle)
-      CLI::UI::Glyph.lookup(handle)
-    end
+    Colorable = T.type_alias { T.any(Symbol, String, CLI::UI::Color) }
+    FrameStylable = T.type_alias { T.any(Symbol, String, CLI::UI::Frame::FrameStyle) }
+    IOLike = T.type_alias { T.any(IO, StringIO) }
+
+    class << self
+      extend T::Sig
 
-    # Color resolution using +CLI::UI::Color.lookup+
-    # Will lookup using +Color.lookup+ unless it's already a CLI::UI::Color (or nil)
-    #
-    # ==== Attributes
-    #
-    # * +input+ - color to resolve
-    #
-    def self.resolve_color(input)
-      case input
-      when CLI::UI::Color, nil
-        input
-      else
-        CLI::UI::Color.lookup(input)
+      # Glyph resolution using +CLI::UI::Glyph.lookup+
+      # Look at the method signature for +Glyph.lookup+ for more details
+      #
+      # ==== Attributes
+      #
+      # * +handle+ - handle of the glyph to resolve
+      #
+      sig { params(handle: String).returns(Glyph) }
+      def glyph(handle)
+        CLI::UI::Glyph.lookup(handle)
       end
-    end
 
-    # Frame style resolution using +CLI::UI::Frame::FrameStyle.lookup+.
-    # Will lookup using +FrameStyle.lookup+ unless it's already a CLI::UI::Frame::FrameStyle(or nil)
-    #
-    # ==== Attributes
-    #
-    # * +input+ - frame style to resolve
-    def self.resolve_style(input)
-      case input
-      when CLI::UI::Frame::FrameStyle, nil
-        input
-      else
-        CLI::UI::Frame::FrameStyle.lookup(input)
+      # Color resolution using +CLI::UI::Color.lookup+
+      # Will lookup using +Color.lookup+ unless it's already a CLI::UI::Color (or nil)
+      #
+      # ==== Attributes
+      #
+      # * +input+ - color to resolve
+      #
+      sig { params(input: Colorable).returns(CLI::UI::Color) }
+      def resolve_color(input)
+        case input
+        when CLI::UI::Color
+          input
+        else
+          CLI::UI::Color.lookup(input)
+        end
       end
-    end
 
-    # Convenience Method for +CLI::UI::Prompt.confirm+
-    #
-    # ==== Attributes
-    #
-    # * +question+ - question to confirm
-    #
-    def self.confirm(question, **kwargs)
-      CLI::UI::Prompt.confirm(question, **kwargs)
-    end
+      # Frame style resolution using +CLI::UI::Frame::FrameStyle.lookup+.
+      # Will lookup using +FrameStyle.lookup+ unless it's already a CLI::UI::Frame::FrameStyle(or nil)
+      #
+      # ==== Attributes
+      #
+      # * +input+ - frame style to resolve
+      sig { params(input: FrameStylable).returns(CLI::UI::Frame::FrameStyle) }
+      def resolve_style(input)
+        case input
+        when CLI::UI::Frame::FrameStyle
+          input
+        else
+          CLI::UI::Frame::FrameStyle.lookup(input.to_s)
+        end
+      end
 
-    # Convenience Method for +CLI::UI::Prompt.ask+
-    #
-    # ==== Attributes
-    #
-    # * +question+ - question to ask
-    # * +kwargs+ - arguments for +Prompt.ask+
-    #
-    def self.ask(question, **kwargs)
-      CLI::UI::Prompt.ask(question, **kwargs)
-    end
+      # Convenience Method for +CLI::UI::Prompt.confirm+
+      #
+      # ==== Attributes
+      #
+      # * +question+ - question to confirm
+      #
+      sig { params(question: String, default: T::Boolean).returns(T::Boolean) }
+      def confirm(question, default: true)
+        CLI::UI::Prompt.confirm(question, default: default)
+      end
 
-    # Convenience Method to resolve text using +CLI::UI::Formatter.format+
-    # Check +CLI::UI::Formatter::SGR_MAP+ for available formatting options
-    #
-    # ==== Attributes
-    #
-    # * +input+ - input to format
-    # * +truncate_to+ - number of characters to truncate the string to (or nil)
-    #
-    def self.resolve_text(input, truncate_to: nil)
-      return input if input.nil?
-      formatted = CLI::UI::Formatter.new(input).format
-      return formatted unless truncate_to
-      CLI::UI::Truncater.call(formatted, truncate_to)
-    end
+      # Convenience Method for +CLI::UI::Prompt.ask+
+      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: Prompt::OptionsHandler).void),
+        ).returns(T.any(String, T::Array[String]))
+      end
+      def ask(
+        question,
+        options: nil,
+        default: nil,
+        is_file: false,
+        allow_empty: true,
+        multiple: false,
+        filter_ui: true,
+        select_ui: true,
+        &options_proc
+      )
+        CLI::UI::Prompt.ask(
+          question,
+          options: options,
+          default: default,
+          is_file: is_file,
+          allow_empty: allow_empty,
+          multiple: multiple,
+          filter_ui: filter_ui,
+          select_ui: select_ui,
+          &options_proc
+        )
+      end
 
-    # Convenience Method to format text using +CLI::UI::Formatter.format+
-    # Check +CLI::UI::Formatter::SGR_MAP+ for available formatting options
-    #
-    # https://user-images.githubusercontent.com/3074765/33799827-6d0721a2-dd01-11e7-9ab5-c3d455264afe.png
-    # https://user-images.githubusercontent.com/3074765/33799847-9ec03fd0-dd01-11e7-93f7-5f5cc540e61e.png
-    #
-    # ==== Attributes
-    #
-    # * +input+ - input to format
-    #
-    # ==== Options
-    #
-    # * +enable_color+ - should color be used? default to true unless output is redirected.
-    #
-    def self.fmt(input, enable_color: enable_color?)
-      CLI::UI::Formatter.new(input).format(enable_color: enable_color)
-    end
+      # Convenience Method to resolve text using +CLI::UI::Formatter.format+
+      # Check +CLI::UI::Formatter::SGR_MAP+ for available formatting options
+      #
+      # ==== Attributes
+      #
+      # * +input+ - input to format
+      # * +truncate_to+ - number of characters to truncate the string to (or nil)
+      #
+      sig { params(input: String, truncate_to: T.nilable(Integer)).returns(String) }
+      def resolve_text(input, truncate_to: nil)
+        formatted = CLI::UI::Formatter.new(input).format
+        return formatted unless truncate_to
 
-    def self.wrap(input)
-      CLI::UI::Wrap.new(input).wrap
-    end
+        CLI::UI::Truncater.call(formatted, truncate_to)
+      end
 
-    # Convenience Method for +CLI::UI::Printer.puts+
-    #
-    # ==== Attributes
-    #
-    # * +msg+ - Message to print
-    # * +kwargs+ - keyword arguments for +Printer.puts+
-    #
-    def self.puts(msg, **kwargs)
-      CLI::UI::Printer.puts(msg, **kwargs)
-    end
+      # Convenience Method to format text using +CLI::UI::Formatter.format+
+      # Check +CLI::UI::Formatter::SGR_MAP+ for available formatting options
+      #
+      # https://user-images.githubusercontent.com/3074765/33799827-6d0721a2-dd01-11e7-9ab5-c3d455264afe.png
+      # https://user-images.githubusercontent.com/3074765/33799847-9ec03fd0-dd01-11e7-93f7-5f5cc540e61e.png
+      #
+      # ==== Attributes
+      #
+      # * +input+ - input to format
+      #
+      # ==== Options
+      #
+      # * +enable_color+ - should color be used? default to true unless output is redirected.
+      #
+      sig { params(input: String, enable_color: T::Boolean).returns(String) }
+      def fmt(input, enable_color: enable_color?)
+        CLI::UI::Formatter.new(input).format(enable_color: enable_color)
+      end
 
-    # Convenience Method for +CLI::UI::Frame.open+
-    #
-    # ==== Attributes
-    #
-    # * +args+ - arguments for +Frame.open+
-    # * +block+ - block for +Frame.open+
-    #
-    def self.frame(*args, **kwargs, &block)
-      CLI::UI::Frame.open(*args, **kwargs, &block)
-    end
+      sig { params(input: String).returns(String) }
+      def wrap(input)
+        CLI::UI::Wrap.new(input).wrap
+      end
 
-    # Convenience Method for +CLI::UI::Spinner.spin+
-    #
-    # ==== Attributes
-    #
-    # * +args+ - arguments for +Spinner.open+
-    # * +block+ - block for +Spinner.open+
-    #
-    def self.spinner(*args, **kwargs, &block)
-      CLI::UI::Spinner.spin(*args, **kwargs, &block)
-    end
+      # Convenience Method for +CLI::UI::Printer.puts+
+      #
+      # ==== Attributes
+      #
+      # * +msg+ - Message to print
+      # * +kwargs+ - keyword arguments for +Printer.puts+
+      #
+      sig do
+        params(
+          msg: String,
+          frame_color: T.nilable(Colorable),
+          to: IOLike,
+          encoding: Encoding,
+          format: T::Boolean,
+          graceful: T::Boolean,
+          wrap: T::Boolean,
+        ).void
+      end
+      def puts(
+        msg,
+        frame_color: nil,
+        to: $stdout,
+        encoding: Encoding::UTF_8,
+        format: true,
+        graceful: true,
+        wrap: true
+      )
+        CLI::UI::Printer.puts(
+          msg,
+          frame_color: frame_color,
+          to: to,
+          encoding: encoding,
+          format: format,
+          graceful: graceful,
+          wrap: wrap,
+        )
+      end
 
-    # Convenience Method to override frame color using +CLI::UI::Frame.with_frame_color+
-    #
-    # ==== Attributes
-    #
-    # * +color+ - color to override to
-    # * +block+ - block for +Frame.with_frame_color_override+
-    #
-    def self.with_frame_color(color, &block)
-      CLI::UI::Frame.with_frame_color_override(color, &block)
-    end
+      # Convenience Method for +CLI::UI::Frame.open+
+      #
+      # ==== Attributes
+      #
+      # * +args+ - arguments for +Frame.open+
+      # * +block+ - block for +Frame.open+
+      #
+      sig do
+        type_parameters(:T).params(
+          text: String,
+          color: T.nilable(Colorable),
+          failure_text: T.nilable(String),
+          success_text: T.nilable(String),
+          timing: T.any(T::Boolean, Numeric),
+          frame_style: FrameStylable,
+          block: T.nilable(T.proc.returns(T.type_parameter(:T))),
+        ).returns(T.nilable(T.type_parameter(:T)))
+      end
+      def frame(
+        text,
+        color: Frame::DEFAULT_FRAME_COLOR,
+        failure_text: nil,
+        success_text: nil,
+        timing: block_given?,
+        frame_style: Frame.frame_style,
+        &block
+      )
+        CLI::UI::Frame.open(
+          text,
+          color: color,
+          failure_text: failure_text,
+          success_text: success_text,
+          timing: timing,
+          frame_style: frame_style,
+          &block
+        )
+      end
 
-    # Duplicate output to a file path
-    #
-    # ==== Attributes
-    #
-    # * +path+ - path to duplicate output to
-    #
-    def self.log_output_to(path)
-      if CLI::UI::StdoutRouter.duplicate_output_to
-        raise 'multiple logs not allowed'
-      end
-      CLI::UI::StdoutRouter.duplicate_output_to = File.open(path, 'w')
-      yield
-    ensure
-      if (file_descriptor = CLI::UI::StdoutRouter.duplicate_output_to)
-        file_descriptor.close
-        CLI::UI::StdoutRouter.duplicate_output_to = nil
+      # Convenience Method for +CLI::UI::Spinner.spin+
+      #
+      # ==== Attributes
+      #
+      # * +args+ - arguments for +Spinner.open+
+      # * +block+ - block for +Spinner.open+
+      #
+      sig do
+        params(title: String, auto_debrief: T::Boolean, block: T.proc.params(task: Spinner::SpinGroup::Task).void)
+          .returns(T::Boolean)
+      end
+      def spinner(title, auto_debrief: true, &block)
+        CLI::UI::Spinner.spin(title, auto_debrief: auto_debrief, &block)
       end
-    end
 
-    # Disable all framing within a block
-    #
-    # ==== Attributes
-    #
-    # * +block+ - block in which to disable frames
-    #
-    def self.raw
-      prev = Thread.current[:no_cliui_frame_inset]
-      Thread.current[:no_cliui_frame_inset] = true
-      yield
-    ensure
-      Thread.current[:no_cliui_frame_inset] = prev
-    end
+      # Convenience Method to override frame color using +CLI::UI::Frame.with_frame_color+
+      #
+      # ==== Attributes
+      #
+      # * +color+ - color to override to
+      # * +block+ - block for +Frame.with_frame_color_override+
+      #
+      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(color, &block)
+        CLI::UI::Frame.with_frame_color_override(color, &block)
+      end
 
-    # Check whether colour is enabled in Formatter output. By default, colour
-    # is enabled when STDOUT is a TTY; that is, when output has not been
-    # redirected to another program or to a file.
-    #
-    def self.enable_color?
-      @enable_color
-    end
+      # Duplicate output to a file path
+      #
+      # ==== Attributes
+      #
+      # * +path+ - path to duplicate output to
+      #
+      sig do
+        type_parameters(:T)
+          .params(path: String, block: T.proc.returns(T.type_parameter(:T)))
+          .returns(T.type_parameter(:T))
+      end
+      def log_output_to(path, &block)
+        if CLI::UI::StdoutRouter.duplicate_output_to
+          raise 'multiple logs not allowed'
+        end
 
-    # Turn colour output in Formatter on or off.
-    #
-    # ==== Attributes
-    #
-    # * +bool+ - true or false; enable or disable colour.
-    #
-    def self.enable_color=(bool)
-      @enable_color = !!bool
-    end
+        CLI::UI::StdoutRouter.duplicate_output_to = File.open(path, 'w')
+        yield
+      ensure
+        if (file_descriptor = CLI::UI::StdoutRouter.duplicate_output_to)
+          begin
+            file_descriptor.close
+          rescue IOError
+            nil
+          end
+          CLI::UI::StdoutRouter.duplicate_output_to = nil
+        end
+      end
 
-    self.enable_color = $stdout.tty?
+      # Disable all framing within a block
+      #
+      # ==== Attributes
+      #
+      # * +block+ - block in which to disable frames
+      #
+      sig { type_parameters(:T).params(block: T.proc.returns(T.type_parameter(:T))).returns(T.type_parameter(:T)) }
+      def raw(&block)
+        prev = Thread.current[:no_cliui_frame_inset]
+        Thread.current[:no_cliui_frame_inset] = true
+        yield
+      ensure
+        Thread.current[:no_cliui_frame_inset] = prev
+      end
+
+      # Check whether colour is enabled in Formatter output. By default, colour
+      # is enabled when STDOUT is a TTY; that is, when output has not been
+      # redirected to another program or to a file.
+      #
+      sig { returns(T::Boolean) }
+      def enable_color?
+        @enable_color
+      end
+
+      # Turn colour output in Formatter on or off.
+      #
+      # ==== Attributes
+      #
+      # * +bool+ - true or false; enable or disable colour.
+      #
+      sig { params(bool: T::Boolean).void }
+      def enable_color=(bool)
+        @enable_color = !!bool
+      end
 
-    # Set the default frame style.
-    # Convenience method for setting the default frame style with +CLI::UI::Frame.frame_style=+
-    #
-    # Raises ArgumentError if +frame_style+ is not valid
-    #
-    # ==== Attributes
-    #
-    # * +symbol+ - the default frame style to use for frames
-    #
-    def self.frame_style=(frame_style)
-      Frame.frame_style = frame_style.to_sym
+      # Set the default frame style.
+      # Convenience method for setting the default frame style with +CLI::UI::Frame.frame_style=+
+      #
+      # Raises ArgumentError if +frame_style+ is not valid
+      #
+      # ==== Attributes
+      #
+      # * +symbol+ - the default frame style to use for frames
+      #
+      sig { params(frame_style: FrameStylable).void }
+      def frame_style=(frame_style)
+        Frame.frame_style = frame_style
+      end
+
+      # Create a terminal link
+      sig { params(url: String, text: String, format: T::Boolean, blue_underline: T::Boolean).returns(String) }
+      def link(url, text, format: true, blue_underline: format)
+        raise 'cannot use blue_underline without format' if blue_underline && !format
+
+        text = "{{blue:{{underline:#{text}}}}}" if blue_underline
+        text = CLI::UI.fmt(text) if format
+        "\x1b]8;;#{url}\x1b\\#{text}\x1b]8;;\x1b\\"
+      end
     end
+
+    self.enable_color = $stdout.tty?
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cli-ui
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Burke Libbey
@@ -10,36 +10,36 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-04-15 00:00:00.000000000 Z
+date: 2022-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '13.0'
 description: Terminal UI framework
 email:
 - burke.libbey@shopify.com
@@ -67,6 +67,7 @@ files:
 - lib/cli/ui/prompt.rb
 - lib/cli/ui/prompt/interactive_options.rb
 - lib/cli/ui/prompt/options_handler.rb
+- lib/cli/ui/sorbet_runtime_stub.rb
 - lib/cli/ui/spinner.rb
 - lib/cli/ui/spinner/async.rb
 - lib/cli/ui/spinner/spin_group.rb
@@ -97,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Terminal UI framework