cli-ui 2.2.3 → 2.3.0

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

@@ -1,10 +1,13 @@
 # typed: true
+# frozen_string_literal: true
+
+require_relative '../work_queue'
 
 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 }
+        DEFAULT_FINAL_GLYPH = ->(success) { success ? CLI::UI::Glyph::CHECK : CLI::UI::Glyph::X }
 
         class << self
           extend T::Sig
@@ -47,6 +50,11 @@ module CLI
         # ==== Options
         #
         # * +:auto_debrief+ - Automatically debrief exceptions or through success_debrief? Default to true
+        # * +:interrupt_debrief+ - Automatically debrief on interrupt. Default to false
+        # * +:max_concurrent+ - Maximum number of concurrent tasks. Default is 0 (effectively unlimited)
+        # * +:work_queue+ - Custom WorkQueue instance. If not provided, a new one will be created
+        # * +: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 Usage
         #
@@ -59,16 +67,31 @@ module CLI
         #
         # https://user-images.githubusercontent.com/3074765/33798558-c452fa26-dce8-11e7-9e90-b4b34df21a46.gif
         #
-        sig { params(auto_debrief: T::Boolean).void }
-        def initialize(auto_debrief: true)
+        sig do
+          params(
+            auto_debrief: T::Boolean,
+            interrupt_debrief: T::Boolean,
+            max_concurrent: Integer,
+            work_queue: T.nilable(WorkQueue),
+            to: IOLike,
+          ).void
+        end
+        def initialize(auto_debrief: true, interrupt_debrief: false, max_concurrent: 0, work_queue: nil, to: $stdout)
           @m = Mutex.new
-          @consumed_lines = 0
           @tasks = []
+          @puts_above = []
           @auto_debrief = auto_debrief
+          @interrupt_debrief = interrupt_debrief
           @start = Time.new
+          @stopped = false
+          @internal_work_queue = work_queue.nil?
+          @work_queue = T.let(
+            work_queue || WorkQueue.new(max_concurrent.zero? ? 1024 : max_concurrent),
+            WorkQueue,
+          )
           if block_given?
             yield self
-            wait
+            wait(to: to)
           end
         end
 
@@ -81,6 +104,9 @@ module CLI
           sig { returns(T::Boolean) }
           attr_reader :success
 
+          sig { returns(T::Boolean) }
+          attr_reader :done
+
           sig { returns(T.nilable(Exception)) }
           attr_reader :exception
 
@@ -95,17 +121,18 @@ module CLI
           sig do
             params(
               title: String,
-              final_glyph: T.proc.params(success: T::Boolean).returns(String),
+              final_glyph: T.proc.params(success: T::Boolean).returns(T.any(Glyph, String)),
               merged_output: T::Boolean,
               duplicate_output_to: IO,
+              work_queue: WorkQueue,
               block: T.proc.params(task: Task).returns(T.untyped),
             ).void
           end
-          def initialize(title, final_glyph:, merged_output:, duplicate_output_to:, &block)
+          def initialize(title, final_glyph:, merged_output:, duplicate_output_to:, work_queue:, &block)
             @title = title
             @final_glyph = final_glyph
             @always_full_render = title =~ Formatter::SCAN_WIDGET
-            @thread = Thread.new do
+            @future = work_queue.enqueue do
               cap = CLI::UI::StdoutRouter::Capture.new(
                 merged_output: merged_output, duplicate_output_to: duplicate_output_to,
               ) { block.call(self) }
@@ -121,7 +148,12 @@ module CLI
             @force_full_render = false
             @done = false
             @exception = nil
-            @success   = false
+            @success = false
+          end
+
+          sig { params(block: T.proc.params(task: Task).void).void }
+          def on_done(&block)
+            @on_done = block
           end
 
           # Checks if a task is finished
@@ -129,18 +161,20 @@ module CLI
           sig { returns(T::Boolean) }
           def check
             return true if @done
-            return false if @thread.alive?
+            return false unless @future.completed?
 
             @done = true
             begin
-              status = @thread.join.status
-              @success = (status == false)
-              @success = false if @thread.value == TASK_FAILED
+              result = @future.value
+              @success = true
+              @success = false if result == TASK_FAILED
             rescue => exc
               @exception = exc
               @success = false
             end
 
+            @on_done&.call(self)
+
             @done
           end
 
@@ -165,7 +199,7 @@ module CLI
           sig { params(index: Integer, force: T::Boolean, width: Integer).returns(String) }
           def render(index, force = true, width: CLI::UI::Terminal.width)
             @m.synchronize do
-              if force || @always_full_render || @force_full_render
+              if !CLI::UI.enable_cursor? || force || @always_full_render || @force_full_render
                 full_render(index, width)
               else
                 partial_render(index)
@@ -190,38 +224,51 @@ module CLI
             end
           end
 
-          sig { void }
-          def interrupt
-            @thread.raise(Interrupt)
-          end
-
           private
 
           sig { params(index: Integer, terminal_width: Integer).returns(String) }
           def full_render(index, terminal_width)
-            prefix = inset +
-              glyph(index) +
-              CLI::UI::Color::RESET.code +
-              ' '
+            o = +''
+
+            o << inset
+            o << glyph(index)
+            o << ' '
+
+            truncation_width = terminal_width - CLI::UI::ANSI.printing_width(o)
 
-            truncation_width = terminal_width - CLI::UI::ANSI.printing_width(prefix)
+            o << CLI::UI.resolve_text(title, truncate_to: truncation_width)
+            o << ANSI.clear_to_end_of_line if CLI::UI.enable_cursor?
 
-            prefix +
-              CLI::UI.resolve_text(title, truncate_to: truncation_width) +
-              "\e[K"
+            o
           end
 
           sig { params(index: Integer).returns(String) }
           def partial_render(index)
-            CLI::UI::ANSI.cursor_forward(inset_width) + glyph(index) + CLI::UI::Color::RESET.code
+            o = +''
+
+            o << CLI::UI::ANSI.cursor_forward(inset_width)
+            o << glyph(index)
+
+            o
           end
 
           sig { params(index: Integer).returns(String) }
           def glyph(index)
             if @done
-              @final_glyph.call(@success)
+              final_glyph = @final_glyph.call(@success)
+              if final_glyph.is_a?(Glyph)
+                CLI::UI.enable_color? ? final_glyph.to_s : final_glyph.char
+              else
+                final_glyph
+              end
+            elsif CLI::UI.enable_cursor?
+              if !@future.started?
+                CLI::UI.enable_color? ? Glyph::HOURGLASS.to_s : Glyph::HOURGLASS.char
+              else
+                CLI::UI.enable_color? ? GLYPHS[index] : RUNES[index]
+              end
             else
-              GLYPHS[index]
+              Glyph::HOURGLASS.char
             end
           end
 
@@ -251,7 +298,7 @@ module CLI
         sig do
           params(
             title: String,
-            final_glyph: T.proc.params(success: T::Boolean).returns(String),
+            final_glyph: T.proc.params(success: T::Boolean).returns(T.any(Glyph, String)),
             merged_output: T::Boolean,
             duplicate_output_to: IO,
             block: T.proc.params(task: Task).void,
@@ -270,23 +317,66 @@ module CLI
               final_glyph: final_glyph,
               merged_output: merged_output,
               duplicate_output_to: duplicate_output_to,
+              work_queue: @work_queue,
               &block
             )
           end
         end
 
+        sig { void }
+        def stop
+          # If we already own the mutex (called from within another synchronized block),
+          # set stopped directly to avoid deadlock
+          if @m.owned?
+            return if @stopped
+
+            @stopped = true
+          else
+            @m.synchronize do
+              return if @stopped
+
+              @stopped = true
+            end
+          end
+          # Interrupt is thread-safe on its own, so we can call it outside the mutex
+          @work_queue.interrupt
+        end
+
+        sig { returns(T::Boolean) }
+        def stopped?
+          if @m.owned?
+            @stopped
+          else
+            @m.synchronize { @stopped }
+          end
+        end
+
         # Tells the group you're done adding tasks and to wait for all of them to finish
         #
+        # ==== Options
+        #
+        # * +: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 Usage:
         #   spin_group = CLI::UI::SpinGroup.new
         #   spin_group.add('Title') { |spinner| sleep 1.0 }
         #   spin_group.wait
         #
-        sig { returns(T::Boolean) }
-        def wait
+        sig { params(to: IOLike).returns(T::Boolean) }
+        def wait(to: $stdout)
           idx = 0
 
+          consumed_lines = 0
+
+          @work_queue.close if @internal_work_queue
+
+          tasks_seen = @tasks.map { false }
+          tasks_seen_done = @tasks.map { false }
+
           loop do
+            break if stopped?
+
             done_count = 0
 
             width = CLI::UI::Terminal.width
@@ -296,21 +386,46 @@ module CLI
 
               @m.synchronize do
                 CLI::UI.raw do
+                  force_full_render = false
+
+                  unless @puts_above.empty?
+                    to.print(CLI::UI::ANSI.cursor_up(consumed_lines)) if CLI::UI.enable_cursor?
+                    while (message = @puts_above.shift)
+                      to.print(CLI::UI::ANSI.insert_lines(message.lines.count)) if CLI::UI.enable_cursor?
+                      message.lines.each do |line|
+                        to.print(CLI::UI::Frame.prefix + CLI::UI.fmt(line))
+                      end
+                      to.print("\n")
+                    end
+                    # we descend with newlines rather than ANSI.cursor_down as the inserted lines may've
+                    # pushed the spinner off the front of the buffer, so we can't move back down below it
+                    to.print("\n" * consumed_lines) if CLI::UI.enable_cursor?
+
+                    force_full_render = true
+                  end
+
                   @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)
+                    if CLI::UI.enable_cursor?
+                      if nat_index > consumed_lines
+                        to.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)
+
+                        to.print(move_to + task.render(idx, idx.zero? || force_full_render, width: width) + move_from)
+                      end
+                    elsif !tasks_seen[int_index] || (task_done && !tasks_seen_done[int_index])
+                      to.print(task.render(idx, true, width: width) + "\n")
                     end
+
+                    tasks_seen[int_index] = true
+                    tasks_seen_done[int_index] ||= task_done
                   end
                 end
               end
@@ -324,13 +439,21 @@ module CLI
           end
 
           if @auto_debrief
-            debrief
+            debrief(to: to)
           else
             all_succeeded?
           end
         rescue Interrupt
-          @tasks.each(&:interrupt)
-          raise
+          @work_queue.interrupt
+          debrief(to: to) if @interrupt_debrief
+          stopped? ? false : raise
+        end
+
+        sig { params(message: String).void }
+        def puts_above(message)
+          @m.synchronize do
+            @puts_above << message
+          end
         end
 
         # Provide an alternative debriefing for failed tasks
@@ -362,10 +485,17 @@ module CLI
 
         # Debriefs failed tasks is +auto_debrief+ is true
         #
-        sig { returns(T::Boolean) }
-        def debrief
+        # ==== Options
+        #
+        # * +:to+ - Target stream, like $stdout or $stderr. Can be anything with print and puts methods,
+        #   or under Sorbet, IO or StringIO. Defaults to $stdout
+        #
+        sig { params(to: IOLike).returns(T::Boolean) }
+        def debrief(to: $stdout)
           @m.synchronize do
             @tasks.each do |task|
+              next unless task.done
+
               title = task.title
               out = task.stdout
               err = task.stderr
@@ -374,22 +504,23 @@ module CLI
                 next @success_debrief&.call(title, out, err)
               end
 
