process_executer 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 658921c991aa6654711a48a4638e0de6d998f9b5bcdabf8314cad15bb7294a0f
-  data.tar.gz: 7aee46a6fe1459cbd4e0bc9a67895a3c9946741b192e3766937b90ddad416c03
+  metadata.gz: a13a780c8c9064d19873068266b40be2a2a8ba7fe1d46866d6e8cb15806d5e53
+  data.tar.gz: e727aab59452dac6ef74819bff2462ad0e1eb56c5b0c1ff1f7e018aed5dbdf77
 SHA512:
-  metadata.gz: c25a01c7d819932a0495b18fc332744c860df5d25c8234df15071ac3ee66a9f6bc6b6e0101e2b02bc0fb691af3a7ac5bf9a77a98565b44964abcbc3d63f4451e
-  data.tar.gz: 915c369b55e999c726c22b2e3ef0b377ac0253afd115615d4cd2cb8ae17244c5f042bde4018bf31cb76ec30baf924761cb26e045577959b29e3f7aedcceddb65
+  metadata.gz: 6e349893ee5fbf19410e35e2a3a43907ccb1b1610f266788e0bd01b972ccc0e875fa2df95a9f9b90aefa0d8910f535a9d2ad34432332df07dbd58a33d299169d
+  data.tar.gz: 29d7455610df17c93b8616fcff42fe44077f46de3e855eba573b45071e8bd51322240763529e2c5b578191ff20ada709073bac2989e6bbfcca20e0687fac09f5

data/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## v3.0.0 (2025-03-18)
+
+[Full Changelog](https://github.com/main-branch/process_executer/compare/v2.0.0..v3.0.0)
+
+Changes since v2.0.0:
+
+* 3d337de feat: remove Options setter methods and add `with` method
+* 706d78a docs: add a list the breaking changes for each major release in the README.md
+* 2903c80 feat: report all option errors instead of just the first one
+* 247150d feat!: do not capture stdout and stderr by default in `ProcessExecuter.run`
+* 4b3ac02 feat: support redirection destinations in the form [:child, fd] and :close
+* ed4620f docs: update README.md to highlight the important parts of this gem
+* 48b4695 fix: allow Integer or IO are used as a redirection source
+* 4424a44 feat!: remove the :merge option from ProcessExecuter.run
+* 7257e5d chore: allow SpawnOptions to accept Integer and IO redirection sources
+* 92441d0 chore: move all options related classes to a new Options module
+* 92c096c chore: remove unneeded test file
+* 91d0db3 feat: implement all possible redirection destinations
+* a58af4a fix: fix complexity error reported by CodeClimate
+* 66d97b7 chore: do not fail the CI build for low coverage on JRuby and TruffleRuby
+* 2fb0ccf feat: refactor options classes
+* bcf35d5 chore: do not fail the CI build for low coverage on JRuby and TruffleRuby
+
 ## v2.0.0 (2025-03-03)
 
 [Full Changelog](https://github.com/main-branch/process_executer/compare/v1.3.0..v2.0.0)

data/README.md

@@ -10,10 +10,41 @@
 Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
 [![Slack](https://img.shields.io/badge/slack-main--branch/process__executer-yellow.svg?logo=slack)](https://main-branch.slack.com/archives/C07NG2BPG8Y)
 
+ProcessExecuter provides an enhanced API for executing commands in subprocesses,
+extending Ruby's built-in `Process.spawn` functionality.
+
+It has additional features like capturing output, handling timeouts, streaming output
+to multiple destinations, and providing detailed result information.
+
+This README documents the HEAD version of process_executer which may contain
+unrelease information. To see the README for the version you are using, consult
+RubyGems.org. Go to the [process_executer page in
+RubyGems.org](https://rubygems.org/gems/process_executer), select your version, and
+then click the "Documentation" link.
+
+## Requirements
+
+* Ruby 3.1.0 or later
+* Compatible with MRI 3.1+, TruffleRuby 24+, and JRuby 9.4+
+* Works on Mac, Linux, and Windows platforms
+
+## Table of Contents
+
+* [Requirements](#requirements)
+* [Table of Contents](#table-of-contents)
 * [Usage](#usage)
-    * [ProcessExecuter.run](#processexecuterrun)
     * [ProcessExecuter::MonitoredPipe](#processexecutermonitoredpipe)
+    * [ProcessExecuter::Result](#processexecuterresult)
     * [ProcessExecuter.spawn\_and\_wait](#processexecuterspawn_and_wait)
+    * [ProcessExecuter.run](#processexecuterrun)
+* [Breaking Changes](#breaking-changes)
+    * [2.x](#2x)
+        * [`ProcessExecuter.spawn`](#processexecuterspawn)
+        * [`ProcessExecuter.run`](#processexecuterrun-1)
+        * [`ProcessExecuter::Result`](#processexecuterresult-1)
+        * [Other](#other)
+    * [3.x](#3x)
+        * [`ProcessExecuter.run`](#processexecuterrun-2)
 * [Installation](#installation)
 * [Contributing](#contributing)
     * [Reporting Issues](#reporting-issues)
@@ -25,53 +56,43 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
 
 ## Usage
 
-[Full YARD documentation](https://rubydoc.info/gems/process_executer/) for this
-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.
+[Full YARD documentation](https://rubydoc.info/gems/process_executer/) for this gem
+is hosted on RubyGems.org. Read below for an overview and several examples.
 
-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
-a given timeout duration.
+This gem contains two public classes and two public methods:
 
-This command takes two forms:
+Classes:
 
-1. When passing a single string the command is passed to a shell:
+* `ProcessExecuter::MonitoredPipe`: allows use of any object with a `#write` method
+  or an array of objects as a redirection destination in `Process.spawn`
+* `ProcessExecuter::Result`: an extension of `Process::Status` that includes more
+  information about the subprocess including timeout status, the command that was
+  run, the subprocess options given, and (in some cases) stdout and stderr captured
+  from the subprocess.
 
-    `ProcessExecuter.run([env, ] command_line, options = {}) ->` {ProcessExecuter::Result}
+Methods:
 
-2. When passing an array of strings the command is run directly (bypassing the shell):
-
-    `ProcessExecuter.run([env, ] exe_path, *args, options = {}) ->` {ProcessExecuter::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.spawn_and_wait`: execute a subprocess and wait for it to exit with
+  an optional timeout. Supports the same interface and features as `Process.spawn`.
+* `ProcessExecuter.run`: builds upon `.spawn_and_wait` adding (1) automatically
+  wrapping stdout and stderr destinations (if given) in a `MonitoredPipe` and (2)
+  raises errors for any problem executing the subprocess (can be turned off).
 
 ### ProcessExecuter::MonitoredPipe
 
-`ProcessExecuter::MonitoredPipe` streams data sent through a pipe to one or more writers.
+`ProcessExecuter::MonitoredPipe` objects can be used as a redirection destination for
+`Process.spawn` to stream output from a subprocess to one or more destinations.
+Destinations are given in this class's initializer.
 
-When a new `MonitoredPipe` is created, a pipe is created (via IO.pipe) and
-a thread is created which reads data as it is written written to the pipe.
+The destinations are all the redirection destinations allowed by `Process.spawn` plus
+the following:
 
-Data that is read from the pipe is written one or more writers passed to
-`MonitoredPipe#initialize`.
+* Any object with a #write method even if it does not have a file descriptor (like
+  instances of StringIO)
+* An array of destinations so that output can be tee'd to several sources
 
-This is useful for streaming process output (stdout and/or stderr) to anything that has a
-`#write` method: a string buffer, a file, or stdout/stderr as seen in the following example:
+Example of capturing stdout to a StringIO (which is not directly possible with
+`Process.spawn`):
 
 ```ruby
 require 'stringio'
@@ -80,11 +101,15 @@ require 'process_executer'
 output_buffer = StringIO.new
 out_pipe = ProcessExecuter::MonitoredPipe.new(output_buffer)
 pid, status = Process.wait2(Process.spawn('echo "Hello World"', out: out_pipe))
+out_pipe.close # Close the pipe so all the data is flushed and resources are not leaked
 output_buffer.string #=> "Hello World\n"
 ```
 
-`MonitoredPipe#initialize` can take more than one writer so that pipe output can be
-streamed (or `tee`d) to multiple writers at the same time:
+Any object that implements `#write` can be used as a destination (not just StringIO).
+For instance, you can use it to parse process output as a stream which might be useful
+for long XML or JSON output.
+
+Example of tee'ing stdout to multiple destinations:
 
 ```ruby
 require 'stringio'
@@ -92,24 +117,42 @@ require 'process_executer'
 
 output_buffer = StringIO.new
 output_file = File.open('process.out', 'w')
-out_pipe = ProcessExecuter::MonitoredPipe.new(output_buffer, output_file)
+out_pipe = ProcessExecuter::MonitoredPipe.new([:tee, output_buffer, output_file])
 pid, status = Process.wait2(Process.spawn('echo "Hello World"', out: out_pipe))
+out_pipe.close
 output_file.close
 output_buffer.string #=> "Hello World\n"
 File.read('process.out') #=> "Hello World\n"
 ```
 
-Since the data is streamed, any object that implements `#write` can be used. For
-insance, you can use it to parse process output as a stream which might be useful for
-long XML or JSON output.
+### ProcessExecuter::Result
+
+An instance of this class is returned from both `.spawn_and_wait` and `.run`.
+
+This class is an extension of
+[Process::Status](https://docs.ruby-lang.org/en/3.3/Process/Status.html) so it
+supports the same interface with the following additions:
+
+* `#command`: the command given to `.spawn_and_wait` or `.run`
+* `#options`: the options given to `.spawn_and_wait` or `.run` (possibly with some
+  changes)
+* `#timed_out?`: true if the process was killed after running for `:timeout_after`
+  seconds
+* `#elapsed_time`: the number of seconds the process was running
+* `#stdout`: the captured stdout from the subprocess (if the stdout destination was
+  wrapped by a `MonitoredPipe`)
+* `#stderr`: the captured stderr from the subprocess (if the stderr destination was
+  wrapped by a `MonitoredPipe`)
 
 ### ProcessExecuter.spawn_and_wait
 
-`ProcessExecuter.spawn` has the same interface as `Process.spawn` but has two
-important behaviorial differences:
+`ProcessExecuter.spawn_and_wait` has the same interface and features as
+[Process.spawn](https://docs.ruby-lang.org/en/3.3/Process.html#method-c-spawn)
+with the following differences:
 
-1. It blocks until the subprocess finishes
+1. It waits for the subprocess to exit
 2. A timeout can be specified using the `:timeout_after` option
+3. It returns a `ProcessExecuter::Result` instead of a `Process::Status`
 
 If the command does not terminate before the number of seconds specified by
 `:timeout_after`, the process is killed by sending it the SIGKILL signal. The
@@ -122,6 +165,73 @@ result.termsig #=> 9
 result.timed_out? #=> true
 ```
 
+If the destination for stdout and stderr are wrapped by a
+ProcessExecuter::MonitoredPipe, the result will return the stdout and stderr
+subprocess output from its `#stdout` and `#stderr` methods.
+
+### ProcessExecuter.run
+
+`ProcessExecuter.run` builds upon `ProcessExecuter.spawn_and_wait` adding the
+following features:
+
+* It automatically wraps any given stdout and stderr destination with a
+  MonitoredPipe. The pipe will be closed when the command exits.
+* It raises an error if there is any problem with the subprocess. This behavior can
+  be turned off with the `raise_errors: false` option.
+
+```ruby
+result = ProcessExecuter.run('echo "Hello World"', out: StringIO.new)
+result.stdout #=> "Hello World\n"
+```
+
+## Breaking Changes
+
+### 2.x
+
+This major release focused on changes to the interface to make it more understandable.
+
+#### `ProcessExecuter.spawn`
+
+* This method was renamed to `ProcessExecuter.spawn_and_wait`
+* The `:timeout` option was renamed to `:timeout_after`
+
+#### `ProcessExecuter.run`
+
+* The `:timeout` option was renamed to `:timeout_after`
+
+#### `ProcessExecuter::Result`
+
+* The `#timeout` method was renamed to `#timed_out`
+
+#### Other
+
+* Dropped support for Ruby 3.0
+
+### 3.x
+
+#### `ProcessExecuter.run`
+
+* The `:merge` option was removed
+
+  This was removed because `Process.spawn` already provides this functionality but in
+  a different way. To merge, you will need to define a redirection where the source
+  is an array of the file descriptors you want to merge. For instance:
+
+  ```Ruby
+  [:out, :err] => 'output.txt'
+  ```
+
+  will merge stdout and stderr from the subprocess into the file output.txt.
+
+* Stdout and stderr redirections are no longer default to a new instance of StringIO
+
+  Calls to `ProcessExecuter.run` that do not define a redirection for stdout or
+  stderr will have to add explicit redirection(s) in order to capture the output.
+
+  This is to align with the functionality in `Process.spawn`. In `Process.spawn`, when
+  an explicit redirection is not given for stdout and stderr, this output will be
+  passed through to the parent process's stdout and stderr.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/lib/process_executer/destination_base.rb

@@ -0,0 +1,83 @@
+# 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/destinations/child_redirection.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles generic objects that respond to write
+    #
+    # @api private
+    class ChildRedirection < ProcessExecuter::DestinationBase
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination responds to write but is not an IO with fileno
+      def self.handles?(destination)
+        destination.is_a?(Array) && destination.size == 2 && destination[0] == :child
+      end
+
+      # This class should not be wrapped in a monitored pipe
+      # @return [Boolean]
+      # @api private
+      def self.compatible_with_monitored_pipe? = false
+    end
+  end
+end

data/lib/process_executer/destinations/close.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles generic objects that respond to write
+    #
+    # @api private
+    class Close < ProcessExecuter::DestinationBase
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination responds to write but is not an IO with fileno
+      def self.handles?(destination)
+        destination == :close
+      end
+
+      # This class should not be wrapped in a monitored pipe
+      # @return [Boolean]
+      # @api private
+      def self.compatible_with_monitored_pipe? = false
+    end
+  end
+end

data/lib/process_executer/destinations/file_descriptor.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'process_executer/destination_base'
+
+module ProcessExecuter
+  module Destinations
+    # Handles numeric file descriptors
+    #
+    # @api private
+    class FileDescriptor < ProcessExecuter::DestinationBase
+      # Writes data to the file descriptor
+      #
+      # @param data [String] the data to write
+      # @return [Integer] the number of bytes written
+      # @raise [SystemCallError] if the file descriptor is invalid
+      #
+      # @example
+      #   fd_handler = ProcessExecuter::Destinations::FileDescriptor.new(3)
+      #   fd_handler.write("Hello world")
+      def write(data)
+        super
+        io = ::IO.open(destination, mode: 'a', autoclose: false)
+        io.write(data)
+        io.close
+      end
+
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination is an Integer that's not stdout/stderr
+      def self.handles?(destination)
+        destination.is_a?(Integer) && ![:out, 1, :err, 2].include?(destination)
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/file_path.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles file path destinations
+    #
+    # @api private
+    class FilePath < ProcessExecuter::DestinationBase
+      # Initializes a new file path destination handler
+      #
+      # Opens the file at the given path for writing.
+      #
+      # @param destination [String] the file path to write to
+      # @return [FilePath] a new file path destination handler
+      # @raise [Errno::ENOENT] if the file path is invalid
+      def initialize(destination)
+        super
+        @file = File.open(destination, 'w', 0o644)
+      end
+
+      # The opened file object
+      #
+      # @return [File] the opened file
+      attr_reader :file
+
+      # Writes data to the file
+      #
+      # @param data [String] the data to write
+      # @return [Integer] the number of bytes written
+      # @raise [IOError] if the file is closed
+      #
+      # @example
+      #   file_handler = ProcessExecuter::Destinations::FilePath.new("output.log")
+      #   file_handler.write("Log entry")
+      def write(data)
+        super
+        file.write data
+      end
+
+      # Closes the file if it's open
+      #
+      # @return [void]
+      def close
+        file.close unless file.closed?
+      end
+
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination is a String
+      def self.handles?(destination)
+        destination.is_a? String
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/file_path_mode.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles file paths with specific open modes
+    #
+    # @api private
+    class FilePathMode < ProcessExecuter::DestinationBase
+      # Initializes a new file path with mode destination handler
+      #
+      # Opens the file at the given path with the specified mode.
+      #
+      # @param destination [Array<String, String>] array with file path and mode
+      # @return [FilePathMode] a new file path with mode destination handler
+      # @raise [Errno::ENOENT] if the file path is invalid
+      # @raise [ArgumentError] if the mode is invalid
+      def initialize(destination)
+        super
+        @file = File.open(destination[0], destination[1], 0o644)
+      end
+
+      # The opened file object
+      #
+      # @return [File] the opened file
+      attr_reader :file
+
+      # Writes data to the file
+      #
+      # @param data [String] the data to write
+      # @return [Integer] the number of bytes written
+      # @raise [IOError] if the file is closed
+      #
+      # @example
+      #   mode_handler = ProcessExecuter::Destinations::FilePathMode.new(["output.log", "a"])
+      #   mode_handler.write("Appended log entry")
+      def write(data)
+        super
+        file.write data
+      end
+
+      # Closes the file if it's open
+      #
+      # @return [void]
+      def close
+        file.close unless file.closed?
+      end
+
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination is an Array with path and mode
+      def self.handles?(destination)
+        destination.is_a?(Array) &&
+          destination.size == 2 &&
+          destination[0].is_a?(String) &&
+          destination[1].is_a?(String)
+      end
+    end
+  end
+end

data/lib/process_executer/destinations/file_path_mode_perms.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Destinations
+    # Handles file paths with specific open modes and permissions
+    #
+    # @api private
+    class FilePathModePerms < ProcessExecuter::DestinationBase
+      # Initializes a new file path with mode and permissions destination handler
+      #
+      # Opens the file at the given path with the specified mode and permissions.
+      #
+      # @param destination [Array<String, String, Integer>] array with file path, mode, and permissions
+      # @return [FilePathModePerms] a new handler instance
+      # @raise [Errno::ENOENT] if the file path is invalid
+      # @raise [ArgumentError] if the mode is invalid
+      def initialize(destination)
+        super
+        @file = File.open(destination[0], destination[1], destination[2])
+      end
+
+      # The opened file object
+      #
+      # @return [File] the opened file
+      attr_reader :file
+
+      # Writes data to the file
+      #
+      # @param data [String] the data to write
+      # @return [Integer] the number of bytes written
+      # @raise [IOError] if the file is closed
+      #
+      # @example
+      #   perms_handler = ProcessExecuter::Destinations::FilePathModePerms.new(["output.log", "w", 0644])
+      #   perms_handler.write("Log entry with specific permissions")
+      def write(data)
+        super
+        file.write data
+      end
+
+      # Closes the file if it's open
+      #
+      # @return [void]
+      def close
+        file.close unless file.closed?
+      end
+
+      # Determines if this class can handle the given destination
+      #
+      # @param destination [Object] the destination to check
+      # @return [Boolean] true if destination is an Array with path, mode, and permissions
+      def self.handles?(destination)
+        destination.is_a?(Array) &&
+          destination.size == 3 &&
+          destination[0].is_a?(String) &&
+          destination[1].is_a?(String) &&
+          destination[2].is_a?(Integer)
+      end
+    end
+  end
+end