process_executer 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c875872382e447e7af6dfec78af45242baa13c7b832d5c25f3e146bbc2b9f1d
-  data.tar.gz: a68da52f9b1dfae542386a0d61abc85cdc0d86ee0471c4893692061db661f4e5
+  metadata.gz: d2bd50be1f3683bc2c8210451c45e270e7072992ec48897a8bbb16cf10790c8b
+  data.tar.gz: e0d1ba5a7c5571b0059db55537726b68baf6017a66941883953ece63f5a58b53
 SHA512:
-  metadata.gz: a0f6b19a6570dab6843b0d76af1839496ae7ff0651a3f485d6465414b3eb6f0d4a78236bc9ae80ad1b4d7e2e43d8c093ef2733e047eaadb27f3c2e7f174e5f82
-  data.tar.gz: 65da6657d7b821f2b0641bcad6278ded70fd78c06497dfa93fa67ab52c6bb0b57443fa6aa92b5cc160b68ff3b4b68165208b2ff77eea0f4b50542e1243a62c8e
+  metadata.gz: bdaab34abbd99de650933f367eedcb40e7a2538d1f48ab8eda6f5df5da3d5f1748543eb28f54f21cc3557c64d34575001da2158caf2f30cc768bec88f657e16c
+  data.tar.gz: 920227450b1da0c56aa3987a2ff1bbeb2c73cd093d04c1318ebb39d02302a408682d0d40c1668eb1f9b37d71f58fe47a6c4b101b75e701fdbaf3db2cdb845b26

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,18 @@ 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).
 
