brut 0.16.0 → 0.17.0

data/lib/brut/tui/markup_string.rb

@@ -0,0 +1,68 @@
+# A string that responds to limited markup that can be used to apply styles to the string
+class Brut::TUI::MarkupString
+  # Create a MarkupString from a normal string.
+  #
+  # @param string [String|Brut::TUI::MarkupString] string to convert.
+  # @return [Brut::TUI::MarkupString] if `string` is a `Brut::TUI::MarkupString` already, returns that, otherwise, wraps
+  #         `string` in a `Brut::TUI::MarkupString`.
+  def self.from_string(string)
+    string.kind_of?(Brut::TUI::MarkupString) ? string : self.new(string.to_s)
+  end
+
+  def initialize(string)
+    @string = string
+  end
+
+  DELIMITERS = {
+    "*" => :bold,
+    "_" => :weak,
+    "`" => :code,
+    "~" => :strike,
+  }.freeze
+
+  # Parse the string for known markup, yielding at key parsing events.
+  #
+  # @yield [directive, value] called for each parsing event, where value depends on directive.  The block
+  #        will be called for all parts of the string.
+  # @yieldparam directive [Symbol] one of `:start`, `:stop`, or `:text`. `:text` is for any text and doesn't include
+  #             the markup characters. `:start` and `:stop` are called when a markup start or stop is found.
+  # @yieldparam value [String|Symbol] For the `:text` `directive`, this is the text fragment from the string, so
+  #             for the string `"*foo*"`, `:text` would be called with `"foo"`.  For `:start` or `:stop`, the value
+  #             is the type of markup encountered, one of `:bold`, `:weak`, `:code`, or `:strike`.
+  def parse(&block)
+    in_delimiter = DELIMITERS.keys.map { [ it, false ] }.to_h
+
+    previous_character          = nil
+    previous_previous_character = nil
+
+    @string.each_char do |char|
+      if DELIMITERS.key?(char) && previous_character != "\\" && previous_previous_character != "\\"
+        style = DELIMITERS[char]
+        if in_delimiter[char]
+          block.(:stop, style)
+          in_delimiter[char] = false
+        else
+          inside_code = in_delimiter["`"]
+          if inside_code
+            block.(:text, char)
+          else
+            block.(:start, style)
+            in_delimiter[char] = true
+          end
+        end
+      else
+        if char == "\\"
+          if previous_character == "\\"
+            block.(:text, char)
+          else
+            # eat it - it is escaping something maybe
+          end
+        else
+          block.(:text, char)
+        end
+      end
+      previous_previous_character = previous_character
+      previous_character          = char
+    end
+  end
+end

data/lib/brut/tui/script/block_step.rb

@@ -0,0 +1,17 @@
+# A step whose behavior is a given block of code.
+# Fires {Brut::TUI::Script::Events::StepStarted} before
+# the code executes and {Brut::TUI::Script::Events::StepCompleted}
+# *only* if the block completes without an exception being thrown.
+class Brut::TUI::Script::BlockStep < Brut::TUI::Script::Step
+  def initialize(event_loop, description, &block)
+    super(event_loop, description)
+    @block = block
+  end
+
+  def run!
+    event_loop << Events::StepStarted.new(step: self)
+    @block.().tap {
+      event_loop << Events::StepCompleted.new(step: self)
+    }
+  end
+end

data/lib/brut/tui/script/events/command_execution_failed.rb

@@ -0,0 +1,4 @@
+# Fired when a subcommand exited nonzero
+class Brut::TUI::Script::Events::CommandExecutionFailed < Brut::TUI::Script::Events::ExecutingCommand
+  def exit? = true
+end

data/lib/brut/tui/script/events/command_execution_succeeded.rb

@@ -0,0 +1,3 @@
+# Fired when a subcommand exited zero (i.e. was successful)
+class Brut::TUI::Script::Events::CommandExecutionSucceeded < Brut::TUI::Script::Events::ExecutingCommand
+end

data/lib/brut/tui/script/events/command_std_err.rb

@@ -0,0 +1,3 @@
+# Fired when a command has provided at least some output on its standard error.
+class Brut::TUI::Script::Events::CommandStdErr < Brut::TUI::Script::Events::CommandStdOut
+end

data/lib/brut/tui/script/events/command_std_out.rb

@@ -0,0 +1,13 @@
+# Fired when a command has provided at least some output on its standard output.
+class Brut::TUI::Script::Events::CommandStdOut < Brut::TUI::Events::BaseEvent
+  def initialize(step:, output:)
+    @step   = step
+    @output = output
+  end
+
+  # Adds `description`, `command` and `output` to the event keywords. `output` is a string
+  # containing whatever output was available. This is likely not terminated with a newline.
+  def deconstruct_keys(keys=nil)
+    super.merge({ description: @step.description, command: @step.command, output: @output })
+  end
+end

data/lib/brut/tui/script/events/executing_command.rb

@@ -0,0 +1,12 @@
+# Fired when a command is executed (this also serves as a base class for the results
+# of such execution).
+class Brut::TUI::Script::Events::ExecutingCommand < Brut::TUI::Events::BaseEvent
+  def initialize(step:)
+    @step = step
+  end
+
+  # Includes `description` and `command` in the keyword arguments
+  def deconstruct_keys(keys=nil)
+    super.merge({ description: @step.description, command: @step.command })
+  end
+end

data/lib/brut/tui/script/events/message.rb

@@ -0,0 +1,15 @@
+# Fired when a step produces a message
+class Brut::TUI::Script::Events::Message < Brut::TUI::Events::BaseEvent
+  def initialize(message:, type:)
+    @message = message
+    @type    = type
+  end
+
+  def to_s = @message
+
+  # Includes `message` and `type`. `type` will be `:notify`, `:warning`, `:success`,
+  # `:error`, or `:done`, however it could be anything else the script may choose to use.
+  def deconstruct_keys(keys=nil)
+    super.merge({ message: @message, type: @type })
+  end
+end

data/lib/brut/tui/script/events/phase_completed.rb

@@ -0,0 +1,4 @@
+# Fired when a phase completes
+class Brut::TUI::Script::Events::PhaseCompleted < Brut::TUI::Script::Events::PhaseStarted
+  def to_s = "#{@name} completed"
+end

data/lib/brut/tui/script/events/phase_started.rb

@@ -0,0 +1,14 @@
+# Fired when a phase starts, but before any steps have executed
+class Brut::TUI::Script::Events::PhaseStarted < Brut::TUI::Events::BaseEvent
+  def initialize(description, step_number:, total_steps:)
+    @description = description
+    @step_number = step_number
+    @total_steps = total_steps
+  end
+
+  # Adds `description`, `step_number` (1-based), and `total_steps` to the keyword arguments.
+  def deconstruct_keys(keys=nil)
+    super.merge({ description: @description, step_number: @step_number, total_steps: @total_steps })
+  end
+  def to_s = @description
+end

data/lib/brut/tui/script/events/script_completed.rb

@@ -0,0 +1,5 @@
+# Fired when the script has completed
+class Brut::TUI::Script::Events::ScriptCompleted < Brut::TUI::Events::BaseEvent
+  def drain_then_exit? = true
+  def to_s = "Done"
+end

data/lib/brut/tui/script/events/script_started.rb

@@ -0,0 +1,12 @@
+# Fired when the script is just starting
+class Brut::TUI::Script::Events::ScriptStarted < Brut::TUI::Events::BaseEvent
+  def initialize(phases:)
+    @phases = phases
+  end
+  # Adds `phases` as an array of `[description,Proc]` representing the phases.
+  # You are discouraged from interacting with the `Proc` objects.
+  def deconstruct_keys(keys=nil)
+    super.merge({ phases: @phases })
+  end 
+  def to_s = "Starting"
+end

data/lib/brut/tui/script/events/step_completed.rb

@@ -0,0 +1,3 @@
+# Fired when a step completes.
+class Brut::TUI::Script::Events::StepCompleted < Brut::TUI::Script::Events::StepStarted
+end

data/lib/brut/tui/script/events/step_started.rb

@@ -0,0 +1,12 @@
+# Fired when a step is about to execute
+class Brut::TUI::Script::Events::StepStarted < Brut::TUI::Events::BaseEvent
+  def initialize(step:)
+    @step = step
+  end
+
+  # Adds `description` to the keyword arguments
+  def deconstruct_keys(keys=nil)
+    super.merge({ description: @step.description })
+  end
+  def to_s = @description
+end

data/lib/brut/tui/script/events.rb

@@ -0,0 +1,14 @@
+module Brut::TUI::Script::Events
+  autoload :ScriptStarted  , "brut/tui/script/events/script_started"
+  autoload :ScriptCompleted , "brut/tui/script/events/script_completed"
+  autoload :PhaseStarted   , "brut/tui/script/events/phase_started"
+  autoload :PhaseCompleted , "brut/tui/script/events/phase_completed"
+  autoload :StepStarted   , "brut/tui/script/events/step_started"
+  autoload :StepCompleted , "brut/tui/script/events/step_completed"
+  autoload :ExecutingCommand , "brut/tui/script/events/executing_command"
+  autoload :CommandStdOut, "brut/tui/script/events/command_std_out"
+  autoload :CommandStdErr, "brut/tui/script/events/command_std_err"
+  autoload :CommandExecutionSucceeded , "brut/tui/script/events/command_execution_succeeded"
+  autoload :CommandExecutionFailed , "brut/tui/script/events/command_execution_failed"
+  autoload :Message , "brut/tui/script/events/message"
+end

data/lib/brut/tui/script/exec_step.rb

@@ -0,0 +1,60 @@
+require "open3"
+
+# A step whose behavior is to run a command as a child process.
+# Fires {Brut::TUI::Script::Events::StepStarted} then
+# {Brut::TUI::Script::Events::ExecutingCommand} before the command is run.
+# The command is then run with `Open3.popen3` and the stderr and stdout
+# are streamed as output is available. Each block of bytes read
+# generates a {Brut::TUI::Script::Events::CommandStdOut}
+# or a {Brut::TUI::Script::Events::CommandStdErr} event with 
+# the bytes reads.
+#
+# If the command exited nonzero, 
+# {Brut::TUI::Script::Events::CommandExecutionSucceeded} is fired,
+# otherwise {Brut::TUI::Script::Events::CommandExecutionFailed} is fired,
+# Either way, {Brut::TUI::Script::Events::StepCompleted} is fired
+# *unless* there is an unhandled exception.
+class Brut::TUI::Script::ExecStep < Brut::TUI::Script::Step
+
+  attr_reader :command
+  def initialize(event_loop, description, command:)
+    super(event_loop, description)
+    @command = command
+  end
+
+  def deconstruct_keys(keys=nil)
+    super.deconstruct_keys(keys).merge({ command: @command, strip_ansi: false })
+  end
+  def run!
+    event_loop << Events::StepStarted.new(step: self)
+    event_loop << Events::ExecutingCommand.new(step: self)
+
+    wait_thread = Open3.popen3(*@command) do |_stdin,stdout,stderr,wait_thread|
+      o = stdout.read_nonblock(10, exception: false)
+      e = stderr.read_nonblock(10, exception: false)
+      while o || e
+        if o
+          if o != :wait_readable
+            event_loop << Events::CommandStdOut.new(step: self, output: o)
+          end
+          o = stdout.read_nonblock(10, exception: false)
+        end
+        if e
+          if e != :wait_readable
+            event_loop << Events::CommandStdErr.new(step: self, output: e)
+          end
+          e = stderr.read_nonblock(10, exception: false)
+        end
+      end
+      wait_thread
+    end
+
+    if wait_thread.value.success?
+      event_loop << Events::CommandExecutionSucceeded.new(step: self)
+    else
+      event_loop << Events::CommandExecutionFailed.new(step: self)
+    end
+    event_loop << Events::StepCompleted.new(step: self)
+  end
+end
+

data/lib/brut/tui/script/logging_subscriber.rb

@@ -0,0 +1,98 @@
+# A subscriber that uses Ruby's logger to log messages.
+# The purpose of this is to ensure that every bit of available information about
+# a `Script` is placed somewhere for later review. This allows any output to the terminal
+# to be more brief or user-friendly without losing information.
+class Brut::TUI::Script::LoggingSubscriber
+  def initialize(progname, logfile:)
+    @logger = Logger.new(logfile, progname:)
+    @logger.formatter = proc { |severity, time, progname, msg|
+      "#{time} - [ #{progname} ] #{severity}: #{strip_ansi(msg)}\n"
+    }
+    @stdout = {}
+    @stderr = {}
+  end
+
+  def on_event_loop_started(event)
+    @logger.debug("TUI Event loop started")
+  end
+
+  def on_exception(event)
+    @logger.error("#{event.exit? ? 'FATAL' : 'non-fatal'} ExceptionEvent: #{event.exception.class}: #{event.exception.message}\n    #{event.exception.backtrace.join("\n    ")}")
+  end
+
+  def on_executing_command(command:)
+    @logger.info("Executing command `#{command}`")
+    @stdout[command] = ''
+    @stderr[command] = ''
+  end
+
+  def on_command_std_out(command:, output:)
+    @stdout[command] << output
+  end
+
+  def on_command_std_err(command:, output:)
+    @stderr[command] << output
+  end
+
+  def on_command_execution_succeeded(command:)
+    if !@stdout[command].empty?
+      @logger.info("\n#{strip_ansi(@stdout[command])}")
+    end
+    if !@stderr[command].empty?
+      @logger.warn("\n#{strip_ansi(@stderr[command])}")
+    end
+    @logger.info("Command `#{command}` executed successfully.")
+  end
+
+  def on_command_execution_failed(command:)
+    if !@stdout[command].empty?
+      @logger.info("\n#{strip_ansi(@stdout[command])}")
+    end
+    if !@stderr[command].empty?
+      @logger.warn("\n#{strip_ansi(@stderr[command])}")
+    end
+    @logger.error("Command `#{command}` failed.")
+    raise "DOH"
+  end
+
+  def on_model_updated(*)
+  end
+
+  def on_tick(*)
+  end
+
+  def on_script_completed(*)
+  end
+
+  def on_script_started(*)
+  end
+
+  def on_any_event(event)
+    case event
+    in { description: }
+      @logger.info(description)
+    in { message:, type: :warning }
+      @logger.warn(message)
+    in { message:, type: :error }
+      @logger.error(message)
+    in { message: }
+      @logger.info(message)
+    in { handler_method_name: }
+      @logger.info(handler_method_name)
+    else
+      @logger.info(event.to_s)
+    end
+  end
+private
+
+  ANSI_ESCAPE = %r{ 
+    \e\[[@-Z\\-_] |           # 1-byte sequences
+    \e\[[0-?]*[ -\/]*[@-~] |  # CSI sequences
+    \e\][^\a]*\a |            # OSC sequences
+    \eP[^\a]*\a |             # DCS
+    \e_[^\a]*\a |             # APC
+    \e\^[^\a]*\a              # PM
+  }x
+
+  def strip_ansi(string) = string.gsub(ANSI_ESCAPE, '')
+end

data/lib/brut/tui/script/puts_subscriber.rb

@@ -0,0 +1,109 @@
+# A subscriber that attempts to provide a user-friend, brief, summarized, fancy
+# output for the script that is running.  It is intended to show you
+# what's happening at a high level, but deferring all details (like child process
+# output) to the {Brut::TUI::Script::LoggingSubscriber}'s log file.
+class Brut::TUI::Script::PutsSubscriber
+  def initialize(progname, terminal:, theme:, stdout: false, stderr: false)
+    @progname      = progname
+    @terminal      = terminal
+    @theme         = theme
+    @prefix_recent = false
+    @stdout        = stdout
+    @stderr        = stderr
+    @stdout_buffer = {}
+    @stderr_buffer = {}
+    @step_indent   = "Phase 1/1 ".length
+  end
+
+  def on_phase_started(description:, step_number:, total_steps:)
+    total_format_string = if total_steps < 10
+                            "%1d"
+                          else
+                            "%2d"
+                          end
+    preamble = sprintf("Phase %d/#{total_format_string}", step_number, total_steps)
+    @step_indent = preamble.length + 1
+    println @theme.reset + @theme.bold + preamble + @theme.reset + " " + @theme.with_markup(description, text: :heading)
+  end
+
+  def on_step_started(description:)
+    println @theme.with_markup(description), step_indent: true
+  end
+
+  def on_executing_command(command:)
+    println @theme.with_markup("> `#{command}`"), step_indent: true
+    $stdout.print @theme.reset
+    @stdout_buffer[command] = ""
+    @stderr_buffer[command] = ""
+  end
+
+  def on_command_execution_failed(command:)
+    println @theme.with_markup("FAILED", text: :error), step_indent: true
+    if !@stdout
+      println ""
+      println @stdout_buffer[command] + "\n"
+    end
+    if !@stderr
+      println ""
+      println @theme.warning + @stderr_buffer[command]
+    end
+
+  end
+
+  def on_exception(exception:)
+    println @theme.error + "Exception: #{exception.class}: #{exception.message}\n    #{exception.backtrace.join("\n    ")}"
+  end
+
+  def on_command_std_out(output:, command:)
+    if @stdout
+      @prefix_recent = false
+      $stdout.print @theme.normal + @theme.weak + output + @theme.reset
+      $stdout.flush
+    else
+      @stdout_buffer[command] << output
+    end
+  end
+
+  def on_command_std_err(output:, command:)
+    if @stderr
+      @prefix_recent = false
+      $stdout.print @theme.warning + output + @theme.reset
+      $stdout.flush
+    else
+      @stderr_buffer[command] << output
+    end
+  end
+
+  def on_command_execution_succeeded(command:)
+    println @theme.with_markup("✅", text: :success), step_indent: true
+  end
+
+  def on_message(message:, type:)
+    if type == :done
+      println @theme.with_markup(message, text: :success)
+    else
+      println @theme.with_markup(message, text: type), step_indent: true
+    end
+  end
+
+
+private
+
+  def prefix_string = "[ #{@progname} ] "
+
+  def step_indent = @step_indent
+
+  def println(message, step_indent: false)
+    @terminal.io.puts prefix + (step_indent ? " " * self.step_indent : "") + message
+  end
+
+  def prefix
+    if @prefix_recent
+      @theme.italic + @theme.weak + prefix_string + @theme.weak_off + @theme.italic_off
+    else
+      @prefix_recent = true
+      prefix_string
+    end
+  end
+end
+

data/lib/brut/tui/script/step.rb

@@ -0,0 +1,13 @@
+# Base class for specific types of steps
+class Brut::TUI::Script::Step
+
+  Events = Brut::TUI::Script::Events
+
+  attr_reader :description
+  def initialize(event_loop, description, exec: nil, &block)
+    @event_loop = event_loop
+    @description = description
+  end
+
+  private attr_reader :event_loop
+end