dry-cli-ui 0.3.1 → 0.5.0

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

@@ -16,15 +16,21 @@ module Dry
           class Handle
             # @param total [Integer]
             # @param bar [TTY::ProgressBar, nil]
-            def initialize(total, bar)
+            # @param color [Symbol, nil] see {Progress.color}
+            def initialize(total, bar, color: nil)
               @total = total
               @bar = bar
+              @color = color
               @current = 0
             end
 
             # @return [Integer] the number of units the operation has
             attr_reader :total
 
+            # @return [Symbol, nil] the Pastel style of the bar's finished part;
+            #   nil for {Configuration#bar_color}
+            attr_reader :color
+
             # @return [Integer] the number of units completed so far
             attr_reader :current
 
@@ -46,32 +52,80 @@ 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
 
+          # Checks a bar's own colour.
+          #
+          # @param value [Symbol, nil] any Pastel style, or nil for {Configuration#bar_color}
+          # @return [Symbol, nil] the value
+          # @raise [ArgumentError] for anything else
+          def self.color(value)
+            return value if value.nil? || Configuration::STYLES.include?(value)
+
+            raise ArgumentError, "color must be a Pastel style or nil, got #{value.inspect}"
+          end
+
+          # A bar between brackets, painted as the configuration says: the
+          # finished part in {Configuration#bar_color}, or in the bar's own
+          # colour when it has one, 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
+          # @param color [Symbol, nil] the finished part's style; nil for {Configuration#bar_color}
+          # @return [String]
+          def self.bar(pastel, config, ratio, columns, color: nil)
+            filled = (ratio * columns).floor
+            "[#{complete(pastel, config, color) * filled}#{incomplete(pastel, config) * (columns - filled)}]"
+          end
+
+          # @param pastel [Pastel::Delegator]
+          # @param config [Configuration]
+          # @param color [Symbol, nil] the style; nil for {Configuration#bar_color}
+          # @return [String] one finished cell, painted
+          def self.complete(pastel, config, color = nil)
+            pastel.decorate(config.bar_complete, *[color || 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.
           #
           # @param label [String]
           # @param total [Integer] the number of units of work
+          # @param color [Symbol, nil] the finished part's Pastel style; nil for
+          #   {Configuration#bar_color}
           # @yieldparam progress [Handle]
           # @return [Object] whatever the block returns
-          # @raise [ArgumentError] when total is not a non-negative Integer
-          def run(label, total:)
+          # @raise [ArgumentError] when total is not a non-negative Integer, or
+          #   color is not a Pastel style
+          def run(label, total:, color: nil)
             raise ArgumentError, "total must be a non-negative Integer, got #{total.inspect}" unless total.is_a?(Integer) && total >= 0
 
+            Progress.color(color)
             started = clock.call
-            bar = start(label, total)
-            handle = Handle.new(total, bar)
+            bar = start(label, total, color)
+            handle = Handle.new(total, bar, color: color)
+            terminal.started(handle, label, progress: handle)
             ok = false
             result = yield handle
             ok = true
@@ -79,6 +133,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,22 +147,26 @@ module Dry
           # @return [#call]
           attr_reader :clock
 
+          # @return [Configuration]
+          attr_reader :config
+
           # @param label [String]
           # @param total [Integer]
+          # @param color [Symbol, nil]
           # @return [TTY::ProgressBar, nil]
-          def start(label, total)
+          def start(label, total, color)
             unless terminal.animated? && total.positive?
               terminal.puts("#{label}...")
               return
             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, color),
+              incomplete: Progress.incomplete(terminal.pastel, config),
               clear: true,
               hide_cursor: true
             )

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

@@ -18,9 +18,11 @@ module Dry
         class Spinner
           # @param terminal [Terminal]
           # @param clock [#call] returns monotonic seconds
-          def initialize(terminal, clock:)
+          # @param config [Configuration] where the frames come from
+          def initialize(terminal, clock:, config: UI.config)
             @terminal = terminal
             @clock = clock
+            @config = config
           end
 
           # Runs the block under a spinner.
@@ -33,6 +35,7 @@ module Dry
             spinner = nil
             line = Line.new { |text| spinner&.update(detail: text.empty? ? "" : " #{text}") }
             started = clock.call
+            terminal.started(line, label)
             spinner = start(label)
             ok = false
             result = Line.call(job, line)
@@ -40,6 +43,7 @@ module Dry
             result
           ensure
             spinner&.stop
+            terminal.finished(line, ok)
             terminal.puts(Outcome.line(terminal, ok ? :done : :failed, line.summary(label), clock.call - started))
           end
 
@@ -51,6 +55,9 @@ module Dry
           # @return [#call]
           attr_reader :clock
 
+          # @return [Configuration]
+          attr_reader :config
+
           # @param label [String]
           # @return [TTY::Spinner, nil] the running spinner, or nil when not animating
           def start(label)
@@ -59,8 +66,9 @@ module Dry
               return
             end
 
-            TTY::Spinner.new(":spinner #{label}:detail", output: terminal.io, format: :dots, hide_cursor: true,
-                                                         clear: true)
+            TTY::Spinner.new(":spinner #{label}:detail", output: terminal.io, frames: config.spinner_frames,
+                                                         interval: 1.0 / config.spinner_frame_seconds,
+                                                         hide_cursor: true, clear: true)
                         .tap { |spinner| spinner.update(detail: "") }
                         .tap(&:auto_spin)
           end

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

@@ -37,23 +37,12 @@ module Dry
         #     end
         #   end
         class Tasks
-          # Frames a running task cycles through on an animated terminal.
-          FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
-
-          # Seconds between spinner frames.
-          INTERVAL = 0.1
-
-          # Checks a `concurrent:` setting.
+          # Checks a `concurrent:` setting. See {Pool.concurrency}.
           #
-          # @param value [Boolean, Integer] true for all at once, false for one
-          #   at a time, or the most that may run at once
+          # @param value [Boolean, Integer]
           # @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
+          def self.concurrency(value) = Pool.concurrency(value)
 
           # One task, or a group of them.
           class Node
@@ -152,9 +141,11 @@ module Dry
 
           # @param terminal [Terminal]
           # @param clock [#call] returns monotonic seconds
-          def initialize(terminal, clock:)
+          # @param config [Configuration] where the spinner frames come from
+          def initialize(terminal, clock:, config: UI.config)
             @terminal = terminal
             @clock = clock
+            @config = config
             @roots = []
             @live = nil
             @lock = Mutex.new
@@ -192,6 +183,9 @@ module Dry
           # @return [#call]
           attr_reader :clock
 
+          # @return [Configuration]
+          attr_reader :config
+
           # @return [Array<Node>]
           attr_reader :roots
 
@@ -205,57 +199,20 @@ module Dry
           # @param concurrent [Boolean, Integer]
           # @return [void]
           def run_all(nodes, concurrent)
-            return nodes.each { |node| execute(node) } unless concurrent
-
-            futures = concurrent == true ? all_at_once(nodes) : at_most(concurrent, nodes)
-            futures.each(&:wait)
-            failed = futures.find(&:rejected?)
-            raise failed.reason if failed
-          end
-
-          # @param nodes [Array<Node>]
-          # @return [Array<Concurrent::Promises::Future>] one per node
-          def all_at_once(nodes)
-            nodes.map { |node| Concurrent::Promises.future(node) { |each| execute(each) } }
-          end
-
-          # Workers that take nodes off a queue until it is empty, or until
-          # one of them raises. A node no worker took stays pending, and is
-          # marked skipped once the tree ends.
-          #
-          # @param limit [Integer]
-          # @param nodes [Array<Node>]
-          # @return [Array<Concurrent::Promises::Future>] one per worker
-          def at_most(limit, nodes)
-            queue = Queue.new
-            nodes.each { |node| queue << node }
-            queue.close
-            stop = Concurrent::AtomicBoolean.new
-            Array.new([limit, nodes.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 work(queue, stop)
-            ok = false
-            while (node = queue.pop) && stop.false?
-              execute(node)
-            end
-            ok = true
-          ensure
-            stop.make_true unless ok
+            Pool.run(nodes, concurrent) { |node| execute(node) }
           end
 
           # @param node [Node]
           # @return [void]
           def execute(node)
             started = clock.call
+            terminal.started(node, node.name) unless node.group?
             change(node, :running)
             ok = false
             node.group? ? run_all(node.children, node.concurrent) : Line.call(node.job, node.line)
             ok = !node.failed?
           ensure
+            terminal.finished(node, ok) unless node.group?
             change(node, ok ? :done : :failed, seconds: clock.call - started)
           end
 
@@ -308,7 +265,7 @@ module Dry
             return unless live?
 
             rows.each_key { |node| terminal.puts(line(node)) }
-            Concurrent::TimerTask.new(execution_interval: INTERVAL) { tick }.tap(&:execute)
+            Concurrent::TimerTask.new(execution_interval: config.spinner_frame_seconds) { tick }.tap(&:execute)
           end
 
           # @return [void]
@@ -321,18 +278,17 @@ module Dry
 
           # @return [void]
           def redraw
-            terminal.print(terminal.cursor.up(rows.size))
-            rows.each_key { |node| terminal.print("#{terminal.cursor.clear_line}#{line(node)}\n") }
+            terminal.print(terminal.cursor.up(rows.size) + rows.each_key.map { |node| "#{terminal.cursor.clear_line}#{line(node)}\n" }.join)
           end
 
           # @param node [Node]
           # @return [String]
           def line(node)
             pastel = terminal.pastel
-            glyph, color = Theme::STATES.fetch(node.state)
-            glyph = FRAMES[frame % FRAMES.size] if node.state == :running && live?
+            frames = config.spinner_frames
+            glyph = frames[frame % frames.size] if node.state == :running && live?
             elapsed = " #{pastel.bright_black("(#{Duration.format(node.seconds)})")}" if node.seconds
-            "#{pastel.bright_black(rows.fetch(node))}#{pastel.decorate(glyph, color)} #{text(node)}#{elapsed}"
+            "#{pastel.bright_black(rows.fetch(node))}#{Theme.marker(pastel, node.state, glyph)} #{text(node)}#{elapsed}"
           end
 
           # What follows the glyph: the name, then the detail while the task

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

@@ -8,6 +8,10 @@ module Dry
       # namespace touches a TTY toolkit class.
       module Widgets
         autoload :Box, File.expand_path("widgets/box", __dir__)
+        autoload :Multi, File.expand_path("widgets/multi", __dir__)
+        autoload :MultiProgress, File.expand_path("widgets/multi_progress", __dir__)
+        autoload :MultiSpinner, File.expand_path("widgets/multi_spinner", __dir__)
+        autoload :Pool, File.expand_path("widgets/pool", __dir__)
         autoload :Outcome, File.expand_path("widgets/outcome", __dir__)
         autoload :Progress, File.expand_path("widgets/progress", __dir__)
         autoload :Prompt, File.expand_path("widgets/prompt", __dir__)

data/lib/dry/cli/ui.rb

@@ -31,13 +31,45 @@ module Dry
       # input stream is exhausted.
       class NonInteractiveError < Error; end
 
+      autoload :Configuration, File.expand_path("ui/configuration", __dir__)
       autoload :Console, File.expand_path("ui/console", __dir__)
       autoload :Duration, File.expand_path("ui/duration", __dir__)
       autoload :Line, File.expand_path("ui/line", __dir__)
+      autoload :StatusBar, File.expand_path("ui/status_bar", __dir__)
       autoload :Terminal, File.expand_path("ui/terminal", __dir__)
       autoload :Theme, File.expand_path("ui/theme", __dir__)
       autoload :Widgets, File.expand_path("ui/widgets", __dir__)
 
+      class << self
+        # Make process-wide settings. A block taking an argument receives the
+        # configuration; any other block runs against it.
+        #
+        # @example
+        #   Dry::CLI::UI.configure do
+        #     spinner_format :dots
+        #     bar_format :box
+        #     bar_color :cyan
+        #   end
+        #
+        # @return [Configuration]
+        def configure(&block)
+          block.arity == 1 ? yield(config) : config.instance_eval(&block)
+          config
+        end
+
+        # @return [Configuration] the process-wide settings
+        def config
+          @config ||= Configuration.new
+        end
+
+        # Forget every process-wide setting.
+        #
+        # @return [void]
+        def reset!
+          @config = nil
+        end
+      end
+
       # The console this command presents through. Writes to the command's own
       # `out` and `err` when dry-cli has set them, and to `$stdout` and
       # `$stderr` otherwise.

data/sig/dry/cli/ui.rbs

@@ -11,6 +11,28 @@ module Dry
 
       def ui: () -> Console
 
+      def self.configure: () { (Configuration config) -> void } -> Configuration
+      def self.config: () -> Configuration
+      def self.reset!: () -> void
+
+      class Configuration
+        type spinner_definition = Symbol | { interval: Numeric, frames: Array[String] | String }
+        type bar_definition = Symbol | { complete: String, incomplete: String }
+
+        def spinner_format: (?spinner_definition value) -> spinner_definition
+        def spinner_format=: (spinner_definition value) -> spinner_definition
+        def bar_format: (?bar_definition value) -> bar_definition
+        def bar_format=: (bar_definition value) -> bar_definition
+        def bar_color: (?Symbol? value) -> Symbol?
+        def bar_color=: (Symbol? value) -> Symbol?
+        def bar_background: (?Symbol? value) -> Symbol?
+        def bar_background=: (Symbol? value) -> Symbol?
+        def spinner_frames: () -> Array[String]
+        def spinner_frame_seconds: () -> Float
+        def bar_complete: () -> String
+        def bar_incomplete: () -> String
+      end
+
       class Line
         def self.call: [T] (^(Line) -> T job, Line line) -> T
         def initialize: () ?{ (String detail) -> void } -> void
@@ -33,7 +55,10 @@ module Dry
         def status: (*_ToS words, ?level: Symbol) -> nil
         def popup: (*_ToS paragraphs, ?title: String?, ?width: Integer?) -> nil
         def spinner: [T] (String label) { (Line line) -> T } -> T
-        def progress: [T] (String label, total: Integer) { (untyped progress) -> T } -> T
+        def multi_spinner: (String title, ?concurrent: (bool | Integer)) { (untyped spinners) -> void } -> Array[untyped]
+        def progress: [T] (String label, total: Integer, ?color: Symbol?) { (untyped progress) -> T } -> T
+        def multi_progress: (String title, ?concurrent: (bool | Integer)) { (untyped bars) -> void } -> Array[untyped]
+        def status_bar: [T] (?String? title, ?hints: Array[String] | String) { () -> T } -> T
         def tasks: (?String? title, ?concurrent: (bool | Integer)) { (untyped tasks) -> void } -> nil
         def table: (Array[Array[_ToS]] rows, ?header: Array[_ToS]?) -> nil
         def prompt: (String question, ?default: untyped, ?choices: (Array[String] | Hash[String, untyped])?) -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-ui
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -176,22 +176,29 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- SPECIFICATION.md
+- examples/.envrc
+- examples/.gitignore
 - examples/Gemfile
 - examples/Gemfile.lock
 - examples/README.md
 - examples/bin/mycli
 - lib/dry-cli-ui.rb
 - lib/dry/cli/ui.rb
+- lib/dry/cli/ui/configuration.rb
 - lib/dry/cli/ui/console.rb
 - lib/dry/cli/ui/duration.rb
 - lib/dry/cli/ui/line.rb
+- lib/dry/cli/ui/status_bar.rb
 - lib/dry/cli/ui/terminal.rb
 - lib/dry/cli/ui/theme.rb
 - lib/dry/cli/ui/version.rb
 - lib/dry/cli/ui/widgets.rb
 - lib/dry/cli/ui/widgets/box.rb
+- lib/dry/cli/ui/widgets/multi.rb
+- lib/dry/cli/ui/widgets/multi_progress.rb
+- lib/dry/cli/ui/widgets/multi_spinner.rb
 - lib/dry/cli/ui/widgets/outcome.rb
+- lib/dry/cli/ui/widgets/pool.rb
 - lib/dry/cli/ui/widgets/progress.rb
 - lib/dry/cli/ui/widgets/prompt.rb
 - lib/dry/cli/ui/widgets/spinner.rb