process_executer 3.2.4 → 4.0.0

data/lib/process_executer.rb

@@ -1,441 +1,479 @@
 # frozen_string_literal: true
 
-require 'logger'
-require 'timeout'
-
-require 'process_executer/destination_base'
-require 'process_executer/destinations'
-require 'process_executer/errors'
-require 'process_executer/monitored_pipe'
-require 'process_executer/options'
-require 'process_executer/result'
-require 'process_executer/runner'
-
-# The `ProcessExecuter` module provides methods to execute subprocess commands
-# with enhanced features such as output capture, timeout handling, and custom
-# environment variables.
+# The {ProcessExecuter} module provides extended versions of
+# [Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn) that
+# block while the command is executing. These methods provide enhanced features such
+# as timeout handling, more flexible redirection options, logging, error raising, and
+# output capturing.
 #
-# Methods:
+# The interface of these methods is the same as the standard library
+# [Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn)
+# method, but with additional options and features.
 #
-# * {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
+# These methods are:
 #
-# Features:
+# * {spawn_with_timeout}: Extends
+#   [Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn) to
+#   run a command and wait (with timeout) for it to finish
+# * {run}: Extends {ProcessExecuter.spawn_with_timeout}, adding more flexible
+#   redirection and other options
+# * {run_with_capture}: Extends {ProcessExecuter.run}, automatically captures stdout and stderr
 #
-# * 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.
+# See the {ProcessExecuter::Error} class for the error architecture for this module.
 #
 # @api public
 module ProcessExecuter
-  # Run a command in a subprocess, wait for it to finish, then return the result
+  # Extends `Process.spawn` to run command and wait (with timeout) for it to finish
+  #
+  # Accepts all [Process.spawn execution
+  # options](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options)
+  # and the additional option `timeout_after`:
+  #
+  # * `timeout_after: <Numeric, nil>`: the amount of time (in seconds) to wait before
+  #   signaling the process with SIGKILL. 0 or nil means no timeout.
   #
-  # 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.
+  # Returns a {Result} object. The {Result} class is a decorator for
+  # [Process::Status](https://docs.ruby-lang.org/en/3.4/Process/Status.html) that
+  # provides additional attributes about the command's status. This includes the
+  # {Result#command command} that was run, the {Result#options options} used to run
+  # it, {Result#elapsed_time elapsed_time} of the command, and whether the command
+  # {Result#timed_out? timed_out?}.
   #
-  # 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.
+  # @overload spawn_with_timeout(*command, **options_hash)
   #
-  # @example
-  #   result = ProcessExecuter.spawn_and_wait('echo hello')
+  #   @param command [Array<String>] see [Process module, Argument `command_line` or
+  #     `exe_path`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Argument+command_line)
+  #     and [Process module, Argument
+  #     `args`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Arguments+args)
+  #
+  #     If the first value is a Hash, it is treated as the environment hash. See
+  #     [Process module, Execution Environment](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Environment).
+  #
+  #   @param options_hash [Hash] In addition to the options documented in [Process
+  #     module, Execution
+  #     Options](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options),
+  #     the following options are supported: `:timeout_after`
+  #
+  #   @option options_hash [Numeric] :timeout_after the amount of time (in seconds)
+  #     to wait before signaling the process with SIGKILL
+  #
+  # @overload spawn_with_timeout(*command, options)
+  #
+  #   @param command [Array<String>] see [Process module, Argument `command_line` or
+  #     `exe_path`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Argument+command_line)
+  #     and [Process module, Argument
+  #     `args`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Arguments+args)
+  #
+  #     If the first value is a Hash, it is treated as the environment hash. See
+  #     [Process module, Execution Environment](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Environment).
+  #
+  #   @param options [ProcessExecuter::Options::SpawnWithTimeoutOptions]
+  #
+  # @example command line given as a single string
+  #   result = ProcessExecuter.spawn_with_timeout('echo "3\n2\n1" | sort')
   #   result.exited? # => true
   #   result.success? # => true
+  #   result.exitstatus # => 0
   #   result.timed_out? # => false
   #
+  # @example command given as an exe_path and args
+  #   result = ProcessExecuter.spawn_with_timeout('ping', '-c', '1', 'localhost')
+  #
   # @example with a timeout
-  #   result = ProcessExecuter.spawn_and_wait('sleep 10', timeout_after: 0.01)
+  #   result = ProcessExecuter.spawn_with_timeout('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
+  # @example with a env hash
+  #   env = { 'EXITSTATUS' => '1' }
+  #   result = ProcessExecuter.spawn_with_timeout(env, 'exit $EXITSTATUS')
+  #   result.success? # => false
+  #   result.exitstatus # => 1
+  #
+  # @example capture stdout to a StringIO buffer
   #   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"
+  #   begin
+  #     result = ProcessExecuter.spawn_with_timeout('echo "3\n2\n1" | sort', out: stdout_pipe)
+  #     stdout_buffer.string # => "1\n2\n3\n"
+  #   ensure
+  #     stdout_pipe.close
+  #   end
+  #
+  # @raise [ProcessExecuter::ArgumentError] If the command or an option is not valid
   #
-  # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-spawn Kernel.spawn
-  #   documentation for valid command and options
+  #   Raised if an invalid option key or value is given, or both an options object
+  #   and options_hash are given.
   #
-  # @see ProcessExecuter::Options#initialize ProcessExecuter::Options#initialize for
-  #   options that may be specified
+  # @raise [ProcessExecuter::SpawnError] `Process.spawn` raised an error before the
+  #   command was run
   #
-  # @param command [Array<String>] The command to execute
-  # @param options_hash [Hash] The options to use when executing the command
+  #   Raised if the
+  #   [Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn)
+  #   method raises an error before the command is run.
   #
-  # @return [ProcessExecuter::Result] The result of the completed subprocess
+  # @return [ProcessExecuter::Result]
   #
-  def self.spawn_and_wait(*command, **options_hash)
-    options = ProcessExecuter.spawn_and_wait_options(options_hash)
-    spawn_and_wait_with_options(command, options)
+  # @api public
+  #
+  def self.spawn_with_timeout(*command, **options_hash)
+    command, options = command_and_options(Options::SpawnWithTimeoutOptions, command, options_hash)
+    ProcessExecuter::Commands::SpawnWithTimeout.new(command, options).call
   end
 
-  # Run a command in a subprocess, wait for it to finish, then return the result
+  # Extends {spawn_with_timeout}, adding more flexible redirection and other options
   #
-  # @see ProcessExecuter.spawn_and_wait for full documentation
+  # Accepts all [Process.spawn execution
+  # options](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options),
+  # the additional options defined by {spawn_with_timeout}, and the additional
+  # options `raise_errors` and `logger`:
   #
-  # @param command [Array<String>] The command to run
-  # @param options [ProcessExecuter::Options::SpawnAndWaitOptions] The options to use when running the command
+  # * `raise_errors: <Boolean>` makes execution errors an exception if true (default
+  #   is `true`)
+  # * `logger: <Logger>` logs the command and its result at `:info` level using the
+  #   given logger (default is not to log)
   #
-  # @return [ProcessExecuter::Result] The result of the completed subprocess
-  # @api private
-  def self.spawn_and_wait_with_options(command, options)
-    begin
-      pid = Process.spawn(*command, **options.spawn_options)
-    rescue StandardError => e
-      raise ProcessExecuter::SpawnError, "Failed to spawn process: #{e.message}"
-    end
-    wait_for_process(pid, command, options)
-  end
-
-  # Execute the given command as a subprocess blocking until it finishes
+  # Internally, this method wraps stdout and stderr redirection options in a
+  # {MonitoredPipe}, enabling more flexible output handling. It allows any object
+  # that responds to `#write` to be used as a destination and supports multiple
+  # destinations using the form `[:tee, destination, ...]`.
   #
-  # Works just like {ProcessExecuter.spawn}, but does the following in addition:
+  # When the command exits with a non-zero exit status or does not exit normally, one
+  # of the following errors will be raised unless the option `raise_errors: false` is
+  # explicitly given:
   #
-  #   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`.
+  # * {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
   #
-  #   2. `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`.
+  # These errors all have a {CommandError#result result} attribute that contains the
+  # {ProcessExecuter::Result} object for this command.
   #
-  #   3. Raises one of the following errors unless `raise_errors` is explicitly set
-  #      to `false`:
+  # If `raise_errors: false` is given and there was an error, the returned
+  # {ProcessExecuter::Result} object indicates what the error is via its
+  # [success?](https://docs.ruby-lang.org/en/3.4/Process/Status.html#method-i-success-3F),
+  # [signaled?](https://docs.ruby-lang.org/en/3.4/Process/Status.html#method-i-signaled-3F),
+  # or {Result#timed_out? timed_out?} attributes.
   #
-  #      * `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
+  # A {ProcessExecuter::ProcessIOError} is raised if an exception occurs while
+  # collecting subprocess output.
   #
-  #      If `raise_errors` is false, the returned Result object will contain the error.
+  # Giving the option `raise_errors: false` will not suppress
+  # {ProcessExecuter::ProcessIOError}, {ProcessExecuter::SpawnError}, or
+  # {ProcessExecuter::ArgumentError} errors.
   #
-  #   4. Raises a `ProcessExecuter::ProcessIOError` if an exception is raised
-  #      while collecting subprocess output. This can not be turned off.
+  # @example capture stdout to a StringIO buffer
+  #   out_buffer = StringIO.new
+  #   result = ProcessExecuter.run('echo HELLO', out: out_buffer)
+  #   out_buffer.string #=> "HELLO\n"
+  #
+  # @example with :raise_errors set to true
+  #   begin
+  #     result = ProcessExecuter.run('exit 1', raise_errors: true)
+  #   rescue ProcessExecuter::FailedError => e
+  #     e.result.exitstatus #=> 1
+  #   end
+  #
+  # @example with :raise_errors set to false
+  #   result = ProcessExecuter.run('exit 1', raise_errors: false)
+  #   result.exitstatus #=> 1
   #
-  #   5. If a `logger` is provided, it will be used to log:
+  # @example with a logger
+  #   logger_buffer = StringIO.new
+  #   logger = Logger.new(logger_buffer, level: :info)
+  #   result = ProcessExecuter.run('echo HELLO', logger: logger)
+  #   logger_buffer.string #=> "INFO -- : PID 5555: [\"echo HELLO\"] exited with status pid 5555 exit 0\n"
   #
-  #      * The command that was executed and its status to `info` level
-  #      * The stdout and stderr output to `debug` level
+  # @overload run(*command, **options_hash)
   #
-  #     By default, Logger.new(nil) is used for the logger.
+  #   @param command [Array<String>] see [Process module, Argument `command_line` or
+  #     `exe_path`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Argument+command_line)
+  #     and [Process module, Argument
+  #     `args`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Arguments+args)
   #
-  # This method takes two forms:
+  #     If the first value is a Hash, it is treated as the environment hash. See
+  #     [Process module, Execution Environment](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Environment).
   #
-  # 1. The command is executed via a shell when the command is given as a single
-  #    string:
+  #   @param [Hash] options_hash in addition to the options supported by
+  #     {spawn_with_timeout}, the following options may be given: `:raise_errors` and
+  #     `:logger`
   #
-  #     `ProcessExecuter.run([env, ] command_line, options = {}) ->` {ProcessExecuter::Result}
+  #   @option options_hash [Boolean] :raise_errors if true, an error will be raised
+  #   if the command fails
   #
-  # 2. The command is executed directly (bypassing the shell) when the command and it
-  #    arguments are given as an array of strings:
+  #   @option options_hash [Logger] :logger a logger to use for logging the command
+  #   and its result at the info level
   #
-  #     `ProcessExecuter.run([env, ] exe_path, *args, options = {}) ->` {ProcessExecuter::Result}
+  #   @option options_hash [Numeric] :timeout_after the amount of time (in seconds)
+  #     to wait before signaling the process with SIGKILL
   #
-  # 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).
+  # @overload run(*command, options)
   #
-  # Argument `options` is a hash of options for the new process. See the options listed below.
+  #   @param command [Array<String>] see [Process module, Argument `command_line` or
+  #     `exe_path`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Argument+command_line)
+  #     and [Process module, Argument
+  #     `args`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Arguments+args)
   #
-  # @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"
+  #     If the first value is a Hash, it is treated as the environment hash. See
+  #     [Process module, Execution Environment](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Environment).
   #
-  # @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"
+  #   @param options [ProcessExecuter::Options::RunOptions]
   #
-  # @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
+  # @raise [ProcessExecuter::ArgumentError] If the command or an option is not valid
   #
-  # @example Run a command which fails
-  #   command = ['exit 1']
-  #   result = ProcessExecuter.run(*command)
-  #   #=> raises ProcessExecuter::FailedError which contains the command result
+  #   Raised if an invalid option key or value is given, or both an options object
+  #   and options_hash are given.
   #
-  # @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
+  # @raise [ProcessExecuter::SpawnError] `Process.spawn` raised an error before the
+  #   command was run
   #
-  # @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, [out:, err:]: StringIO.new)
-  #   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 destinations (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: [:tee, 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"
-  #   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 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] :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
-  # @option options_hash [Logger] :logger The logger to use
-  #
-  # @raise [ProcessExecuter::Error] if the command could not be executed or failed
-  #
-  # @return [ProcessExecuter::Result] The result of the completed subprocess
+  #   Raised if the
+  #   [Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn)
+  #   method raises an error before the command is run.
+  #
+  # @raise [ProcessExecuter::FailedError] If the command ran and failed
+  #
+  # @raise [ProcessExecuter::SignaledError] If the command ran and terminated due to
+  #   an unhandled signal
+  #
+  # @raise [ProcessExecuter::TimeoutError] If the command timed out
+  #
+  # @raise [ProcessExecuter::ProcessIOError] If there was an exception while
+  #   collecting subprocess output
+  #
+  # @return [ProcessExecuter::Result]
+  #
+  # @api public
   #
   def self.run(*command, **options_hash)
-    options = ProcessExecuter.run_options(options_hash)
-    run_with_options(command, options)
+    command, options = command_and_options(Options::RunOptions, command, options_hash)
+    ProcessExecuter::Commands::Run.new(command, options).call
   end
 
-  # Run a command with the given options
+  # Extends {run}, automatically capturing stdout and stderr
+  #
+  # Accepts all [Process.spawn execution
+  # options](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options),
+  # the additional options defined by {spawn_with_timeout} and {run}, and the
+  # additional options `merge_output`, `encoding`, `stdout_encoding`, and
+  # `stderr_encoding`:
+  #
+  # * `merge_output: <Boolean>` if true merges stdout and stderr into a single
+  #   capture buffer (default is false)
+  # * `encoding: <Encoding>` sets the encoding for both stdout and stderr captures
+  #   (default is `Encoding::UTF_8`)
+  # * `stdout_encoding: <Encoding>` sets the encoding for the stdout capture and, if
+  #   not nil, overrides the `encoding` option for stdout (default is nil)
+  # * `stderr_encoding: <Encoding>` sets the encoding for the stderr capture and, if
+  #   not nil, overrides the `encoding` option for stderr (default is nil)
   #
-  # @see ProcessExecuter.run for full documentation
+  # The captured output is accessed in the returned object's `#stdout` and `#stderr`
+  # methods. Merged output (if the `merged_output: true` option is given) is accessed
+  # in the `#stdout` method.
   #
-  # @param command [Array<String>] The command to run
-  # @param options [ProcessExecuter::Options::RunOptions] The options to use when running the command
+  # stdout and stderr redirection destinations may be given by the user (e.g. `out:
+  # <destination>` or `err: <destination>`). These redirections will receive the
+  # output in addition to the internal capture.
   #
-  # @return [ProcessExecuter::Result] The result of the completed subprocess
+  # Unless told otherwise, the internally captured output is assumed to be in UTF-8
+  # encoding. This assumption can be changed with the `encoding`,
+  # `stdout_encoding`, or `stderr_encoding` options. These options accept any
+  # encoding objects returned by `Encoding.list` or their String equivalent given by
+  # `#to_s`.
   #
-  # @api private
-  def self.run_with_options(command, options)
-    ProcessExecuter::Runner.new.call(command, options)
-  end
-
-  # Wait for process to terminate
+  # The bytes captured are not transcoded. They are interpreted as being in the
+  # specified encoding. The user will have to check the validity of the
+  # encoding by calling `#valid_encoding?` on the captured output (e.g.,
+  # `result.stdout.valid_encoding?`).
   #
-  # If a `:timeout_after` is specified in options, terminate the process after the
-  # specified number of seconds.
+  # A `ProcessExecuter::ArgumentError` will be raised if both an options object and
+  # an options_hash are given.
   #
-  # @param pid [Integer] the process ID
-  # @param options [ProcessExecuter::Options] the options used
+  # @example capture stdout and stderr
+  #   result =
+  #   ProcessExecuter.run_with_capture('echo HELLO; echo ERROR >&2')
+  #   result.stdout #=> "HELLO\n" result.stderr #=> "ERROR\n"
   #
-  # @return [ProcessExecuter::Result] The result of the completed subprocess
+  # @example merge stdout and stderr
+  #   result = ProcessExecuter.run_with_capture('echo HELLO; echo ERROR >&2', merge_output: true)
+  #   # order of output is not guaranteed
+  #   result.stdout #=> "HELLO\nERROR\n" result.stderr #=> ""
   #
-  # @api private
+  # @example default encoding
+  #   result = ProcessExecuter.run_with_capture('echo HELLO')
+  #   result.stdout #=> "HELLO\n"
+  #   result.stdout.encoding #=> #<Encoding:UTF-8>
+  #   result.stdout.valid_encoding? #=> 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
+  # @example custom encoding
+  #   result = ProcessExecuter.run_with_capture('echo HELLO', encoding: Encoding::ISO_8859_1)
+  #   result.stdout #=> "HELLO\n"
+  #   result.stdout.encoding #=> #<Encoding:ISO-8859-1>
+  #   result.stdout.valid_encoding? #=> true
   #
-  # @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
-
-  # Convert a hash to a SpawnOptions object
+  # @example custom encoding with invalid bytes
+  #   File.binwrite('output.txt', "\xFF\xFE") # little-endian BOM marker is not valid UTF-8
+  #   result = ProcessExecuter.run_with_capture('cat output.txt')
+  #   result.stdout #=> "\xFF\xFE"
+  #   result.stdout.encoding #=> #<Encoding:UTF-8>
+  #   result.stdout.valid_encoding? #=> false
   #
-  # @example
-  #   options_hash = { out: $stdout }
-  #   options = ProcessExecuter.spawn_options(options_hash) # =>
-  #     #<ProcessExecuter::Options::SpawnOptions:0x00007f8f9b0b3d20 out: $stdout>
-  #   ProcessExecuter.spawn_options(options) # =>
-  #     #<ProcessExecuter::Options::SpawnOptions:0x00007f8f9b0b3d20 out: $stdout>
+  # @overload run_with_capture(*command, **options_hash)
   #
-  # @param obj [Hash, SpawnOptions] the object to be converted
+  #   @param command [Array<String>] see [Process module, Argument `command_line` or
+  #     `exe_path`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Argument+command_line)
+  #     and [Process module, Argument
+  #     `args`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Arguments+args)
   #
-  # @return [SpawnOptions]
+  #     If the first value is a Hash, it is treated as the environment hash. See
+  #     [Process module, Execution Environment](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Environment).
   #
-  # @raise [ArgumentError] if obj is not a Hash or SpawnOptions
+  #   @param options_hash [Hash] in addition to the options supported by {run},
+  #     `merge_output` may be given
   #
-  # @api public
+  #   @option options_hash [Boolean] :merge_output if true, stdout and stderr will be
+  #     merged into a single capture buffer
   #
-  def self.spawn_options(obj)
-    case obj
-    when ProcessExecuter::Options::SpawnOptions
-      obj
-    when Hash
-      ProcessExecuter::Options::SpawnOptions.new(**obj)
-    else
-      raise ArgumentError, "Expected a Hash or ProcessExecuter::Options::SpawnOptions but got a #{obj.class}"
-    end
-  end
-
-  # Convert a hash to a SpawnAndWaitOptions object
+  #   @option options_hash [Encoding, String] :encoding the encoding to assume for
+  #     the internal stdout and stderr captures
   #
-  # @example
-  #   options_hash = { out: $stdout }
-  #   options = ProcessExecuter.spawn_and_wait_options(options_hash) # =>
-  #     #<ProcessExecuter::Options::SpawnAndWaitOptions:0x00007f8f9b0b3d20 out: $stdout>
-  #   ProcessExecuter.spawn_and_wait_options(options) # =>
-  #     #<ProcessExecuter::Options::SpawnAndWaitOptions:0x00007f8f9b0b3d20 out: $stdout>
+  #     The default is `Encoding::UTF_8`. This option is overridden by the `stdout_encoding`
+  #     and `stderr_encoding` options if they are given and not nil.
   #
-  # @param obj [Hash, SpawnAndWaitOptions] the object to be converted
+  #   @option options_hash [Encoding, String, nil] :stdout_encoding the encoding to
+  #     assume for the internal stdout capture
   #
-  # @return [SpawnAndWaitOptions]
+  #     The default is nil, which means the `encoding` option is used. If this option is
+  #     is not nil, it is used instead of the `encoding` option.
   #
-  # @raise [ArgumentError] if obj is not a Hash or SpawnOptions
+  #   @option options_hash [Encoding, String, nil] :stderr_encoding the encoding to
+  #     assume for the internal stderr capture
   #
-  # @api public
+  #     The default is nil, which means the `encoding` option is used. If this option
+  #     is not nil, it is used instead of the `encoding` option.
   #
-  def self.spawn_and_wait_options(obj)
-    case obj
-    when ProcessExecuter::Options::SpawnAndWaitOptions
-      obj
-    when Hash
-      ProcessExecuter::Options::SpawnAndWaitOptions.new(**obj)
-    else
-      raise ArgumentError, "Expected a Hash or ProcessExecuter::Options::SpawnAndWaitOptions but got a #{obj.class}"
-    end
-  end
-
-  # Convert a hash to a RunOptions object
+  # @overload run_with_capture(*command, options)
+  #
+  #   @param command [Array<String>] see [Process module, Argument `command_line` or
+  #     `exe_path`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Argument+command_line)
+  #     and [Process module, Argument
+  #     `args`](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Arguments+args)
+  #
+  #     If the first value is a Hash, it is treated as the environment hash. See
+  #     [Process module, Execution Environment](https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Environment).
+  #
+  #   @param options [ProcessExecuter::Options::RunWithCaptureOptions]
+  #
+  # @raise [ProcessExecuter::ArgumentError] If the command or an option is not valid
   #
-  # @example
-  #   options_hash = { out: $stdout }
-  #   options = ProcessExecuter.run_options(options_hash) # =>
-  #     #<ProcessExecuter::Options::RunOptions:0x00007f8f9b0b3d20 out: $stdout>
-  #   ProcessExecuter.run_options(options) # =>
-  #     #<ProcessExecuter::Options::RunOptions:0x00007f8f9b0b3d20 out: $stdout>
+  #   Raised if an invalid option key or value is given, or both an options object
+  #   and options_hash are given.
   #
-  # @param obj [Hash, RunOptions] the object to be converted
+  # @raise [ProcessExecuter::SpawnError] `Process.spawn` raised an error before the
+  #   command was run
   #
-  # @return [RunOptions]
+  #   Raised if the
+  #   [Process.spawn](https://docs.ruby-lang.org/en/3.4/Process.html#method-c-spawn)
+  #   method raises an error before the command is run.
   #
-  # @raise [ArgumentError] if obj is not a Hash or SpawnOptions
+  # @raise [ProcessExecuter::FailedError] If the command ran and failed
+  #
+  # @raise [ProcessExecuter::SignaledError] If the command ran and terminated due to
+  #   an unhandled signal
+  #
+  # @raise [ProcessExecuter::TimeoutError] If the command timed out
+  #
+  # @raise [ProcessExecuter::ProcessIOError] If there was an exception while
+  #   collecting subprocess output
+  #
+  # @return [ProcessExecuter::ResultWithCapture]
+  #
+  #   Where `#stdout` and `#stderr` are strings whose encoding is determined by the
+  #   `:encoding`, `:stdout_encoding`, or `:stderr_encoding` options.
   #
   # @api public
   #
-  def self.run_options(obj)
-    case obj
-    when ProcessExecuter::Options::RunOptions
-      obj
-    when Hash
-      ProcessExecuter::Options::RunOptions.new(**obj)
+  def self.run_with_capture(*command, **options_hash)
+    command, options = command_and_options(Options::RunWithCaptureOptions, command, options_hash)
+    ProcessExecuter::Commands::RunWithCapture.new(command, options).call
+  end
+
+  # Takes a command and options_hash to determine the options object
+  #
+  # To support either passing an options object or an options_hash, this method takes
+  # a command and an options_hash and returns the command (with the trailing options
+  # object removed if one is given) and and options object.
+  #
+  # @example options hash not empty
+  #   command, options = ProcessExecuter.command_and_options(
+  #     ProcessExecuter::Options::RunOptions,
+  #     ['echo hello'],
+  #     { out: $stdout }
+  #   )
+  #   command #=> ['echo hello']
+  #   options #=> a new RunOptions instance initialized with the options hash
+  #
+  # @example options_hash empty, command DOES NOT end with an options object
+  #   command, options = ProcessExecuter.command_and_options(
+  #     ProcessExecuter::Options::RunOptions,
+  #     ['echo hello'],
+  #     {}
+  #   )
+  #   command #=> ['echo hello']
+  #   options #=> a new RunOptions instance initialized with defaults
+  #
+  # @example options_hash empty, command ends with an options object
+  #   command, options = ProcessExecuter.command_and_options(
+  #     ProcessExecuter::Options::RunOptions,
+  #     ['echo hello', ProcessExecuter::Options::RunOptions.new(out: $stdout)],
+  #     {}
+  #   )
+  #   command #=> ['echo hello'] # options object is removed
+  #   options #=> the RunOptions object from command[-1]
+  #
+  # @param options_class [Class] the class of the options object
+  #
+  # @param command [Array] the command to be executed (possibly with an instance of
+  #   options_class at the end)
+  #
+  # @param options_hash [Hash] the (possibly empty) hash of options
+  #
+  # @return [Array] An array containing two elements: the command and an options object
+  #
+  #   The command is an array of strings and the options is an instance of the
+  #   specified options_class.
+  #
+  # @raise [ProcessExecuter::ArgumentError] If both an options object and an
+  #   options_hash are given
+  #
+  # @api private
+  #
+  private_class_method def self.command_and_options(options_class, command, options_hash)
+    if command[-1].is_a?(options_class) && !options_hash.empty?
+      raise ProcessExecuter::ArgumentError, 'Provide either an options object or an options hash, not both.'
+    end
+
+    if !options_hash.empty?
+      [command, options_class.new(**options_hash)]
+    elsif command[-1].is_a?(options_class)
+      [command[..-2], command[-1]]
     else
-      raise ArgumentError, "Expected a Hash or ProcessExecuter::Options::RunOptions but got a #{obj.class}"
+      [command, options_class.new]
     end
   end
 end
+
+require 'logger'
+require 'timeout'
+
+require 'process_executer/commands'
+require 'process_executer/destinations'
+require 'process_executer/errors'
+require 'process_executer/monitored_pipe'
+require 'process_executer/options'
+require 'process_executer/result'
+require 'process_executer/result_with_capture'