dry-cli-ui 0.4.0 → 0.5.1

data/lib/dry/cli/ui/console.rb

@@ -75,7 +75,7 @@ module Dry
           @config = config
         end
 
-        # A framed panel. Given a level, it takes that level's title, colour
+        # A framed panel, preceded by a blank line. Given a level, it takes that level's title, colour
         # and stream; without one it is untitled unless given a title, and goes
         # to `out`.
         #
@@ -91,7 +91,7 @@ module Dry
           theme = level && Theme.level(level)
           terminal = theme ? stream(theme) : out
           widget = Widgets::Box.new(terminal, width: width || box_width)
-          terminal.print(widget.render(paragraphs, title: title || theme&.title, color: theme&.color))
+          terminal.print("\n#{widget.render(paragraphs, title: title || theme&.title, color: theme&.color)}")
           nil
         end
 
@@ -158,26 +158,30 @@ module Dry
         # @param title [String] the headline
         # @param concurrent [Boolean, Integer] all at once (the default), one at
         #   a time, or at most this many at once
+        # @param stop [Stop, nil] once set, no more jobs start; see {#stoppable}
         # @yieldparam spinners [Widgets::MultiSpinner::Builder] declares each `spinner`
         # @return [Array<Object>] what each job returned, in declaration order
         # @raise [ArgumentError] without a block, or with an invalid concurrent
-        def multi_spinner(title, concurrent: true, &)
+        def multi_spinner(title, concurrent: true, stop: nil, &)
           raise ArgumentError, "multi_spinner needs a block" unless block_given?
 
-          Widgets::MultiSpinner.new(err, clock: clock, config: config).run(title, concurrent: concurrent, &)
+          Widgets::MultiSpinner.new(err, clock: clock, config: config).run(title, concurrent: concurrent, stop: stop, &)
         end
 
         # Runs a block with a progress bar showing percent, count and ETA.
         #
         # @param label [String]
         # @param total [Integer] units of work
+        # @param color [Symbol, nil] the finished part's Pastel style; nil for
+        #   the configured `bar_color`
         # @yieldparam progress [Widgets::Progress::Handle] call `advance` as units complete
         # @return [Object] whatever the block returns
-        # @raise [ArgumentError] without a block, or when total is not a non-negative Integer
-        def progress(label, total:, &)
+        # @raise [ArgumentError] without a block, when total is not a
+        #   non-negative Integer, or when color is not a Pastel style
+        def progress(label, total:, color: nil, &)
           raise ArgumentError, "progress needs a block" unless block_given?
 
-          Widgets::Progress.new(err, clock: clock, config: config).run(label, total: total, &)
+          Widgets::Progress.new(err, clock: clock, config: config).run(label, total: total, color: color, &)
         end
 
         # Runs several jobs at once, each with a progress bar of its own,
@@ -194,13 +198,18 @@ module Dry
         # @param title [String] the headline
         # @param concurrent [Boolean, Integer] all at once (the default), one at
         #   a time, or at most this many at once
+        # @param count [Symbol] what the headline bar counts: `:units`, the sum
+        #   of every bar (the default), or `:jobs`, how many jobs have ended
+        # @param total [Integer, nil] the headline bar's total, when the jobs'
+        #   totals do not add up to it; nil to work it out
+        # @param stop [Stop, nil] once set, no more jobs start; see {#stoppable}
         # @yieldparam bars [Widgets::MultiProgress::Builder] declares each `progress`
         # @return [Array<Object>] what each job returned, in declaration order
-        # @raise [ArgumentError] without a block, or with an invalid concurrent
-        def multi_progress(title, concurrent: true, &)
+        # @raise [ArgumentError] without a block, or with an invalid concurrent, count or total
+        def multi_progress(title, concurrent: true, count: :units, total: nil, stop: nil, &)
           raise ArgumentError, "multi_progress needs a block" unless block_given?
 
