process_executer 2.0.0 → 3.0.0

data/lib/process_executer/options.rb

@@ -1,171 +1,12 @@
 # frozen_string_literal: true
 
-require 'pp'
+require_relative 'options/base'
+require_relative 'options/spawn_options'
+require_relative 'options/spawn_and_wait_options'
+require_relative 'options/run_options'
+require_relative 'options/option_definition'
 
 module ProcessExecuter
-  # Validate ProcessExecuter::Executer#spawn options and return Process.spawn options
-  #
-  # Valid options are those accepted by Process.spawn plus the following additions:
-  #
-  # * `:timeout_after`: the number of seconds to allow a process to run before killing it
-  #
-  # @api public
-  #
-  class Options
-    # :nocov:
-    # SimpleCov on JRuby seems to hav a bug that causes hashes declared on multiple lines
-    # to not be counted as covered.
-
-    # These options should be passed to `Process.spawn`
-    #
-    # Additionally, any options whose key is an Integer or an IO object will
-    # be passed to `Process.spawn`.
-    #
-    SPAWN_OPTIONS = %i[
-      in out err unsetenv_others pgroup new_pgroup rlimit_resourcename umask
-      close_others chdir
-    ].freeze
-
-    # These options are allowed by `ProcessExecuter.spawn` but should NOT be passed
-    # to `Process.spawn`
-    #
-    NON_SPAWN_OPTIONS = %i[
-      timeout_after raise_errors
-    ].freeze
-
-    # Any `SPAWN_OPTIONS` set to `NOT_SET` will not be passed to `Process.spawn`
-    #
-    NOT_SET = :not_set
-
-    # The default values for all options
-    # @return [Hash]
-    DEFAULTS = {
-      in: NOT_SET,
-      out: NOT_SET,
-      err: NOT_SET,
-      unsetenv_others: NOT_SET,
-      pgroup: NOT_SET,
-      new_pgroup: NOT_SET,
-      rlimit_resourcename: NOT_SET,
-      umask: NOT_SET,
-      close_others: NOT_SET,
-      chdir: NOT_SET,
-      raise_errors: true,
-      timeout_after: nil
-    }.freeze
-
-    # :nocov:
-
-    # All options allowed by this class
-    #
-    ALL_OPTIONS = (SPAWN_OPTIONS + NON_SPAWN_OPTIONS).freeze
-
-    # Create accessor functions for all options. Assumes that the options are stored
-    # in a hash named `@options`
-    #
-    ALL_OPTIONS.each do |option|
-      define_method(option) do
-        @options[option]
-      end
-    end
-
-    # Create a new Options object
-    #
-    # @example
-    #   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_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.
-    #
-    def initialize(**options)
-      assert_no_unknown_options(options)
-      @options = DEFAULTS.merge(options)
-      assert_timeout_is_valid
-    end
-
-    # Returns the options to be passed to Process.spawn
-    #
-    # @example
-    #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout_after: 10)
-    #   options.spawn_options # => { out: $stdout, err: $stderr }
-    #
-    # @return [Hash]
-    #
-    def spawn_options
-      {}.tap do |spawn_options|
-        options.each do |option, value|
-          spawn_options[option] = value if include_spawn_option?(option, value)
-        end
-      end
-    end
-
-    private
-
-    # @!attribute [r]
-    #
-    # Options with values
-    #
-    # All options have values. If an option is not given in the initializer, it
-    # will have the value `NOT_SET`.
-    #
-    # @return [Hash<Symbol, Object>]
-    #
-    # @api private
-    #
-    attr_reader :options
-
-    # Determine if the options hash contains any unknown options
-    # @param options [Hash] the hash of options
-    # @return [void]
-    # @raise [ArgumentError] if the options hash contains any unknown options
-    # @api private
-    def assert_no_unknown_options(options)
-      unknown_options = options.keys.reject { |key| valid_option?(key) }
-      raise ArgumentError, "Unknown options: #{unknown_options.join(', ')}" unless unknown_options.empty?
-    end
-
-    # Raise an error if timeout_after is not a non-negative real number
-    # @return [void]
-    # @raise [ArgumentError] if timeout_after is not a non-negative real number
-    # @api private
-    def assert_timeout_is_valid
-      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_after_message
-    end
-
-    # The message to be used when raising an error for an invalid timeout_after
-    # @return [String]
-    # @api private
-    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
-    # @param option [Symbol] the option to be tested
-    # @return [Boolean] true if the given option is a valid option
-    # @api private
-    def valid_option?(option)
-      ALL_OPTIONS.include?(option) || option.is_a?(Integer) || option.respond_to?(:fileno)
-    end
-
-    # Determine if the given option should be passed to `Process.spawn`
-    # @param option [Symbol, Integer, IO] the option to be tested
-    # @param value [Object] the value of the option
-    # @return [Boolean] true if the given option should be passed to `Process.spawn`
-    # @api private
-    def include_spawn_option?(option, value)
-      (option.is_a?(Integer) || option.is_a?(IO) || SPAWN_OPTIONS.include?(option)) && value != NOT_SET
-    end
-  end
+  # Options related to spawning or running a command
+  module Options; end
 end

data/lib/process_executer/result.rb

@@ -80,7 +80,9 @@ module ProcessExecuter
     #   result.timed_out? # => true
     # @return [Boolean]
     #
-    def timed_out? = @timed_out
+    def timed_out?
+      @timed_out
+    end
 
     # Overrides the default success? method to return nil if the process timed out
     #
@@ -107,9 +109,8 @@ module ProcessExecuter
 
     # 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).
+    # This output is only returned if the `:out` option value is a
+    # `ProcessExecuter::MonitoredPipe`.
     #
     # @example
     #   # Note that `ProcessExecuter.run` will wrap the given out: object in a
@@ -120,22 +121,16 @@ module ProcessExecuter
     # @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
+      pipe = options.stdout_redirection_value
+      return nil unless pipe.is_a?(ProcessExecuter::MonitoredPipe)
 
-      nil
+      pipe.destination.string
     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).
+    # This output is only returned if the `:err` option value is a
+    # `ProcessExecuter::MonitoredPipe`.
     #
     # @example
     #   # Note that `ProcessExecuter.run` will wrap the given err: object in a
@@ -146,15 +141,10 @@ module ProcessExecuter
     # @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
+      pipe = options.stderr_redirection_value
+      return nil unless pipe.is_a?(ProcessExecuter::MonitoredPipe)
 
-      nil
+      pipe.destination.string
     end
   end
 end

data/lib/process_executer/runner.rb

@@ -15,24 +15,6 @@ module ProcessExecuter
   # @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
@@ -45,20 +27,12 @@ module ProcessExecuter
     #   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.
+    # @param options [ProcessExecuter::Options::RunOptions] Options for running the command
     #
     # @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) }
+    def call(command, options)
+      spawn(command, options).tap { |result| process_result(result) }
     end
 
     private
@@ -66,11 +40,7 @@ module ProcessExecuter
     # 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.
+    # @param options [ProcessExecuter::Options::RunOptions] Options for running the command
     #
     # @raise [ProcessExecuter::ProcessIOError] If an exception was raised while collecting subprocess output
     # @raise [ProcessExecuter::TimeoutError] If the command times out
@@ -79,17 +49,47 @@ module ProcessExecuter
     #
     # @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)
+    def spawn(command, options)
+      opened_pipes = wrap_stdout_stderr(options)
+      ProcessExecuter.spawn_and_wait_with_options(command, options)
     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
+      opened_pipes.each { |key, value| close_pipe(command, key, value) }
+    end
+
+    # Wrap the stdout and stderr redirection options with a MonitoredPipe
+    # @param options [ProcessExecuter::Options::RunOptions] Options for running the command
+    # @return [Hash<Object, ProcessExecuter::MonitoredPipe>] The opened pipes (the Object is the option key)
+    # @api private
+    def wrap_stdout_stderr(options)
+      options.each_with_object({}) do |key_value, opened_pipes|
+        key, value = key_value
+
+        next unless should_wrap?(options, key, value)
+
+        wrapped_destination = ProcessExecuter::MonitoredPipe.new(value)
+        opened_pipes[key] = wrapped_destination
+        options.merge!(key => wrapped_destination)
+      end
+    end
+
+    # Should the redirection option be wrapped by a MonitoredPipe
+    # @param key [Object] The option key
+    # @param value [Object] The option value
+    # @return [Boolean] Whether the option should be wrapped
+    # @api private
+    def should_wrap?(options, key, value)
+      (options.stdout_redirection?(key) || options.stderr_redirection?(key)) &&
+        ProcessExecuter::Destinations.compatible_with_monitored_pipe?(value)
+    end
+
+    # Close the pipe and raise an error if the pipe raised an exception
+    # @return [void]
+    # @raise [ProcessExecuter::ProcessIOError] If an exception was raised while
+    #   collecting subprocess output
+    # @api private
+    def close_pipe(command, option_key, pipe)
+      pipe.close
+      raise_pipe_error(command, option_key, pipe) if pipe.exception
     end
 
     # Process the result of the command and return a ProcessExecuter::Result
@@ -110,8 +110,16 @@ module ProcessExecuter
     def process_result(result)
       log_result(result)
 
-      return unless result.options.raise_errors
+      raise_errors(result) if result.options.raise_errors
+    end
 
+    # Raise an error if the command failed
+    # @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
+    # @api private
+    def raise_errors(result)
       raise TimeoutError, result if result.timed_out?
       raise SignaledError, result if result.signaled?
       raise FailedError, result unless result.success?
@@ -123,14 +131,14 @@ module ProcessExecuter
     # @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}" }
+      result.options.logger.info { "#{result.command} exited with status #{result}" }
+      result.options.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 option_key [Symbol] The name of the pipe that raised the exception
     # @param pipe [ProcessExecuter::MonitoredPipe] The pipe that raised the exception
     #
     # @raise [ProcessExecuter::ProcessIOError]
@@ -139,8 +147,8 @@ module ProcessExecuter
     #
     # @api private
     #
-    def raise_pipe_error(command, pipe_name, pipe)
-      error = ProcessExecuter::ProcessIOError.new("Pipe Exception for #{command}: #{pipe_name}")
+    def raise_pipe_error(command, option_key, pipe)
+      error = ProcessExecuter::ProcessIOError.new("Pipe Exception for #{command}: #{option_key.inspect}")
       raise(error, cause: pipe.exception)
     end
   end

data/lib/process_executer/version.rb

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

data/lib/process_executer.rb

@@ -1,25 +1,29 @@
 # 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'
 
-require 'logger'
-require 'timeout'
-
 # 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.
@@ -27,7 +31,6 @@ require 'timeout'
 #   options that were given, and success, failure, or timeout states.
 #
 # @api public
-#
 module ProcessExecuter
   # Run a command in a subprocess, wait for it to finish, then return the result
   #
@@ -70,7 +73,20 @@ module ProcessExecuter
   # @return [ProcessExecuter::Result] The result of the completed subprocess
   #
   def self.spawn_and_wait(*command, **options_hash)
-    options = ProcessExecuter::Options.new(**options_hash)
+    options = ProcessExecuter.spawn_and_wait_options(options_hash)
+    spawn_and_wait_with_options(command, options)
+  end
+
+  # Run a command in a subprocess, wait for it to finish, then return the result
+  #
+  # @see ProcessExecuter.spawn_and_wait for full documentation
+  #
+  # @param command [Array<String>] The command to run
+  # @param options [ProcessExecuter::Options::SpawnAndWaitOptions] The options to use when running the command
+  #
+  # @return [ProcessExecuter::Result] The result of the completed subprocess
+  # @api private
+  def self.spawn_and_wait_with_options(command, options)
     pid = Process.spawn(*command, **options.spawn_options)
     wait_for_process(pid, command, options)
   end
@@ -83,14 +99,11 @@ module ProcessExecuter
   #      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
+  #   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`.
   #
-  #   4. Raises one of the following errors unless `raise_errors` is explicitly set
+  #   3. Raises one of the following errors unless `raise_errors` is explicitly set
   #      to `false`:
   #
   #      * `ProcessExecuter::FailedError` if the command returns a non-zero
@@ -101,10 +114,10 @@ module ProcessExecuter
   #
   #      If `raise_errors` is false, the returned Result object will contain the error.
   #
-  #   5. Raises a `ProcessExecuter::ProcessIOError` if an exception is raised
+  #   4. 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:
+  #   5. 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
@@ -199,7 +212,7 @@ module ProcessExecuter
   #
   # @example Capture stdout and stderr into a single buffer
   #   command = ['echo "stdout" && echo "stderr" 1>&2']
-  #   result = ProcessExecuter.run(*command, merge: true)
+  #   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
@@ -223,18 +236,16 @@ module ProcessExecuter
   #   # stderr is still captured to a StringIO buffer internally
   #   result.stderr #=> "stderr\n"
   #
-  # @example Capture to multiple writers (e.g. files, buffers, STDOUT, etc.)
+  # @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: [out_buffer, out_file])
+  #   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"
-  #   # 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
@@ -252,7 +263,6 @@ module ProcessExecuter
   #   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
@@ -265,7 +275,6 @@ module ProcessExecuter
   #
   # @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
@@ -276,6 +285,7 @@ module ProcessExecuter
   # @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::FailedError] if the command returned a non-zero exit status
   # @raise [ProcessExecuter::SignaledError] if the command exited because of an unhandled signal
@@ -284,8 +294,23 @@ module ProcessExecuter
   #
   # @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)
+  def self.run(*command, **options_hash)
+    options = ProcessExecuter.run_options(options_hash)
+    run_with_options(command, options)
+  end
+
+  # Run a command with the given options
+  #
+  # @see ProcessExecuter.run for full documentation
+  #
+  # @param command [Array<String>] The command to run
+  # @param options [ProcessExecuter::Options::RunOptions] The options to use when running the command
+  #
+  # @return [ProcessExecuter::Result] The result of the completed subprocess
+  #
+  # @api private
+  def self.run_with_options(command, options)
+    ProcessExecuter::Runner.new.call(command, options)
   end
 
   # Wait for process to terminate
@@ -328,4 +353,88 @@ module ProcessExecuter
 
     [process_status, timed_out]
   end
+
+  # Convert a hash to a SpawnOptions object
+  #
+  # @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>
+  #
+  # @param obj [Hash, SpawnOptions] the object to be converted
+  #
+  # @return [SpawnOptions]
+  #
+  # @raise [ArgumentError] if obj is not a Hash or SpawnOptions
+  #
+  # @api public
+  #
+  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
+  #
+  # @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>
+  #
+  # @param obj [Hash, SpawnAndWaitOptions] the object to be converted
+  #
+  # @return [SpawnAndWaitOptions]
+  #
+  # @raise [ArgumentError] if obj is not a Hash or SpawnOptions
+  #
+  # @api public
+  #
+  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
+  #
+  # @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>
+  #
+  # @param obj [Hash, RunOptions] the object to be converted
+  #
+  # @return [RunOptions]
+  #
+  # @raise [ArgumentError] if obj is not a Hash or SpawnOptions
+  #
+  # @api public
+  #
+  def self.run_options(obj)
+    case obj
+    when ProcessExecuter::Options::RunOptions
+      obj
+    when Hash
+      ProcessExecuter::Options::RunOptions.new(**obj)
+    else
+      raise ArgumentError, "Expected a Hash or ProcessExecuter::Options::RunOptions but got a #{obj.class}"
+    end
+  end
 end