cli-ui 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8dec5198cdbbb3a6060fc448a9a03b5bc6eca461b94a62ead0f128664bb0ee2
-  data.tar.gz: bed02e7e27771141c08859c11d7e01f690438bb46d4022f5225d8cb42e39efe4
+  metadata.gz: 8f063229317bef21e8a24f2190dd907c1a1080eefad787871dc8f07b95a3c31b
+  data.tar.gz: 6379c4023ca55081b2d5260ce79ed9615c304c7ab099b9318883a04ef4d11e1e
 SHA512:
-  metadata.gz: 6944f7c1b8492e69bd078b2ca0d9901d26694e4542976cb07729efff2cb59438cbc2ec61692b75ccf178ffcec896a297264be5734520695f9bc11779f2698ead
-  data.tar.gz: c9795b1749d3db7cb57bccca815495ed9b2e8ee02092fe95b46bf451f2993e65c33f8b48e9f6520b2984b7278db64cb9e92bb1fe58a761691a9b313dab6ef464
+  metadata.gz: 07f5f6b944ceeadd42359bc5c3edde469fb034641ad0ea274306097ec2471af1d8b6fb1fbc85f5d30c43ddb1472b6af1ee1688a921deea6404cbf642239d4ffe
+  data.tar.gz: 25c645e1b2c6078e3ace849ef02ff85b727e88df4dedfa4baf200a56760369cf440ca435fe8ca18e3e24f301dfa80e772e48c6ccdf12a5dd9b6e4c2d5b4ae353

data/README.md

@@ -52,6 +52,11 @@ For large numbers of options, using `e`, `:`, or `G` will toggle "line select" m
 CLI::UI.ask('What language/framework do you use?', options: %w(rails go ruby python))
 ```
 
+To set the color of instruction text:
+```ruby
+CLI::UI::Prompt.instructions_color = CLI::UI::Color::GRAY
+```
+
 Can also assign callbacks to each option
 
 ```ruby
@@ -175,6 +180,12 @@ end
 
 ---
 
+## Sorbet
+
+We make use of [Sorbet](https://sorbet.org/) in cli-ui. We provide stubs for Sorbet so that you can use this gem even
+if you aren't using Sorbet. We activate these stubs if `T` is undefined when the gem is loaded. For this reason, if you
+would like to use this gem and your project _does_ use Sorbet, ensure you load Sorbet _before_ loading cli-ui.
+
 ## Example Usage
 
 The following code makes use of nested-framing, multi-threaded spinners, formatted text, and more.

data/lib/cli/ui/ansi.rb

@@ -133,6 +133,21 @@ module CLI
           cmd
         end
 
+        sig { returns(String) }
+        def enter_alternate_screen
+          control('?1049', 'h')
+        end
+
+        sig { returns(String) }
+        def exit_alternate_screen
+          control('?1049', 'l')
+        end
+
+        sig { returns(Regexp) }
+        def match_alternate_screen
+          /#{Regexp.escape(control('?1049', ''))}[hl]/
+        end
+
         # Show the cursor
         #
         sig { returns(String) }

data/lib/cli/ui/color.rb

@@ -88,7 +88,7 @@ module CLI
         def lookup(name)
           MAP.fetch(name.to_sym)
         rescue KeyError
-          raise InvalidColorName, name
+          raise InvalidColorName, name.to_sym
         end
 
         # All available colors by name

data/lib/cli/ui/formatter.rb

@@ -116,7 +116,7 @@ module CLI
         return content unless enable_color
         return content if stack == prev_fmt
 
-        unless stack.empty? && (@nodes.size.zero? || T.must(@nodes.last)[1].empty?)
+        unless stack.empty? && (@nodes.empty? || T.must(@nodes.last)[1].empty?)
           content << apply_format('', stack, sgr_map)
         end
         content
@@ -167,7 +167,8 @@ module CLI
             index = sc.pos - 2 # rewind past '}}'
             raise(FormatError.new(
               "invalid widget handle at index #{index}: '#{widget_handle}'",
-              @text, index
+              @text,
+              index,
             ))
           end
         elsif (match = sc.scan(SCAN_FUNCNAME))

data/lib/cli/ui/frame/frame_stack.rb

@@ -4,9 +4,6 @@ module CLI
   module UI
     module Frame
       module FrameStack
-        COLOR_ENVVAR = 'CLI_FRAME_STACK'
-        STYLE_ENVVAR = 'CLI_STYLE_STACK'
-
         class StackItem
           extend T::Sig
 
@@ -32,12 +29,7 @@ module CLI
           # Fetch all items off the frame stack
           sig { returns(T::Array[StackItem]) }
           def items
-            colors = ENV.fetch(COLOR_ENVVAR, '').split(':').map(&:to_sym)
-            styles = ENV.fetch(STYLE_ENVVAR, '').split(':').map(&:to_sym)
-
-            colors.each_with_index.map do |color, i|
-              StackItem.new(color, styles[i] || Frame.frame_style)
-            end
+            Thread.current[:cliui_frame_stack] ||= []
           end
 
           # Push a new item onto the frame stack.
@@ -71,44 +63,13 @@ module CLI
               raise ArgumentError, 'Must give one of item or color: and style:'
             end
 
-            item ||= StackItem.new(T.must(color), T.must(style))
-
-            curr = items
-            curr << item
-
-            serialize(curr)
+            items.push(item || StackItem.new(T.must(color), T.must(style)))
           end
 
           # Removes and returns the last stack item off the stack
           sig { returns(T.nilable(StackItem)) }
           def pop
-            curr = items
-            ret = curr.pop
-
-            serialize(curr)
-
-            ret.nil? ? nil : ret
-          end
-
-          private
-
-          # Serializes the item stack into two ENV variables.
-          #
-          # This is done to preserve backward compatibility with earlier versions of cli/ui.
-          # This ensures that any code that relied upon previous stack behavior should continue
-          # to work.
-          sig { params(items: T::Array[StackItem]).void }
-          def serialize(items)
-            colors = []
-            styles = []
-
-            items.each do |item|
-              colors << item.color.name
-              styles << item.frame_style.style_name
-            end
-
-            ENV[COLOR_ENVVAR] = colors.join(':')
-            ENV[STYLE_ENVVAR] = styles.join(':')
+            items.pop
           end
         end
       end

data/lib/cli/ui/frame/frame_style/box.rb

@@ -112,7 +112,7 @@ module CLI
               preamble_start = Frame.prefix_width
               # If prefix_width is non-zero, we need to subtract the width of
               # the final space, since we're going to write over it.
-              preamble_start -= 1 unless preamble_start.zero?
+              preamble_start -= 1 if preamble_start.nonzero?
               preamble_end = preamble_start + preamble_width
 
               suffix_width = CLI::UI::ANSI.printing_width(suffix)

data/lib/cli/ui/frame/frame_style/bracket.rb

@@ -126,7 +126,7 @@ module CLI
 
               # If prefix_width is non-zero, we need to subtract the width of
               # the final space, since we're going to write over it.
-              preamble_start -= 1 unless preamble_start.zero?
+              preamble_start -= 1 if preamble_start.nonzero?
 
               # Jumping around the line can cause some unwanted flashes
               o << CLI::UI::ANSI.hide_cursor

data/lib/cli/ui/frame.rb

@@ -54,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
         #
@@ -82,6 +84,7 @@ module CLI
             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
@@ -92,6 +95,7 @@ module CLI
           success_text: nil,
           timing: block_given?,
           frame_style: self.frame_style,
+          to: $stdout,
           &block
         )
           frame_style = CLI::UI.resolve_style(frame_style)
@@ -109,8 +113,8 @@ module CLI
 
           t_start = Time.now
           CLI::UI.raw do
-            print(prefix.chop)
-            puts frame_style.start(text, color: color)
+            to.print(prefix.chop)
+            to.puts(frame_style.start(text, color: color))
           end
           FrameStack.push(color: color, style: frame_style)
 
@@ -123,7 +127,7 @@ module CLI
           rescue
             closed = true
             t_diff = elapsed(t_start, timing)
-            close(failure_text, color: :red, elapsed: t_diff)
+            close(failure_text, color: :red, elapsed: t_diff, to: to)
             raise
           else
             success
@@ -131,9 +135,9 @@ module CLI
             unless closed
               t_diff = elapsed(t_start, timing)
               if T.unsafe(success) != false
-                close(success_text, color: color, elapsed: t_diff)
+                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
@@ -150,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
         #
@@ -164,8 +170,15 @@ module CLI
         #
         # MUST be inside an open frame or it raises a +UnnestedFrameException+
         #
-        sig { params(text: T.nilable(String), color: T.nilable(Colorable), frame_style: T.nilable(FrameStylable)).void }
-        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
 
@@ -173,8 +186,8 @@ module CLI
           frame_style = CLI::UI.resolve_style(frame_style || fs_item.frame_style)
 
           CLI::UI.raw do
-            print(prefix.chop)
-            puts frame_style.divider(text.to_s, color: divider_color)
+            to.print(prefix.chop)
+            to.puts(frame_style.divider(text.to_s, color: divider_color))
           end
 
           FrameStack.push(fs_item)
@@ -192,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
         #
@@ -210,9 +225,10 @@ module CLI
             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)
+        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
 
@@ -221,8 +237,8 @@ module CLI
           elapsed_string = elapsed ? "(#{elapsed.round(2)}s)" : nil
 
           CLI::UI.raw do
-            print(prefix.chop)
-            puts frame_style.close(text.to_s, color: close_color, right_text: elapsed_string)
+            to.print(prefix.chop)
+            to.puts(frame_style.close(text.to_s, color: close_color, right_text: elapsed_string))
           end
         end
 

data/lib/cli/ui/progress.rb

@@ -45,7 +45,7 @@ module CLI
           print(CLI::UI::ANSI.hide_cursor)
           yield(bar)
         ensure
-          puts bar.to_s
+          puts(bar)
           CLI::UI.raw do
             print(ANSI.show_cursor)
           end
@@ -83,7 +83,7 @@ module CLI
         @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(self)
         print(CLI::UI::ANSI.previous_line + "\n")
       end
 

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

@@ -111,21 +111,29 @@ module CLI
           # so to get the # of lines, you need to join then split
 
           # since lines may be longer than the terminal is wide, we need to
-          # determine how many extra lines would be taken up by them
-          max_width = (@terminal_width_at_calculation_time -
-                       @options.count.to_s.size - # Width of the displayed number
-                       5 -                        # Extra characters added during rendering
-                       (@multiple ? 1 : 0)        # Space for the checkbox, if rendered
-                      ).to_f
+          # determine how many extra lines would be taken up by them.
+          #
+          # To accomplish this we split the string by new lines and add the
+          # extra characters to the first line.
+          # Then we calculate how many lines would be needed to render the string
+          # based on the terminal width
+          # 3 = space before the number, the . after the number, the space after the .
+          # multiple check is for the space for the checkbox, if rendered
+          # options.count.to_s.size gets us the max size of the number we will display
+          extra_chars = @marker.length + 3 + @options.count.to_s.size + (@multiple ? 1 : 0)
 
           @option_lengths = @options.map do |text|
-            width = 1 if text.empty?
-            width ||= text
-              .split("\n")
-              .reject(&:empty?)
-              .sum { |l| (CLI::UI.fmt(l, enable_color: false).length / max_width).ceil }
+            next 1 if text.empty?
 
-            width
+            # Find the length of all the lines in this string
+            non_empty_line_lengths = text.split("\n").reject(&:empty?).map do |line|
+              CLI::UI.fmt(line, enable_color: false).length
+            end
+            # The first line has the marker and number, so we add that so we can take it into account
+            non_empty_line_lengths[0] += extra_chars
+            # Finally, we need to calculate how many lines each one will take. We can do that by dividing each one
+            # by the width of the terminal, rounding up to the nearest natural number
+            non_empty_line_lengths.sum { |length| (length.to_f / @terminal_width_at_calculation_time).ceil }
           end
         end
 
@@ -285,7 +293,7 @@ module CLI
         # rubocop:disable Style/WhenThen,Layout/SpaceBeforeSemicolon,Style/Semicolon
         sig { void }
         def wait_for_user_input
-          char = read_char
+          char = Prompt.read_char
           @last_char = char
 
           case char
@@ -375,17 +383,6 @@ module CLI
           @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 # returns nil at end of input
-          end
-        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
@@ -497,8 +494,10 @@ module CLI
             message = "  #{num}#{num ? "." : " "}#{padding}"
 
             format = '%s'
-            # If multiple, bold only selected. If not multiple, bold everything
-            format = "{{bold:#{format}}}" if !@multiple || is_chosen
+            # If multiple, bold selected. If not multiple, do not bold any options.
+            # Bolding options can cause confusion as some users may perceive bold white (default color) as selected
+            # rather than the actual selected color.
+            format = "{{bold:#{format}}}" if @multiple && is_chosen
             format = "{{cyan:#{format}}}" if @multiple && is_chosen && num != @active
             format = " #{format}"
 
@@ -508,7 +507,7 @@ module CLI
             if num == @active
 
               color = filtering? || selecting? ? 'green' : 'blue'
-              message = message.split("\n").map { |l| "{{#{color}:> #{l.strip}}}" }.join("\n")
+              message = message.split("\n").map { |l| "{{#{color}:#{@marker} #{l.strip}}}" }.join("\n")
             end
 
             puts CLI::UI.fmt(message)

data/lib/cli/ui/prompt.rb

@@ -29,6 +29,22 @@ module CLI
       class << self
         extend T::Sig
 
+        sig { returns(Color) }
+        def instructions_color
+          @instructions_color ||= Color::YELLOW
+        end
+
+        # Set the instructions color.
+        #
+        # ==== Attributes
+        #
+        # * +color+ - the color to use for prompt instructions
+        #
+        sig { params(color: Colorable).void }
+        def instructions_color=(color)
+          @instructions_color = CLI::UI.resolve_color(color)
+        end
+
         # 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+
@@ -167,19 +183,21 @@ module CLI
         def ask_password(question)
           require 'io/console'
 
-          STDOUT.print(CLI::UI.fmt('{{?}} ' + question)) # Do not use puts_question to avoid the new line.
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen 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.to_s.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
+            password
+          end
         end
 
         # Asks the user a yes/no question.
@@ -197,6 +215,36 @@ module CLI
           ask_interactive(question, default ? ['yes', 'no'] : ['no', 'yes'], filter_ui: false) == 'yes'
         end
 
+        # Present the user with a message and wait for any key to be pressed, returning the pressed key.
+        #
+        # ==== Example Usage:
+        #
+        #   CLI::UI::Prompt.any_key # Press any key to continue...
+        #
+        #   CLI::UI::Prompt.any_key('Press RETURN to continue...') # Then check if that's what they pressed
+        sig { params(prompt: String).returns(T.nilable(String)) }
+        def any_key(prompt = 'Press any key to continue...')
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            puts_question(prompt)
+            read_char
+          end
+        end
+
+        # Wait for any key to be pressed, returning the pressed key.
+        sig { returns(T.nilable(String)) }
+        def read_char
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            if $stdin.tty? && !ENV['TEST']
+              require 'io/console'
+              $stdin.getch # raw mode for tty
+            else
+              $stdin.getc # returns nil at end of input
+            end
+          end
+        rescue Errno::EIO, Errno::EPIPE, IOError
+          "\e"
+        end
+
         private
 
         sig do
@@ -208,23 +256,25 @@ module CLI
             raise(ArgumentError, 'conflicting arguments: default enabled but allow_empty is false')
           end
 
-          if default
-            puts_question("#{question} (empty = #{default})")
-          else
-            puts_question(question)
-          end
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            if default
+              puts_question("#{question} (empty = #{default})")
+            else
+              puts_question(question)
+            end
 
-          # Ask a free form question
-          loop do
-            line = readline(is_file: is_file)
+            # Ask a free form question
+            loop do
+              line = readline(is_file: is_file)
 
-            if line.empty? && default
-              write_default_over_empty_input(default)
-              return default
-            end
+              if line.empty? && default
+                write_default_over_empty_input(default)
+                return default
+              end
 
-            if !line.empty? || allow_empty
-              return line
+              if !line.empty? || allow_empty
+                return line
+              end
             end
           end
         end
@@ -259,33 +309,38 @@ module CLI
           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, default: default)
-
-          # Clear the line
-          print(ANSI.previous_line + ANSI.clear_to_end_of_line)
-          # Force StdoutRouter to prefix
-          print(ANSI.previous_line + "\n")
-
-          # reset the question to include the answer
-          resp_text = case resp
-          when Array
-            case resp.size
-            when 0
-              '<nothing>'
-            when 1..2
-              resp.join(' and ')
+
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            puts_question("#{question} " + instructions_color.code + "(#{instructions})" + Color::RESET.code)
+            resp = interactive_prompt(options, multiple: multiple, default: default)
+
+            # Clear the line
+            print(ANSI.previous_line + ANSI.clear_to_end_of_line)
+            # Force StdoutRouter to prefix
+            print(ANSI.previous_line + "\n")
+
+            # reset the question to include the answer
+            resp_text = case resp
+            when Array
+              case resp.size
+              when 0
+                '<nothing>'
+              when 1..2
+                resp.join(' and ')
+              else
+                "#{resp.size} items"
+              end
             else
-              "#{resp.size} items"
+              resp
             end
-          else
-            resp
-          end
-          puts_question("#{question} (You chose: {{italic:#{resp_text}}})")
-
-          return T.must(handler).call(resp) if block_given?
+            puts_question("#{question} (You chose: {{italic:#{resp_text}}})")
 
-          resp
+            if block_given?
+              T.must(handler).call(resp)
+            else
+              resp
+            end
+          end
         end
 
         # Useful for stubbing in tests
@@ -294,13 +349,15 @@ module CLI
             .returns(T.any(T::Array[String], String))
         end
         def interactive_prompt(options, multiple: false, default: nil)
-          InteractiveOptions.call(options, multiple: multiple, default: default)
+          CLI::UI::StdoutRouter::Capture.in_alternate_screen do
+            InteractiveOptions.call(options, multiple: multiple, default: default)
+          end
         end
 
         sig { params(default: String).void }
         def write_default_over_empty_input(default)
           CLI::UI.raw do
-            STDERR.puts(
+            $stderr.puts(
               CLI::UI::ANSI.cursor_up(1) +
               "\r" +
               CLI::UI::ANSI.cursor_forward(4) + # TODO: width
@@ -312,7 +369,7 @@ module CLI
 
         sig { params(str: String).void }
         def puts_question(str)
-          STDOUT.puts(CLI::UI.fmt('{{?}} ' + str))
+          $stdout.puts(CLI::UI.fmt('{{?}} ' + str))
         end
 
         sig { params(is_file: T::Boolean).returns(String) }
@@ -340,7 +397,7 @@ module CLI
             print(CLI::UI::Color::RESET.code)
             line.to_s.chomp
           rescue Interrupt
-            CLI::UI.raw { STDERR.puts('^C' + CLI::UI::Color::RESET.code) }
+            CLI::UI.raw { $stderr.puts('^C' + CLI::UI::Color::RESET.code) }
             raise
           end
         end

data/lib/cli/ui/sorbet_runtime_stub.rb

@@ -154,4 +154,16 @@ module T
       def [](type); end
     end
   end
+
+  class << self
+    def const_added(name)
+      super
+      raise 'When using both cli-ui and sorbet, you must require sorbet before cli-ui'
+    end
+
+    def method_added(name)
+      super
+      raise 'When using both cli-ui and sorbet, you must require sorbet before cli-ui'
+    end
+  end
 end

data/lib/cli/ui/spinner/spin_group.rb

@@ -4,6 +4,41 @@ module CLI
   module UI
     module Spinner
       class SpinGroup
+        DEFAULT_FINAL_GLYPH = ->(success) { success ? CLI::UI::Glyph::CHECK.to_s : CLI::UI::Glyph::X.to_s }
+
+        class << self
+          extend T::Sig
+
+          sig { returns(Mutex) }
+          attr_reader :pause_mutex
+
+          sig { returns(T::Boolean) }
+          def paused?
+            @paused
+          end
+
+          sig do
+            type_parameters(:T)
+              .params(block: T.proc.returns(T.type_parameter(:T)))
+              .returns(T.type_parameter(:T))
+          end
+          def pause_spinners(&block)
+            previous_paused = T.let(nil, T.nilable(T::Boolean))
+            @pause_mutex.synchronize do
+              previous_paused = @paused
+              @paused = true
+            end
+            block.call
+          ensure
+            @pause_mutex.synchronize do
+              @paused = previous_paused
+            end
+          end
+        end
+
+        @pause_mutex = Mutex.new
+        @paused = false
+
         extend T::Sig
 
         # Initializes a new spin group
@@ -11,7 +46,7 @@ module CLI
         #
         # ==== Options
         #
-        # * +:auto_debrief+ - Automatically debrief exceptions? Default to true
+        # * +:auto_debrief+ - Automatically debrief exceptions or through success_debrief? Default to true
         #
         # ==== Example Usage
         #
@@ -57,12 +92,23 @@ module CLI
           # * +title+ - Title of the task
           # * +block+ - Block for the task, will be provided with an instance of the spinner
           #
-          sig { params(title: String, block: T.proc.params(task: Task).returns(T.untyped)).void }
-          def initialize(title, &block)
+          sig do
+            params(
+              title: String,
+              final_glyph: T.proc.params(success: T::Boolean).returns(String),
+              merged_output: T::Boolean,
+              duplicate_output_to: IO,
+              block: T.proc.params(task: Task).returns(T.untyped),
+            ).void
+          end
+          def initialize(title, final_glyph:, merged_output:, duplicate_output_to:, &block)
             @title = title
+            @final_glyph = final_glyph
             @always_full_render = title =~ Formatter::SCAN_WIDGET
             @thread = Thread.new do
-              cap = CLI::UI::StdoutRouter::Capture.new(with_frame_inset: false) { block.call(self) }
+              cap = CLI::UI::StdoutRouter::Capture.new(
+                merged_output: merged_output, duplicate_output_to: duplicate_output_to,
+              ) { block.call(self) }
               begin
                 cap.run
               ensure
@@ -173,7 +219,7 @@ module CLI
           sig { params(index: Integer).returns(String) }
           def glyph(index)
             if @done
-              @success ? CLI::UI::Glyph::CHECK.to_s : CLI::UI::Glyph::X.to_s
+              @final_glyph.call(@success)
             else
               GLYPHS[index]
             end
@@ -202,10 +248,30 @@ module CLI
         #   spin_group.add('Title') { |spinner| sleep 1.0 }
         #   spin_group.wait
         #
-        sig { params(title: String, block: T.proc.params(task: Task).void).void }
-        def add(title, &block)
+        sig do
+          params(
+            title: String,
+            final_glyph: T.proc.params(success: T::Boolean).returns(String),
+            merged_output: T::Boolean,
+            duplicate_output_to: IO,
+            block: T.proc.params(task: Task).void,
+          ).void
+        end
+        def add(
+          title,
+          final_glyph: DEFAULT_FINAL_GLYPH,
+          merged_output: false,
+          duplicate_output_to: File.new(File::NULL, 'w'),
+          &block
+        )
           @m.synchronize do
-            @tasks << Task.new(title, &block)
+            @tasks << Task.new(
+              title,
+              final_glyph: final_glyph,
+              merged_output: merged_output,
+              duplicate_output_to: duplicate_output_to,
+              &block
+            )
           end
         end
 
@@ -221,32 +287,36 @@ module CLI
           idx = 0
 
           loop do
-            all_done = T.let(true, T::Boolean)
+            done_count = 0
 
             width = CLI::UI::Terminal.width
 
-            @m.synchronize do
-              CLI::UI.raw do
-                @tasks.each.with_index do |task, int_index|
-                  nat_index = int_index + 1
-                  task_done = task.check
-                  all_done = false unless task_done
-
-                  if nat_index > @consumed_lines
-                    print(task.render(idx, true, width: width) + "\n")
-                    @consumed_lines += 1
-                  else
-                    offset = @consumed_lines - int_index
-                    move_to = CLI::UI::ANSI.cursor_up(offset) + "\r"
-                    move_from = "\r" + CLI::UI::ANSI.cursor_down(offset)
-
-                    print(move_to + task.render(idx, idx.zero?, width: width) + move_from)
+            self.class.pause_mutex.synchronize do
+              next if self.class.paused?
+
+              @m.synchronize do
+                CLI::UI.raw do
+                  @tasks.each.with_index do |task, int_index|
+                    nat_index = int_index + 1
+                    task_done = task.check
+                    done_count += 1 if task_done
+
+                    if nat_index > @consumed_lines
+                      print(task.render(idx, true, width: width) + "\n")
+                      @consumed_lines += 1
+                    else
+                      offset = @consumed_lines - int_index
+                      move_to = CLI::UI::ANSI.cursor_up(offset) + "\r"
+                      move_from = "\r" + CLI::UI::ANSI.cursor_down(offset)
+
+                      print(move_to + task.render(idx, idx.zero?, width: width) + move_from)
+                    end
                   end
                 end
               end
             end
 
-            break if all_done
+            break if done_count == @tasks.size
 
             idx = (idx + 1) % GLYPHS.size
             Spinner.index = idx
@@ -273,6 +343,16 @@ module CLI
           @failure_debrief = block
         end
 
+        # Provide a debriefing for successful tasks
+        sig do
+          params(
+            block: T.proc.params(title: String, out: String, err: String).void,
+          ).void
+        end
+        def success_debrief(&block)
+          @success_debrief = block
+        end
+
         sig { returns(T::Boolean) }
         def all_succeeded?
           @m.synchronize do
@@ -286,13 +366,15 @@ module CLI
         def debrief
           @m.synchronize do
             @tasks.each do |task|
-              next if task.success
-
               title = task.title
-              e = task.exception
               out = task.stdout
               err = task.stderr
 
+              if task.success
+                next @success_debrief&.call(title, out, err)
+              end
+
+              e = task.exception
               next @failure_debrief.call(title, e, out, err) if @failure_debrief
 
               CLI::UI::Frame.open('Task Failed: ' + title, color: :red, timing: Time.new - @start) do

data/lib/cli/ui/spinner.rb

@@ -61,7 +61,7 @@ module CLI
         #
         # ==== Options
         #
-        # * +:auto_debrief+ - Automatically debrief exceptions? Default to true
+        # * +:auto_debrief+ - Automatically debrief exceptions or through success_debrief? Default to true
         #
         # ==== Block
         #

data/lib/cli/ui/stdout_router.rb

@@ -2,6 +2,7 @@
 
 require 'cli/ui'
 require 'stringio'
+require_relative '../../../vendor/reentrant_mutex'
 
 module CLI
   module UI
@@ -35,7 +36,11 @@ module CLI
 
           T.unsafe(@stream).write_without_cli_ui(*prepend_id(@stream, args))
           if (dup = StdoutRouter.duplicate_output_to)
-            T.unsafe(dup).write(*prepend_id(dup, args))
+            begin
+              T.unsafe(dup).write(*prepend_id(dup, args))
+            rescue IOError
+              # Ignore
+            end
           end
         end
 
@@ -86,48 +91,122 @@ module CLI
       class Capture
         extend T::Sig
 
-        @m = Mutex.new
+        @capture_mutex = Mutex.new
+        @stdin_mutex = ReentrantMutex.new
         @active_captures = 0
         @saved_stdin = nil
 
         class << self
           extend T::Sig
 
+          sig { returns(T.nilable(Capture)) }
+          def current_capture
+            Thread.current[:cliui_current_capture]
+          end
+
+          sig { returns(Capture) }
+          def current_capture!
+            T.must(current_capture)
+          end
+
+          sig { type_parameters(:T).params(block: T.proc.returns(T.type_parameter(:T))).returns(T.type_parameter(:T)) }
+          def in_alternate_screen(&block)
+            stdin_synchronize do
+              previous_print_captured_output = current_capture&.print_captured_output
+              current_capture&.print_captured_output = true
+              Spinner::SpinGroup.pause_spinners do
+                if outermost_uncaptured?
+                  begin
+                    prev_hook = Thread.current[:cliui_output_hook]
+                    Thread.current[:cliui_output_hook] = nil
+                    replay = current_capture!.stdout.gsub(ANSI.match_alternate_screen, '')
+                    CLI::UI.raw do
+                      print("#{ANSI.enter_alternate_screen}#{replay}")
+                    end
+                  ensure
+                    Thread.current[:cliui_output_hook] = prev_hook
+                  end
+                end
+                block.call
+              ensure
+                print(ANSI.exit_alternate_screen) if outermost_uncaptured?
+              end
+            ensure
+              current_capture&.print_captured_output = !!previous_print_captured_output
+            end
+          end
+
+          sig { type_parameters(:T).params(block: T.proc.returns(T.type_parameter(:T))).returns(T.type_parameter(:T)) }
+          def stdin_synchronize(&block)
+            @stdin_mutex.synchronize do
+              case $stdin
+              when BlockingInput
+                $stdin.synchronize do
+                  block.call
+                end
+              else
+                block.call
+              end
+            end
+          end
+
           sig { type_parameters(:T).params(block: T.proc.returns(T.type_parameter(:T))).returns(T.type_parameter(:T)) }
           def with_stdin_masked(&block)
-            @m.synchronize do
+            @capture_mutex.synchronize do
               if @active_captures.zero?
-                @saved_stdin = $stdin
-                $stdin, w = IO.pipe
-                $stdin.close
-                w.close
+                @stdin_mutex.synchronize do
+                  @saved_stdin = $stdin
+                  $stdin = BlockingInput.new(@saved_stdin)
+                end
               end
               @active_captures += 1
             end
 
             yield
           ensure
-            @m.synchronize do
+            @capture_mutex.synchronize do
               @active_captures -= 1
               if @active_captures.zero?
-                $stdin = @saved_stdin
+                @stdin_mutex.synchronize do
+                  $stdin = @saved_stdin
+                end
               end
             end
           end
+
+          private
+
+          sig { returns(T::Boolean) }
+          def outermost_uncaptured?
+            @stdin_mutex.count == 1 && $stdin.is_a?(BlockingInput)
+          end
         end
 
         sig do
-          params(with_frame_inset: T::Boolean, block: T.proc.void).void
+          params(
+            with_frame_inset: T::Boolean,
+            merged_output: T::Boolean,
+            duplicate_output_to: IO,
+            block: T.proc.void,
+          ).void
         end
-        def initialize(with_frame_inset: true, &block)
+        def initialize(
+          with_frame_inset: true,
+          merged_output: false,
+          duplicate_output_to: File.open(File::NULL, 'w'),
+          &block
+        )
           @with_frame_inset = with_frame_inset
+          @merged_output = merged_output
+          @duplicate_output_to = duplicate_output_to
           @block = block
-          @stdout = ''
-          @stderr = ''
+          @print_captured_output = false
+          @out = StringIO.new
+          @err = StringIO.new
         end
 
-        sig { returns(String) }
-        attr_reader :stdout, :stderr
+        sig { returns(T::Boolean) }
+        attr_accessor :print_captured_output
 
         sig { returns(T.untyped) }
         def run
@@ -135,8 +214,7 @@ module CLI
 
           StdoutRouter.assert_enabled!
 
-          out = StringIO.new
-          err = StringIO.new
+          Thread.current[:cliui_current_capture] = self
 
           prev_frame_inset = Thread.current[:no_cliui_frame_inset]
           prev_hook = Thread.current[:cliui_output_hook]
@@ -148,24 +226,90 @@ module CLI
           self.class.with_stdin_masked do
             Thread.current[:no_cliui_frame_inset] = !@with_frame_inset
             Thread.current[:cliui_output_hook] = ->(data, stream) do
+              stream = :stdout if @merged_output
               case stream
-              when :stdout then out.write(data)
-              when :stderr then err.write(data)
+              when :stdout
+                @out.write(data)
+                @duplicate_output_to.write(data)
+              when :stderr
+                @err.write(data)
               else raise
               end
-              false # suppress writing to terminal
+              print_captured_output # suppress writing to terminal by default
             end
 
-            begin
-              @block.call
-            ensure
-              @stdout = out.string
-              @stderr = err.string
-            end
+            @block.call
           end
         ensure
           Thread.current[:cliui_output_hook] = prev_hook
           Thread.current[:no_cliui_frame_inset] = prev_frame_inset
+          Thread.current[:cliui_current_capture] = nil
+        end
+
+        sig { returns(String) }
+        def stdout
+          @out.string
+        end
+
+        sig { returns(String) }
+        def stderr
+          @err.string
+        end
+
+        class BlockingInput
+          extend T::Sig
+
+          sig { params(stream: IO).void }
+          def initialize(stream)
+            @stream = stream
+            @m = ReentrantMutex.new
+          end
+
+          sig { type_parameters(:T).params(block: T.proc.returns(T.type_parameter(:T))).returns(T.type_parameter(:T)) }
+          def synchronize(&block)
+            @m.synchronize do
+              previous_allowed_to_read = Thread.current[:cliui_allowed_to_read]
+              Thread.current[:cliui_allowed_to_read] = true
+              block.call
+            ensure
+              Thread.current[:cliui_allowed_to_read] = previous_allowed_to_read
+            end
+          end
+
+          READING_METHODS = [
+            :each,
+            :each_byte,
+            :each_char,
+            :each_codepoint,
+            :each_line,
+            :getbyte,
+            :getc,
+            :getch,
+            :gets,
+            :read,
+            :read_nonblock,
+            :readbyte,
+            :readchar,
+            :readline,
+            :readlines,
+            :readpartial,
+          ]
+
+          NON_READING_METHODS = IO.instance_methods(false) - READING_METHODS
+
+          READING_METHODS.each do |method|
+            define_method(method) do |*args, **kwargs, &block|
+              raise(IOError, 'closed stream') unless Thread.current[:cliui_allowed_to_read]
+
+              @stream.send(method, *args, **kwargs, &block)
+            end
+          end
+
+          NON_READING_METHODS.each do |method|
+            define_method(method) do |*args, **kwargs, &block|
+              @stream.send(method, *args, **kwargs, &block)
+            end
+          end
         end
       end
 

data/lib/cli/ui/version.rb

@@ -2,6 +2,6 @@
 
 module CLI
   module UI
-    VERSION = '2.0.0'
+    VERSION = '2.2.0'
   end
 end

data/lib/cli/ui.rb

@@ -89,6 +89,17 @@ module CLI
         CLI::UI::Prompt.confirm(question, default: default)
       end
 
+      # Convenience Method for +CLI::UI::Prompt.any_key+
+      #
+      # ==== Attributes
+      #
+      # * +prompt+ - prompt to present
+      #
+      sig { params(prompt: String).returns(T.nilable(String)) }
+      def any_key(prompt = 'Press any key to continue')
+        CLI::UI::Prompt.any_key(prompt)
+      end
+
       # Convenience Method for +CLI::UI::Prompt.ask+
       sig do
         params(

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cli-ui
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Burke Libbey
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-11-18 00:00:00.000000000 Z
+date: 2023-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest