process_executer 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c875872382e447e7af6dfec78af45242baa13c7b832d5c25f3e146bbc2b9f1d
-  data.tar.gz: a68da52f9b1dfae542386a0d61abc85cdc0d86ee0471c4893692061db661f4e5
+  metadata.gz: 658921c991aa6654711a48a4638e0de6d998f9b5bcdabf8314cad15bb7294a0f
+  data.tar.gz: 7aee46a6fe1459cbd4e0bc9a67895a3c9946741b192e3766937b90ddad416c03
 SHA512:
-  metadata.gz: a0f6b19a6570dab6843b0d76af1839496ae7ff0651a3f485d6465414b3eb6f0d4a78236bc9ae80ad1b4d7e2e43d8c093ef2733e047eaadb27f3c2e7f174e5f82
-  data.tar.gz: 65da6657d7b821f2b0641bcad6278ded70fd78c06497dfa93fa67ab52c6bb0b57443fa6aa92b5cc160b68ff3b4b68165208b2ff77eea0f4b50542e1243a62c8e
+  metadata.gz: c25a01c7d819932a0495b18fc332744c860df5d25c8234df15071ac3ee66a9f6bc6b6e0101e2b02bc0fb691af3a7ac5bf9a77a98565b44964abcbc3d63f4451e
+  data.tar.gz: 915c369b55e999c726c22b2e3ef0b377ac0253afd115615d4cd2cb8ae17244c5f042bde4018bf31cb76ec30baf924761cb26e045577959b29e3f7aedcceddb65

data/.yardopts

@@ -3,6 +3,4 @@
 --markup-provider=redcarpet
 --markup markdown
 - CHANGELOG.md
-- CONTRIBUTING.md
-- RELEASING.md
 - LICENSE.txt

data/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to the process_executer gem will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v2.0.0 (2025-03-03)
+
+[Full Changelog](https://github.com/main-branch/process_executer/compare/v1.3.0..v2.0.0)
+
+Changes since v1.3.0:
+
+* f0836cc feat: refactor the interface to simplify the gem
+
+## v1.3.0 (2025-02-26)
+
+[Full Changelog](https://github.com/main-branch/process_executer/compare/v1.2.0..v1.3.0)
+
+Changes since v1.2.0:
+
+* d1e189b build: add Ruby 3.4 to the CI workflow
+* e805dfc feat: implement ProcessExecuter.run_command
+* bad822f fix: update the yard build in the rake file and update included files
+* 6fbdc5e feat: allow #spawn to accept file descriptors for redirection destination
+* d745685 test: make it so that tests do not give unnecessary output
+
 ## v1.2.0 (2024-10-10)
 
 [Full Changelog](https://github.com/main-branch/process_executer/compare/v1.1.2..v1.2.0)

data/README.md

@@ -11,15 +11,16 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
 [![Slack](https://img.shields.io/badge/slack-main--branch/process__executer-yellow.svg?logo=slack)](https://main-branch.slack.com/archives/C07NG2BPG8Y)
 
 * [Usage](#usage)
-  * [ProcessExecuter::MonitoredPipe](#processexecutermonitoredpipe)
-  * [ProcessExecuter.spawn](#processexecuterspawn)
+    * [ProcessExecuter.run](#processexecuterrun)
+    * [ProcessExecuter::MonitoredPipe](#processexecutermonitoredpipe)
+    * [ProcessExecuter.spawn\_and\_wait](#processexecuterspawn_and_wait)
 * [Installation](#installation)
 * [Contributing](#contributing)
-  * [Reporting Issues](#reporting-issues)
-  * [Developing](#developing)
-  * [Commit message guidelines](#commit-message-guidelines)
-  * [Pull request guidelines](#pull-request-guidelines)
-  * [Releasing](#releasing)
+    * [Reporting Issues](#reporting-issues)
+    * [Developing](#developing)
+    * [Commit message guidelines](#commit-message-guidelines)
+    * [Pull request guidelines](#pull-request-guidelines)
+    * [Releasing](#releasing)
 * [License](#license)
 
 ## Usage
@@ -29,6 +30,36 @@ gem is hosted on RubyGems.org. Read below of an overview and several examples.
 
 This gem contains the following important classes:
 
+### ProcessExecuter.run
+
+`ProcessExecuter.run` execute the given command as a subprocess blocking until it is finished.
+
+A Result object is returned which includes the process's status and output.
+
+Supports the same features as
+[Process.spawn](https://docs.ruby-lang.org/en/3.3/Process.html#method-c-spawn).
+In addition, it (1) blocks until the command has exited, (2) captures stdout and
+stderr to a buffer or file, and (3) can optionally kill the command if it exceeds
+a given timeout duration.
+
+This command takes two forms:
+
+1. When passing a single string the command is passed to a shell:
+
+    `ProcessExecuter.run([env, ] command_line, options = {}) ->` {ProcessExecuter::Result}
+
+2. When passing an array of strings the command is run directly (bypassing the shell):
+
+    `ProcessExecuter.run([env, ] exe_path, *args, options = {}) ->` {ProcessExecuter::Result}
+
+Argument env, if given, is a hash that affects ENV for the new process; see
+[Execution
+Environment](https://docs.ruby-lang.org/en/3.3/Process.html#module-Process-label-Execution+Environment).
+
+Argument options is a hash of options for the new process; see the options listed below.
+
+See comprehensive examples in the YARD documentation for this method.
+
 ### ProcessExecuter::MonitoredPipe
 
 `ProcessExecuter::MonitoredPipe` streams data sent through a pipe to one or more writers.
@@ -68,27 +99,27 @@ output_buffer.string #=> "Hello World\n"
 File.read('process.out') #=> "Hello World\n"
 ```
 
-Since the data is streamed, any object that implements `#write` can be used. For insance,
-you can use it to parse process output as a stream which might be useful for long XML
-or JSON output.
+Since the data is streamed, any object that implements `#write` can be used. For
+insance, you can use it to parse process output as a stream which might be useful for
+long XML or JSON output.
 
-### ProcessExecuter.spawn
+### ProcessExecuter.spawn_and_wait
 
 `ProcessExecuter.spawn` has the same interface as `Process.spawn` but has two
 important behaviorial differences:
 
 1. It blocks until the subprocess finishes
-2. A timeout can be specified using the `:timeout` option
+2. A timeout can be specified using the `:timeout_after` option
 
-If the command does not terminate before the timeout, the process is killed by
-sending it the SIGKILL signal. The returned status object's `timeout?` attribute will
-return `true`. For example:
+If the command does not terminate before the number of seconds specified by
+`:timeout_after`, the process is killed by sending it the SIGKILL signal. The
+returned Result object's `timed_out?` attribute will return `true`. For example:
 
 ```ruby
-status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
-status.signaled? #=> true
-status.termsig #=> 9
-status.timeout? #=> true
+result = ProcessExecuter.spawn_and_wait('sleep 10', timeout_after: 0.01)
+result.signaled? #=> true
+result.termsig #=> 9
+result.timed_out? #=> true
 ```
 
 ## Installation

data/Rakefile

@@ -7,7 +7,7 @@ desc 'Run the same tasks that the CI build will run'
 if RUBY_PLATFORM == 'java'
   task default: %w[spec rubocop bundle:audit build]
 else
-  task default: %w[spec rubocop yard yard:audit yard:coverage bundle:audit build]
+  task default: %w[spec rubocop yard bundle:audit build]
 end
 
 # Bundler Audit
@@ -50,28 +50,33 @@ RuboCop::RakeTask.new
 # YARD
 
 unless RUBY_PLATFORM == 'java'
-  # YARD
+  # yard:build
 
   require 'yard'
-  YARD::Rake::YardocTask.new do |t|
-    t.files = %w[lib/**/*.rb examples/**/*]
+
+  YARD::Rake::YardocTask.new('yard:build') do |t|
+    t.files = %w[lib/**/*.rb]
+    t.stats_options = ['--list-undoc']
   end
 
   CLEAN << '.yardoc'
   CLEAN << 'doc'
 
-  # Yardstick
+  # yard:audit
 
   desc 'Run yardstick to show missing YARD doc elements'
   task :'yard:audit' do
     sh "yardstick 'lib/**/*.rb'"
   end
 
-  # Yardstick coverage
+  # yard:coverage
 
   require 'yardstick/rake/verify'
 
   Yardstick::Rake::Verify.new(:'yard:coverage') do |verify|
     verify.threshold = 100
+    verify.require_exact_threshold = false
   end
+
+  task yard: %i[yard:build yard:audit yard:coverage]
 end

data/lib/process_executer/errors.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# rubocop:disable Layout/LineLength
+
+module ProcessExecuter
+  # Base class for all ProcessExecuter::Command errors
+  #
+  # It is recommended to rescue `ProcessExecuter::Error` to catch any
+  # runtime error raised by this gem unless you need more specific error handling.
+  #
+  # Custom errors are arranged in the following class hierarchy:
+  #
+  # ```text
+  # ::StandardError
+  #   └─> Error
+  #       ├─> CommandError
+  #       │   ├─> FailedError
+  #       │   └─> SignaledError
+  #       │       └─> TimeoutError
+  #       └─> ProcessIOError
+  # ```
+  #
+  # | Error Class | Description |
+  # | --- | --- |
+  # | `Error` | This catch-all error serves as the base class for other custom errors. |
+  # | `CommandError` | A subclass of this error is raised when there is a problem executing a command. |
+  # | `FailedError` | Raised when the command exits with a non-zero status code. |
+  # | `SignaledError` | Raised when the command is terminated as a result of receiving a signal. This could happen if the process is forcibly terminated or if there is a serious system error. |
+  # | `TimeoutError` | This is a specific type of `SignaledError` that is raised when the command times out and is killed via the SIGKILL signal. Raised when the operation takes longer than the specified timeout duration (if provided). |
+  # | `ProcessIOError` | Raised when an error was encountered reading or writing to the command's subprocess. |
+  #
+  # @example Rescuing any error
+  #   begin
+  #     ProcessExecuter.run_command('git', 'status')
+  #   rescue ProcessExecuter::Error => e
+  #     puts "An error occurred: #{e.message}"
+  #   end
+  #
+  # @example Rescuing a timeout error
+  #   begin
+  #     timeout_after = 0.1 # seconds
+  #     ProcessExecuter.run_command('sleep', '1', timeout_after:)
+  #   rescue ProcessExecuter::TimeoutError => e # Catch the more specific error first!
+  #     puts "Command took too long and timed out: #{e}"
+  #   rescue ProcessExecuter::Error => e
+  #     puts "Some other error occured: #{e}"
+  #   end
+  #
+  # @api public
+  #
+  class Error < ::StandardError; end
+
+  # Raised when a command fails or exits because of an uncaught signal
+  #
+  # The command executed, status, stdout, and stderr are available from this
+  # object.
+  #
+  # The Gem will raise a more specific error for each type of failure:
+  #
+  # * {FailedError}: when the command exits with a non-zero status
+  # * {SignaledError}: when the command exits because of an uncaught signal
+  # * {TimeoutError}: when the command times out
+  #
+  # @api public
+  #
+  class CommandError < ProcessExecuter::Error
+    # Create a CommandError object
+    #
+    # @example
+    #   `exit 1` # set $? appropriately for this example
+    #   result = ProcessExecuter::Result.new(%w[git status], $?, 'stdout', 'stderr')
+    #   error = ProcessExecuter::CommandError.new(result)
+    #   error.to_s #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #
+    # @param result [Result] The result of the command including the command,
+    #   status, stdout, and stderr
+    #
+    def initialize(result)
+      @result = result
+      super(error_message)
+    end
+
+    # The human readable representation of this error
+    #
+    # @example
+    #   error.error_message #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #
+    # @return [String]
+    #
+    def error_message
+      "#{result.command}, status: #{result}, stderr: #{result.stderr.inspect}"
+    end
+
+    # @attribute [r] result
+    #
+    # The result of the command including the command, its status and its output
+    #
+    # @example
+    #   error.result #=> #<ProcessExecuter::Result:0x00007f9b1b8b3d20>
+    #
+    # @return [Result]
+    #
+    attr_reader :result
+  end
+
+  # Raised when the command returns a non-zero exitstatus
+  #
+  # @api public
+  #
+  class FailedError < ProcessExecuter::CommandError; end
+
+  # Raised when the command exits because of an uncaught signal
+  #
+  # @api public
+  #
+  class SignaledError < ProcessExecuter::CommandError; end
+
+  # Raised when the command takes longer than the configured timeout_after
+  #
+  # @example
+  #   result.timed_out? #=> true
+  #
+  # @api public
+  #
+  class TimeoutError < ProcessExecuter::SignaledError; end
+
+  # Raised when the output of a command can not be read
+  #
+  # @api public
+  #
+  class ProcessIOError < ProcessExecuter::Error; end
+end
+
+# rubocop:enable Layout/LineLength

data/lib/process_executer/monitored_pipe.rb

@@ -281,19 +281,56 @@ module ProcessExecuter
     # @api private
     def monitor_pipe
       new_data = pipe_reader.read_nonblock(chunk_size)
-      # SimpleCov under JRuby reports the begin statement as not covered, but it is
-      # :nocov:
-      begin
-        # :nocov:
-        writers.each { |w| w.write(new_data) }
-      rescue StandardError => e
-        @exception = e
-        @state = :closing
-      end
+      write_data(new_data)
     rescue IO::WaitReadable
       pipe_reader.wait_readable(0.001)
     end
 
+    # Check if the writer is a file descriptor
+    #
+    # @param writer [#write] the writer to check
+    # @return [Boolean] true if the writer is a file descriptor
+    # @api private
+    def file_descriptor?(writer) = writer.is_a?(Integer) || writer.is_a?(Symbol)
+
+    # Write the data read from the pipe to all destinations
+    #
+    # If an exception is raised by a writer, set the state to `:closing`
+    # so that the pipe can be closed.
+    #
+    # @param data [String] the data read from the pipe
+    # @return [void]
+    # @api private
+    def write_data(data)
+      writers.each do |w|
+        file_descriptor?(w) ? write_data_to_fd(w, data) : w.write(data)
+      end
+    rescue StandardError => e
+      @exception = e
+      @state = :closing
+    end
+
+    # Write data to the given file_descriptor correctly handling stdout and stderr
+    # @param file_descriptor [Integer, Symbol] the file descriptor to write to (either an integer or :out or :err)
+    # @param data [String] the data to write
+    # @return [void]
+    # @api private
+    def write_data_to_fd(file_descriptor, data)
+      # The case line is not marked as not covered only when using TruffleRuby
+      # :nocov:
+      case file_descriptor
+      # :nocov:
+      when :out, 1
+        $stdout.write data
+      when :err, 2
+        $stderr.write data
+      else
+        io = IO.open(file_descriptor, mode: 'a', autoclose: false)
+        io.write(data)
+        io.close
+      end
+    end
+
     # Read any remaining data from the pipe and close it
     #
     # @return [void]

data/lib/process_executer/options.rb

@@ -7,7 +7,7 @@ module ProcessExecuter
   #
   # Valid options are those accepted by Process.spawn plus the following additions:
   #
-  # * `:timeout`:
+  # * `:timeout_after`: the number of seconds to allow a process to run before killing it
   #
   # @api public
   #
@@ -30,7 +30,7 @@ module ProcessExecuter
     # to `Process.spawn`
     #
     NON_SPAWN_OPTIONS = %i[
-      timeout
+      timeout_after raise_errors
     ].freeze
 
     # Any `SPAWN_OPTIONS` set to `NOT_SET` will not be passed to `Process.spawn`
@@ -50,7 +50,8 @@ module ProcessExecuter
       umask: NOT_SET,
       close_others: NOT_SET,
       chdir: NOT_SET,
-      timeout: nil
+      raise_errors: true,
+      timeout_after: nil
     }.freeze
 
     # :nocov:
@@ -71,14 +72,14 @@ module ProcessExecuter
     # Create a new Options object
     #
     # @example
-    #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout: 10)
+    #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout_after: 10)
     #
     # @param options [Hash] Process.spawn options plus additional options listed below.
     #
     #   See [Process.spawn](https://ruby-doc.org/core/Process.html#method-c-spawn)
     #   for a list of valid options that can be passed to `Process.spawn`.
     #
-    # @option options [Integer, Float, nil] :timeout
+    # @option options [Integer, Float, nil] :timeout_after
     #   Number of seconds to wait for the process to terminate. Any number
     #   may be used, including Floats to specify fractional seconds. A value of 0 or nil
     #   will allow the process to run indefinitely.
@@ -92,7 +93,7 @@ module ProcessExecuter
     # Returns the options to be passed to Process.spawn
     #
     # @example
-    #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout: 10)
+    #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout_after: 10)
     #   options.spawn_options # => { out: $stdout, err: $stderr }
     #
     # @return [Hash]
@@ -130,22 +131,24 @@ module ProcessExecuter
       raise ArgumentError, "Unknown options: #{unknown_options.join(', ')}" unless unknown_options.empty?
     end
 
-    # Raise an error if timeout is not a real non-negative number
+    # Raise an error if timeout_after is not a non-negative real number
     # @return [void]
-    # @raise [ArgumentError] if timeout is not a real non-negative number
+    # @raise [ArgumentError] if timeout_after is not a non-negative real number
     # @api private
     def assert_timeout_is_valid
-      return if @options[:timeout].nil?
-      return if @options[:timeout].is_a?(Numeric) && @options[:timeout].real? && !@options[:timeout].negative?
+      return if @options[:timeout_after].nil?
+      return if @options[:timeout_after].is_a?(Numeric) &&
+                @options[:timeout_after].real? &&
+                !@options[:timeout_after].negative?
 
-      raise ArgumentError, invalid_timeout_message
+      raise ArgumentError, invalid_timeout_after_message
     end
 
-    # The message to be used when raising an error for an invalid timeout
+    # The message to be used when raising an error for an invalid timeout_after
     # @return [String]
     # @api private
-    def invalid_timeout_message
-      "timeout must be nil or a real non-negative number but was #{options[:timeout].pretty_inspect}"
+    def invalid_timeout_after_message
+      "timeout_after must be nil or a non-negative real number but was #{options[:timeout_after].pretty_inspect}"
     end
 
     # Determine if the given option is a valid option

data/lib/process_executer/result.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module ProcessExecuter
+  # A decorator for Process::Status that adds the following attributes:
+  #
+  # * `command`: the command that was used to spawn the process
+  # * `options`: the options that were used to spawn the process
+  # * `elapsed_time`: the secs the command ran
+  # * `stdout`: the captured stdout output
+  # * `stderr`: the captured stderr output
+  # * `timed_out?`: true if the process timed out
+  #
+  # @api public
+  #
+  class Result < SimpleDelegator
+    # Create a new Result object
+    #
+    # @param status [Process::Status] the status to delegate to
+    # @param command [Array] the command that was used to spawn the process
+    # @param options [ProcessExecuter::Options] the options that were used to spawn the process
+    # @param timed_out [Boolean] true if the process timed out
+    # @param elapsed_time [Numeric] the secs the command ran
+    #
+    # @example
+    #   command = ['sleep 1']
+    #   options = ProcessExecuter::Options.new(timeout_after: 0.5)
+    #   start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    #   timed_out = false
+    #   status = nil
+    #   pid = Process.spawn(*command, **options.spawn_options)
+    #   Timeout.timeout(options.timeout_after) do
+    #     _pid, status = Process.wait2(pid)
+    #   rescue Timeout::Error
+    #     Process.kill('KILL', pid)
+    #     timed_out = true
+    #     _pid, status = Process.wait2(pid)
+    #   end
+    #   elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+    #
+    #   ProcessExecuter::Result.new(status, command:, options:, timed_out:, elapsed_time:)
+    #
+    # @api public
+    #
+    def initialize(status, command:, options:, timed_out:, elapsed_time:)
+      super(status)
+      @command = command
+      @options = options
+      @timed_out = timed_out
+      @elapsed_time = elapsed_time
+    end
+
+    # The command that was used to spawn the process
+    # @see Process.spawn
+    # @example
+    #   result.command #=> [{ 'GIT_DIR' => '/path/to/repo' }, 'git', 'status']
+    # @return [Array]
+    attr_reader :command
+
+    # The options that were used to spawn the process
+    # @see Process.spawn
+    # @example
+    #   result.options #=> { chdir: '/path/to/repo', timeout_after: 0.5 }
+    # @return [Hash]
+    # @api public
+    attr_reader :options
+
+    # The secs the command ran
+    # @example
+    #   result.elapsed_time #=> 10
+    # @return [Numeric, nil]
+    # @api public
+    attr_reader :elapsed_time
+
+    # @!attribute [r] timed_out?
+    # True if the process timed out and was sent the SIGKILL signal
+    # @example
+    #   result = ProcessExecuter.spawn('sleep 10', timeout_after: 0.01)
+    #   result.timed_out? # => true
+    # @return [Boolean]
+    #
+    def timed_out? = @timed_out
+
+    # Overrides the default success? method to return nil if the process timed out
+    #
+    # This is because when a timeout occurs, Windows will still return true.
+    #
+    # @example
+    #   result = ProcessExecuter.spawn('sleep 10', timeout_after: 0.01)
+    #   result.success? # => nil
+    # @return [true, nil]
+    #
+    def success?
+      return nil if timed_out? # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+
+      super
+    end
+
+    # Return a string representation of the result
+    # @example
+    #   result.to_s #=> "pid 70144 SIGKILL (signal 9) timed out after 10s"
+    # @return [String]
+    def to_s
+      "#{super}#{timed_out? ? " timed out after #{options.timeout_after}s" : ''}"
+    end
+
+    # Return the captured stdout output
+    #
+    # This output is only returned if the `:out` option was set to a
+    # `ProcessExecuter::MonitoredPipe` that includes a writer that implements `#string`
+    # method (e.g. a StringIO).
+    #
+    # @example
+    #   # Note that `ProcessExecuter.run` will wrap the given out: object in a
+    #   # ProcessExecuter::MonitoredPipe
+    #   result = ProcessExecuter.run('echo hello': out: StringIO.new)
+    #   result.stdout #=> "hello\n"
+    #
+    # @return [String, nil]
+    #
+    def stdout
+      Array(options.out).each do |pipe|
+        next unless pipe.is_a?(ProcessExecuter::MonitoredPipe)
+
+        pipe.writers.each do |writer|
+          return writer.string if writer.respond_to?(:string)
+        end
+      end
+
+      nil
+    end
+
+    # Return the captured stderr output
+    #
+    # This output is only returned if the `:err` option was set to a
+    # `ProcessExecuter::MonitoredPipe` that includes a writer that implements `#string`
+    # method (e.g. a StringIO).
+    #
+    # @example
+    #   # Note that `ProcessExecuter.run` will wrap the given err: object in a
+    #   # ProcessExecuter::MonitoredPipe
+    #   result = ProcessExecuter.run('echo ERROR 1>&2', err: StringIO.new)
+    #   resuilt.stderr #=> "ERROR\n"
+    #
+    # @return [String, nil]
+    #
+    def stderr
+      Array(options.err).each do |pipe|
+        next unless pipe.is_a?(ProcessExecuter::MonitoredPipe)
+
+        pipe.writers.each do |writer|
+          return writer.string if writer.respond_to?(:string)
+        end
+      end
+
+      nil
+    end
+  end
+end

data/lib/process_executer/runner.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module ProcessExecuter
+  # The `Runner` class executes subprocess commands and captures their status and output.
+  #
+  # It does the following:
+  # - Run commands (`call`) with options for capturing output, handling timeouts, and merging stdout/stderr.
+  # - Process command results, including logging and error handling.
+  # - Raise detailed exceptions for common command failures, such as timeouts or subprocess errors.
+  #
+  # This class is used internally by {ProcessExecuter.run}.
+  #
+  # @api public
+  #
+  class Runner
+    # Create a new RunCommand instance
+    #
+    # @example
+    #   runner = Runner.new()
+    #   result = runner.call('echo', 'hello')
+    #
+    # @param logger [Logger] The logger to use. Defaults to a no-op logger if nil.
+    #
+    def initialize(logger = Logger.new(nil))
+      @logger = logger
+    end
+
+    # The logger to use
+    # @example
+    #   runner.logger #=> #<Logger:0x00007f9b1b8b3d20>
+    # @return [Logger]
+    attr_reader :logger
+
+    # Run a command and return the status including stdout and stderr output
+    #
+    # @example
+    #   runner = ProcessExecuter::Runner.new()
+    #   result = runner.call('echo hello')
+    #   result = ProcessExecuter.run('echo hello')
+    #   result.success? # => true
+    #   result.exitstatus # => 0
+    #   result.stdout # => "hello\n"
+    #   result.stderr # => ""
+    #
+    # @param command [Array<String>] The command to run
+    # @param out [#write, Array<#write>, nil] The object (or array of objects) to which stdout is written
+    # @param err [#write, Array<#write>, nil] The object (or array of objects) to which stderr is written
+    # @param merge [Boolean] Write both stdout and stderr into the buffer for stdout
+    # @param options_hash [Hash] Additional options to pass to Process.spawn
+    #
+    #   See {ProcessExecuter.run} for a full list of options.
+    #
+    # @return [ProcessExecuter::Result] The result of the completed subprocess
+    #
+    def call(*command, out: nil, err: nil, merge: false, **options_hash)
+      out ||= StringIO.new
+      err ||= (merge ? out : StringIO.new)
+
+      spawn(command, out:, err:, **options_hash).tap { |result| process_result(result) }
+    end
+
+    private
+
+    # Wrap the output buffers in pipes and then execute the command
+    #
+    # @param command [Array<String>] The command to execute
+    # @param out [#write, Array<#write>] The object (or array of objects) to which stdout is written
+    # @param err [#write, Array<#write>] The object (or array of objects) to which stderr is written
+    # @param options_hash [Hash] Additional options to pass to Process.spawn
+    #
+    #   See {ProcessExecuter.run} for a full list of options.
+    #
+    # @raise [ProcessExecuter::ProcessIOError] If an exception was raised while collecting subprocess output
+    # @raise [ProcessExecuter::TimeoutError] If the command times out
+    #
+    # @return [ProcessExecuter::Result] The result of the completed subprocess
+    #
+    # @api private
+    #
+    def spawn(command, out:, err:, **options_hash)
+      out = [out] unless out.is_a?(Array)
+      err = [err] unless err.is_a?(Array)
+      out_pipe = ProcessExecuter::MonitoredPipe.new(*out)
+      err_pipe = ProcessExecuter::MonitoredPipe.new(*err)
+      ProcessExecuter.spawn_and_wait(*command, out: out_pipe, err: err_pipe, **options_hash)
+    ensure
+      out_pipe.close
+      err_pipe.close
+      raise_pipe_error(command, :stdout, out_pipe) if out_pipe.exception
+      raise_pipe_error(command, :stderr, err_pipe) if err_pipe.exception
+    end
+
+    # Process the result of the command and return a ProcessExecuter::Result
+    #
+    # Log the command and result, and raise an error if the command failed.
+    #
+    # @param result [ProcessExecuter::Result] The result of the command
+    #
+    # @return [Void]
+    #
+    # @raise [ProcessExecuter::FailedError] If the command failed
+    # @raise [ProcessExecuter::SignaledError] If the command was signaled
+    # @raise [ProcessExecuter::TimeoutError] If the command times out
+    # @raise [ProcessExecuter::ProcessIOError] If an exception was raised while collecting subprocess output
+    #
+    # @api private
+    #
+    def process_result(result)
+      log_result(result)
+
+      return unless result.options.raise_errors
+
+      raise TimeoutError, result if result.timed_out?
+      raise SignaledError, result if result.signaled?
+      raise FailedError, result unless result.success?
+    end
+
+    # Log the result of running the command
+    # @param result [ProcessExecuter::Result] the result of the command including
+    #   the command, status, stdout, and stderr
+    # @return [void]
+    # @api private
+    def log_result(result)
+      logger.info { "#{result.command} exited with status #{result}" }
+      logger.debug { "stdout:\n#{result.stdout.inspect}\nstderr:\n#{result.stderr.inspect}" }
+    end
+
+    # Raise an error when there was exception while collecting the subprocess output
+    #
+    # @param command [Array<String>] The command that was executed
+    # @param pipe_name [Symbol] The name of the pipe that raised the exception
+    # @param pipe [ProcessExecuter::MonitoredPipe] The pipe that raised the exception
+    #
+    # @raise [ProcessExecuter::ProcessIOError]
+    #
+    # @return [void] This method always raises an error
+    #
+    # @api private
+    #
+    def raise_pipe_error(command, pipe_name, pipe)
+      error = ProcessExecuter::ProcessIOError.new("Pipe Exception for #{command}: #{pipe_name}")
+      raise(error, cause: pipe.exception)
+    end
+  end
+end

data/lib/process_executer/version.rb

@@ -2,5 +2,5 @@
 
 module ProcessExecuter
   # The current Gem version
-  VERSION = '1.2.0'
+  VERSION = '2.0.0'
 end

data/lib/process_executer.rb

@@ -1,77 +1,331 @@
 # frozen_string_literal: true
 
+require 'process_executer/errors'
 require 'process_executer/monitored_pipe'
 require 'process_executer/options'
-require 'process_executer/status'
+require 'process_executer/result'
+require 'process_executer/runner'
 
+require 'logger'
 require 'timeout'
 
-# Execute a command in a subprocess and optionally capture its output
+# The `ProcessExecuter` module provides methods to execute subprocess commands
+# with enhanced features such as output capture, timeout handling, and custom
+# environment variables.
+#
+# Methods:
+# * {run}: Executes a command and returns the result which includes the process
+#   status and output
+# * {spawn_and_wait}: a thin wrapper around `Process.spawn` that blocks until the
+#   command finishes
+#
+# Features:
+# * Supports executing commands via a shell or directly.
+# * Captures stdout and stderr to buffers, files, or custom objects.
+# * Optionally enforces timeouts and terminates long-running commands.
+# * Provides detailed status information, including the command that was run, the
+#   options that were given, and success, failure, or timeout states.
 #
 # @api public
 #
 module ProcessExecuter
-  # Execute the specified command as a subprocess and return the exit status
+  # Run a command in a subprocess, wait for it to finish, then return the result
   #
-  # This is a convenience method that calls Process.spawn and blocks until the
-  # command has terminated.
+  # This method is a thin wrapper around
+  # [Process.spawn](https://docs.ruby-lang.org/en/3.3/Process.html#method-c-spawn)
+  # and blocks until the command terminates.
   #
-  # The command will be send the SIGKILL signal if it does not terminate within
-  # the specified timeout.
+  # A timeout may be specified with the `:timeout_after` option. The command will be
+  # sent the SIGKILL signal if it does not terminate within the specified timeout.
   #
   # @example
-  #   status = ProcessExecuter.spawn('echo hello')
-  #   status.exited? # => true
-  #   status.success? # => true
-  #   status.timeout? # => false
+  #   result = ProcessExecuter.spawn_and_wait('echo hello')
+  #   result.exited? # => true
+  #   result.success? # => true
+  #   result.timed_out? # => false
   #
   # @example with a timeout
-  #   status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
-  #   status.exited? # => false
-  #   status.success? # => nil
-  #   status.signaled? # => true
-  #   status.termsig # => 9
-  #   status.timeout? # => true
+  #   result = ProcessExecuter.spawn_and_wait('sleep 10', timeout_after: 0.01)
+  #   result.exited? # => false
+  #   result.success? # => nil
+  #   result.signaled? # => true
+  #   result.termsig # => 9
+  #   result.timed_out? # => true
   #
   # @example capturing stdout to a string
-  #   stdout = StringIO.new
-  #   status = ProcessExecuter.spawn('echo hello', out: stdout)
-  #   stdout.string # => "hello"
+  #   stdout_buffer = StringIO.new
+  #   stdout_pipe = ProcessExecuter::MonitoredPipe.new(stdout_buffer)
+  #   result = ProcessExecuter.spawn_and_wait('echo hello', out: stdout_pipe)
+  #   stdout_buffer.string # => "hello\n"
   #
   # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-spawn Kernel.spawn
   #   documentation for valid command and options
   #
-  # @see ProcessExecuter::Options#initialize See ProcessExecuter::Options#initialize
-  #   for options that may be specified
+  # @see ProcessExecuter::Options#initialize ProcessExecuter::Options#initialize for
+  #   options that may be specified
   #
-  # @param command [Array<String>] the command to execute
-  # @param options_hash [Hash] the options to use when exectuting the command
+  # @param command [Array<String>] The command to execute
+  # @param options_hash [Hash] The options to use when executing the command
   #
-  # @return [Process::Status] the exit status of the proceess
+  # @return [ProcessExecuter::Result] The result of the completed subprocess
   #
-  def self.spawn(*command, **options_hash)
+  def self.spawn_and_wait(*command, **options_hash)
     options = ProcessExecuter::Options.new(**options_hash)
     pid = Process.spawn(*command, **options.spawn_options)
-    wait_for_process(pid, options)
+    wait_for_process(pid, command, options)
+  end
+
+  # Execute the given command as a subprocess blocking until it finishes
+  #
+  # Works just like {ProcessExecuter.spawn}, but does the following in addition:
+  #
+  #   1. If nothing is specified for `out`, stdout is captured to a `StringIO` object
+  #      which can be accessed via the Result object in `result.options.out`. The
+  #      same applies to `err`.
+  #
+  #   2. If `merge` is set to `true`, stdout and stderr are captured to the same
+  #      buffer.
+  #
+  #   3. `out` and `err` are automatically wrapped in a
+  #      `ProcessExecuter::MonitoredPipe` object so that any object that implements
+  #      `#write` (or an Array of such objects) can be given for `out` and `err`.
+  #
+  #   4. Raises one of the following errors unless `raise_errors` is explicitly set
+  #      to `false`:
+  #
+  #      * `ProcessExecuter::FailedError` if the command returns a non-zero
+  #        exitstatus
+  #      * `ProcessExecuter::SignaledError` if the command exits because of
+  #        an unhandled signal
+  #      * `ProcessExecuter::TimeoutError` if the command times out
+  #
+  #      If `raise_errors` is false, the returned Result object will contain the error.
+  #
+  #   5. Raises a `ProcessExecuter::ProcessIOError` if an exception is raised
+  #      while collecting subprocess output. This can not be turned off.
+  #
+  #   6. If a `logger` is provided, it will be used to log:
+  #
+  #      * The command that was executed and its status to `info` level
+  #      * The stdout and stderr output to `debug` level
+  #
+  #     By default, Logger.new(nil) is used for the logger.
+  #
+  # This method takes two forms:
+  #
+  # 1. The command is executed via a shell when the command is given as a single
+  #    string:
+  #
+  #     `ProcessExecuter.run([env, ] command_line, options = {}) ->` {ProcessExecuter::Result}
+  #
+  # 2. The command is executed directly (bypassing the shell) when the command and it
+  #    arguments are given as an array of strings:
+  #
+  #     `ProcessExecuter.run([env, ] exe_path, *args, options = {}) ->` {ProcessExecuter::Result}
+  #
+  # Optional argument `env` is a hash that affects ENV for the new process; see
+  # [Execution
+  # Environment](https://docs.ruby-lang.org/en/3.3/Process.html#module-Process-label-Execution+Environment).
+  #
+  # Argument `options` is a hash of options for the new process. See the options listed below.
+  #
+  # @example Run a command given as a single string (uses shell)
+  #   # The command must be properly shell escaped when passed as a single string.
+  #   command = 'echo "stdout: `pwd`" && echo "stderr: $HOME" 1>&2'
+  #   result = ProcessExecuter.run(command)
+  #   result.success? #=> true
+  #   result.stdout #=> "stdout: /Users/james/projects/main-branch/process_executer\n"
+  #   result.stderr #=> "stderr: /Users/james\n"
+  #
+  # @example Run a command given as an array of strings (does not use shell)
+  #   # The command and its args must be provided as separate strings in the array.
+  #   # Shell expansions and redirections are not supported.
+  #   command = ['git', 'clone', 'https://github.com/main-branch/process_executer']
+  #   result = ProcessExecuter.run(*command)
+  #   result.success? #=> true
+  #   result.stdout #=> ""
+  #   result.stderr #=> "Cloning into 'process_executer'...\n"
+  #
+  # @example Run a command with a timeout
+  #   command = ['sleep', '1']
+  #   result = ProcessExecuter.run(*command, timeout_after: 0.01)
+  #   #=> raises ProcessExecuter::TimeoutError which contains the command result
+  #
+  # @example Run a command which fails
+  #   command = ['exit 1']
+  #   result = ProcessExecuter.run(*command)
+  #   #=> raises ProcessExecuter::FailedError which contains the command result
+  #
+  # @example Run a command which exits due to an unhandled signal
+  #   command = ['kill -9 $$']
+  #   result = ProcessExecuter.run(*command)
+  #   #=> raises ProcessExecuter::SignaledError which contains the command result
+  #
+  # @example Do not raise an error when the command fails
+  #   command = ['echo "Some error" 1>&2 && exit 1']
+  #   result = ProcessExecuter.run(*command, raise_errors: false)
+  #   result.success? #=> false
+  #   result.exitstatus #=> 1
+  #   result.stdout #=> ""
+  #   result.stderr #=> "Some error\n"
+  #
+  # @example Set environment variables
+  #   env = { 'FOO' => 'foo', 'BAR' => 'bar' }
+  #   command = 'echo "$FOO$BAR"'
+  #   result = ProcessExecuter.run(env, *command)
+  #   result.stdout #=> "foobar\n"
+  #
+  # @example Set environment variables when using a command array
+  #   env = { 'FOO' => 'foo', 'BAR' => 'bar' }
+  #   command = ['ruby', '-e', 'puts ENV["FOO"] + ENV["BAR"]']
+  #   result = ProcessExecuter.run(env, *command)
+  #   result.stdout #=> "foobar\n"
+  #
+  # @example Unset environment variables
+  #   env = { 'FOO' => nil } # setting to nil unsets the variable in the environment
+  #   command = ['echo "FOO: $FOO"']
+  #   result = ProcessExecuter.run(env, *command)
+  #   result.stdout #=> "FOO: \n"
+  #
+  # @example Reset existing environment variables and add new ones
+  #   env = { 'PATH' => '/bin' }
+  #   result = ProcessExecuter.run(env, 'echo "Home: $HOME" && echo "Path: $PATH"', unsetenv_others: true)
+  #   result.stdout #=> "Home: \n/Path: /bin\n"
+  #
+  # @example Run command in a different directory
+  #   command = ['pwd']
+  #   result = ProcessExecuter.run(*command, chdir: '/tmp')
+  #   result.stdout #=> "/tmp\n"
+  #
+  # @example Capture stdout and stderr into a single buffer
+  #   command = ['echo "stdout" && echo "stderr" 1>&2']
+  #   result = ProcessExecuter.run(*command, merge: true)
+  #   result.stdout #=> "stdout\nstderr\n"
+  #   result.stderr #=> "stdout\nstderr\n"
+  #   result.stdout.object_id == result.stderr.object_id #=> true
+  #
+  # @example Capture to an explicit buffer
+  #   out = StringIO.new
+  #   err = StringIO.new
+  #   command = ['echo "stdout" && echo "stderr" 1>&2']
+  #   result = ProcessExecuter.run(*command, out: out, err: err)
+  #   out.string #=> "stdout\n"
+  #   err.string #=> "stderr\n"
+  #
+  # @example Capture to a file
+  #   # Same technique can be used for stderr
+  #   out = File.open('stdout.txt', 'w')
+  #   err = StringIO.new
+  #   command = ['echo "stdout" && echo "stderr" 1>&2']
+  #   result = ProcessExecuter.run(*command, out: out, err: err)
+  #   out.close
+  #   File.read('stdout.txt') #=> "stdout\n"
+  #   # stderr is still captured to a StringIO buffer internally
+  #   result.stderr #=> "stderr\n"
+  #
+  # @example Capture to multiple writers (e.g. files, buffers, STDOUT, etc.)
+  #   # Same technique can be used for stderr
+  #   out_buffer = StringIO.new
+  #   out_file = File.open('stdout.txt', 'w')
+  #   command = ['echo "stdout" && echo "stderr" 1>&2']
+  #   result = ProcessExecuter.run(*command, out: [out_buffer, out_file])
+  #   # You must manage closing resources you create yourself
+  #   out_file.close
+  #   out_buffer.string #=> "stdout\n"
+  #   File.read('stdout.txt') #=> "stdout\n"
+  #   # Since one of the out writers has a #string method, Result#stdout will
+  #   # return the string from that writer
+  #   result.stdout #=> "stdout\n"
+  #
+  # @param command [Array<String>] The command to run
+  #
+  #   If the first element of command is a Hash, it is added to the ENV of
+  #   the new process. See [Execution Environment](https://ruby-doc.org/3.3.6/Process.html#module-Process-label-Execution+Environment)
+  #   for more details. The env hash is then removed from the command array.
+  #
+  #   If the first and only (remaining) command element is a string, it is passed to
+  #   a subshell if it begins with a shell reserved word, contains special built-ins,
+  #   or includes shell metacharacters.
+  #
+  #   Care must be taken to properly escape shell metacharacters in the command string.
+  #
+  #   Otherwise, the command is run bypassing the shell. When bypassing the shell, shell expansions
+  #   and redirections are not supported.
+  #
+  # @param logger [Logger] The logger to use
+  # @param options_hash [Hash] Additional options
+  # @option options_hash [Numeric] :timeout_after The maximum seconds to wait for the
+  #   command to complete
+  #
+  #     If zero or nil, the command will not time out. If the command
+  #     times out, it is killed via a SIGKILL signal. A {ProcessExecuter::TimeoutError}
+  #     will be raised if the `:raise_errors` option is true.
+  #
+  #     If the command does not exit when receiving the SIGKILL signal, this method may hang indefinitely.
+  #
+  # @option options_hash [#write] :out (nil) The object to write stdout to
+  # @option options_hash [#write] :err (nil) The object to write stderr to
+  # @option options_hash [Boolean] :merge (false) If true, stdout and stderr are written to the same capture buffer
+  # @option options_hash [Boolean] :raise_errors (true) Raise an exception if the command fails
+  # @option options_hash [Boolean] :unsetenv_others (false) If true, unset all environment variables before
+  #   applying the new ones
+  # @option options_hash [true, Integer, nil] :pgroup (nil) true or 0: new process group; non-zero: join
+  #   the group, nil: existing group
+  # @option options_hash [Boolean] :new_pgroup (nil) Create a new process group (Windows only)
+  # @option options_hash [Integer] :rlimit_resource_name (nil) Set resource limits (see Process.setrlimit)
+  # @option options_hash [Integer] :umask (nil) Set the umask (see File.umask)
+  # @option options_hash [Boolean] :close_others (false) If true, close non-standard file descriptors
+  # @option options_hash [String] :chdir (nil) The directory to run the command in
+  #
+  # @raise [ProcessExecuter::FailedError] if the command returned a non-zero exit status
+  # @raise [ProcessExecuter::SignaledError] if the command exited because of an unhandled signal
+  # @raise [ProcessExecuter::TimeoutError] if the command timed out
+  # @raise [ProcessExecuter::ProcessIOError] if an exception was raised while collecting subprocess output
+  #
+  # @return [ProcessExecuter::Result] The result of the completed subprocess
+  #
+  def self.run(*command, logger: Logger.new(nil), **options_hash)
+    ProcessExecuter::Runner.new(logger).call(*command, **options_hash)
   end
 
   # Wait for process to terminate
   #
-  # If a timeout is speecified in options, kill the process after options.timeout seconds.
+  # If a `:timeout_after` is specified in options, terminate the process after the
+  # specified number of seconds.
   #
-  # @param pid [Integer] the process id
+  # @param pid [Integer] the process ID
   # @param options [ProcessExecuter::Options] the options used
   #
-  # @return [ProcessExecuter::Status] the status of the process
+  # @return [ProcessExecuter::Result] The result of the completed subprocess
   #
   # @api private
   #
-  private_class_method def self.wait_for_process(pid, options)
-    Timeout.timeout(options.timeout) do
-      ProcessExecuter::Status.new(Process.wait2(pid).last, false)
-    end
-  rescue Timeout::Error
-    Process.kill('KILL', pid)
-    ProcessExecuter::Status.new(Process.wait2(pid).last, true)
+  private_class_method def self.wait_for_process(pid, command, options)
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    process_status, timed_out = wait_for_process_raw(pid, options.timeout_after)
+    elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+    ProcessExecuter::Result.new(process_status, command:, options:, timed_out:, elapsed_time:)
+  end
+
+  # Wait for a process to terminate returning the status and timed out flag
+  #
+  # @param pid [Integer] the process ID
+  # @param timeout_after [Numeric, nil] the number of seconds to wait for the process to terminate
+  # @return [Array<Process::Status, Boolean>] an array containing the process status and a boolean
+  #   indicating whether the process timed out
+  # @api private
+  private_class_method def self.wait_for_process_raw(pid, timeout_after)
+    timed_out = false
+
+    process_status =
+      begin
+        Timeout.timeout(timeout_after) { Process.wait2(pid).last }
+      rescue Timeout::Error
+        Process.kill('KILL', pid)
+        timed_out = true
+        Process.wait2(pid).last
+      end
+
+    [process_status, timed_out]
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - James Couball
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-11 00:00:00.000000000 Z
+date: 2025-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -210,7 +209,6 @@ files:
 - ".markdownlint.yml"
 - ".rspec"
 - ".rubocop.yml"
-- ".tool-versions"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile
@@ -218,9 +216,11 @@ files:
 - README.md
 - Rakefile
 - lib/process_executer.rb
+- lib/process_executer/errors.rb
 - lib/process_executer/monitored_pipe.rb
 - lib/process_executer/options.rb
-- lib/process_executer/status.rb
+- lib/process_executer/result.rb
+- lib/process_executer/runner.rb
 - lib/process_executer/version.rb
 - package.json
 - process_executer.gemspec
@@ -231,10 +231,9 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/main-branch/process_executer
   source_code_uri: https://github.com/main-branch/process_executer
-  documentation_uri: https://rubydoc.info/gems/process_executer/1.2.0
-  changelog_uri: https://rubydoc.info/gems/process_executer/1.2.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/process_executer/2.0.0
+  changelog_uri: https://rubydoc.info/gems/process_executer/2.0.0/file/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -251,8 +250,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements:
 - 'Platform: Mac, Linux, or Windows'
 - 'Ruby: MRI 3.1 or later, TruffleRuby 24 or later, or JRuby 9.4 or later'
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: An API for executing commands in a subprocess
 test_files: []

data/.tool-versions

@@ -1 +0,0 @@
-ruby 3.3.5

data/lib/process_executer/status.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require 'delegate'
-require 'forwardable'
-
-module ProcessExecuter
-  # A simple delegator for Process::Status that adds a `timeout?` attribute
-  #
-  # @api public
-  #
-  class Status < SimpleDelegator
-    extend Forwardable
-
-    # Create a new Status object from a Process::Status and timeout flag
-    #
-    # @param status [Process::Status] the status to delegate to
-    # @param timeout [Boolean] true if the process timed out
-    #
-    # @example
-    #   status = Process.wait2(pid).last
-    #   timeout = false
-    #   ProcessExecuter::Status.new(status, timeout)
-    #
-    # @api public
-    #
-    def initialize(status, timeout)
-      super(status)
-      @timeout = timeout
-    end
-
-    # @!attribute [r] timeout?
-    #
-    # True if the process timed out and was sent the SIGKILL signal
-    #
-    # @example
-    #   status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
-    #   status.timeout? # => true
-    #
-    # @return [Boolean]
-    #
-    # @api public
-    #
-    def timeout? = @timeout
-  end
-end