+## 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,6 +11,7 @@ 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.run](#processexecuterrun)
   * [ProcessExecuter::MonitoredPipe](#processexecutermonitoredpipe)
   * [ProcessExecuter.spawn](#processexecuterspawn)
 * [Installation](#installation)
@@ -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
+an timeout.
+
+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::Command::Result}
+
+2. When passing an array of strings the command is run directly (bypassing the shell):
+
+    `ProcessExecuter.run([env, ] exe_path, *args, options = {}) ->` {ProcessExecuter::Command::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.

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/command/errors.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# rubocop:disable Layout/LineLength
+
+module ProcessExecuter
+  module Command
+    # Base class for all ProcessExecuter::Command errors
+    #
+    # It is recommended to rescue `ProcessExecuter::Command::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::Command::Error => e
+    #     puts "An error occurred: #{e.message}"
+    #   end
+    #
+    # @example Rescuing a timeout error
+    #   begin
+    #     timeout_duration = 0.1 # seconds
+    #     ProcessExecuter.run_command('sleep', '1', timeout: timeout_duration)
+    #   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::Command::Error
+      # Create a CommandError object
+      #
+      # @example
+      #   `exit 1` # set $? appropriately for this example
+      #   result = ProcessExecuter::Command::Result.new(%w[git status], $?, 'stdout', 'stderr')
+      #   error = ProcessExecuter::Command::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_to_s.inspect}"
+      end
+
+      # @attribute [r] result
+      #
+      # The result of the command including the command, its status and its output
+      #
+      # @example
+      #   error.result #=> #<ProcessExecuter::Command::Result:0x00007f9b1b8b3d20>
+      #
+      # @return [Result]
+      #
+      attr_reader :result
+    end
+
+    # Raised when the command returns a non-zero exitstatus
+    #
+    # @api public
+    #
+    class FailedError < ProcessExecuter::Command::CommandError; end
+
+    # Raised when the command exits because of an uncaught signal
+    #
+    # @api public
+    #
+    class SignaledError < ProcessExecuter::Command::CommandError; end
+
+    # Raised when the command takes longer than the configured timeout
+    #
+    # @example
+    #   result.status.timeout? #=> true
+    #
+    # @api public
+    #
+    class TimeoutError < ProcessExecuter::Command::SignaledError
+      # Create a TimeoutError object
+      #
+      # @example
+      #   command = %w[sleep 10]
+      #   timeout_duration = 1
+      #   status = ProcessExecuter.spawn(*command, timeout: timeout_duration)
+      #   result = Result.new(command, status, 'stdout', 'err output')
+      #   error = TimeoutError.new(result, timeout_duration)
+      #   error.error_message
+      #     #=> '["sleep", "10"], status: pid 70144 SIGKILL (signal 9), stderr: "err output", timed out after 1s'
+      #
+      # @param result [Result] The result of the command including the git command,
+      #   status, stdout, and stderr
+      #
+      # @param timeout_duration [Numeric] The duration the subprocess was allowed
+      #   to run before being terminated
+      #
+      def initialize(result, timeout_duration)
+        @timeout_duration = timeout_duration
+        super(result)
+      end
+
+      # The amount of time the subprocess was allowed to run before being killed
+      #
+      # @example
+      #   `kill -9 $$` # set $? appropriately for this example
+      #   result = Result.new(%w[git status], $?, '', "killed")
+      #   error = TimeoutError.new(result, 10)
+      #   error.timeout_duration #=> 10
+      #
+      # @return [Numeric]
+      #
+      attr_reader :timeout_duration
+    end
+
+    # Raised when the output of a command can not be read
+    #
+    # @api public
+    #
+    class ProcessIOError < ProcessExecuter::Command::Error; end
+  end
+end
+
+# rubocop:enable Layout/LineLength

data/lib/process_executer/command/result.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module ProcessExecuter
+  module Command
+    # A wrapper around {ProcessExecuter::Status} which adds captured command output
+    #
+    # This class is used to represent the result of a subprocess execution, combining
+    # the process status with the captured output for easier access and manipulation.
+    #
+    # Features:
+    # * Provides access to the process's status, stdout, and stderr.
+    # * Allows conversion of stdout and stderr buffers to strings.
+    #
+    # @example Create a Result object
+    #   status = ProcessExecuter.spawn(*command, timeout:, out:, err:)
+    #   result = ProcessExecuter::Command::Result.new(command, status, out_buffer.string, err_buffer.string)
+    #
+    # @api public
+    #
+    class Result < SimpleDelegator
+      # Create a new Result object
+      # @example
+      #   status = ProcessExecuter.spawn(*command, timeout:, out:, err:)
+      #   Result.new(command, status, out_buffer.string, err_buffer.string)
+      # @param command [Array<String>] The command that was executed
+      # @param status [ProcessExecuter::Status] The status of the process
+      # @param stdout [String] The stdout output from the process
+      # @param stderr [String] The stderr output from the process
+      def initialize(command, status, stdout, stderr)
+        super(status)
+        @command = command
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      # The command that was run
+      # @example
+      #   result.command #=> %w[git status]
+      # @return [Array<String>]
+      attr_reader :command
+
+      # The captured stdout output from the process
+      # @example
+      #   result.stdout #=> "On branch master\nnothing to commit, working tree clean\n"
+      # @return [String]
+      attr_reader :stdout
+
+      # The captured stderr output from the process
+      # @example
+      #   result.stderr #=> "ERROR: file not found"
+      # @return [String]
+      attr_reader :stderr
+
+      # Return the stdout output as a string
+      # @example When stdout is a StringIO containing "Hello World"
+      #   result.stdout_to_s #=> "Hello World"
+      # @example When stdout is a File object
+      #   result.stdout_to_s #=> #<File:/tmp/output.txt>
+      # @return [String, Object] Returns a String if stdout is a StringIO; otherwise, returns the stdout object
+      def stdout_to_s
+        stdout.respond_to?(:string) ? stdout.string : stdout
+      end
+
+      # Return the stderr output as a string
+      # @example When stderr is a StringIO containing "Hello World"
+      #   result.stderr_to_s #=> "Hello World"
+      # @example When stderr is a File object
+      #   result.stderr_to_s #=> #<File:/tmp/output.txt>
+      # @return [String, Object] Returns a String if stderr is a StringIO; otherwise, returns the stderr object
+      def stderr_to_s
+        stderr.respond_to?(:string) ? stderr.string : stderr
+      end
+    end
+  end
+end

data/lib/process_executer/command/runner.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'result'
+
+module ProcessExecuter
+  module Command
+    # 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()
+      #   status = runner.call('echo', 'hello')
+      #
+      # @param logger [Logger] The logger to use. Defaults to a no-op logger if nil.
+      #
+      def initialize(logger)
+        @logger = logger || Logger.new(nil)
+      end
+
+      # The logger to use
+      # @example
+      #   runner.logger #=> #<Logger:0x00007f9b1b8b3d20>
+      # @return [Logger]
+      attr_reader :logger
+
+      # rubocop:disable Metrics/ParameterLists
+
+      # Run a command and return the status including stdout and stderr output
+      #
+      # @example
+      #   command = %w[git status]
+      #   status = run(command)
+      #   status.success? # => true
+      #   status.exitstatus # => 0
+      #   status.out # => "On branch master\nnothing to commit, working tree clean\n"
+      #   status.err # => ""
+      #
+      # @param command [Array<String>] The command to run
+      # @param out [#write] The object to which stdout is written
+      # @param err [#write] The object to which stderr is written
+      # @param merge [Boolean] Write both stdout and stderr into the buffer for stdout
+      # @param raise_errors [Boolean] Raise an exception if the command fails
+      # @param options_hash [Hash] Additional options to pass to Process.spawn
+      #
+      #   See {ProcessExecuter.run} for a full list of options.
+      #
+      # @return [ProcessExecuter::Command::Result] The status of the subprocess and captured stdout and stderr output
+      #
+      def call(*command, out: nil, err: nil, merge: false, raise_errors: true, **options_hash)
+        out ||= StringIO.new
+        err ||= (merge ? out : StringIO.new)
+
+        status = spawn(command, out:, err:, **options_hash)
+
+        process_result(command, status, out, err, options_hash[:timeout], raise_errors)
+      end
+
+      # rubocop:enable Metrics/ParameterLists
+
+      private
+
+      # Wrap the output buffers in pipes and then execute the command
+      #
+      # @param command [Array<String>] The command to execute
+      # @param out [#write] The object to which stdout is written
+      # @param err [#write] The object 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::Command::ProcessIOError] If an exception was raised while collecting subprocess output
+      # @raise [ProcessExecuter::Command::TimeoutError] If the command times out
+      #
+      # @return [ProcessExecuter::Status] The status 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(*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
+
+      # rubocop:disable Metrics/ParameterLists
+
+      # Process the result of the command and return a ProcessExecuter::Command::Result
+      #
+      # Log the command and result, and raise an error if the command failed.
+      #
+      # @param command [Array<String>] The git command that was executed
+      # @param status [Process::Status] The status of the completed subprocess
+      # @param out [#write] The object that stdout was written to
+      # @param err [#write] The object that stderr was written to
+      # @param timeout [Numeric, nil] The maximum seconds to wait for the command to complete
+      # @param raise_errors [Boolean] Raise an exception if the command fails
+      #
+      # @return [ProcessExecuter::Command::Result] The status of the subprocess and captured stdout and stderr output
+      #
+      # @raise [ProcessExecuter::Command::FailedError] If the command failed
+      # @raise [ProcessExecuter::Command::SignaledError] If the command was signaled
+      # @raise [ProcessExecuter::Command::TimeoutError] If the command times out
+      # @raise [ProcessExecuter::Command::ProcessIOError] If an exception was raised while collecting subprocess output
+      #
+      # @api private
+      #
+      def process_result(command, status, out, err, timeout, raise_errors)
+        Result.new(command, status, out, err).tap do |result|
+          log_result(result)
+
+          if raise_errors
+            raise TimeoutError.new(result, timeout) if status.timeout?
+            raise SignaledError, result if status.signaled?
+            raise FailedError, result unless status.success?
+          end
+        end
+      end
+
+      # rubocop:enable Metrics/ParameterLists
+
+      # Log the command and result of the subprocess
+      # @param result [ProcessExecuter::Command::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_to_s.inspect}\nstderr:\n#{result.stderr_to_s.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::Command::ProcessIOError]
+      #
+      # @return [void] This method always raises an error
+      #
+      # @api private
+      #
+      def raise_pipe_error(command, pipe_name, pipe)
+        error = ProcessExecuter::Command::ProcessIOError.new("Pipe Exception for #{command}: #{pipe_name}")
+        raise(error, cause: pipe.exception)
+      end
+    end
+  end
+end

data/lib/process_executer/command.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  # This module contains classes for implementing ProcessExecuter.run_command
+  module Command; end
+end
+
+require_relative 'command/errors'
+require_relative 'command/result'
+require_relative 'command/runner'
+
+# Runs a command and returns the result

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/status.rb

@@ -15,6 +15,7 @@ module ProcessExecuter
     #
     # @param status [Process::Status] the status to delegate to
     # @param timeout [Boolean] true if the process timed out
+    # @param timeout_duration [Numeric, nil] The secs the command ran before being killed OR o or nil for no timeout
     #
     # @example
     #   status = Process.wait2(pid).last
@@ -23,23 +24,47 @@ module ProcessExecuter
     #
     # @api public
     #
-    def initialize(status, timeout)
+    def initialize(status, timeout, timeout_duration)
       super(status)
       @timeout = timeout
+      @timeout_duration = timeout_duration
     end
 
+    # The secs the command ran before being killed OR o or nil for no timeout
+    # @example
+    #   status.timeout_duration #=> 10
+    # @return [Numeric, nil]
+    attr_reader :timeout_duration
+
     # @!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
+
+    # 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
+    #   status = ProcessExecuter.spawn('sleep 10', timeout: 0.01)
+    #   status.success? # => nil
+    # @return [Boolean, nil]
+    #
+    def success?
+      return nil if timeout? # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+
+      super
+    end
+
+    # Return a string representation of the status
+    # @example
+    #   status.to_s #=> "pid 70144 SIGKILL (signal 9) timed out after 10s"
+    # @return [String]
+    def to_s
+      "#{super}#{timeout? ? " timed out after #{timeout_duration}s" : ''}"
+    end
   end
 end

data/lib/process_executer/version.rb

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

data/lib/process_executer.rb

@@ -2,21 +2,36 @@
 
 require 'process_executer/monitored_pipe'
 require 'process_executer/options'
+require 'process_executer/command'
 require 'process_executer/status'
 
+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 captures its output and status in a result object.
+# * {spawn}: Executes a command and returns its exit status.
+#
+# 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 success, failure, or timeout states.
 #
 # @api public
 #
 module ProcessExecuter
-  # Execute the specified command as a subprocess and return the exit status
+  # Execute the given command as a subprocess and return the exit status
   #
-  # This is a convenience method that calls Process.spawn and blocks until the
-  # command has terminated.
+  # This is a convenience method that calls
+  # [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 command will be sent the SIGKILL signal if it does not terminate within
   # the specified timeout.
   #
   # @example
@@ -44,10 +59,10 @@ module ProcessExecuter
   # @see ProcessExecuter::Options#initialize See 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 [Process::Status] the exit status of the process
   #
   def self.spawn(*command, **options_hash)
     options = ProcessExecuter::Options.new(**options_hash)
@@ -55,23 +70,210 @@ module ProcessExecuter
     wait_for_process(pid, options)
   end
 
+  # Execute the given command as a subprocess, blocking until it finishes
+  #
+  # Returns a result object 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 exits
+  # 2. Captures stdout and stderr to a buffer or file
+  # 3. Optionally kills the command if it exceeds a timeout
+  #
+  # 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::Command::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::Command::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.string #=> "stdout: /Users/james/projects/main-branch/process_executer\n"
+  #   result.stderr.string #=> "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.string #=> ""
+  #   result.stderr.string #=> "Cloning into 'process_executer'...\n"
+  #
+  # @example Run a command with a timeout
+  #   command = ['sleep', '1']
+  #   result = ProcessExecuter.run(*command, timeout: 0.01)
+  #   #=> raises ProcessExecuter::Command::TimeoutError which contains the command result
+  #
+  # @example Run a command which fails
+  #   command = ['exit 1']
+  #   result = ProcessExecuter.run(*command)
+  #   #=> raises ProcessExecuter::Command::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::Command::SignaledError which contains the command result
+  #
+  # @example Return a result instead of raising an error when `raise_errors` is `false`
+  #   # By setting `raise_errors` to `false`, exceptions will not be raised even
+  #   # if the command fails.
+  #   command = ['echo "Some error" 1>&2 && exit 1']
+  #   result = ProcessExecuter.run(*command, raise_errors: false)
+  #   # An error is not raised
+  #   result.success? #=> false
+  #   result.exitstatus #=> 1
+  #   result.stdout.string #=> ""
+  #   result.stderr.string #=> "Some error\n"
+  #
+  # @example Set environment variables
+  #   env = { 'FOO' => 'foo', 'BAR' => 'bar' }
+  #   command = 'echo "$FOO$BAR"'
+  #   result = ProcessExecuter.run(env, *command)
+  #   result.stdout.string #=> "foobar\n"
+  #
+  # @example Set environment variables when using a command array
+  #   env = { 'GIT_DIR' => '/path/to/.git' }
+  #   command = ['git', 'status']
+  #   result = ProcessExecuter.run(env, *command)
+  #   result.stdout.string #=> "On branch main\nYour branch is ..."
+  #
+  # @example Unset environment variables
+  #   env = { 'GIT_DIR' => nil } # setting to nil unsets the variable in the environment
+  #   command = ['git', 'status']
+  #   result = ProcessExecuter.run(env, *command)
+  #   result.stdout.string #=> "On branch main\nYour branch is ..."
+  #
+  # @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.string #=> "Home: \n/Path: /bin\n"
+  #
+  # @example Run command in a different directory
+  #   command = ['pwd']
+  #   result = ProcessExecuter.run(*command, chdir: '/tmp')
+  #   result.stdout.string #=> "/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.string #=> "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"
+  #   result.stdout.object_id == out.object_id #=> true
+  #   result.stderr.object_id == err.object_id #=> true
+  #
+  # @example Capture to a file
+  #   # Same technique can be used for stderr
+  #   out = File.open('stdout.txt', 'w')
+  #   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.string #=> "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"
+  #
+  # @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 The maximum seconds to wait for the command to complete
+  #
+  #     If timeout is zero or nil, the command will not time out. If the command
+  #     times out, it is killed via a SIGKILL signal and {ProcessExecuter::Command::TimeoutError} is raised.
+  #
+  #     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::Command::FailedError] if the command returned a non-zero exit status
+  # @raise [ProcessExecuter::Command::SignaledError] if the command exited because of an unhandled signal
+  # @raise [ProcessExecuter::Command::TimeoutError] if the command timed out
+  # @raise [ProcessExecuter::Command::ProcessIOError] if an exception was raised while collecting subprocess output
+  #
+  # @return [ProcessExecuter::Command::Result] A result object containing the process status and captured output
+  #
+  def self.run(*command, logger: Logger.new(nil), **options_hash)
+    ProcessExecuter::Command::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 is specified in options, terminate the process after options.timeout 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::Status] the process status including Process::Status attributes and a timeout flag
   #
   # @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)
+      ProcessExecuter::Status.new(Process.wait2(pid).last, false, options.timeout)
     end
   rescue Timeout::Error
     Process.kill('KILL', pid)
-    ProcessExecuter::Status.new(Process.wait2(pid).last, true)
+    ProcessExecuter::Status.new(Process.wait2(pid).last, true, options.timeout)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: process_executer
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-11 00:00:00.000000000 Z
+date: 2025-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -218,6 +218,10 @@ files:
 - README.md
 - Rakefile
 - lib/process_executer.rb
+- lib/process_executer/command.rb
+- lib/process_executer/command/errors.rb
+- lib/process_executer/command/result.rb
+- lib/process_executer/command/runner.rb
 - lib/process_executer/monitored_pipe.rb
 - lib/process_executer/options.rb
 - lib/process_executer/status.rb
@@ -231,8 +235,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/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/1.3.0
+  changelog_uri: https://rubydoc.info/gems/process_executer/1.3.0/file/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []