dry-cli-ui 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b4b7ae4869fa6a7623aafc109ef5c26af41436021cc62e4efd5ba87602c64a3
-  data.tar.gz: ecbc221a29f2a9be94a4041fd4642ac5367af9bd4b1e7cc4bff828da20e871c5
+  metadata.gz: d64ee9f8fedbc7de0fcd1875acf59d07876ef6acaffbfcc8574b197de0e8d6fd
+  data.tar.gz: 2f7e11eca1a0dff40b3df7cba685bca7f97d4884515db1107805036e746e20bc
 SHA512:
-  metadata.gz: d46a4ec8716f6aaea3f17d8e2eda6ba29f90272516d812270b77ba604ff372e6327c840cbcc54b9ac7511eabd78dcf709c8c6072932927e6ff72ff6c35a5931d
-  data.tar.gz: 0ce772edc045b9deca09aca086de303d7f01cc2ce7ff5ca912077eeb3a5753cd397bc9cdfc8c1b4704d0c125c67f8077176266fc693df6dcbe97a06a9f971850
+  metadata.gz: d9105f75325a1a7f8282e989d4c847320fb481880a7a529041d98d4bff9457dc5235d08a5c3b311c0b3d442a6dc4c3923b6c72844bd2fbb55ec04f2824b906e3
+  data.tar.gz: d095b784083ba57db9592e51ef2d56274dd9cb187fcac350d35aaea51b8e64c519a800e3f7f899b2b248acfe8035733c4fa63930b64086cdbebea17c8af4636b

data/CHANGELOG.md

@@ -1,7 +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
 
@@ -424,6 +424,30 @@ Generating text...
 
 `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
@@ -750,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.
 
@@ -805,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
 ```
@@ -862,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.6.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.6.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.6.0"
+      VERSION = "0.6.1"
     end
   end
 end

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

@@ -113,8 +113,8 @@ module Dry
           def call(job) = spinner?(job) ? Line.call(job.work, job.handle) : super
 
           # @param job [Job]
-          # @return [Boolean]
-          def reported_failure?(job) = spinner?(job) && job.handle.failed?
+          # @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
@@ -131,11 +131,7 @@ module Dry
 
           # @param job [Job]
           # @return [String]
-          def summary(job)
-            return job.handle.summary(job.label) if spinner?(job)
-
-            "#{job.label} #{job.handle.current}/#{job.handle.total || '?'}"
-          end
+          def summary(job) = job.handle.summary(job.label)
 
           # @param width [Integer]
           # @return [String]

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.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Konstantin Gredeskoul