dry-cli-ui 0.3.1 → 0.4.0

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

@@ -64,13 +64,15 @@ module Dry
         # @param width [Integer, nil] force the terminal width; nil asks the terminal
         # @param box_width [Integer, nil] box width in columns; nil fills the terminal
         # @param clock [#call] returns monotonic seconds
+        # @param config [Configuration] spinner and bar formats; {UI.config} by default
         def initialize(out: $stdout, err: $stderr, input: $stdin, env: ENV, color: nil, animate: nil,
-                       width: nil, box_width: nil, clock: Duration::CLOCK)
+                       width: nil, box_width: nil, clock: Duration::CLOCK, config: UI.config)
           @out = Terminal.new(out, env: env, color: color, animate: animate, width: width)
           @err = Terminal.new(err, env: env, color: color, animate: animate, width: width)
           @input = input
           @box_width = box_width
           @clock = clock
+          @config = config
         end
 
         # A framed panel. Given a level, it takes that level's title, colour
@@ -142,7 +144,27 @@ module Dry
         def spinner(label, &)
           raise ArgumentError, "spinner needs a block" unless block_given?
 
-          Widgets::Spinner.new(err, clock: clock).run(label, &)
+          Widgets::Spinner.new(err, clock: clock, config: config).run(label, &)
+        end
+
+        # Runs several jobs at once, each under a spinner of its own, beneath a
+        # headline spinner. Each job is given a {Line}. See {Widgets::MultiSpinner}.
+        #
+        # @example
+        #   ui.multi_spinner("Fetching", concurrent: 3) do |m|
+        #     assets.each { |asset| m.spinner(asset.name) { fetch(asset) } }
+        #   end
+        #
+        # @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
+        # @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, &)
+          raise ArgumentError, "multi_spinner needs a block" unless block_given?
+
+          Widgets::MultiSpinner.new(err, clock: clock, config: config).run(title, concurrent: concurrent, &)
         end
 
         # Runs a block with a progress bar showing percent, count and ETA.
@@ -155,7 +177,30 @@ module Dry
         def progress(label, total:, &)
           raise ArgumentError, "progress needs a block" unless block_given?
 
-          Widgets::Progress.new(err, clock: clock).run(label, total: total, &)
+          Widgets::Progress.new(err, clock: clock, config: config).run(label, total: total, &)
+        end
+
+        # Runs several jobs at once, each with a progress bar of its own,
+        # beneath a headline bar that counts them all. Each job is given a
+        # {Widgets::Progress::Handle}. See {Widgets::MultiProgress}.
+        #
+        # @example
+        #   ui.multi_progress("Downloading") do |m|
+        #     files.each do |file|
+        #       m.progress(file.name, total: file.size) { |bar| download(file) { |n| bar.advance(n) } }
+        #     end
+        #   end
+        #
+        # @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
+        # @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, "multi_progress needs a block" unless block_given?
+
+          Widgets::MultiProgress.new(err, clock: clock, config: config).run(title, concurrent: concurrent, &)
         end
 
         # Declares a tree of tasks, then runs it, showing each task's state
@@ -181,7 +226,31 @@ module Dry
         def tasks(title = nil, concurrent: false, &)
           raise ArgumentError, "tasks needs a block" unless block_given?
 
-          Widgets::Tasks.new(err, clock: clock).run(title, concurrent: concurrent, &)
+          Widgets::Tasks.new(err, clock: clock, config: config).run(title, concurrent: concurrent, &)
+        end
+
+        # Keeps a status line at the bottom of the screen while the block runs,
+        # saying how the command is doing overall. Every spinner, progress
+        # bar, multi widget and task tree started inside the block reports to
+        # it. Without an animated `err` it does nothing but run the block, and
+        # inside another status bar it does the same. See {StatusBar}.
+        #
+        # @example
+        #   ui.status_bar("deploy", hints: ["^C cancel"]) do
+        #     ui.multi_progress("Uploading") { |m| ... }
+        #     ui.tasks("Migrate") { |t| ... }
+        #   end
+        #
+        # @param title [String, nil] shown first, in bold
+        # @param hints [Array<String>] shown at the right edge
+        # @return [Object] whatever the block returns
+        # @raise [ArgumentError] without a block
+        def status_bar(title = nil, hints: [], &)
+          raise ArgumentError, "status_bar needs a block" unless block_given?
+          return yield if !err.animated? || err.reporter
+
+          others = out.animated? ? [out] : []
+          StatusBar.new(err, others: others, title: title, hints: Array(hints), clock: clock, config: config).run(&)
         end
 
         # Prints a table to `out`.
@@ -237,6 +306,9 @@ module Dry
         # @return [#call]
         attr_reader :clock
 
+        # @return [Configuration]
+        attr_reader :config
+
         # @param theme [Theme::Level]
         # @return [Terminal]
         def stream(theme)

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

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require "monitor"
+require "strings"
+
+module Dry
+  class CLI
+    module UI
+      # A line kept at the bottom of the screen while a block runs, under a
+      # rule, saying how the command is doing overall:
+      #
+      #   ⠋ deploy · Migrating users · 2 running · 5 done · 1 failed · [◼◼◼◼      ] 42% · 12.3s   ^C cancel
+      #
+      # Every spinner, progress bar, multi widget and task tree started inside
+      # the block reports to it, so a command only supplies the title and the
+      # hints. Everything else the console writes prints above it, and the
+      # scrollback stays intact: no scroll region is set.
+      #
+      # It works by standing between the console's terminals and their
+      # streams. Each write first clears the two rows below the cursor, then
+      # writes, then draws them again, and puts the cursor back where the
+      # write left it. Writes that bypass the console, such as a bare `puts`,
+      # land where the bar is and are drawn over by the next write.
+      class StatusBar
+        # Rows the bar takes: a rule, then the status line.
+        ROWS = 2
+
+        # Columns of the overall progress bar.
+        BAR = 10
+
+        # Clears from the cursor to the end of the screen.
+        CLEAR_BELOW = "\e[J"
+
+        # The last column a stream's cursor is in, followed through what is
+        # written to it, so the cursor can be put back after the bar is drawn.
+        class Column
+          # One control sequence, a line break, or a run of text.
+          TOKEN = /\e\[[\d;?]*[A-Za-z]|\e[78]|\r|\n|[^\e\r\n]+|\e/
+
+          def initialize
+            @column = 0
+            @saved = 0
+          end
+
+          # @return [Integer] zero-based
+          attr_reader :column
+
+          # @param text [String] what was just written
+          # @return [Integer] the column after it
+          def follow(text)
+            text.scan(TOKEN) { |token| step(token) }
+            column
+          end
+
+          private
+
+          # @param token [String]
+          # @return [void]
+          def step(token)
+            case token
+            when "\n", "\r" then @column = 0
+            when "\e7", "\e[s" then @saved = @column
+            when "\e8", "\e[u" then @column = @saved
+            when /\A\e\[(\d*)([GCD])\z/ then move(Regexp.last_match(1), Regexp.last_match(2))
+            when /\A\e/ then nil
+            else @column += Strings::ANSI.sanitize(token).then { |plain| Unicode::DisplayWidth.of(plain) }
+            end
+          end
+
+          # @param count [String] the sequence's number, empty for its default
+          # @param kind [String] G, C or D
+          # @return [void]
+          def move(count, kind)
+            n = count.empty? ? 1 : count.to_i
+            @column = case kind
+                      when "G" then n - 1
+                      when "C" then @column + n
+                      else [@column - n, 0].max
+                      end
+          end
+        end
+
+        # Stands in for a terminal's stream while the bar runs.
+        class Output
+          # @param io [IO] the real stream
+          # @param bar [StatusBar]
+          def initialize(io, bar)
+            @io = io
+            @bar = bar
+          end
+
+          # @param text [#to_s]
+          # @return [Integer] bytes written
+          def write(*text)
+            text = text.join
+            @bar.around_write(@io, text)
+            text.bytesize
+          end
+
+          # @param text [Array<#to_s>]
+          # @return [nil]
+          def print(*text)
+            write(*text)
+            nil
+          end
+
+          # @param text [#to_s]
+          # @return [self]
+          def <<(text)
+            write(text)
+            self
+          end
+
+          # @return [Boolean] always true: a bar is only drawn on a terminal
+          def tty? = true
+
+          # @return [void]
+          def flush
+            @io.flush if @io.respond_to?(:flush)
+          end
+
+          # @return [Boolean]
+          def respond_to_missing?(name, include_private = false) = @io.respond_to?(name, include_private) || super
+
+          # Anything else the stream answers, such as `winsize`.
+          def method_missing(name, ...)
+            @io.respond_to?(name) ? @io.public_send(name, ...) : super
+          end
+        end
+
+        # @param terminal [Terminal] where the bar is drawn
+        # @param others [Array<Terminal>] other terminals on the same screen,
+        #   whose writes must also go above the bar
+        # @param title [String, nil]
+        # @param hints [Array<String>] shown at the right, such as "^C cancel"
+        # @param clock [#call] returns monotonic seconds
+        # @param config [Configuration] where the spinner frames and bar characters come from
+        def initialize(terminal, others: [], title: nil, hints: [], clock: Duration::CLOCK, config: UI.config)
+          @terminal = terminal
+          @terminals = [terminal, *others]
+          @title = title
+          @hints = hints
+          @clock = clock
+          @config = config
+          @monitor = Monitor.new
+          @column = Column.new
+          @running = {}
+          @finished = []
+          @done = 0
+          @failed = 0
+          @frame = 0
+        end
+
+        # Draws the bar, runs the block, and takes the bar away again.
+        #
+        # @return [Object] whatever the block returns
+        def run
+          @started = clock.call
+          ticker = Concurrent::TimerTask.new(execution_interval: config.spinner_frame_seconds) { tick }
+          streams = @terminals.to_h { |terminal| [terminal, terminal.io] }
+          streams.each { |terminal, io| terminal.redirect(Output.new(io, self), reporter: self, reserved: ROWS) }
+          begin
+            terminal.print("")
+            ticker.execute
+            yield
+          ensure
+            ticker.shutdown
+            ticker.wait_for_termination(1)
+            streams.each { |terminal, io| terminal.redirect(io) }
+            synchronize { terminal.io.print(CLEAR_BELOW) }
+          end
+        end
+
+        # Records that work has started. Widgets report through {Terminal#started}.
+        #
+        # @param key [Object] identifies the work until it finishes
+        # @param label [String]
+        # @param progress [#current, #total, nil] read whenever the bar is drawn
+        # @return [void]
+        def started(key, label, progress: nil)
+          synchronize { @running[key] = [label, progress] }
+        end
+
+        # Records that work has ended. Widgets report through {Terminal#finished}.
+        #
+        # @param key [Object] as given to {#started}
+        # @param succeeded [Boolean]
+        # @return [void]
+        def finished(key, succeeded)
+          synchronize do
+            _, progress = @running.delete(key)
+            @finished << progress if progress
+            succeeded ? @done += 1 : @failed += 1
+          end
+        end
+
+        # Writes text to a stream above the bar. For {Output}.
+        #
+        # @param io [IO]
+        # @param text [String]
+        # @return [void]
+        def around_write(io, text)
+          synchronize do
+            @column.follow(text)
+            io.print("#{CLEAR_BELOW}#{text}#{footer}")
+          end
+        end
+
+        # The status line, as wide as the terminal at most.
+        #
+        # @return [String]
+        def line
+          synchronize do
+            pastel = terminal.pastel
+            fields = [title && pastel.bold(title), current, *counts, meter, Duration.format(clock.call - @started)]
+            fit(" #{glyph} #{fields.compact.join(pastel.bright_black(' · '))}", pastel.bright_black(hints.join("  ")))
+          end
+        end
+
+        private
+
+        # @return [Terminal]
+        attr_reader :terminal
+
+        # @return [String, nil]
+        attr_reader :title
+
+        # @return [Array<String>]
+        attr_reader :hints
+
+        # @return [#call]
+        attr_reader :clock
+
+        # @return [Configuration]
+        attr_reader :config
+
+        # @return [void]
+        def synchronize(&) = @monitor.synchronize(&)
+
+        # @return [void]
+        def tick
+          synchronize do
+            @frame += 1
+            terminal.io.print("")
+          end
+        end
+
+        # The rule and the status line below the cursor, and the sequence that
+        # puts the cursor back. From the start of a row, the bar starts on that
+        # row; from anywhere else, on the next.
+        #
+        # @return [String]
+        def footer
+          rule = terminal.pastel.bright_black("─" * terminal.width)
+          rows = "\e[2K#{rule}\n\e[2K#{line}"
+          col = @column.column
+          return "#{rows}\e[#{ROWS - 1}A\r" if col.zero?
+
+          "\n#{rows}\e[#{ROWS}A\e[#{col + 1}G"
+        end
+
+        # @return [String] a turning spinner while anything runs, a dot otherwise
+        def glyph
+          return terminal.pastel.bright_black("·") if @running.empty?
+
+          frames = config.spinner_frames
+          terminal.pastel.cyan(frames[@frame % frames.size])
+        end
+
+        # @return [String, nil] the label of the work started most recently
+        def current = @running.values.last&.first
+
+        # @return [Array<String>]
+        def counts
+          pastel = terminal.pastel
+          [
+            (pastel.cyan("#{@running.size} running") if @running.any?),
+            (pastel.green("#{@done} done") if @done.positive?),
+            (pastel.red("#{@failed} failed") if @failed.positive?)
+          ].compact
+        end
+
+        # @return [String, nil] a bar over every progress reported so far
+        def meter
+          progress = @finished + @running.values.filter_map(&:last)
+          total = progress.sum(&:total)
+          return if total.zero?
+
+          ratio = progress.sum(&:current).fdiv(total)
+          "#{Widgets::Progress.bar(terminal.pastel, config, ratio, BAR)} #{(ratio * 100).floor}%"
+        end
+
+        # The left part, with the hints right-aligned after it when they fit,
+        # truncated to the terminal's width.
+        #
+        # @param left [String]
+        # @param right [String]
+        # @return [String]
+        def fit(left, right)
+          width = terminal.width
+          gap = width - display(left) - display(right) - 1
+          return "#{left}#{' ' * gap}#{right}" if gap >= 2 && !hints.empty?
+
+          Strings::Truncate.truncate(left, width - 1)
+        end
+
+        # @param text [String]
+        # @return [Integer] columns, not counting escape codes
+        def display(text) = Unicode::DisplayWidth.of(Strings::ANSI.sanitize(text))
+      end
+    end
+  end
+end

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

@@ -37,6 +37,42 @@ module Dry
         # @return [IO] the stream this terminal writes to
         attr_reader :io
 
+        # @return [StatusBar, nil] what widgets report their work to, while a status bar runs
+        attr_reader :reporter
+
+        # Sends what this terminal writes, and what its widgets report, to a
+        # {StatusBar}, and keeps rows free for it at the bottom of the screen.
+        # Called again with the original stream to undo it.
+        #
+        # @param io [IO]
+        # @param reporter [StatusBar, nil]
+        # @param reserved [Integer] rows at the bottom widgets must not use
+        # @return [void]
+        def redirect(io, reporter: nil, reserved: 0)
+          @io = io
+          @reporter = reporter
+          @reserved = reserved
+        end
+
+        # Reports that a widget started some work.
+        #
+        # @param key [Object] identifies the work until it finishes
+        # @param label [String]
+        # @param progress [#current, #total, nil]
+        # @return [void]
+        def started(key, label, progress: nil)
+          reporter&.started(key, label, progress: progress)
+        end
+
+        # Reports that a widget's work ended.
+        #
+        # @param key [Object] as given to {#started}
+        # @param succeeded [Boolean]
+        # @return [void]
+        def finished(key, succeeded)
+          reporter&.finished(key, succeeded)
+        end
+
         # Whether the stream is an interactive terminal.
         #
         # @return [Boolean]
@@ -67,9 +103,9 @@ module Dry
           @width || (tty? ? TTY::Screen.width : DEFAULT_WIDTH)
         end
 
-        # @return [Integer] rows available
+        # @return [Integer] rows available, less any a status bar keeps
         def height
-          tty? ? TTY::Screen.height : DEFAULT_HEIGHT
+          (tty? ? TTY::Screen.height : DEFAULT_HEIGHT) - @reserved.to_i
         end
 
         # @return [Pastel::Delegator] a colouriser that is a no-op when colour is off

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

@@ -30,15 +30,30 @@ module Dry
           fatal: Level.new(name: :fatal, title: "Fatal", glyph: "✖", color: :magenta, stream: :err)
         }.freeze
 
-        # Glyphs for the states an operation passes through.
+        # Glyphs and colours for the states an operation passes through: bold
+        # yellow until it ends, then a green check, a red cross, or a yellow
+        # dash for work that was skipped.
         STATES = {
-          pending: ["○", :bright_black],
-          running: ["▸", :cyan],
-          done: ["✓", :green],
-          failed: ["✗", :red],
-          skipped: ["–", :bright_black]
+          pending: [" ", %i[bold yellow]],
+          running: ["▸", %i[bold yellow]],
+          done: ["✓", %i[green]],
+          failed: ["𝘅", %i[red]],
+          skipped: ["—", %i[yellow]]
         }.freeze
 
+        # A state's glyph between brackets, the glyph in the state's colour:
+        # `[✓]`, `[✗]`, or `[ ]` while pending. Task trees and the multi
+        # widgets mark every row with one.
+        #
+        # @param pastel [Pastel::Delegator]
+        # @param state [Symbol] one of the keys of {STATES}
+        # @param glyph [String, nil] drawn instead of the state's own, such as a spinner frame
+        # @return [String]
+        def self.marker(pastel, state, glyph = nil)
+          default, color = STATES.fetch(state)
+          "[#{pastel.decorate(glyph || default, *color)}]"
+        end
+
         # Looks up a level by name.
         #
         # @param name [Symbol] one of {LEVELS}' keys

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.3.1"
+      VERSION = "0.4.0"
     end
   end
 end