process_executer 3.2.3 → 4.0.0

data/lib/process_executer/destinations/file_path_mode.rb

@@ -1,17 +1,18 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles file paths with specific open modes
     #
     # @api private
-    class FilePathMode < ProcessExecuter::DestinationBase
+    class FilePathMode < DestinationBase
       # Initializes a new file path with mode destination handler
       #
-      # Opens the file at the given path with the specified mode.
+      # Redirects to the file at destination via `open(destination[0], destination[1], 0644)`
       #
       # @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)
@@ -26,13 +27,16 @@ module ProcessExecuter
 
       # Writes data to the file
       #
+      # @example
+      #   mode_handler = ProcessExecuter::Destinations::FilePathMode.new(["output.log", "a"])
+      #   mode_handler.write("Appended log entry")
+      #
       # @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

data/lib/process_executer/destinations/file_path_mode_perms.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles file paths with specific open modes and permissions
     #
     # @api private
-    class FilePathModePerms < ProcessExecuter::DestinationBase
+    class FilePathModePerms < 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])
@@ -26,13 +30,16 @@ module ProcessExecuter
 
       # Writes data to the file
       #
+      # @example
+      #   perms_handler = ProcessExecuter::Destinations::FilePathModePerms.new(["output.log", "w", 0644])
+      #   perms_handler.write("Log entry with specific permissions")
+      #
       # @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

data/lib/process_executer/destinations/io.rb

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles IO objects
     #
     # @api private
-    class IO < ProcessExecuter::DestinationBase
+    class IO < DestinationBase
       # Writes data to the IO object
       #
-      # @param data [String] the data to write
-      # @return [Integer] the number of bytes written
-      # @raise [IOError] if the IO object is closed
-      #
       # @example
       #   io = File.open('file.txt', 'w')
       #   io_handler = ProcessExecuter::Destinations::IO.new(io)
       #   io_handler.write("Hello world")
+      #
+      # @param data [String] the data to write
+      #
+      # @return [Integer] the number of bytes written
+      #
+      # @raise [IOError] if the IO object is closed
+      #
       def write(data)
         super
         destination.write data

data/lib/process_executer/destinations/monitored_pipe.rb

@@ -1,20 +1,25 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles monitored pipes
     #
     # @api private
-    class MonitoredPipe < ProcessExecuter::DestinationBase
+    class MonitoredPipe < DestinationBase
       # Writes data to the monitored pipe
       #
-      # @param data [String] the data to write
-      # @return [Object] the return value of the pipe's write method
-      #
       # @example
-      #   pipe = ProcessExecuter::MonitoredPipe.new
+      #   stringio_dest = StringIO.new
+      #   pipe = ProcessExecuter::MonitoredPipe.new(stringio_dest)
       #   pipe_handler = ProcessExecuter::Destinations::MonitoredPipe.new(pipe)
       #   pipe_handler.write("Data to pipe")
+      #
+      # @param data [String] the data to write
+      #
+      # @return [Integer] the number of bytes written
+      #
       def write(data)
         super
         destination.write data

data/lib/process_executer/destinations/stderr.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles standard error redirection
     #
     # @api private
-    class Stderr < ProcessExecuter::DestinationBase
+    class Stderr < DestinationBase
       # Writes data to standard error
       #
-      # @param data [String] the data to write
-      # @return [Integer] the number of bytes written
-      #
       # @example
       #   stderr_handler = ProcessExecuter::Destinations::Stderr.new(:err)
       #   stderr_handler.write("Error message")
+      #
+      # @param data [String] the data to write
+      #
+      # @return [Integer] the number of bytes written
+      #
       def write(data)
         super
         $stderr.write data

data/lib/process_executer/destinations/stdout.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
     # Handles standard output redirection
     #
     # @api private
-    class Stdout < ProcessExecuter::DestinationBase
+    class Stdout < DestinationBase
       # Writes data to standard output
       #
-      # @param data [String] the data to write
-      # @return [Integer] the number of bytes written
-      #
       # @example
       #   stdout_handler = ProcessExecuter::Destinations::Stdout.new(:out)
       #   stdout_handler.write("Hello world")
+      #
+      # @param data [String] the data to write
+      #
+      # @return [Integer] the number of bytes written
+      #
       def write(data)
         super
         $stdout.write data

data/lib/process_executer/destinations/tee.rb

@@ -1,47 +1,54 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
-    # Handles destination for writing to multiple destinations
+    # Handles a destination for writing to multiple destinations
     #
     # The destination is an array with the first element being :tee and the rest
     # being the destinations.
     #
     # @api private
-    class Tee < ProcessExecuter::DestinationBase
-      # Initializes a new file path with mode and permissions destination handler
+    class Tee < DestinationBase
+      # Initializes a destination handler for writing to multiple output destinations
+      #
+      # @param destination [Array<Symbol, Object...>] array in the form [:tee, destination...]
       #
-      # Opens the file at the given path with the specified mode and permissions.
+      # @raise [ArgumentError] if a child destination is invalid or incompatible
       #
-      # @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
         @child_destinations = destination[1..].map { |dest| ProcessExecuter::Destinations.factory(dest) }
       end
 
-      # The opened file object
+      # An array of child destinations
+      #
+      # @return [Array<ProcessExecuter::Destinations::DestinationBase>]
+      #   An array of the child destination handlers
       #
-      # @return [File] the opened file
       attr_reader :child_destinations
 
-      # Writes data to the file
+      # Writes data each of the {child_destinations}
+      #
+      # @example
+      #   tee = ProcessExecuter::Destinations::Tee.new([:tee, "output1.log", "output2.log"])
+      #   tee.write("Log entry with specific permissions")
+      #   tee.close # Important to close the tee to ensure all data is flushed
       #
       # @param data [String] the data to write
-      # @return [Integer] the number of bytes written
+      #
+      # @return [Integer] the number of bytes in the input data (which is written to each destination)
+      #
       # @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
         child_destinations.each { |dest| dest.write(data) }
+        data.bytesize
       end
 
-      # Closes the file if it's open
+      # Closes the child_destinations
       #
       # @return [void]
       def close
@@ -51,7 +58,7 @@ module ProcessExecuter
       # 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
+      # @return [Boolean] true if destination is an Array in the form [:tee, destination...]
       def self.handles?(destination)
         destination.is_a?(Array) && destination.size > 1 && destination[0] == :tee
       end

data/lib/process_executer/destinations/writer.rb

@@ -1,21 +1,24 @@
 # frozen_string_literal: true
 
+require_relative 'destination_base'
+
 module ProcessExecuter
   module Destinations
-    # Handles generic objects that respond to write
+    # Handles generic objects that respond to `#write`
     #
     # @api private
-    class Writer < ProcessExecuter::DestinationBase
+    class Writer < DestinationBase
       # Writes data to the destination object
       #
-      # @param data [String] the data to write
-      # @return [Object] the return value of the destination's write method
-      # @raise [NoMethodError] if the destination doesn't respond to write
-      #
       # @example
       #   buffer = StringIO.new
       #   writer_handler = ProcessExecuter::Destinations::Writer.new(buffer)
       #   writer_handler.write("Hello world")
+      #
+      # @param data [String] the data to write
+      #
+      # @return [Integer] the number of bytes written
+      #
       def write(data)
         super
         destination.write data
@@ -24,7 +27,9 @@ module ProcessExecuter
       # 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
+      #
+      # @return [Boolean] true if destination responds to #write and is not an IO object with a #fileno
+      #
       def self.handles?(destination)
         destination.respond_to?(:write) && (!destination.respond_to?(:fileno) || destination.fileno.nil?)
       end

data/lib/process_executer/destinations.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'destinations/child_redirection'
+require_relative 'destinations/destination_base'
 require_relative 'destinations/file_descriptor'
 require_relative 'destinations/file_path'
 require_relative 'destinations/file_path_mode'
@@ -15,54 +16,68 @@ require_relative 'destinations/writer'
 module ProcessExecuter
   # Collection of destination handler implementations
   #
-  # @api public
+  # @api private
   module Destinations
     # Creates appropriate destination objects based on the given destination
     #
     # This factory method dynamically finds and instantiates the appropriate
     # destination class for handling the provided destination.
     #
+    # @example
+    #   ProcessExecuter::Destinations.factory(1) #=> Returns a Stdout instance
+    #   ProcessExecuter::Destinations.factory("output.log") #=> Returns a FilePath instance
+    #
     # @param destination [Object] the destination to create a handler for
-    # @return [DestinationBase] an instance of the appropriate destination handler
-    # @raise [ArgumentError] if no matching destination class is found
     #
-    # @example
-    #   ProcessExecuter.destination_factory(1) #=> Returns a Stdout instance
-    #   ProcessExecuter.destination_factory("output.log") #=> Returns a FilePath instance
+    # @return [ProcessExecuter::Destinations::DestinationBase] an instance of the
+    #   appropriate destination handler
+    #
+    # @raise [ProcessExecuter::ArgumentError] if no matching destination class is found
+    #
     def self.factory(destination)
       matching_class = matching_destination_class(destination)
       return matching_class.new(destination) if matching_class
 
-      raise ArgumentError, 'wrong exec redirect action'
+      raise ProcessExecuter::ArgumentError, "Destination #{destination.inspect} is not compatible with MonitoredPipe"
     end
 
-    # Determines if the given destination is compatible with a monitored pipe
+    # Determines if the given destination type can be managed by a {MonitoredPipe}
+    #
+    # Returns true if {MonitoredPipe} can forward data to this destination type.
     #
-    # If true, this destination should not be wrapped in a monitored pipe.
+    # Returns false otherwise (e.g., for destinations like :close or [:child, fd]
+    # which have special meaning to Process.spawn and are not simply data sinks for
+    # {MonitoredPipe}).
     #
     # @example
-    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?(1) #=> true
-    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?([:child, 6]) #=> false
-    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?([:close]) #=> false
+    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?(1)
+    #     #=> true
+    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?([:child, 6])
+    #     #=> false
+    #   ProcessExecuter::Destinations.compatible_with_monitored_pipe?(:close)
+    #     #=> false
     #
     # @param destination [Object] the destination to check
-    # @return [Boolean, nil] true if the destination is compatible with a monitored pipe
-    # @raise [ArgumentError] if no matching destination class is found
-    # @api public
+    #
+    # @return [Boolean] true if {MonitoredPipe} can forward data to this destination type
+    #
     def self.compatible_with_monitored_pipe?(destination)
       matching_class = matching_destination_class(destination)
       matching_class&.compatible_with_monitored_pipe?
     end
 
     # Determines the destination class that can handle the given destination
+    #
     # @param destination [Object] the destination to check
-    # @return [Class] the destination class that can handle the given destination
-    # @api private
+    #
+    # @return [Class, nil] the handler class for the given destination or `nil` if no match
+    #
     def self.matching_destination_class(destination)
       destination_classes =
         ProcessExecuter::Destinations.constants
                                      .map { |const| ProcessExecuter::Destinations.const_get(const) }
                                      .select { |const| const.is_a?(Class) }
+                                     .reject { |klass| klass == ProcessExecuter::Destinations::DestinationBase }
 
       destination_classes.find { |klass| klass.handles?(destination) }
     end

data/lib/process_executer/errors.rb

@@ -1,18 +1,19 @@
 # frozen_string_literal: true
 
-# rubocop:disable Layout/LineLength
-
 module ProcessExecuter
-  # Base class for all ProcessExecuter::Command errors
+  # rubocop:disable Layout/LineLength
+
+  # Base class for all {ProcessExecuter} errors
   #
-  # It is recommended to rescue `ProcessExecuter::Error` to catch any
-  # runtime error raised by this gem unless you need more specific error handling.
+  # It is recommended to rescue {ProcessExecuter::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
+  #       ├─> ArgumentError
   #       ├─> CommandError
   #       │   ├─> FailedError
   #       │   └─> SignaledError
@@ -24,16 +25,17 @@ module ProcessExecuter
   # | Error Class | Description |
   # | --- | --- |
   # | `Error` | This catch-all error serves as the base class for other custom errors. |
+  # | `ArgumentError` | Raised when an invalid argument is passed to a method. |
   # | `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. |
+  # | `FailedError` | Raised when the command exits with a non-zero exit status. |
   # | `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). |
+  # | `TimeoutError` | This is a specific type of `SignaledError` that is raised when the command times out and is killed via the SIGKILL signal. |
   # | `ProcessIOError` | Raised when an error was encountered reading or writing to the command's subprocess. |
-  # | `SpawnError` | Raised when the process could not execute. Check the  |
+  # | `SpawnError` | Raised when the process could not execute. Check the `#cause` for the original exception from `Process.spawn`.  |
   #
   # @example Rescuing any error
   #   begin
-  #     ProcessExecuter.run_command('git', 'status')
+  #     ProcessExecuter.run('git', 'status')
   #   rescue ProcessExecuter::Error => e
   #     puts "An error occurred: #{e.message}"
   #   end
@@ -41,23 +43,37 @@ module ProcessExecuter
   # @example Rescuing a timeout error
   #   begin
   #     timeout_after = 0.1 # seconds
-  #     ProcessExecuter.run_command('sleep', '1', timeout_after:)
+  #     ProcessExecuter.run('sleep', '1', timeout_after:)
   #   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}"
+  #     puts "Some other error occurred: #{e}"
   #   end
   #
   # @api public
   #
   class Error < ::StandardError; end
 
+  # rubocop:enable Layout/LineLength
+
+  # Raised when an invalid argument is passed to a method
+  #
+  # @example Raising ProcessExecuter::ArgumentError due to invalid option value
+  #   begin
+  #     ProcessExecuter.run('echo Hello', timeout_after: 'not_a_number')
+  #   rescue ProcessExecuter::ArgumentError => e
+  #     e.message #=> 'timeout_after must be nil or a non-negative real number but was "not_a_number"'
+  #   end
+  #
+  # @api public
+  #
+  class ArgumentError < ProcessExecuter::Error; 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 command executed and its result are available from this object.
   #
-  # The Gem will raise a more specific error for each type of failure:
+  # This 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
@@ -70,12 +86,18 @@ module ProcessExecuter
     #
     # @example
     #   `exit 1` # set $? appropriately for this example
-    #   result = ProcessExecuter::Result.new(%w[git status], $?, 'stdout', 'stderr')
+    #   result_data = {
+    #     command: ['exit 1'],
+    #     options: ProcessExecuter::Options::RunOptions.new,
+    #     timed_out: false,
+    #     elapsed_time: 0.01
+    #   }
+    #   result = ProcessExecuter::Result.new($?, **result_data)
     #   error = ProcessExecuter::CommandError.new(result)
-    #   error.to_s #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #   error.to_s #=> '["exit 1"], status: pid 29686 exit 1'
     #
-    # @param result [Result] The result of the command including the command,
-    #   status, stdout, and stderr
+    # @param result [ProcessExecuter::Result] The result of the command including the
+    #   command and exit status
     #
     def initialize(result)
       @result = result
@@ -85,12 +107,12 @@ module ProcessExecuter
     # The human readable representation of this error
     #
     # @example
-    #   error.error_message #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #   error.error_message #=> '["git", "status"], status: pid 89784 exit 1'
     #
     # @return [String]
     #
     def error_message
-      "#{result.command}, status: #{result}, stderr: #{result.stderr.inspect}"
+      "#{result.command}, status: #{result}"
     end
 
     # @attribute [r] result
@@ -100,12 +122,12 @@ module ProcessExecuter
     # @example
     #   error.result #=> #<ProcessExecuter::Result:0x00007f9b1b8b3d20>
     #
-    # @return [Result]
+    # @return [ProcessExecuter::Result]
     #
     attr_reader :result
   end
 
-  # Raised when the command returns a non-zero exitstatus
+  # Raised when the command returns a non-zero exit status
   #
   # @api public
   #
@@ -120,13 +142,17 @@ module ProcessExecuter
   # Raised when the command takes longer than the configured timeout_after
   #
   # @example
-  #   result.timed_out? #=> true
+  #   begin
+  #     ProcessExecuter.spawn_with_timeout('sleep 1', timeout_after: 0.1)
+  #   rescue ProcessExecuter::TimeoutError => e
+  #     puts "Command timed out: #{e.result.command}"
+  #   end
   #
   # @api public
   #
   class TimeoutError < ProcessExecuter::SignaledError; end
 
-  # Raised when the output of a command can not be read
+  # Raised if an exception occurred while processing subprocess output
   #
   # @api public
   #
@@ -140,5 +166,3 @@ module ProcessExecuter
   #
   class SpawnError < ProcessExecuter::Error; end
 end
-
-# rubocop:enable Layout/LineLength