+              # exception will not be set if the wait loop is stopped before the task is checked
               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
                 if e
-                  puts "#{e.class}: #{e.message}"
-                  puts "\tfrom #{e.backtrace.join("\n\tfrom ")}"
+                  to.puts("#{e.class}: #{e.message}")
+                  to.puts("\tfrom #{e.backtrace.join("\n\tfrom ")}")
                 end
 
                 CLI::UI::Frame.divider('STDOUT')
                 out = '(empty)' if out.nil? || out.strip.empty?
-                puts out
+                to.puts(out)
 
                 CLI::UI::Frame.divider('STDERR')
                 err = '(empty)' if err.nil? || err.strip.empty?
-                puts err
+                to.puts(err)
               end
             end
             @tasks.all?(&:success)

data/lib/cli/ui/spinner.rb

@@ -22,7 +22,7 @@ module CLI
 
       colors = [CLI::UI::Color::CYAN.code] * (RUNES.size / 2).ceil +
         [CLI::UI::Color::MAGENTA.code] * (RUNES.size / 2).to_i
-      GLYPHS = colors.zip(RUNES).map(&:join)
+      GLYPHS = colors.zip(RUNES).map { |c, r| c + r + CLI::UI::Color::RESET.code }.freeze
 
       class << self
         extend T::Sig
@@ -62,6 +62,8 @@ module CLI
         # ==== Options
         #
         # * +:auto_debrief+ - Automatically debrief exceptions or through success_debrief? Default to true
+        # * +:to+ - Target stream, like $stdout or $stderr. Can be anything with print and puts methods,
+        #   or under Sorbet, IO or StringIO. Defaults to $stdout.
         #
         # ==== Block
         #
@@ -72,13 +74,17 @@ module CLI
         #   CLI::UI::Spinner.spin('Title') { sleep 1.0 }
         #
         sig do
-          params(title: String, auto_debrief: T::Boolean, block: T.proc.params(task: SpinGroup::Task).void)
-            .returns(T::Boolean)
+          params(
+            title: String,
+            auto_debrief: T::Boolean,
+            to: IOLike,
+            block: T.proc.params(task: SpinGroup::Task).void,
+          ).returns(T::Boolean)
         end
-        def spin(title, auto_debrief: true, &block)
+        def spin(title, auto_debrief: true, to: $stdout, &block)
           sg = SpinGroup.new(auto_debrief: auto_debrief)
           sg.add(title, &block)
-          sg.wait
+          sg.wait(to: to)
         end
       end
     end

data/lib/cli/ui/stdout_router.rb

@@ -1,4 +1,5 @@
 # typed: true
+# frozen_string_literal: true
 
 require 'cli/ui'
 require 'stringio'
@@ -18,7 +19,8 @@ module CLI
 
         sig { params(args: Object).returns(Integer) }
         def write(*args)
-          args = args.map do |str|
+          strs = args.map do |obj|
+            str = obj.to_s
             if auto_frame_inset?
               str = str.dup # unfreeze
               str = str.to_s.force_encoding(Encoding::UTF_8)
@@ -31,13 +33,13 @@ module CLI
 
           # hook return of false suppresses output.
           if (hook = Thread.current[:cliui_output_hook])
-            return 0 if hook.call(args.map(&:to_s).join, @name) == false
+            return 0 if hook.call(strs.join, @name) == false
           end
 
-          ret = T.unsafe(@stream).write_without_cli_ui(*prepend_id(@stream, args))
+          ret = T.unsafe(@stream).write_without_cli_ui(*prepend_id(@stream, strs))
           if (dup = StdoutRouter.duplicate_output_to)
             begin
-              T.unsafe(dup).write(*prepend_id(dup, args))
+              T.unsafe(dup).write(*prepend_id(dup, strs))
             rescue IOError
               # Ignore
             end

data/lib/cli/ui/table.rb