-          Widgets::MultiProgress.new(err, clock: clock, config: config).run(title, concurrent: concurrent, &)
+          Widgets::MultiProgress.new(err, clock: clock, config: config).run(title, concurrent: concurrent, count: count, total: total, stop: stop, &)
         end
 
         # Declares a tree of tasks, then runs it, showing each task's state
@@ -253,6 +262,26 @@ module Dry
           StatusBar.new(err, others: others, title: title, hints: Array(hints), clock: clock, config: config).run(&)
         end
 
+        # Runs the block with Ctrl-C asking for a stop instead of interrupting.
+        # Hand the stop to `multi_spinner` or `multi_progress` as `stop:`, and
+        # the jobs running finish while the rest are skipped. A second Ctrl-C
+        # interrupts as usual. See {Stop}.
+        #
+        # @example
+        #   ui.stoppable do |stop|
+        #     done = ui.multi_spinner("Fetching", concurrent: 4, stop: stop) { |m| ... }
+        #     ui.info "Stopped after #{done.compact.size}" if stop.stopped?
+        #   end
+        #
+        # @yieldparam stop [Stop]
+        # @return [Object] whatever the block returns
+        # @raise [ArgumentError] without a block
+        def stoppable(&)
+          raise ArgumentError, "stoppable needs a block" unless block_given?
+
+          Stop.new.trap(&)
+        end
+
         # Prints a table to `out`.
         #
         # @example

data/lib/dry/cli/ui/status_bar.rb

@@ -284,7 +284,7 @@ module Dry
         # @return [String, nil] a bar over every progress reported so far
         def meter
           progress = @finished + @running.values.filter_map(&:last)
-          total = progress.sum(&:total)
+          total = progress.sum { |item| item.total || item.current }
           return if total.zero?
 
           ratio = progress.sum(&:current).fdiv(total)

data/lib/dry/cli/ui/stop.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      # A request to stop starting new work, which any thread may make or
+      # check. The multi widgets take one as `stop:`: once it is set, jobs
+      # already running finish, and jobs not yet started are skipped.
+      #
+      # {#trap} sets it on Ctrl-C, so a command can end early and still report
+      # what it did. A second Ctrl-C interrupts as usual.
+      #
+      # @example
+      #   ui.stoppable do |stop|
+      #     files = ui.multi_spinner("Downloading", concurrent: 10, stop: stop) { |m| ... }
+      #     ui.info "Stopped after #{files.compact.size} files" if stop.stopped?
+      #   end
+      class Stop
+        # A plain flag rather than an atomic one, which takes a lock, and a
+        # trap handler may not. Setting it once, to true, is safe to race.
+        def initialize
+          @stopped = false
+        end
+
+        # @return [Boolean] whether a stop was asked for
+        def stopped? = @stopped
+
+        # Asks for a stop.
+        #
+        # @return [self]
+        def stop!
+          @stopped = true
+          self
+        end
+
+        # Runs the block with the signal trapped: the first one asks for a
+        # stop, and the next raises `Interrupt`. The previous handler is put
+        # back when the block ends.
+        #
+        # @param signal [String]
+        # @yieldparam stop [Stop] this stop
+        # @return [Object] whatever the block returns
+        def trap(signal = "INT")
+          previous = Signal.trap(signal) { stopped? ? raise(Interrupt) : stop! }
+          yield self
+        ensure
+          Signal.trap(signal, previous || "DEFAULT")
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/ui/version.rb

@@ -11,7 +11,7 @@ module Dry
     # Presentation helpers for Dry::CLI commands.
     module UI
       # The gem version.
-      VERSION = "0.4.0"
+      VERSION = "0.5.1"
     end
   end
 end

data/lib/dry/cli/ui/widgets/multi.rb

@@ -16,8 +16,13 @@ module Dry
         # limit, is drawn before the first job starts.
         #
         # On an animated terminal the rows are drawn once and redrawn in place.
-        # Otherwise, or when there are more rows than the screen has, it prints
-        # `Title...`, then each job's outcome as it ends, then the headline's.
+        # When there are more rows than the screen has, only the jobs running
+        # are shown under the headline, as many as fit. Without animation it
+        # prints `Title...`, then each job's outcome as it ends, then the headline's.
+        #
+        # Given a {Stop} that is set, jobs already running finish, jobs not yet
+        # started are marked skipped, and so is the headline; while the running
+        # jobs finish, the headline says `stopping`.
         #
         # When a job raises, jobs already running finish, jobs not yet started
         # are marked skipped, the headline is marked failed, and the first error
@@ -72,6 +77,7 @@ module Dry
             @live = nil
             @lock = Mutex.new
             @frame = 0
+            @drawn = 0
           end
 
           # Declares the jobs with the block, then runs them.
@@ -79,19 +85,21 @@ module Dry
           # @param title [String] the headline above the jobs
           # @param concurrent [Boolean, Integer] all at once, one at a time, or
           #   at most this many at once
+          # @param stop [Stop, nil] once set, no more jobs start
           # @yieldparam builder [Object] declares the jobs
           # @return [Array<Object>] what each job returned, in declaration
           #   order; nil for a job that never ran
           # @raise [ArgumentError] with an invalid concurrent
           # @raise [Exception] the first error a job raised
-          def run(title, concurrent: true)
+          def run(title, concurrent: true, stop: nil)
             Pool.concurrency(concurrent)
             yield builder
             @title = title
+            @stop = stop
             @started = clock.call
             ticker = start
             begin
-              Pool.run(jobs, concurrent) { |job| execute(job) }
+              Pool.run(jobs, concurrent, stop: stop) { |job| execute(job) }
             ensure
               ticker&.shutdown
               ticker&.wait_for_termination(1)
@@ -117,6 +125,9 @@ module Dry
           # @return [String]
           attr_reader :title
 
+          # @return [Stop, nil]
+          attr_reader :stop
+
           # @return [Float] when the headline started, by the clock
           attr_reader :started
 
@@ -182,7 +193,9 @@ module Dry
               return
             end
 
-            rows.each { |row| terminal.puts(row) }
+            drawn = rows
+            drawn.each { |row| terminal.puts(row) }
+            @drawn = drawn.size
             Concurrent::TimerTask.new(execution_interval: config.spinner_frame_seconds) { tick }.tap(&:execute)
           end
 
@@ -206,12 +219,21 @@ module Dry
           def finish
             jobs.each { |job| change(job, :skipped) if job.state == :pending }
             lock.synchronize do
-              self.state = jobs.all? { |job| job.state == :done } ? :done : :failed
+              self.state = outcome
               @seconds = clock.call - started
               live? ? redraw : terminal.puts(Outcome.line(terminal, state, headline_summary, @seconds))
             end
           end
 
+          # @return [Symbol] the headline's state once every job has ended:
+          #   failed when any job failed, skipped when any was skipped
+          def outcome
+            states = jobs.map(&:state)
+            return :failed if states.include?(:failed)
+
+            states.include?(:skipped) ? :skipped : :done
+          end
+
           # @param job [Job]
           # @param state [Symbol]
           # @param seconds [Float, nil]
@@ -228,15 +250,23 @@ module Dry
             end
           end
 
-          # Whether to redraw in place: needs cursor movement, and every row on
-          # the screen, since the cursor cannot move above the top row.
+          # Whether to redraw in place, which needs cursor movement.
           #
           # @return [Boolean]
           def live?
-            @live = terminal.animated? && jobs.size + 1 < terminal.height if @live.nil?
+            @live = terminal.animated? if @live.nil?
             @live
           end
 
+          # Whether some rows must be left out, since the cursor cannot move
+          # above the top row of the screen.
+          #
+          # @return [Boolean]
+          def crowded?
+            @crowded = jobs.size + 1 >= terminal.height if @crowded.nil?
+            @crowded
+          end
+
           # @return [void]
           def tick
             lock.synchronize do
@@ -245,18 +275,34 @@ module Dry
             end
           end
 
+          # Draws the rows over the ones drawn last, clearing the screen below
+          # first, since there may be fewer rows than before.
+          #
           # @return [void]
           def redraw
-            terminal.print(terminal.cursor.up(jobs.size + 1) + rows.map { |row| "#{terminal.cursor.clear_line}#{row}\n" }.join)
+            drawn = rows
+            terminal.print(terminal.cursor.up(@drawn) + terminal.cursor.clear_screen_down + drawn.map { |row| "#{terminal.cursor.clear_line}#{row}\n" }.join)
+            @drawn = drawn.size
           end
 
-          # The headline, then one row per job with its tree branch.
+          # The headline, then one row per job shown, with its tree branch.
           #
           # @return [Array<String>]
           def rows
             width = label_width
-            branches = jobs.each_with_index.map { |_, index| index == jobs.size - 1 ? "└─ " : "├─ " }
-            [headline(width), *jobs.zip(branches).map { |job, branch| terminal.pastel.bright_black(branch) + row(job, width - branch.length) }]
+            shown = visible
+            branches = shown.each_index.map { |index| index == shown.size - 1 ? "└─ " : "├─ " }
+            [headline(width), *shown.zip(branches).map { |job, branch| terminal.pastel.bright_black(branch) + row(job, width - branch.length) }]
+          end
+
+          # Every job; when crowded, only the running ones, as many as leave
+          # the bottom row free.
+          #
+          # @return [Array<Job>]
+          def visible
+            return jobs unless crowded?
+
+            jobs.select { |job| job.state == :running }.first([terminal.height - 2, 0].max)
           end
 
           # The columns every label is padded to, so what follows lines up.
@@ -269,12 +315,15 @@ module Dry
           # @param width [Integer]
           # @return [String]
           def headline(width)
-            return "#{glyph(state)} #{running_headline(width)}" if state == :running
+            return "#{glyph(state)} #{running_headline(width)}#{stopping}" if state == :running
 
             elapsed = " #{terminal.pastel.bright_black("(#{Duration.format(@seconds)})")}"
             "#{glyph(state)} #{headline_summary}#{elapsed}"
           end
 
+          # @return [String] ` stopping` once a stop is asked for, or nothing
+          def stopping = stop&.stopped? ? " #{terminal.pastel.yellow('stopping')}" : ""
+
           # @param job [Job]
           # @param width [Integer] the columns its label is padded to
           # @return [String]

data/lib/dry/cli/ui/widgets/multi_progress.rb

@@ -14,7 +14,7 @@ module Dry
         # @example
         #   ui.multi_progress("Downloading") do |m|
         #     files.each do |file|
-        #       m.progress(file.name, total: file.size) do |bar|
+        #       m.progress(file.name, total: file.size, color: file.large? ? :yellow : nil) do |bar|
         #         download(file) { |bytes| bar.advance(bytes) }
         #       end
         #     end
@@ -32,19 +32,49 @@ module Dry
             # Declares a job with a progress bar of its own.
             #
             # @param label [String]
-            # @param total [Integer] units of work
+            # @param total [Integer, nil] units of work; nil when the job finds
+            #   out as it runs, and sets `total=` on its handle
+            # @param color [Symbol, nil] the finished part's Pastel style; nil for
+            #   {Configuration#bar_color}
             # @yieldparam progress [Progress::Handle] call `advance` as units complete
             # @return [self]
-            # @raise [ArgumentError] without a block, or when total is not a non-negative Integer
-            def progress(label, total:, &work)
+            # @raise [ArgumentError] without a block, when total is neither nil
+            #   nor a non-negative Integer, or when color is not a Pastel style
+            def progress(label, total:, color: nil, &work)
               raise ArgumentError, "progress #{label.inspect} needs a block" unless work
-              raise ArgumentError, "total must be a non-negative Integer, got #{total.inspect}" unless total.is_a?(Integer) && total >= 0
 
-              @jobs << Multi::Job.new(label, work, Progress::Handle.new(total, nil))
+              Progress.total(total) unless total.nil?
+
+              @jobs << Multi::Job.new(label, work, Progress::Handle.new(total, nil, color: Progress.color(color)))
               self
             end
           end
 
+          # What the headline bar can count.
+          COUNTS = %i[units jobs].freeze
+
+          # Declares the jobs with the block, then runs them.
+          #
+          # @param title [String] the headline above the jobs
+          # @param concurrent [Boolean, Integer] see {Multi#run}
+          # @param count [Symbol] what the headline bar counts: `:units`, the
+          #   sum of every bar, or `:jobs`, how many jobs have ended
+          # @param total [Integer, nil] the headline bar's total; nil for the
+          #   sum of every bar's, or the number of jobs when counting jobs
+          # @param stop [Stop, nil] see {Multi#run}
+          # @yieldparam builder [Builder] declares the jobs
+          # @return [Array<Object>] what each job returned, in declaration order
+          # @raise [ArgumentError] with an invalid concurrent, count or total
+          # @raise [Exception] the first error a job raised
+          def run(title, concurrent: true, count: :units, total: nil, stop: nil, &)
+            raise ArgumentError, "count must be one of #{COUNTS.inspect}, got #{count.inspect}" unless COUNTS.include?(count)
+
+            Progress.total(total) unless total.nil?
+            @count = count
+            @total = total
+            super(title, concurrent: concurrent, stop: stop, &)
+          end
+
           private
 
           # @param job [Job]
@@ -55,12 +85,12 @@ module Dry
           # @param width [Integer]
           # @return [String]
           def running(job, width)
-            "#{job.label.ljust(width)} #{meter(job.handle.current, job.handle.total, job.started)}"
+            "#{job.label.ljust(width)} #{meter(job.handle.current, job.handle.total, job.started, job.handle.color)}"
           end
 
           # @param job [Job]
           # @return [String]
-          def summary(job) = "#{job.label} #{job.handle.current}/#{job.handle.total}"
+          def summary(job) = "#{job.label} #{job.handle.current}/#{job.handle.total || '?'}"
 
           # @param width [Integer]
           # @return [String]
@@ -71,24 +101,40 @@ module Dry
           # @return [String]
           def headline_summary = "#{title} #{current}/#{total}"
 
-          # @return [Integer] units completed across every job
-          def current = jobs.sum { |job| job.handle.current }
+          # @return [Integer] units completed across every job, or jobs ended
+          def current
+            return jobs.count(&:seconds) if @count == :jobs
 
-          # @return [Integer] units across every job
-          def total = jobs.sum { |job| job.handle.total }
+            jobs.sum { |job| job.handle.current }
+          end
+
+          # @return [Integer] the total given; or units across every job,
+          #   counting what a job without a total has done so far; or every job
+          def total
+            return @total if @total
+            return jobs.size if @count == :jobs
+
+            jobs.sum { |job| job.handle.total || job.handle.current }
+          end
 
           # `[◼◼◼   ] 48%  96/200  ETA 3.1s`, with the count right-aligned to
           # the widest any row can show, so every count ends in one column.
           #
+          # A bar whose total is not known yet is drawn empty, counting `12/?`.
+          #
           # @param done [Integer]
-          # @param all [Integer]
+          # @param all [Integer, nil]
           # @param since [Float, nil] when the work started, by the clock
+          # @param color [Symbol, nil] the bar's own colour, if any
           # @return [String]
-          def meter(done, all, since)
-            ratio = all.zero? ? 1.0 : done.fdiv(all)
-            bar = Progress.bar(terminal.pastel, config, ratio, bar_columns)
+          def meter(done, all, since, color = nil)
+            ratio = if all.nil? then 0.0
+                    elsif all.zero? then 1.0
+                    else done.fdiv(all)
+                    end
+            bar = Progress.bar(terminal.pastel, config, ratio, bar_columns, color: color)
             format("%<bar>s %<percent>3d%%  %<count>s  ETA %<eta>s",
-                   bar: bar, percent: (ratio * 100).floor, count: "#{done}/#{all}".rjust(count_width), eta: eta(done, all, since))
+                   bar: bar, percent: (ratio * 100).floor, count: "#{done}/#{all || '?'}".rjust(count_width), eta: eta(done, all, since))
           end
 
           # The widest count any row shows: the headline's, once every job is done.
@@ -104,11 +150,12 @@ module Dry
           end
 
           # @param done [Integer]
-          # @param all [Integer]
+          # @param all [Integer, nil]
           # @param since [Float, nil]
-          # @return [String] the time left at the rate so far, or `--` before any progress
+          # @return [String] the time left at the rate so far, or `--` before
+          #   any progress or while the total is not known
           def eta(done, all, since)
-            return "--" if since.nil? || done.zero?
+            return "--" if since.nil? || done.zero? || all.nil?
 
             Duration.format((clock.call - since) / done * (all - done))
           end

data/lib/dry/cli/ui/widgets/pool.rb

@@ -11,7 +11,8 @@ module Dry
         #
         # When one raises, items already running finish, items not yet
         # started are never started, and the first error is re-raised once
-        # everything running has stopped.
+        # everything running has stopped. Once a {Stop} is set, items not yet
+        # started are never started either.
         module Pool
           # Checks a `concurrent:` setting.
           #
@@ -29,13 +30,14 @@ module Dry
           #
           # @param items [Array]
           # @param concurrent [Boolean, Integer] see {.concurrency}
+          # @param stop [Stop, nil] checked before each item starts
           # @yieldparam item [Object] one of the items
           # @return [void]
           # @raise [Exception] the first error any block raised
-          def self.run(items, concurrent, &)
-            return items.each(&) unless concurrent
+          def self.run(items, concurrent, stop: nil, &each)
+            return items.each { |item| stop&.stopped? ? break : each.call(item) } unless concurrent
 
-            futures = concurrent == true ? all_at_once(items, &) : at_most(concurrent, items, &)
+            futures = concurrent == true ? all_at_once(items, &each) : at_most(concurrent, items, stop, &each)
             futures.each(&:wait)
             failed = futures.find(&:rejected?)
             raise failed.reason if failed
@@ -52,26 +54,28 @@ module Dry
           #
           # @param limit [Integer]
           # @param items [Array]
+          # @param stop [Stop, nil]
           # @return [Array<Concurrent::Promises::Future>] one per worker
-          def self.at_most(limit, items, &)
+          def self.at_most(limit, items, stop, &)
             queue = Queue.new
             items.each { |item| queue << item }
             queue.close
-            stop = Concurrent::AtomicBoolean.new
-            Array.new([limit, items.size].min) { Concurrent::Promises.future { work(queue, stop, &) } }
+            failed = Concurrent::AtomicBoolean.new
+            Array.new([limit, items.size].min) { Concurrent::Promises.future { work(queue, failed, stop, &) } }
           end
 
           # @param queue [Queue] closed, so `pop` returns nil once it is empty
-          # @param stop [Concurrent::AtomicBoolean] set once any worker raises
+          # @param failed [Concurrent::AtomicBoolean] set once any worker raises
+          # @param stop [Stop, nil]
           # @return [void]
-          def self.work(queue, stop, &each)
+          def self.work(queue, failed, stop, &each)
             ok = false
-            while (item = queue.pop) && stop.false?
+            while !stop&.stopped? && (item = queue.pop) && failed.false?
               each.call(item)
             end
             ok = true
           ensure
-            stop.make_true unless ok
+            failed.make_true unless ok
           end
 
           private_class_method :all_at_once, :at_most, :work