process_executer 2.0.0 → 3.1.0

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,8 +73,25 @@ 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)
-    pid = Process.spawn(*command, **options.spawn_options)
+    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)
+    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
 
@@ -83,14 +103,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 +118,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 +216,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 +240,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 +267,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 +279,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,16 +289,29 @@ 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::Error] if the command could not be executed or failed
+  #
+  # @return [ProcessExecuter::Result] The result of the completed subprocess
+  #
+  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
   #
-  # @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
+  # @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
   #
-  def self.run(*command, logger: Logger.new(nil), **options_hash)
-    ProcessExecuter::Runner.new(logger).call(*command, **options_hash)
+  # @api private
+  def self.run_with_options(command, options)
+    ProcessExecuter::Runner.new.call(command, options)
   end
 
   # Wait for process to terminate
@@ -328,4 +354,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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - James Couball
 bindir: exe
 cert_chain: []
-date: 2025-03-03 00:00:00.000000000 Z
+date: 2025-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -216,9 +216,28 @@ files:
 - README.md
 - Rakefile
 - lib/process_executer.rb
+- lib/process_executer/destination_base.rb
+- lib/process_executer/destinations.rb
+- lib/process_executer/destinations/child_redirection.rb
+- lib/process_executer/destinations/close.rb
+- lib/process_executer/destinations/file_descriptor.rb
+- lib/process_executer/destinations/file_path.rb
+- lib/process_executer/destinations/file_path_mode.rb
+- lib/process_executer/destinations/file_path_mode_perms.rb
+- lib/process_executer/destinations/io.rb
+- lib/process_executer/destinations/monitored_pipe.rb
+- lib/process_executer/destinations/stderr.rb
+- lib/process_executer/destinations/stdout.rb
+- lib/process_executer/destinations/tee.rb
+- lib/process_executer/destinations/writer.rb
 - lib/process_executer/errors.rb
 - lib/process_executer/monitored_pipe.rb
 - lib/process_executer/options.rb
+- lib/process_executer/options/base.rb
+- lib/process_executer/options/option_definition.rb
+- lib/process_executer/options/run_options.rb
+- lib/process_executer/options/spawn_and_wait_options.rb
+- lib/process_executer/options/spawn_options.rb
 - lib/process_executer/result.rb
 - lib/process_executer/runner.rb
 - lib/process_executer/version.rb
@@ -231,8 +250,8 @@ 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/2.0.0
-  changelog_uri: https://rubydoc.info/gems/process_executer/2.0.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/process_executer/3.1.0
+  changelog_uri: https://rubydoc.info/gems/process_executer/3.1.0/file/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: