dry-cli-ui 0.3.1 → 0.4.0

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

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # Runs several named jobs, by default all at once, under one headline,
+        # and shows the state of each on a row of its own. {MultiSpinner} and
+        # {MultiProgress} decide what a row says; this class runs the jobs and
+        # draws the rows.
+        #
+        # The block only declares the jobs; nothing runs until it returns, so
+        # every row, including those of jobs still waiting under a concurrency
+        # 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 a job raises, jobs already running finish, jobs not yet started
+        # are marked skipped, the headline is marked failed, and the first error
+        # is re-raised.
+        class Multi
+          # What a job's row is prefixed with when rows are printed one by one.
+          PLAIN_INDENT = "  "
+
+          # One declared job.
+          class Job
+            # @param label [String]
+            # @param work [Proc]
+            # @param handle [Object] what the work is given to report through
+            def initialize(label, work, handle)
+              @label = label
+              @work = work
+              @handle = handle
+              @state = :pending
+            end
+
+            # @return [String]
+            attr_reader :label
+
+            # @return [Proc]
+            attr_reader :work
+
+            # @return [Object] a {Line} or a {Progress::Handle}
+            attr_reader :handle
+
+            # @return [Symbol] one of the keys of {Theme::STATES}
+            attr_accessor :state
+
+            # @return [Float, nil] when the job started, by the widget's clock
+            attr_accessor :started
+
+            # @return [Float, nil] how long the job ran, once it has ended
+            attr_accessor :seconds
+
+            # @return [Object] what the work returned
+            attr_accessor :value
+          end
+
+          # @param terminal [Terminal]
+          # @param clock [#call] returns monotonic seconds
+          # @param config [Configuration] where the spinner frames come from
+          def initialize(terminal, clock:, config: UI.config)
+            @terminal = terminal
+            @clock = clock
+            @config = config
+            @jobs = []
+            @state = :pending
+            @live = nil
+            @lock = Mutex.new
+            @frame = 0
+          end
+
+          # Declares the jobs with the block, then runs them.
+          #
+          # @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
+          # @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)
+            Pool.concurrency(concurrent)
+            yield builder
+            @title = title
+            @started = clock.call
+            ticker = start
+            begin
+              Pool.run(jobs, concurrent) { |job| execute(job) }
+            ensure
+              ticker&.shutdown
+              ticker&.wait_for_termination(1)
+              finish
+            end
+            jobs.map(&:value)
+          end
+
+          private
+
+          # @return [Terminal]
+          attr_reader :terminal
+
+          # @return [#call]
+          attr_reader :clock
+
+          # @return [Configuration]
+          attr_reader :config
+
+          # @return [Array<Job>]
+          attr_reader :jobs
+
+          # @return [String]
+          attr_reader :title
+
+          # @return [Float] when the headline started, by the clock
+          attr_reader :started
+
+          # @return [Mutex] held while a row changes or the rows are drawn
+          attr_reader :lock
+
+          # @return [Symbol] the headline's state
+          attr_accessor :state
+
+          # @return [Integer] the spinner frame to draw next
+          attr_accessor :frame
+
+          # @return [Object] what the declaration block is given: the
+          #   subclass's Builder, appending to {#jobs}
+          def builder = self.class::Builder.new(jobs)
+
+          # Runs a job's work with its handle.
+          #
+          # @param job [Job]
+          # @return [Object] what the work returns
+          def call(job) = job.work.call(job.handle)
+
+          # @param job [Job]
+          # @return [#current, #total, nil] what a status bar reads the job's progress from
+          def progress_of(_job) = nil
+
+          # @param job [Job]
+          # @return [Boolean] whether the work reported a failure without raising
+          def reported_failure?(_job) = false
+
+          # What follows a running job's glyph.
+          #
+          # @param job [Job]
+          # @param width [Integer] the columns its label is padded to
+          # @return [String]
+          def running(job, _width) = job.label
+
+          # What follows a job's glyph once it has ended.
+          #
+          # @param job [Job]
+          # @return [String]
+          def summary(job) = job.label
+
+          # What follows the headline's glyph while jobs run.
+          #
+          # @param width [Integer] the columns the title is padded to
+          # @return [String]
+          def running_headline(_width) = title
+
+          # What follows the headline's glyph once every job has ended.
+          #
+          # @return [String]
+          def headline_summary = title
+
+          # Draws every row and starts the spinners turning when live, or
+          # prints the title otherwise.
+          #
+          # @return [Concurrent::TimerTask, nil]
+          def start
+            self.state = :running
+            unless live?
+              terminal.puts("#{title}...")
+              return
+            end
+
+            rows.each { |row| terminal.puts(row) }
+            Concurrent::TimerTask.new(execution_interval: config.spinner_frame_seconds) { tick }.tap(&:execute)
+          end
+
+          # @param job [Job]
+          # @return [void]
+          def execute(job)
+            job.started = clock.call
+            terminal.started(job, job.label, progress: progress_of(job))
+            change(job, :running)
+            ok = false
+            job.value = call(job)
+            ok = !reported_failure?(job)
+          ensure
+            terminal.finished(job, ok)
+            change(job, ok ? :done : :failed, seconds: clock.call - job.started)
+          end
+
+          # Marks jobs that never started as skipped, and ends the headline.
+          #
+          # @return [void]
+          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
+              @seconds = clock.call - started
+              live? ? redraw : terminal.puts(Outcome.line(terminal, state, headline_summary, @seconds))
+            end
+          end
+
+          # @param job [Job]
+          # @param state [Symbol]
+          # @param seconds [Float, nil]
+          # @return [void]
+          def change(job, state, seconds: nil)
+            lock.synchronize do
+              job.state = state
+              job.seconds = seconds
+              if live?
+                redraw
+              elsif state != :running
+                terminal.puts("#{PLAIN_INDENT}#{row(job, 0)}")
+              end
+            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.
+          #
+          # @return [Boolean]
+          def live?
+            @live = terminal.animated? && jobs.size + 1 < terminal.height if @live.nil?
+            @live
+          end
+
+          # @return [void]
+          def tick
+            lock.synchronize do
+              self.frame += 1
+              redraw
+            end
+          end
+
+          # @return [void]
+          def redraw
+            terminal.print(terminal.cursor.up(jobs.size + 1) + rows.map { |row| "#{terminal.cursor.clear_line}#{row}\n" }.join)
+          end
+
+          # The headline, then one row per job 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) }]
+          end
+
+          # The columns every label is padded to, so what follows lines up.
+          #
+          # @return [Integer]
+          def label_width
+            [title.length, *jobs.map { |job| job.label.length + 3 }].max
+          end
+
+          # @param width [Integer]
+          # @return [String]
+          def headline(width)
+            return "#{glyph(state)} #{running_headline(width)}" if state == :running
+
+            elapsed = " #{terminal.pastel.bright_black("(#{Duration.format(@seconds)})")}"
+            "#{glyph(state)} #{headline_summary}#{elapsed}"
+          end
+
+          # @param job [Job]
+          # @param width [Integer] the columns its label is padded to
+          # @return [String]
+          def row(job, width)
+            return "#{glyph(:running)} #{running(job, width)}" if job.state == :running
+
+            elapsed = " #{terminal.pastel.bright_black("(#{Duration.format(job.seconds)})")}" if job.seconds
+            "#{glyph(job.state)} #{job.state == :pending ? job.label : summary(job)}#{elapsed}"
+          end
+
+          # A state's marker, `[✓]`; a turning spinner, `[⠏]`, for a running row, live.
+          #
+          # @param state [Symbol]
+          # @return [String]
+          def glyph(state)
+            frames = config.spinner_frames
+            Theme.marker(terminal.pastel, state, (frames[frame % frames.size] if state == :running && live?))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # Several progress bars under one headline bar that counts them all,
+        # like TTY::ProgressBar::Multi. Each job is given a {Progress::Handle}.
+        #
+        # Every row shows a bar, a percentage, a count and an ETA while its job
+        # runs, and is replaced by `✓ label 120/120 (1.1s)` when it ends. The
+        # bar's characters come from {Configuration#bar_format}.
+        #
+        # @example
+        #   ui.multi_progress("Downloading") do |m|
+        #     files.each do |file|
+        #       m.progress(file.name, total: file.size) do |bar|
+        #         download(file) { |bytes| bar.advance(bytes) }
+        #       end
+        #     end
+        #   end
+        #
+        # See {Multi} for how the jobs run and how the rows are drawn.
+        class MultiProgress < Multi
+          # What the declaration block is given.
+          class Builder
+            # @param jobs [Array<Multi::Job>] the list new jobs are appended to
+            def initialize(jobs)
+              @jobs = jobs
+            end
+
+            # Declares a job with a progress bar of its own.
+            #
+            # @param label [String]
+            # @param total [Integer] units of work
+            # @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, "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))
+              self
+            end
+          end
+
+          private
+
+          # @param job [Job]
+          # @return [Progress::Handle]
+          def progress_of(job) = job.handle
+
+          # @param job [Job]
+          # @param width [Integer]
+          # @return [String]
+          def running(job, width)
+            "#{job.label.ljust(width)} #{meter(job.handle.current, job.handle.total, job.started)}"
+          end
+
+          # @param job [Job]
+          # @return [String]
+          def summary(job) = "#{job.label} #{job.handle.current}/#{job.handle.total}"
+
+          # @param width [Integer]
+          # @return [String]
+          def running_headline(width)
+            "#{title.ljust(width)} #{meter(current, total, started)}"
+          end
+
+          # @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 across every job
+          def total = jobs.sum { |job| job.handle.total }
+
+          # `[◼◼◼   ] 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.
+          #
+          # @param done [Integer]
+          # @param all [Integer]
+          # @param since [Float, nil] when the work started, by the clock
+          # @return [String]
+          def meter(done, all, since)
+            ratio = all.zero? ? 1.0 : done.fdiv(all)
+            bar = Progress.bar(terminal.pastel, config, ratio, bar_columns)
+            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))
+          end
+
+          # The widest count any row shows: the headline's, once every job is done.
+          #
+          # @return [Integer]
+          def count_width = "#{total}/#{total}".length
+
+          # One width for every bar, so the headline's lines up with the jobs'.
+          #
+          # @return [Integer]
+          def bar_columns
+            [terminal.width - label_width - 3 - Progress::CHROME, Progress::MIN_BAR].max
+          end
+
+          # @param done [Integer]
+          # @param all [Integer]
+          # @param since [Float, nil]
+          # @return [String] the time left at the rate so far, or `--` before any progress
+          def eta(done, all, since)
+            return "--" if since.nil? || done.zero?
+
+            Duration.format((clock.call - since) / done * (all - done))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # Several spinners under one headline, one per job, all turning at once.
+        #
+        # Each job is given a {Line}: its detail is drawn after the label while
+        # the job runs, on an animated terminal, and {Line#fail} ends it as
+        # `✗ label: reason` without raising. The headline ends `✓` when every
+        # job succeeded, and `✗` otherwise.
+        #
+        # @example
+        #   ui.multi_spinner("Fetching", concurrent: 2) do |m|
+        #     m.spinner("fonts") { fetch(:fonts) }
+        #     m.spinner("images") { |line| fetch(:images) { |name| line.detail = name } }
+        #   end
+        #
+        # See {Multi} for how the jobs run and how the rows are drawn.
+        class MultiSpinner < Multi
+          # What the declaration block is given.
+          class Builder
+            # @param jobs [Array<Multi::Job>] the list new jobs are appended to
+            def initialize(jobs)
+              @jobs = jobs
+            end
+
+            # Declares a job with a spinner of its own.
+            #
+            # @param label [String]
+            # @yieldparam line [Line] reports on the work while it runs
+            # @return [self]
+            # @raise [ArgumentError] without a block
+            def spinner(label, &work)
+              raise ArgumentError, "spinner #{label.inspect} needs a block" unless work
+
+              @jobs << Multi::Job.new(label, work, Line.new)
+              self
+            end
+          end
+
+          private
+
+          # @param job [Job]
+          # @return [Object]
+          def call(job) = Line.call(job.work, job.handle)
+
+          # @param job [Job]
+          # @return [Boolean]
+          def reported_failure?(job) = job.handle.failed?
+
+          # The label, then the detail when the job has one.
+          #
+          # @param job [Job]
+          # @return [String]
+          def running(job, _width)
+            detail = job.handle.detail
+            detail.empty? ? job.label : "#{job.label} #{detail}"
+          end
+
+          # @param job [Job]
+          # @return [String] the label, with the reason once the job has failed
+          def summary(job) = job.handle.summary(job.label)
+        end
+      end
+    end
+  end
+end

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

