dry-cli-ui 0.1.0

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # Questions, choices and yes/no confirmations.
+        #
+        # When both the input and the output are interactive terminals, this
+        # uses arrow-key menus and line editing. Otherwise it prints the
+        # question and reads a line, so answers can be piped in:
+        #
+        #   printf 'production\ny\n' | mycli deploy
+        #
+        # An exhausted input returns the default. A question without a
+        # default raises {NonInteractiveError} rather than inventing an answer.
+        class Prompt
+          # @param input [IO] where answers come from
+          # @param terminal [Terminal] where questions go
+          # @param backend [TTY::Prompt, nil] the interactive implementation; built on first use when nil
+          def initialize(input:, terminal:, backend: nil)
+            @input = input
+            @terminal = terminal
+            @backend = backend
+          end
+
+          # Asks for a free-form answer, or for one of a list of choices.
+          #
+          # @param question [String]
+          # @param default [Object, nil] returned for an empty answer; for choices, the name of one
+          # @param choices [Array<String>, Hash{String => Object}, nil]
+          #   names to pick from, or names mapped to the values to return
+          # @return [Object, nil] the answer, or the chosen value
+          # @raise [NonInteractiveError] when the input is exhausted and there is no default
+          def ask(question, default: nil, choices: nil)
+            if interactive?
+              options = default.nil? ? {} : { default: default }
+              choices ? backend.select(question, choices, **options) : backend.ask(question, **options)
+            else
+              choices ? plain_select(question, pairs(choices), default) : plain_ask(question, default)
+            end
+          end
+
+          # Asks a yes/no question.
+          #
+          # @param question [String]
+          # @param default [Boolean] returned for an empty answer or an exhausted input
+          # @return [Boolean]
+          def confirm(question, default: false)
+            return backend.yes?(question, default: default) if interactive?
+
+            loop do
+              terminal.print("#{question} #{default ? '(Y/n)' : '(y/N)'} ")
+              case read&.downcase
+              in nil | "" then return default
+              in "y" | "yes" then return true
+              in "n" | "no" then return false
+              else terminal.puts("Please answer y or n.")
+              end
+            end
+          end
+
+          private
+
+          # @return [IO]
+          attr_reader :input
+
+          # @return [Terminal]
+          attr_reader :terminal
+
+          # @return [TTY::Prompt]
+          def backend
+            @backend ||= TTY::Prompt.new(
+              input: input,
+              output: terminal.io,
+              enable_color: terminal.color?,
+              interrupt: :signal
+            )
+          end
+
+          # @return [Boolean]
+          def interactive?
+            input.respond_to?(:tty?) && input.tty? && terminal.animated?
+          end
+
+          # @return [String, nil] the next line without surrounding whitespace, or nil at the end of input
+          def read
+            input.gets&.strip
+          end
+
+          # @param question [String]
+          # @param default [Object, nil]
+          # @return [Object, nil]
+          def plain_ask(question, default)
+            terminal.print("#{question}#{" [#{default}]" unless default.nil?} ")
+            answer = read
+            raise NonInteractiveError, "no answer for #{question.inspect} and no default" if answer.nil? && default.nil?
+
+            answer.nil? || answer.empty? ? default : answer
+          end
+
+          # @param question [String]
+          # @param options [Array<Array(String, Object)>]
+          # @param default [Object, nil] the name of the default choice
+          # @return [Object]
+          def plain_select(question, options, default)
+            terminal.puts(question)
+            options.each_with_index { |(name, _), index| terminal.puts("  #{index + 1}) #{name}") }
+            loop do
+              terminal.print("Choose 1-#{options.size}#{" [#{default}]" unless default.nil?}: ")
+              line = read
+              answer = line.nil? || line.empty? ? default&.to_s : line
+              found = choice(options, answer) if answer
+              return found.last if found
+              raise NonInteractiveError, "no valid choice for #{question.inspect}" if line.nil?
+
+              terminal.puts("Choose a number from 1 to #{options.size}, or type a choice.")
+            end
+          end
+
+          # @param options [Array<Array(String, Object)>]
+          # @param answer [String] a 1-based position or a name
+          # @return [Array(String, Object), nil]
+          def choice(options, answer)
+            return options[answer.to_i - 1] if answer.match?(/\A\d+\z/) && answer.to_i.between?(1, options.size)
+
+            options.find { |name, _| name.to_s == answer }
+          end
+
+          # @param choices [Array<String>, Hash{String => Object}]
+          # @return [Array<Array(String, Object)>]
+          def pairs(choices)
+            choices.is_a?(Hash) ? choices.to_a : choices.map { |name| [name, name] }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "tty-spinner"
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # Shows that a block is running, then how it ended and how long it took.
+        #
+        # On an animated terminal the spinner turns until the block returns
+        # and is replaced by the outcome line. Anywhere else it prints
+        # `Label...` before the block and the outcome line after it.
+        class Spinner
+          # @param terminal [Terminal]
+          # @param clock [#call] returns monotonic seconds
+          def initialize(terminal, clock:)
+            @terminal = terminal
+            @clock = clock
+          end
+
+          # Runs the block under a spinner.
+          #
+          # @param label [String]
+          # @yield the work to show progress for
+          # @return [Object] whatever the block returns
+          # @raise [Exception] whatever the block raises, after marking the spinner failed
+          def run(label)
+            started = clock.call
+            spinner = start(label)
+            ok = false
+            result = yield
+            ok = true
+            result
+          ensure
+            spinner&.stop
+            terminal.puts(Outcome.line(terminal, ok ? :done : :failed, label, clock.call - started))
+          end
+
+          private
+
+          # @return [Terminal]
+          attr_reader :terminal
+
+          # @return [#call]
+          attr_reader :clock
+
+          # @param label [String]
+          # @return [TTY::Spinner, nil] the running spinner, or nil when not animating
+          def start(label)
+            unless terminal.animated?
+              terminal.puts("#{label}...")
+              return
+            end
+
+            TTY::Spinner.new(":spinner #{label}", output: terminal.io, format: :dots, hide_cursor: true, clear: true)
+                        .tap(&:auto_spin)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # A single line with a coloured glyph: `✓ Connected to the database`.
+        # The light-weight sibling of {Box}.
+        module Status
+          # @param terminal [Terminal]
+          # @param level [Theme::Level]
+          # @param text [String]
+          # @return [String] the line, without a newline
+          def self.line(terminal, level, text)
+            "#{terminal.pastel.decorate(level.glyph, level.color)} #{text}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "tty-table"
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # Rows and an optional bold header, framed with box-drawing lines.
+        #
+        # Tables are data, so they are never narrowed to fit the terminal: a
+        # column is not truncated and a table is not rotated. A table wider
+        # than the screen wraps the way any long line does.
+        class Table
+          # Wider than any table anyone will render. TTY::Table otherwise
+          # measures the screen, warns on STDERR, and turns a wide table on
+          # its side.
+          UNLIMITED = 1_000_000
+
+          # @param terminal [Terminal]
+          def initialize(terminal)
+            @terminal = terminal
+          end
+
+          # @param rows [Array<Array<#to_s>>]
+          # @param header [Array<#to_s>, nil]
+          # @return [String] the table ending in a newline, or "" when there are no rows
+          def render(rows, header: nil)
+            return "" if rows.empty?
+
+            table = TTY::Table.new(
+              header: header&.map { |cell| terminal.pastel.bold(cell.to_s) },
+              rows: rows.map { |row| row.map(&:to_s) }
+            )
+            "#{table.render(:unicode, padding: [0, 1], width: UNLIMITED)}\n"
+          end
+
+          private
+
+          # @return [Terminal]
+          attr_reader :terminal
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # Runs a tree of named tasks and shows the state of each: pending,
+        # running, done, failed or skipped, with elapsed times.
+        #
+        # The block only declares the tree; nothing runs until it returns, so
+        # the whole shape is known before the first task starts. Tasks run in
+        # order, except inside a group declared `concurrent: true`, whose
+        # tasks all run at once.
+        #
+        # On an animated terminal the tree is drawn once and redrawn in place,
+        # with a spinner beside every running task. Otherwise, or when the
+        # tree is taller than the screen, each line is printed once it has
+        # something final to say.
+        #
+        # When a task raises, it and every group above it are marked failed,
+        # tasks already running beside it finish, everything that had not
+        # started is marked skipped, and the error is re-raised.
+        #
+        # @example
+        #   ui.tasks("Deploy") do |t|
+        #     t.task("Build assets") { build }
+        #     t.group("Migrate", concurrent: true) do |g|
+        #       g.task("users") { migrate(:users) }
+        #       g.task("orders") { migrate(:orders) }
+        #     end
+        #   end
+        class Tasks
+          # Frames a running task cycles through on an animated terminal.
+          FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+          # Seconds between spinner frames.
+          INTERVAL = 0.1
+
+          # One task, or a group of them.
+          class Node
+            # @param name [String]
+            # @param job [Proc, nil] the work; nil for a group
+            # @param concurrent [Boolean] whether a group runs its tasks at once
+            def initialize(name, job = nil, concurrent: false)
+              @name = name
+              @job = job
+              @concurrent = concurrent
+              @children = []
+              @state = :pending
+              @seconds = nil
+            end
+
+            # @return [String]
+            attr_reader :name
+
+            # @return [Proc, nil]
+            attr_reader :job
+
+            # @return [Boolean]
+            attr_reader :concurrent
+            alias concurrent? concurrent
+
+            # @return [Array<Node>]
+            attr_reader :children
+
+            # @return [Symbol] one of the keys of {Theme::STATES}
+            attr_accessor :state
+
+            # @return [Float, nil] how long the node ran, once it has finished
+            attr_accessor :seconds
+
+            # @return [Boolean] whether this node holds tasks rather than work
+            def group? = job.nil?
+          end
+
+          # What the declaration block is given.
+          class Builder
+            # @param nodes [Array<Node>] the list new nodes are appended to
+            def initialize(nodes)
+              @nodes = nodes
+            end
+
+            # Declares a task.
+            #
+            # @param name [String]
+            # @yield the work
+            # @return [self]
+            # @raise [ArgumentError] without a block
+            def task(name, &job)
+              raise ArgumentError, "task #{name.inspect} needs a block" unless job
+
+              nodes << Node.new(name, job)
+              self
+            end
+
+            # Declares a group of tasks.
+            #
+            # @param name [String]
+            # @param concurrent [Boolean] run the group's tasks at the same time
+            # @yieldparam group [Builder] declares the tasks inside the group
+            # @return [self]
+            # @raise [ArgumentError] without a block
+            def group(name, concurrent: false)
+              raise ArgumentError, "group #{name.inspect} needs a block" unless block_given?
+
+              node = Node.new(name, concurrent: concurrent)
+              nodes << node
+              yield Builder.new(node.children)
+              self
+            end
+
+            private
+
+            # @return [Array<Node>]
+            attr_reader :nodes
+          end
+
+          # @param terminal [Terminal]
+          # @param clock [#call] returns monotonic seconds
+          def initialize(terminal, clock:)
+            @terminal = terminal
+            @clock = clock
+            @roots = []
+            @live = nil
+            @lock = Mutex.new
+            @frame = 0
+          end
+
+          # Declares the tree with the block, then runs it.
+          #
+          # @param title [String, nil] a heading printed above the tree
+          # @param concurrent [Boolean] run the top-level tasks at the same time
+          # @yieldparam tasks [Builder]
+          # @return [nil]
+          def run(title = nil, concurrent: false)
+            yield Builder.new(roots)
+            terminal.puts(terminal.pastel.bold(title)) if title
+            ticker = start_ticker
+            begin
+              run_all(roots, concurrent)
+            ensure
+              ticker&.shutdown
+              ticker&.wait_for_termination(1)
+              skip_pending
+            end
+            nil
+          end
+
+          private
+
+          # @return [Terminal]
+          attr_reader :terminal
+
+          # @return [#call]
+          attr_reader :clock
+
+          # @return [Array<Node>]
+          attr_reader :roots
+
+          # @return [Mutex] held while the tree changes or is drawn
+          attr_reader :lock
+
+          # @return [Integer] the spinner frame to draw next
+          attr_accessor :frame
+
+          # @param nodes [Array<Node>]
+          # @param concurrent [Boolean]
+          # @return [void]
+          def run_all(nodes, concurrent)
+            return nodes.each { |node| execute(node) } unless concurrent
+
+            futures = nodes.map { |node| Concurrent::Promises.future(node) { |each| execute(each) } }
+            futures.each(&:wait)
+            failed = futures.find(&:rejected?)
+            raise failed.reason if failed
+          end
+
+          # @param node [Node]
+          # @return [void]
+          def execute(node)
+            started = clock.call
+            change(node, :running)
+            ok = false
+            node.group? ? run_all(node.children, node.concurrent?) : node.job.call
+            ok = true
+          ensure
+            change(node, ok ? :done : :failed, seconds: clock.call - started)
+          end
+
+          # @return [void]
+          def skip_pending
+            rows.each_key { |node| change(node, :skipped) if node.state == :pending }
+          end
+
+          # @param node [Node]
+          # @param state [Symbol]
+          # @param seconds [Float, nil]
+          # @return [void]
+          def change(node, state, seconds: nil)
+            lock.synchronize do
+              node.state = state
+              node.seconds = seconds
+              if live?
+                redraw
+              elsif settled?(node)
+                terminal.puts(line(node))
+              end
+            end
+          end
+
+          # Whether a node has reached the state plain output reports: a group
+          # once it starts, so its children appear beneath it, and a task once
+          # it ends.
+          #
+          # @param node [Node]
+          # @return [Boolean]
+          def settled?(node)
+            return true if node.state == :skipped
+
+            node.group? ? node.state == :running : node.state != :running
+          end
+
+          # Whether to redraw in place. Needs cursor movement, and a tree that
+          # fits on screen: the cursor cannot move above the top row.
+          #
+          # @return [Boolean]
+          def live?
+            @live = terminal.animated? && rows.size < terminal.height if @live.nil?
+            @live
+          end
+
+          # Draws the tree and starts turning the spinners, when live.
+          #
+          # @return [Concurrent::TimerTask, nil]
+          def start_ticker
+            return unless live?
+
+            rows.each_key { |node| terminal.puts(line(node)) }
+            Concurrent::TimerTask.new(execution_interval: INTERVAL) { tick }.tap(&:execute)
+          end
+
+          # @return [void]
+          def tick
+            lock.synchronize do
+              self.frame += 1
+              redraw
+            end
+          end
+
+          # @return [void]
+          def redraw
+            terminal.print(terminal.cursor.up(rows.size))
+            rows.each_key { |node| terminal.print("#{terminal.cursor.clear_line}#{line(node)}\n") }
+          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?
+            elapsed = " #{pastel.bright_black("(#{Duration.format(node.seconds)})")}" if node.seconds
+            "#{pastel.bright_black(rows.fetch(node))}#{pastel.decorate(glyph, color)} #{node.name}#{elapsed}"
+          end
+
+          # Every node in display order, with the tree branch drawn before it.
+          #
+          # @return [Hash{Node => String}]
+          def rows
+            @rows ||= layout(roots, "", {})
+          end
+
+          # @param nodes [Array<Node>]
+          # @param prefix [String]
+          # @param acc [Hash{Node => String}]
+          # @return [Hash{Node => String}]
+          def layout(nodes, prefix, acc)
+            nodes.each_with_index do |node, index|
+              last = index == nodes.size - 1
+              acc[node] = "#{prefix}#{last ? '└─ ' : '├─ '}"
+              layout(node.children, "#{prefix}#{last ? '   ' : '│  '}", acc)
+            end
+            acc
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      # The renderers behind {Console}. Each one takes a {Terminal} and owns
+      # both its rich form and its plain fallback. Nothing outside this
+      # namespace touches a TTY toolkit class.
+      module Widgets
+        autoload :Box, File.expand_path("widgets/box", __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__)
+        autoload :Spinner, File.expand_path("widgets/spinner", __dir__)
+        autoload :Status, File.expand_path("widgets/status", __dir__)
+        autoload :Table, File.expand_path("widgets/table", __dir__)
+        autoload :Tasks, File.expand_path("widgets/tasks", __dir__)
+      end
+    end
+  end
+end

data/lib/dry/cli/ui.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "ui/version"
+
+# The dry-rb namespace, which dry-cli lives in. This gem is not part of dry-rb.
+module Dry
+  class CLI
+    # Runtime presentation for Dry::CLI commands: boxes, status lines,
+    # spinners, progress bars, task trees, tables and prompts.
+    #
+    # Include it in a command, or in the base class every command inherits
+    # from, and call {#ui}. Everything else loads the first time it is used,
+    # so including the module costs a command nothing at boot.
+    #
+    # @example
+    #   class Import < Dry::CLI::Command
+    #     include Dry::CLI::UI
+    #
+    #     def call(**)
+    #       ui.spinner("Loading YAML") { load_rules }
+    #       ui.success "Imported #{rules.size} rules"
+    #     rescue => e
+    #       ui.error("Import failed", e.message)
+    #     end
+    #   end
+    module UI
+      # Base class for every error this gem raises.
+      class Error < StandardError; end
+
+      # Raised when a prompt needs an answer, no default was given, and the
+      # input stream is exhausted.
+      class NonInteractiveError < Error; end
+
+      autoload :Console, File.expand_path("ui/console", __dir__)
+      autoload :Duration, File.expand_path("ui/duration", __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__)
+
+      # 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.
+      #
+      # Override it to configure the console:
+      #
+      # @example
+      #   def ui = @ui ||= Dry::CLI::UI::Console.new(box_width: 72)
+      #
+      # @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
+        )
+      end
+    end
+  end
+end

data/lib/dry-cli-ui.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "dry/cli/ui"

data/sig/dry/cli/ui.rbs

@@ -0,0 +1,32 @@
+module Dry
+  class CLI
+    module UI
+      VERSION: String
+
+      class Error < StandardError
+      end
+
+      class NonInteractiveError < Error
+      end
+
+      def ui: () -> Console
+
+      class Console
+        def debug: (*_ToS paragraphs, ?width: Integer?) -> nil
+        def info: (*_ToS paragraphs, ?width: Integer?) -> nil
+        def success: (*_ToS paragraphs, ?width: Integer?) -> nil
+        def warn: (*_ToS paragraphs, ?width: Integer?) -> nil
+        def error: (*_ToS paragraphs, ?width: Integer?) -> nil
+        def fatal: (*_ToS paragraphs, ?width: Integer?) -> nil
+        def box: (*_ToS paragraphs, ?title: String?, ?level: Symbol?, ?width: Integer?) -> nil
+        def status: (*_ToS words, ?level: Symbol) -> nil
+        def spinner: [T] (String label) { () -> T } -> T
+        def progress: [T] (String label, total: Integer) { (untyped progress) -> T } -> T
+        def tasks: (?String? title, ?concurrent: bool) { (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
+        def confirm: (String question, ?default: bool) -> bool
+      end
+    end
+  end
+end