@@ -0,0 +1,87 @@
+# typed: true
+
+module CLI
+  module UI
+    module Table
+      extend T::Sig
+
+      class << self
+        extend T::Sig
+
+        # Prints a formatted table to the specified output
+        # Automatically pads columns to align based on the longest cell in each column,
+        # ignoring the width of ANSI color codes.
+        #
+        # ==== Attributes
+        #
+        # * +table+ - (required) 2D array of strings representing the table data
+        #
+        # ==== Options
+        #
+        # * +:col_spacing+ - Number of spaces between columns. Defaults to 1
+        # * +: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
+        #
+        #   CLI::UI::Table.puts_table([
+        #     ["{{bold:header_1}}", "{{bold:header_2}}"],
+        #     ["really_long_cell",  "short"],
+        #     ["row2",              "row2"]
+        #   ])
+        #
+        # Default Output:
+        #   header_1         header_2
+        #   really_long_cell short
+        #   row2             row2
+        #
+        sig { params(table: T::Array[T::Array[String]], col_spacing: Integer, to: IOLike).void }
+        def puts_table(table, col_spacing: 1, to: $stdout)
+          col_sizes = table.transpose.map do |col|
+            col.map { |cell| CLI::UI::ANSI.printing_width(CLI::UI.resolve_text(cell)) }.max
+          end
+
+          table.each do |row|
+            padded_row = row.each_with_index.map do |cell, i|
+              col_size = T.must(col_sizes[i]) # guaranteed to be non-nil
+              cell_size = CLI::UI::ANSI.printing_width(CLI::UI.resolve_text(cell))
+              padded_cell = cell + ' ' * (col_size - cell_size)
+              padded_cell
+            end
+            CLI::UI.puts(padded_row.join(' ' * col_spacing), to: to)
+          end
+        end
+
+        # Captures a table's output as an array of strings without printing to the terminal
+        # Can be used to further manipulate or format the table output
+        #
+        # ==== Attributes
+        #
+        # * +table+ - (required) 2D array of strings representing the table data
+        #
+        # ==== Options
+        #
+        # * +:col_spacing+ - Number of spaces between columns. Defaults to 1
+        #
+        # ==== Returns
+        #
+        # * +Array[String]+ - Array of strings, each representing a row of the formatted table
+        #
+        # ==== Example
+        #
+        #   CLI::UI::Table.capture_table([
+        #     ["{{bold:header_1}}", "{{bold:header_2}}"],
+        #     ["really_long_cell",  "short"],
+        #     ["row2",              "row2"]
+        #   ])
+        #
+        sig { params(table: T::Array[T::Array[String]], col_spacing: Integer).returns(T::Array[String]) }
+        def capture_table(table, col_spacing: 1)
+          strio = StringIO.new
+          puts_table(table, col_spacing: col_spacing, to: strio)
+          strio.string.lines.map(&:chomp)
+        end
+      end
+    end
+  end
+end

data/lib/cli/ui/terminal.rb

@@ -1,4 +1,5 @@
 # typed: true
+# frozen_string_literal: true
 
 require 'cli/ui'
 require 'io/console'

data/lib/cli/ui/version.rb

@@ -1,7 +1,8 @@
 # typed: true
+# frozen_string_literal: true
 
 module CLI
   module UI
-    VERSION = '2.2.3'
+    VERSION = '2.3.0'
   end
 end

data/lib/cli/ui/widgets/base.rb

@@ -1,4 +1,5 @@
 # typed: true
+# frozen_string_literal: true
 
 require('cli/ui')
 

data/lib/cli/ui/widgets.rb

@@ -1,4 +1,5 @@
 # typed: true
+# frozen_string_literal: true
 
 require('cli/ui')
 
@@ -80,7 +81,7 @@ module CLI
 
         sig { params(argstring: String, pattern: Regexp).void }
         def initialize(argstring, pattern)
-          super
+          super(nil)
           @argstring = argstring
           @pattern   = pattern
         end