dry-cli-ui 0.3.0 → 0.4.0

data/examples/bin/mycli

@@ -0,0 +1,206 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Load the gems examples/Gemfile names, even when run as bin/mycli without
+# bundle exec; otherwise Ruby picks the newest installed dry-cli-ui instead.
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+require "bundler/setup"
+
+require "fileutils"
+require "dry/cli"
+require "dry/cli/help"
+require "dry/cli/autocomplete/command"
+require "dry/cli/ui"
+require "net/http"
+require "prime"
+
+module Foo
+  module CLI
+    module Commands
+      extend Dry::CLI::Registry
+
+      class Version < Dry::CLI::Command
+        desc "Print version"
+
+        def call(*)
+          puts "1.0.0"
+        end
+      end
+
+      # Shared by the two URL commands: follows redirects, and asks for the
+      # body as it is stored, so the bytes counted match Content-Length.
+      module HTTP
+        HEADERS = { "Accept-Encoding" => "identity" }.freeze
+        REDIRECTS = 5
+
+        module_function
+
+        # @return [Array(URI, Integer, nil)] where the URL ends up, and its size when the server says
+        # @raise [RuntimeError] for a response that is neither a redirect nor a success
+        def resolve(url, hops = REDIRECTS)
+          uri = URI(url)
+          response = start(uri) { |http| http.head(uri.request_uri, HEADERS) }
+          if response.is_a?(Net::HTTPRedirection) && hops.positive?
+            return resolve(URI.join(uri, response["location"]).to_s, hops - 1)
+          end
+          raise "HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          [uri, response.content_length]
+        end
+
+        # @yieldparam bytes [Integer] the size of each chunk as it arrives
+        # @return [String] the body
+        # @raise [RuntimeError] for a response that is not a success
+        def download(uri)
+          body = +""
+          start(uri) do |http|
+            http.request_get(uri.request_uri, HEADERS) do |response|
+              raise "HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+              response.read_body do |chunk|
+                body << chunk
+                yield chunk.bytesize if block_given?
+              end
+            end
+          end
+          body
+        end
+
+        def start(uri, &)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 10, &)
+        end
+      end
+
+      # One progress bar per URL, filling as bytes arrive, under a headline
+      # bar that counts every byte.
+      class FetchUrlsProgress < Dry::CLI::Command
+        include Dry::CLI::UI
+
+        desc "Fetch URLs with a progress bar each, and write them all to urls.txt"
+        argument :urls, type: :array, required: true, desc: "URLs to fetch, separated by spaces"
+
+        def call(urls:, **)
+          # A bar's total is fixed when it is declared, so ask each URL for its
+          # size first, with a HEAD request. A URL that fails here is left out.
+          found = urls.filter_map do |url|
+            [url, *HTTP.resolve(url)]
+          rescue StandardError => e
+            ui.status "#{url}: #{e.message}", level: :warn
+            nil
+          end
+          return ui.error("None of the #{urls.size} URLs could be fetched") if found.empty?
+
+          bodies = ui.multi_progress("Fetching #{found.size} URLs", concurrent: 8) do |m|
+            found.each do |url, uri, size|
+              m.progress(url, total: size || 1) do |bar|
+                sleep rand(1..4)
+                # Move the bar one byte at a time, as each chunk arrives.
+                body = HTTP.download(uri) { |bytes| bytes.times { bar.advance } if size }
+                bar.advance unless size # no Content-Length: done in one step
+                body
+              end
+            end
+          end
+
+          File.write("urls.txt", bodies.join("\n"))
+          ui.success "Wrote #{bodies.sum(&:bytesize)} bytes from #{found.size} of #{urls.size} URLs to urls.txt"
+        rescue StandardError => e
+          ui.error("Fetching failed", e.message)
+        end
+      end
+
+      # One spinner per URL, each saying what it is doing, and one file per URL.
+      class FetchUrls < Dry::CLI::Command
+        include Dry::CLI::UI
+
+        desc "Fetch URLs with a spinner each, and write each to its own file"
+        argument :urls, type: :array, required: true, desc: "URLs to fetch, separated by spaces"
+
+        def call(urls:, **)
+          bodies = ui.multi_spinner("Fetching #{urls.size} URLs", concurrent: 8) do |m|
+            urls.each do |url|
+              m.spinner(url) do |line|
+                line.detail = "resolving"
+                uri, = HTTP.resolve(url)
+                line.detail = "downloading #{uri.host}"
+                sleep rand(1..4) # slow enough to watch
+                HTTP.download(uri)
+              rescue StandardError => e
+                line.fail(e.message)
+                nil
+              end
+            end
+          end
+
+          files = urls.zip(bodies).filter_map do |url, body|
+            next unless body
+
+            "#{friendly_filename(url)}.txt".tap { |file| File.write(file, body) }
+          end
+          ui.success "Wrote #{files.size} of #{urls.size} URLs", files.join("\n")
+        end
+
+        private
+
+        def friendly_filename(url)
+          url.sub(%r{\Ahttps?://}, "").gsub(/[^\w.-]+/, "_").delete_suffix("_")
+        end
+      end
+
+      class ComputePrimes < Dry::CLI::Command
+        include Dry::CLI::UI
+
+        def self.closest_prime(n)
+          # Primes must be greater than 1
+          return 2 if n <= 2
+          return n if ::Prime.prime?(n)
+
+          distance = 1
+          loop do
+            lower = n - distance
+            upper = n + distance
+
+            primes = []
+            primes << lower if lower > 1 && ::Prime.prime?(lower)
+            primes << upper if ::Prime.prime?(upper)
+
+            # Return the prime(s) found at the shortest distance
+            return primes.size == 1 ? primes.first : primes if primes.any?
+
+            distance += 1
+          end
+        end
+
+        desc 'Compute closest prime to a given number in the array'
+        option :max, default: 100_000, desc: "Maximum integer to compute closest primes for", type: :integer
+
+        def call(max:)
+          ui.info "Computing closest primes..."
+          File.open('primes.txt', 'w') do |f|
+            integers = (1..max.to_i)
+            ui.progress("Computing Primes", total: integers.size) do |bar|
+              integers.each do |i|
+                p = ComputePrimes.closest_prime(i)
+                f.puts "closest prime to #{i} is #{p}"
+                bar.advance
+              end
+            end
+          end
+          ui.success("Computed #{max} primes, they are in the 'primes.txt' files.")
+        rescue StandardError => e
+          ui.error("Import failed", e.message)
+        end
+      end
+
+      register "version",         Version, aliases: ["v", "-v", "--version"]
+      register "urls_progress",   FetchUrlsProgress
+      register "urls_spinner",    FetchUrls
+      register "completion",      ::Dry::CLI::Autocomplete::Command[::Foo::CLI::Commands], hidden: true
+      register "primes",          ComputePrimes
+    end
+  end
+end
+
+Dry::CLI.new(Foo::CLI::Commands).call
+
+FileUtils.rm_f(Dir.glob("#{File.expand_path('../', __dir__)}/*.txt"))

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, over a gray track the whole bar's width.
+        DEFAULTS = {
+          spinner_format: :dots,
+          bar_format: { complete: "◼", incomplete: " " }.freeze,
+          bar_color: :green,
+          bar_background: :on_bright_black
+        }.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_bright_black; 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,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)