@@ -16,7 +16,7 @@ module Dry
           def self.line(terminal, state, label, seconds)
             glyph, color = Theme::STATES.fetch(state)
             pastel = terminal.pastel
-            "#{pastel.decorate(glyph, color)} #{label} #{pastel.bright_black("(#{Duration.format(seconds)})")}"
+            "#{pastel.decorate(glyph, *color)} #{label} #{pastel.bright_black("(#{Duration.format(seconds)})")}"
           end
         end
       end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # Runs a list of items one at a time, all at once, or at most so many
+        # at once, for every widget that runs several pieces of work.
+        #
+        # 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.
+        module Pool
+          # Checks a `concurrent:` setting.
+          #
+          # @param value [Boolean, Integer] true for all at once, false for one
+          #   at a time, or the most that may run at once
+          # @return [Boolean, Integer] the value
+          # @raise [ArgumentError] for anything else
+          def self.concurrency(value)
+            return value if [true, false].include?(value) || (value.is_a?(Integer) && value.positive?)
+
+            raise ArgumentError, "concurrent must be true, false or a positive Integer, got #{value.inspect}"
+          end
+
+          # Runs the block for each item.
+          #
+          # @param items [Array]
+          # @param concurrent [Boolean, Integer] see {.concurrency}
+          # @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
+
+            futures = concurrent == true ? all_at_once(items, &) : at_most(concurrent, items, &)
+            futures.each(&:wait)
+            failed = futures.find(&:rejected?)
+            raise failed.reason if failed
+          end
+
+          # @param items [Array]
+          # @return [Array<Concurrent::Promises::Future>] one per item
+          def self.all_at_once(items, &)
+            items.map { |item| Concurrent::Promises.future(item, &) }
+          end
+
+          # Workers that take items off a queue until it is empty, or until
+          # one of them raises.
+          #
+          # @param limit [Integer]
+          # @param items [Array]
+          # @return [Array<Concurrent::Promises::Future>] one per worker
+          def self.at_most(limit, items, &)
+            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, &) } }
+          end
+
+          # @param queue [Queue] closed, so `pop` returns nil once it is empty
+          # @param stop [Concurrent::AtomicBoolean] set once any worker raises
+          # @return [void]
+          def self.work(queue, stop, &each)
+            ok = false
+            while (item = queue.pop) && stop.false?
+              each.call(item)
+            end
+            ok = true
+          ensure
+            stop.make_true unless ok
+          end
+
+          private_class_method :all_at_once, :at_most, :work
+        end
+      end
+    end
+  end
+end

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

@@ -46,17 +46,47 @@ module Dry
             attr_writer :current
           end
 
-          # Columns kept for the label, percentage, count and ETA around the bar.
-          CHROME = 34
+          # Columns kept for the brackets, percentage, count and ETA around the bar.
+          CHROME = 36
 
           # Narrowest bar drawn.
           MIN_BAR = 10
 
+          # A bar between brackets, painted as the configuration says: the
+          # finished part in {Configuration#bar_color}, and all of it on
+          # {Configuration#bar_background}.
+          #
+          # @param pastel [Pastel::Delegator] a no-op when colour is off
+          # @param config [Configuration]
+          # @param ratio [Float] how much is finished, from 0 to 1
+          # @param columns [Integer] the bar's width inside the brackets
+          # @return [String]
+          def self.bar(pastel, config, ratio, columns)
+            filled = (ratio * columns).floor
+            "[#{complete(pastel, config) * filled}#{incomplete(pastel, config) * (columns - filled)}]"
+          end
+
+          # @param pastel [Pastel::Delegator]
+          # @param config [Configuration]
+          # @return [String] one finished cell, painted
+          def self.complete(pastel, config)
+            pastel.decorate(config.bar_complete, *[config.bar_color, config.bar_background].compact)
+          end
+
+          # @param pastel [Pastel::Delegator]
+          # @param config [Configuration]
+          # @return [String] one unfinished cell, painted
+          def self.incomplete(pastel, config)
+            pastel.decorate(config.bar_incomplete, *[config.bar_background].compact)
+          end
+
           # @param terminal [Terminal]
           # @param clock [#call] returns monotonic seconds
-          def initialize(terminal, clock:)
+          # @param config [Configuration] where the bar's characters come from
+          def initialize(terminal, clock:, config: UI.config)
             @terminal = terminal
             @clock = clock
+            @config = config
           end
 
           # Runs the block with a progress bar.
@@ -72,6 +102,7 @@ module Dry
             started = clock.call
             bar = start(label, total)
             handle = Handle.new(total, bar)
+            terminal.started(handle, label, progress: handle)
             ok = false
             result = yield handle
             ok = true
@@ -79,6 +110,7 @@ module Dry
           ensure
             if handle
               bar&.stop
+              terminal.finished(handle, ok)
               summary = "#{label} #{handle.current}/#{total}"
               terminal.puts(Outcome.line(terminal, ok ? :done : :failed, summary, clock.call - started))
             end
@@ -92,6 +124,9 @@ module Dry
           # @return [#call]
           attr_reader :clock
 
+          # @return [Configuration]
+          attr_reader :config
+
           # @param label [String]
           # @param total [Integer]
           # @return [TTY::ProgressBar, nil]
@@ -102,12 +137,12 @@ module Dry
             end
 
             TTY::ProgressBar.new(
-              "#{label} :bar :percent  :current/:total  ETA :eta",
+              "#{label} [:bar] :percent  :current/:total  ETA :eta",
               total: total,
               width: [terminal.width - label.length - CHROME, MIN_BAR].max,
               output: terminal.io,
-              complete: "█",
-              incomplete: "░",
+              complete: Progress.complete(terminal.pastel, config),
+              incomplete: Progress.incomplete(terminal.pastel, config),
               clear: true,
               hide_cursor: true
             )