dry-cli-ui 0.3.1 → 0.5.0

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "pastel"
+require "tty/spinner/formats"
+require "tty/progressbar/formats"
+
+module Dry
+  class CLI
+    module UI
+      # Process-wide settings, made once through {UI.configure}:
+      #
+      #   Dry::CLI::UI.configure do
+      #     spinner_format :dots                          # any TTY::Spinner format name
+      #     bar_format :box                               # any TTY::ProgressBar bar format name
+      #     bar_color :cyan                               # any Pastel style, or nil
+      #     bar_background nil                            # any Pastel style, or nil
+      #   end
+      #
+      #   Dry::CLI::UI.configure do |config|
+      #     config.spinner_format = { interval: 8, frames: %w[◐ ◓ ◑ ◒] }
+      #     config.bar_format = { complete: "#", incomplete: "." }
+      #   end
+      #
+      # Anything not set reads from {DEFAULTS}.
+      class Configuration
+        # What a setting reads before it is set: a green `◼` for each finished
+        # part of a bar, with no background behind it.
+        DEFAULTS = {
+          spinner_format: :dots,
+          bar_format: { complete: "◼", incomplete: " " }.freeze,
+          bar_color: :green,
+          bar_background: nil
+        }.freeze
+
+        # Every style name Pastel knows, for checking colour settings.
+        STYLES = Pastel.new(enabled: true).styles.keys.freeze
+
+        # Marks a DSL call made without a value, which reads instead of writes.
+        UNSET = Object.new.freeze
+        private_constant :UNSET
+
+        def initialize
+          @values = {}
+        end
+
+        # @!method spinner_format(value = UNSET)
+        #   Reads the spinner format, or sets it when given a value.
+        #   @param value [Symbol, Hash] a key of `TTY::Formats::FORMATS`, or
+        #     `{ interval:, frames: }`: frames per second, and the frames
+        #   @return [Symbol, Hash]
+        # @!method bar_format(value = UNSET)
+        #   Reads the bar format, or sets it when given a value.
+        #   @param value [Symbol, Hash] a key of `TTY::ProgressBar::Formats::FORMATS`,
+        #     or `{ complete:, incomplete: }`
+        #   @return [Symbol, Hash]
+        # @!method bar_color(value = UNSET)
+        #   Reads the colour a bar's finished part is drawn in, or sets it.
+        #   @param value [Symbol, nil] a Pastel style, such as :green; nil for none
+        #   @return [Symbol, nil]
+        # @!method bar_background(value = UNSET)
+        #   Reads the background the whole bar is drawn on, or sets it.
+        #   @param value [Symbol, nil] a Pastel style, such as :on_blue; nil for none
+        #   @return [Symbol, nil]
+        DEFAULTS.each_key do |name|
+          define_method(name) do |value = UNSET|
+            return @values.fetch(name) { DEFAULTS.fetch(name) } if UNSET.equal?(value)
+
+            public_send(:"#{name}=", value)
+          end
+        end
+
+        # @param value [Symbol, Hash] see {#spinner_format}
+        # @raise [ArgumentError] for an unknown name or a malformed Hash
+        def spinner_format=(value)
+          @values[:spinner_format] = spinner_definition(value) && value
+        end
+
+        # @param value [Symbol, Hash] see {#bar_format}
+        # @raise [ArgumentError] for an unknown name or a malformed Hash
+        def bar_format=(value)
+          @values[:bar_format] = bar_definition(value) && value
+        end
+
+        # @param value [Symbol, nil] see {#bar_color}
+        # @raise [ArgumentError] for a style Pastel does not know
+        def bar_color=(value)
+          @values[:bar_color] = style(:bar_color, value)
+        end
+
+        # @param value [Symbol, nil] see {#bar_background}
+        # @raise [ArgumentError] for a style Pastel does not know
+        def bar_background=(value)
+          @values[:bar_background] = style(:bar_background, value)
+        end
+
+        # @return [Array<String>] the frames a spinner cycles through
+        def spinner_frames
+          frames = spinner_definition(spinner_format).fetch(:frames)
+          frames.is_a?(String) ? frames.chars : frames
+        end
+
+        # @return [Float] seconds between two spinner frames
+        def spinner_frame_seconds
+          1.0 / spinner_definition(spinner_format).fetch(:interval)
+        end
+
+        # @return [String] what a finished part of a bar is drawn with
+        def bar_complete
+          bar_definition(bar_format).fetch(:complete)
+        end
+
+        # @return [String] what an unfinished part of a bar is drawn with
+        def bar_incomplete
+          bar_definition(bar_format).fetch(:incomplete)
+        end
+
+        private
+
+        # @param value [Symbol, Hash]
+        # @return [Hash{Symbol => Object}] with :interval and :frames
+        def spinner_definition(value)
+          return TTY::Formats::FORMATS.fetch(value) { unknown(:spinner_format, value) } if value.is_a?(Symbol)
+
+          valid = value.is_a?(Hash) && value[:interval].is_a?(Numeric) && value[:interval].positive? &&
+                  (value[:frames].is_a?(String) || value[:frames].is_a?(Array)) && !value[:frames].empty?
+          valid ? value : malformed(:spinner_format, value, "{ interval: Numeric, frames: Array }")
+        end
+
+        # @param value [Symbol, Hash]
+        # @return [Hash{Symbol => String}] with :complete and :incomplete
+        def bar_definition(value)
+          return TTY::ProgressBar::Formats::FORMATS.fetch(value) { unknown(:bar_format, value) } if value.is_a?(Symbol)
+
+          valid = value.is_a?(Hash) && value[:complete].is_a?(String) && value[:incomplete].is_a?(String)
+          valid ? value : malformed(:bar_format, value, "{ complete: String, incomplete: String }")
+        end
+
+        # @param setting [Symbol]
+        # @param value [Symbol, nil]
+        # @return [Symbol, nil] the value
+        # @raise [ArgumentError] for anything but nil or a style Pastel knows
+        def style(setting, value)
+          return value if value.nil? || STYLES.include?(value)
+
+          raise ArgumentError, "#{setting} must be a Pastel style or nil, got #{value.inspect}"
+        end
+
+        # @raise [ArgumentError]
+        def unknown(setting, value)
+          raise ArgumentError, "#{setting} #{value.inspect} is not a known format"
+        end
+
+        # @raise [ArgumentError]
+        def malformed(setting, value, shape)
+          raise ArgumentError, "#{setting} must be a format name or #{shape}, got #{value.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -64,16 +64,18 @@ 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
+        # 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`.
         #
@@ -89,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
 
@@ -142,20 +144,66 @@ 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.
         #
         # @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).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,
+        # 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 +229,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 +309,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