process_executer 3.2.4 → 4.0.0

data/process_executer.gemspec

@@ -8,8 +8,17 @@ Gem::Specification.new do |spec|
   spec.authors = ['James Couball']
   spec.email = ['jcouball@yahoo.com']
 
-  spec.summary = 'An API for executing commands in a subprocess'
-  spec.description = 'An API for executing commands in a subprocess'
+  spec.summary = <<~SUMMARY
+    Enhanced subprocess execution with timeouts, output capture, and flexible redirection
+  SUMMARY
+
+  spec.description = <<~DESCRIPTION
+    ProcessExecuter provides a simple API for running commands in a subprocess,
+    with options for capturing output, handling timeouts, logging, and more.
+    It also provides the MonitoredPipe class which expands the output
+    redirection capabilities of Ruby's Process.spawn.
+  DESCRIPTION
+
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 3.1.0'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 3.2.4
+  version: 4.0.0
 platform: ruby
 authors:
 - James Couball
@@ -211,7 +211,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: An API for executing commands in a subprocess
+description: |
+  ProcessExecuter provides a simple API for running commands in a subprocess,
+  with options for capturing output, handling timeouts, logging, and more.
+  It also provides the MonitoredPipe class which expands the output
+  redirection capabilities of Ruby's Process.spawn.
 email:
 - jcouball@yahoo.com
 executables: []
@@ -231,10 +235,14 @@ files:
 - README.md
 - Rakefile
 - lib/process_executer.rb
-- lib/process_executer/destination_base.rb
+- lib/process_executer/commands.rb
+- lib/process_executer/commands/run.rb
+- lib/process_executer/commands/run_with_capture.rb
+- lib/process_executer/commands/spawn_with_timeout.rb
 - lib/process_executer/destinations.rb
 - lib/process_executer/destinations/child_redirection.rb
 - lib/process_executer/destinations/close.rb
+- lib/process_executer/destinations/destination_base.rb
 - lib/process_executer/destinations/file_descriptor.rb
 - lib/process_executer/destinations/file_path.rb
 - lib/process_executer/destinations/file_path_mode.rb
@@ -251,10 +259,11 @@ files:
 - 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/run_with_capture_options.rb
 - lib/process_executer/options/spawn_options.rb
+- lib/process_executer/options/spawn_with_timeout_options.rb
 - lib/process_executer/result.rb
-- lib/process_executer/runner.rb
+- lib/process_executer/result_with_capture.rb
 - lib/process_executer/version.rb
 - package.json
 - process_executer.gemspec
@@ -266,8 +275,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/3.2.4
-  changelog_uri: https://rubydoc.info/gems/process_executer/3.2.4/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/process_executer/4.0.0
+  changelog_uri: https://rubydoc.info/gems/process_executer/4.0.0/file/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -287,5 +296,6 @@ requirements:
 - 'Ruby: MRI 3.1 or later, TruffleRuby 24 or later, or JRuby 9.4 or later'
 rubygems_version: 3.6.7
 specification_version: 4
-summary: An API for executing commands in a subprocess
+summary: Enhanced subprocess execution with timeouts, output capture, and flexible
+  redirection
 test_files: []

data/lib/process_executer/destination_base.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-module ProcessExecuter
-  # Base class for all destination handlers
-  #
-  # Provides the common interface and functionality for all destination
-  # classes that handle different types of output redirection.
-  #
-  # @api private
-  class DestinationBase
-    # Initializes a new destination handler
-    #
-    # @param destination [Object] the destination to write to
-    # @return [DestinationBase] a new destination handler instance
-    def initialize(destination)
-      @destination = destination
-      @data_written = []
-    end
-
-    # The destination object this handler manages
-    #
-    # @return [Object] the destination object
-    attr_reader :destination
-
-    # The data written to the destination
-    #
-    # @return [Array<String>] the data written to the destination
-    attr_reader :data_written
-
-    # The data written to the destination as a single string
-    # @return [String]
-    def string
-      data_written.join
-    end
-
-    # Writes data to the destination
-    #
-    # This is an abstract method that must be implemented by subclasses.
-    #
-    # @param data [String] the data to write
-    # @return [void]
-    # @raise [NotImplementedError] if the subclass doesn't implement this method
-    def write(data)
-      @data_written << data
-    end
-
-    # Closes the destination if necessary
-    #
-    # By default, this method does nothing. Subclasses should override
-    # this method if they need to perform cleanup.
-    #
-    # @return [void]
-    def close; end
-
-    # Determines if this class can handle the given destination
-    #
-    # This is an abstract class method that must be implemented by subclasses.
-    #
-    # @param destination [Object] the destination to check
-    # @return [Boolean] true if this class can handle the destination
-    # @raise [NotImplementedError] if the subclass doesn't implement this method
-    def self.handles?(destination)
-      raise NotImplementedError
-    end
-
-    # Determines if this destination class can be wrapped by MonitoredPipe
-    #
-    # All destination types can be wrapped by MonitoredPipe unless they explicitly
-    # opt out.
-    #
-    # @return [Boolean]
-    # @api private
-    def self.compatible_with_monitored_pipe? = true
-
-    # Determines if this destination instance can be wrapped by MonitoredPipe
-    #
-    # @return [Boolean]
-    # @api private
-    def compatible_with_monitored_pipe?
-      self.class.compatible_with_monitored_pipe?
-    end
-  end
-end

data/lib/process_executer/runner.rb

@@ -1,144 +0,0 @@
-# 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
-    # 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 options [ProcessExecuter::Options::RunOptions] Options for running the command
-    #
-    # @return [ProcessExecuter::Result] The result of the completed subprocess
-    #
-    def call(command, options)
-      spawn(command, options).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 options [ProcessExecuter::Options::RunOptions] Options for running the command
-    #
-    # @raise [ProcessExecuter::Error] if the command could not be executed or failed
-    #
-    # @return [ProcessExecuter::Result] The result of the completed subprocess
-    #
-    # @api private
-    #
-    def spawn(command, options)
-      opened_pipes = wrap_stdout_stderr(options)
-      ProcessExecuter.spawn_and_wait_with_options(command, options)
-    ensure
-      opened_pipes.each_value(&:close)
-      opened_pipes.each { |option_key, pipe| raise_pipe_error(command, option_key, pipe) }
-    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
-
-    # 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::Error] if the command could not be executed or failed
-    #
-    # @api private
-    #
-    def process_result(result)
-      log_result(result)
-
-      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?
-    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)
-      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 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]
-    #
-    # @return [void] This method always raises an error
-    #
-    # @api private
-    #
-    def raise_pipe_error(command, option_key, pipe)
-      return unless pipe.exception
-
-      error = ProcessExecuter::ProcessIOError.new("Pipe Exception for #{command}: #{option_key.inspect}")
-      raise(error, cause: pipe.exception)
-    end
-  end
-end