dry-cli-ui 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d1ad3344ddfd395caef9b2ec0128f05cda8248a98afa864b1b61ed1d1db0b5e
-  data.tar.gz: d55f3256373ec25c1201dd0c39525eeb49b50f16989806740f720ed3e59f0f13
+  metadata.gz: d64ee9f8fedbc7de0fcd1875acf59d07876ef6acaffbfcc8574b197de0e8d6fd
+  data.tar.gz: 2f7e11eca1a0dff40b3df7cba685bca7f97d4884515db1107805036e746e20bc
 SHA512:
-  metadata.gz: fe5bb8356f594b5a8670ee7c8b9a5cdc0ec87e2480bea892f0e98389a8d43218fd2de162f77de9444990e3d197e7679352995f1da3eb234094df68a5ea5c2d25
-  data.tar.gz: b982df4a36156203f92f39b3b3c8da0e9b5fe8672092333c09d7dd70e48759f0470fc82060dea4a16bdbc9daca3e219361ca0c7f95f114961b740b20354e2105
+  metadata.gz: d9105f75325a1a7f8282e989d4c847320fb481880a7a529041d98d4bff9457dc5235d08a5c3b311c0b3d442a6dc4c3923b6c72844bd2fbb55ec04f2824b906e3
+  data.tar.gz: d095b784083ba57db9592e51ef2d56274dd9cb187fcac350d35aaea51b8e64c519a800e3f7f899b2b248acfe8035733c4fa63930b64086cdbebea17c8af4636b

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.6.1]
+
+- A progress handle takes `fail(reason = nil)`, as a `Line` does: the bar ends `𝘅 label 3/3: reason` without raising, in `ui.progress` and in a row of `ui.multi_progress`, where the jobs after it still run and the headline ends `𝘅`. For work that carries on after some of its units failed.
+
+## [0.6.0]
+
+- `m.spinner(label)` inside `ui.multi_progress` declares a row with a spinner in place of a bar, for a phase whose size is never known, so one widget can show phases of known and unknown size together. The row shows its `Line`'s detail while it runs and ends `[✓] label`; it counts as a job and as no units on the headline.
+
+## [0.6.0]
+
+- `ui` reads the command's public `stdout`, `stderr` and `stdin`, the streams dry-cli was called with. Before, it looked for `out` and `err`, which dry-cli no longer has, and wrote to `$stdout` and `$stderr` instead. Prompts now read from the command's `stdin`.
+- `ui` builds its console again when those streams change, so a command registered as an instance, or run in-process by `Dry::CLI::Launcher`, writes each call to that call's streams.
+- `ui_options` configures the console `ui` builds, in place of overriding `ui`.
+- Needs dry-cli with public command streams and `Dry::CLI::Launcher`; the Gemfile takes it from kigster/dry-cli until it is released.
+
 ## [0.5.1]
 
 - `ui.stoppable { |stop| ... }` makes Ctrl-C ask for a stop instead of interrupting, and `ui.multi_spinner` and `ui.multi_progress` take `stop:`. Once it is set, the jobs running finish, the rest are skipped, and the headline says `stopping`, then ends skipped. A second Ctrl-C interrupts. `Dry::CLI::UI::Stop` is the object behind it.

data/README.md

@@ -86,7 +86,7 @@ class Import < ApplicationCommand
 end
 ```
 
-`ui` writes to the command's `out` and `err` when dry-cli has set them, and to `$stdout` and `$stderr` otherwise.
+`ui` writes to the command's `stdout` and `stderr`, and reads prompt answers from its `stdin`: the streams dry-cli was called with. Outside a dry-cli command it uses `$stdout`, `$stderr` and `$stdin`. The console is built again when those streams change, so a command registered as an instance writes each call to that call's streams.
 
 ### Without dry-cli
 
@@ -399,6 +399,55 @@ Downloading...
 
 Any other `count:`, or a `total:` that is not a non-negative Integer, raises `ArgumentError`.
 
+A phase whose size is never known goes on a row of its own with `m.spinner(label)`, beside the bars. Its row turns and shows the detail its `Line` is given, as in `multi_spinner`, with no bar, and it ends `[✓] label (0.1s)`, or `[𝘅] label: reason` after `line.fail`. It counts as a job and as no units, so `count: :jobs` suits a headline over phases run one at a time:
+
+```ruby
+ui.multi_progress("Generating text", concurrent: false, count: :jobs) do |m|
+  m.spinner("Finding PDFs") { |line| pdfs = find_pdfs { |dir| line.detail = dir } }
+  m.progress("Extracting", total: nil) do |bar|
+    bar.total = pdfs.size
+    pdfs.each { |pdf| extract(pdf) && bar.advance }
+  end
+  m.spinner("Indexing") { index }
+end
+```
+
+Piped:
+
+```text
+Generating text...
+  [✓] Finding PDFs (0.0s)
+  [✓] Extracting 3/3 (0.0s)
+  [✓] Indexing (0.0s)
+✓ Generating text 3/3 (0.0s)
+```
+
+`m.spinner` without a block raises `ArgumentError`.
+
+A job that carries on after some of its units failed ends its row with `bar.fail(reason)` rather than raising, so the jobs after it still run. Its row ends `[𝘅] label 3/3: reason`, the headline ends `𝘅`, and the call returns as usual. `ui.progress` takes the same `bar.fail`.
+
+```ruby
+ui.multi_progress("Generating text", concurrent: false, count: :jobs) do |m|
+  m.spinner("Finding PDFs") { pdfs = find_pdfs }
+  m.progress("Extracting", total: nil) do |bar|
+    bar.total = pdfs.size
+    failed = pdfs.count { |pdf| !extract(pdf).tap { bar.advance } }
+    bar.fail("#{failed} failed") if failed.positive?
+  end
+  m.spinner("Indexing") { index }
+end
+```
+
+Piped, with one PDF that would not extract:
+
+```text
+Generating text...
+  [✓] Finding PDFs (0.0s)
+  [𝘅] Extracting 3/3: 1 failed (0.0s)
+  [✓] Indexing (0.0s)
+𝘅 Generating text 3/3 (0.0s)
+```
+
 Piped:
 
 ```text
@@ -725,7 +774,7 @@ Errors raised inside a block are never swallowed: the widget marks itself failed
 | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `info`, `success`, `box`, `table`, `status` at those levels | `debug`, `warn`, `error`, `fatal`, `popup`, spinners, progress bars, their multi forms, task trees, the status bar, prompts |
 
-`mycli export > rules.csv` therefore writes only the command's results to the file, while its progress stays on the screen. `ui` writes to the streams dry-cli was called with, so `Dry::CLI.new(registry).call(out: io, err: io)` captures everything.
+`mycli export > rules.csv` therefore writes only the command's results to the file, while its progress stays on the screen. `ui` writes to the streams dry-cli was called with, so `Dry::CLI.new(registry).call(stdout: io, stderr: io)` captures everything.
 
 A stream that is not a terminal, or runs under `TERM=dumb`, gets no animation, no cursor movement and no escape codes. [`NO_COLOR`](https://no-color.org) turns colour off and leaves animation on.
 
@@ -780,20 +829,18 @@ end
 
 ### Console options
 
-Override `ui` to configure the console:
+Override `ui_options` to configure the console `ui` builds. The streams come from the command:
 
 ```ruby
 class ApplicationCommand < Dry::CLI::Command
   include Dry::CLI::UI
 
-  def ui
-    @ui ||= Dry::CLI::UI::Console.new(
-      out: out || $stdout,
-      err: err || $stderr,
+  private def ui_options
+    {
       box_width: 72,     # boxes are 72 columns rather than the whole terminal
       color: nil,        # true or false to override detection
       animate: nil       # true or false to override detection
-    )
+    }
   end
 end
 ```
@@ -837,7 +884,15 @@ err.string   # => "Loading...\n✓ Loading (0.0s)\nContinue? (y/N) "
 out.string   # => the Success box
 ```
 
-Through dry-cli, `Dry::CLI.new(registry).call(arguments: %w[import], out: out, err: err)` gives every command's `ui` those streams.
+Through dry-cli, `Dry::CLI.new(registry).call(arguments: %w[import], stdin: input, stdout: out, stderr: err)` gives every command's `ui` those streams.
+
+To run the whole CLI in the same process as its specs, as Aruba's in-process launcher does, bind a `Dry::CLI::Launcher` to it. Each run gets its own streams, and exits are recorded rather than ending the process:
+
+```ruby
+Launcher = Dry::CLI::Launcher[MyCLI::Commands]
+
+Launcher.new(%w[import], StringIO.new("y\n"), out, err, kernel).execute!
+```
 
 ## Relationship to dry-cli-help
 

data/examples/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    dry-cli-ui (0.5.0)
+    dry-cli-ui (0.6.1)
       concurrent-ruby (~> 1.3)
       dry-cli (>= 1.0)
       pastel (~> 0.8)
@@ -84,7 +84,7 @@ CHECKSUMS
   dry-cli (1.4.1) sha256=b8015bb76c708aa8705a36faf694973e75eeeffca39b89c8e172dc6f66a7d874
   dry-cli-autocomplete (0.1.3) sha256=14f76447bda0000c71739b585c827dc0a0a763e30a68a8b4b2dff91f640768e4
   dry-cli-help (0.2.1) sha256=eaaaf6edb787ffe810425b4e4bb1a675d89397ccc759102d70b5b26e7bc692da
-  dry-cli-ui (0.5.0)
+  dry-cli-ui (0.6.1)
   dry-inflector (1.3.1) sha256=7fb0c2bb04f67638f25c52e7ba39ab435d922a3a5c3cd196120f63accb682dcc
   forwardable (1.4.0) sha256=f1cd40cc9812937980e1c76f1aa053660990a7c9b6a98fc37d945468afcce838
   pastel (0.8.0) sha256=481da9fb7d2f6e6b1a08faf11fa10363172dc40fd47848f096ae21209f805a75

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.5.1"
+      VERSION = "0.6.1"
     end
   end
 end

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

@@ -11,6 +11,12 @@ module Dry
         # runs, and is replaced by `✓ label 120/120 (1.1s)` when it ends. The
         # bar's characters come from {Configuration#bar_format}.
         #
+        # A job declared with `spinner` instead has no bar: its row turns and
+        # shows its {Line}'s detail, as in {MultiSpinner}, and ends
+        # `✓ label (0.4s)`. It suits a phase whose size is never known, among
+        # phases whose size is. It counts as a job and as no units, so a
+        # headline over such rows reads best with `count: :jobs`.
+        #
         # @example
         #   ui.multi_progress("Downloading") do |m|
         #     files.each do |file|
@@ -20,6 +26,13 @@ module Dry
         #     end
         #   end
         #
+        # @example Phases, one at a time, some of known size
+        #   ui.multi_progress("Generating", concurrent: false, count: :jobs) do |m|
+        #     m.spinner("Finding") { |line| found = find { |dir| line.detail = dir } }
+        #     m.progress("Extracting", total: nil) { |bar| bar.total = found.size; found.each { extract(it) && bar.advance } }
+        #     m.spinner("Indexing") { index }
+        #   end
+        #
         # See {Multi} for how the jobs run and how the rows are drawn.
         class MultiProgress < Multi
           # What the declaration block is given.
@@ -48,6 +61,20 @@ module Dry
               @jobs << Multi::Job.new(label, work, Progress::Handle.new(total, nil, color: Progress.color(color)))
               self
             end
+
+            # Declares a job with a spinner in place of a bar, for work whose
+            # size is never known.
+            #
+            # @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
 
           # What the headline bar can count.
@@ -78,19 +105,33 @@ module Dry
           private
 
           # @param job [Job]
-          # @return [Progress::Handle]
-          def progress_of(job) = job.handle
+          # @return [Boolean] whether the job was declared with `spinner`
+          def spinner?(job) = job.handle.is_a?(Line)
+
+          # @param job [Job]
+          # @return [Object]
+          def call(job) = spinner?(job) ? Line.call(job.work, job.handle) : super
+
+          # @param job [Job]
+          # @return [Boolean] whether its line or its bar was told to fail
+          def reported_failure?(job) = job.handle.failed?
+
+          # @param job [Job]
+          # @return [Progress::Handle, nil] nil for a spinner, which has no progress
+          def progress_of(job) = spinner?(job) ? nil : job.handle
 
           # @param job [Job]
           # @param width [Integer]
           # @return [String]
           def running(job, width)
+            return [job.label, job.handle.detail].reject(&:empty?).join(" ") if spinner?(job)
+
             "#{job.label.ljust(width)} #{meter(job.handle.current, job.handle.total, job.started, job.handle.color)}"
           end
 
           # @param job [Job]
           # @return [String]
-          def summary(job) = "#{job.label} #{job.handle.current}/#{job.handle.total || '?'}"
+          def summary(job) = job.handle.summary(job.label)
 
           # @param width [Integer]
           # @return [String]
@@ -105,7 +146,7 @@ module Dry
           def current
             return jobs.count(&:seconds) if @count == :jobs
 
-            jobs.sum { |job| job.handle.current }
+            bars.sum { |job| job.handle.current }
           end
 
           # @return [Integer] the total given; or units across every job,
@@ -114,9 +155,12 @@ module Dry
             return @total if @total
             return jobs.size if @count == :jobs
 
-            jobs.sum { |job| job.handle.total || job.handle.current }
+            bars.sum { |job| job.handle.total || job.handle.current }
           end
 
+          # @return [Array<Job>] the jobs that have a bar
+          def bars = jobs.reject { spinner?(it) }
+
           # `[◼◼◼   ] 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.
           #

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

@@ -56,6 +56,33 @@ module Dry
               self
             end
 
+            # Ends the work as a failure when the block returns, without
+            # raising: for work that went on after some of its units failed.
+            #
+            # @param reason [#to_s, nil] said after the count, such as "2 failed"
+            # @return [self]
+            def fail(reason = nil)
+              @failed = true
+              @reason = reason&.to_s
+              self
+            end
+
+            # @return [Boolean] whether {#fail} was called
+            def failed? = @failed == true
+
+            # @return [String, nil] what {#fail} was given
+            attr_reader :reason
+
+            # The label and the count, with the failure's reason after it when
+            # there is one: `Extracting 1002/1002: 2 failed`.
+            #
+            # @param label [String]
+            # @return [String]
+            def summary(label)
+              count = "#{label} #{current}/#{total || '?'}"
+              failed? && !reason.to_s.empty? ? "#{count}: #{reason}" : count
+            end
+
             private
 
             # @return [TTY::ProgressBar, nil]
@@ -150,14 +177,13 @@ module Dry
             terminal.started(handle, label, progress: handle)
             ok = false
             result = yield handle
-            ok = true
+            ok = !handle.failed?
             result
           ensure
             if handle
               bar&.stop
               terminal.finished(handle, ok)
-              summary = "#{label} #{handle.current}/#{handle.total}"
-              terminal.puts(Outcome.line(terminal, ok ? :done : :failed, summary, clock.call - started))
+              terminal.puts(Outcome.line(terminal, ok ? :done : :failed, handle.summary(label), clock.call - started))
             end
           end
 

data/lib/dry/cli/ui.rb

@@ -69,23 +69,65 @@ module Dry
         def reset!
           @config = nil
         end
+
+        # The IO beneath a dry-cli stream, or the stream itself when it is not one.
+        #
+        # Asks for the class rather than for `raw`, which `io/console` also defines on every IO, to
+        # put a terminal into raw mode.
+        #
+        # @param stream [IO, Dry::CLI::Stream]
+        # @return [IO]
+        def raw(stream)
+          defined?(Dry::CLI::Stream) && stream.is_a?(Dry::CLI::Stream) ? stream.raw : stream
+        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.
+      # The console this command presents through.
       #
-      # Override it to configure the console:
+      # In a dry-cli command it writes to the command's own `stdout` and `stderr`, and reads prompt
+      # answers from its `stdin`: the streams the CLI was called with. Anywhere else it uses
+      # `$stdout`, `$stderr` and `$stdin`.
       #
-      # @example
-      #   def ui = @ui ||= Dry::CLI::UI::Console.new(box_width: 72)
+      # The console is built again whenever those streams change. A command registered as an
+      # instance is used for every call to its CLI, each time with that call's streams, as when a
+      # test suite runs the CLI in-process with a StringIO per test.
+      #
+      # Configure the console by overriding {#ui_options}.
       #
       # @return [Dry::CLI::UI::Console]
       def ui
-        @ui ||= Console.new(
-          out: (respond_to?(:out, true) && __send__(:out)) || $stdout,
-          err: (respond_to?(:err, true) && __send__(:err)) || $stderr
-        )
+        streams = ui_streams
+        @ui = nil unless @ui_streams && streams.all? { |name, io| @ui_streams[name].equal?(io) }
+        @ui_streams = streams
+        @ui ||= Console.new(**streams, **ui_options)
+      end
+
+      private
+
+      # The streams {#ui} presents through, as keywords for {Console#initialize}.
+      #
+      # A dry-cli command gives its own public `stdout`, `stderr` and `stdin`. Its output streams
+      # render dry-cli's own styles; the console writes to the IO beneath them, since it decides
+      # colour for itself.
+      #
+      # @return [Hash{Symbol => IO}] `out:`, `err:` and `input:`
+      def ui_streams
+        {
+          out: UI.raw(respond_to?(:stdout) ? stdout : $stdout),
+          err: UI.raw(respond_to?(:stderr) ? stderr : $stderr),
+          input: respond_to?(:stdin) ? stdin : $stdin
+        }
+      end
+
+      # Options for {Console#initialize} other than its streams. Override it to configure the
+      # console {#ui} builds.
+      #
+      # @example
+      #   def ui_options = { box_width: 72 }
+      #
+      # @return [Hash{Symbol => Object}]
+      def ui_options
+        {}
       end
     end
   end

data/sig/dry/cli/ui.rbs

@@ -11,6 +11,11 @@ module Dry
 
       def ui: () -> Console
 
+      private def ui_streams: () -> { out: untyped, err: untyped, input: untyped }
+      private def ui_options: () -> Hash[Symbol, untyped]
+
+      def self.raw: (untyped stream) -> untyped
+
       def self.configure: () { (Configuration config) -> void } -> Configuration
       def self.config: () -> Configuration
       def self.reset!: () -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-ui
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -229,7 +229,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 4.0.22
 specification_version: 4
 summary: 'Runtime terminal UI for dry-cli commands: spinners, progress, boxes, task
   trees, tables, prompts'