dry-cli-ui 0.6.0 → 0.7.0

data/lib/dry/cli/ui.rb

@@ -34,14 +34,25 @@ module Dry
       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 :Flags, File.expand_path("ui/flags", __dir__)
+      autoload :Invocation, File.expand_path("ui/invocation", __dir__)
       autoload :Line, File.expand_path("ui/line", __dir__)
+      autoload :Logging, File.expand_path("ui/logging", __dir__)
+      autoload :Report, File.expand_path("ui/report", __dir__)
+      autoload :Reporting, File.expand_path("ui/reporting", __dir__)
       autoload :Stop, File.expand_path("ui/stop", __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__)
 
+      @started_at = ::Time.now
+
       class << self
+        # @return [Time] when this gem loaded, which stands for when the process started. Stamps
+        #   the file name of a report `-o` writes.
+        attr_reader :started_at
+
         # Make process-wide settings. A block taking an argument receives the
         # configuration; any other block runs against it.
         #
@@ -69,23 +80,78 @@ 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. Under dry-cli 1.4 and
+      # earlier, which give a command only `out` and `err`, it writes to those and reads `$stdin`.
+      # 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, invocation: Invocation.for(self), **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(ui_stream(:stdout, :out) || $stdout),
+          err: UI.raw(ui_stream(:stderr, :err) || $stderr),
+          input: respond_to?(:stdin) ? stdin : $stdin
+        }
+      end
+
+      # One of the command's output streams: the public one, or the protected one dry-cli 1.4 and
+      # earlier set on a command it runs.
+      #
+      # @param name [Symbol] the public reader, `:stdout` or `:stderr`
+      # @param legacy_name [Symbol] the protected reader, `:out` or `:err`
+      # @return [IO, Dry::CLI::Stream, nil] nil when the command has neither, or was never run
+      def ui_stream(name, legacy_name)
+        return public_send(name) if respond_to?(name)
+
+        __send__(legacy_name) if respond_to?(legacy_name, true)
+      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,9 +11,69 @@ module Dry
 
       def ui: () -> Console
 
+      private def ui_streams: () -> { out: untyped, err: untyped, input: untyped }
+      private def ui_stream: (Symbol name, Symbol legacy_name) -> 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
+      def self.started_at: () -> Time
+
+      module Flags
+        OPTIONS: Hash[Symbol, Hash[Symbol, Hash[Symbol, untyped]]]
+        OPTIONAL_VALUES: Array[Symbol]
+        SWITCHES: Array[String]
+
+        def self.arguments: (Array[String] argv, ?switches: Array[String]) -> Array[String]
+        def self.switches: (untyped command) -> Array[String]
+        def flags: (*Symbol names) -> Array[Symbol]
+      end
+
+      class Invocation
+        attr_reader executable: String
+        attr_reader action: String?
+        attr_reader name: String
+        attr_reader started_at: Time
+        attr_reader directory: String
+
+        def self.new: (executable: String, action: String?, name: String, started_at: Time, directory: String) -> Invocation
+        def self.for: (?untyped command, ?program: String, ?started_at: Time, ?directory: String) -> Invocation
+        def self.root: (String directory) -> String
+        def basename: () -> String
+        def report_path: (String? value) -> String?
+        def log_path: (String? value) -> String?
+      end
+
+      class Report
+        def color?: () -> true
+      end
+
+      class Logging
+        LEVELS: Array[String]
+        FORMATS: Hash[String, Symbol]
+        INSPECT_LIMIT: Integer
+        FRAME_LIMIT: Integer
+
+        def self.level: (String | Symbol name) -> Symbol
+        def self.formatter: (String | Symbol name) -> untyped
+        def self.formats: () -> Array[String]
+        def self.logger: (String name) -> untyped
+        def self.locals: (Exception exception) -> Array[Hash[Symbol, untyped]]?
+        def self.record: (Exception exception) -> void
+        def initialize: (String? target, io: untyped, level: String | Symbol, format: String | Symbol) -> void
+        def run: [T] () { () -> T } -> T
+      end
+
+      module Reporting
+        def output: [T] (?String? value) { (untyped io) -> T } -> T
+        def logging: [T] (String? value, ?level: String | Symbol, ?format: String | Symbol) { () -> T } -> T
+        def with_flags: [T] (?output: String?, ?log: String?, ?log_level: String | Symbol, ?log_format: String | Symbol, **untyped) { (untyped io) -> T } -> T
+        def logger: () -> untyped
+        def log_exception: (Exception exception, ?String? message, ?level: String | Symbol) -> nil
+      end
 
       class Configuration
         type spinner_definition = Symbol | { interval: Numeric, frames: Array[String] | String }
@@ -27,6 +87,10 @@ module Dry
         def bar_color=: (Symbol? value) -> Symbol?
         def bar_background: (?Symbol? value) -> Symbol?
         def bar_background=: (Symbol? value) -> Symbol?
+        def bar_failed_color: (?Symbol? value) -> Symbol?
+        def bar_failed_color=: (Symbol? value) -> Symbol?
+        def bar_aux_color: (?Symbol? value) -> Symbol?
+        def bar_aux_color=: (Symbol? value) -> Symbol?
         def spinner_frames: () -> Array[String]
         def spinner_frame_seconds: () -> Float
         def bar_complete: () -> String
@@ -44,6 +108,28 @@ module Dry
         def summary: (String label) -> String
       end
 
+      module Widgets
+        class Progress
+          class Handle
+            type outcome = :ok | :aux | :failed
+
+            OUTCOMES: Array[outcome]
+
+            def total: () -> Integer?
+            def total=: (Integer value) -> Integer
+            def color: () -> Symbol?
+            def current: () -> Integer
+            def counts: () -> { ok: Integer, aux: Integer, failed: Integer }
+            def advance: (?Integer step, ?as: outcome) -> self
+            def fail: (?_ToS? reason) -> self
+            def failed?: () -> bool
+            def reason: () -> String?
+            def finish: () -> self
+            def summary: (String label) -> String
+          end
+        end
+      end
+
       class Stop
         def stopped?: () -> bool
         def stop!: () -> self
@@ -51,6 +137,8 @@ module Dry
       end
 
       class Console
+        include Reporting
+
         def debug: (*_ToS paragraphs, ?width: Integer?) -> nil
         def info: (*_ToS paragraphs, ?width: Integer?) -> nil
         def success: (*_ToS paragraphs, ?width: Integer?) -> nil
@@ -62,14 +150,15 @@ module Dry
         def popup: (*_ToS paragraphs, ?title: String?, ?width: Integer?) -> nil
         def spinner: [T] (String label) { (Line line) -> T } -> T
         def multi_spinner: (String title, ?concurrent: (bool | Integer), ?stop: Stop?) { (untyped spinners) -> void } -> Array[untyped]
-        def progress: [T] (String label, total: Integer, ?color: Symbol?) { (untyped progress) -> T } -> T
+        def progress: [T] (String label, total: Integer, ?color: Symbol?) { (Widgets::Progress::Handle progress) -> T } -> T
+        def legend: (?failed: _ToS?, ?aux: _ToS?, ?ok: _ToS?) -> nil
         def multi_progress: (String title, ?concurrent: (bool | Integer), ?count: (:units | :jobs), ?total: Integer?, ?stop: Stop?) { (untyped bars) -> void } -> Array[untyped]
         def stoppable: [T] () { (Stop stop) -> T } -> T
         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
-        def confirm: (String question, ?default: bool) -> bool
+        def confirm: (String question, ?default: bool, ?yes: bool) -> bool
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-ui
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: binding_of_caller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: pastel
   requirement: !ruby/object:Gem::Requirement
@@ -51,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: semantic_logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
 - !ruby/object:Gem::Dependency
   name: strings
   requirement: !ruby/object:Gem::Requirement
@@ -187,7 +229,12 @@ files:
 - lib/dry/cli/ui/configuration.rb
 - lib/dry/cli/ui/console.rb
 - lib/dry/cli/ui/duration.rb
+- lib/dry/cli/ui/flags.rb
+- lib/dry/cli/ui/invocation.rb
 - lib/dry/cli/ui/line.rb
+- lib/dry/cli/ui/logging.rb
+- lib/dry/cli/ui/report.rb
+- lib/dry/cli/ui/reporting.rb
 - lib/dry/cli/ui/status_bar.rb
 - lib/dry/cli/ui/stop.rb
 - lib/dry/cli/ui/terminal.rb
@@ -195,6 +242,7 @@ files:
 - lib/dry/cli/ui/version.rb
 - lib/dry/cli/ui/widgets.rb
 - lib/dry/cli/ui/widgets/box.rb
+- lib/dry/cli/ui/widgets/legend.rb
 - lib/dry/cli/ui/widgets/multi.rb
 - lib/dry/cli/ui/widgets/multi_progress.rb
 - lib/dry/cli/ui/widgets/multi_spinner.rb