process_executer 3.2.4 → 4.0.0

data/lib/process_executer/options/run_options.rb

@@ -1,19 +1,17 @@
 # frozen_string_literal: true
 
-require_relative 'spawn_and_wait_options'
+require_relative 'spawn_with_timeout_options'
 require_relative 'option_definition'
 
 module ProcessExecuter
   module Options
-    # Define options for the `ProcessExecuter.run`
+    # Define options for {ProcessExecuter.run}
     #
     # @api public
     #
-    class RunOptions < SpawnAndWaitOptions
+    class RunOptions < SpawnWithTimeoutOptions
       private
 
-      # :nocov: SimpleCov on JRuby reports the last with the last argument line is not covered
-
       # The options allowed for objects of this class
       # @return [Array<OptionDefinition>]
       # @api private
@@ -24,21 +22,24 @@ module ProcessExecuter
           OptionDefinition.new(:logger, default: Logger.new(nil), validator: method(:validate_logger))
         ].freeze
       end
-      # :nocov:
 
-      # Validate the raise_errors option value
-      # @return [String, nil] the error message if the value is not valid
+      # Note an error if raise_errors is not true or false
+      # @param _key [Symbol] the option key (not used)
+      # @param _value [Object] the option value (not used)
+      # @return [Void]
       # @api private
-      def validate_raise_errors
+      def validate_raise_errors(_key, _value)
         return if [true, false].include?(raise_errors)
 
         errors << "raise_errors must be true or false but was #{raise_errors.inspect}"
       end
 
-      # Validate the logger option value
-      # @return [String, nil] the error message if the value is not valid
+      # Note an error if the logger option is not valid
+      # @param _key [Symbol] the option key (not used)
+      # @param _value [Object] the option value (not used)
+      # @return [Void]
       # @api private
-      def validate_logger
+      def validate_logger(_key, _value)
         return if logger.respond_to?(:info) && logger.respond_to?(:debug)
 
         errors << "logger must respond to #info and #debug but was #{logger.inspect}"

data/lib/process_executer/options/run_with_capture_options.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative 'option_definition'
+require_relative 'run_options'
+
+module ProcessExecuter
+  module Options
+    # Define options for {ProcessExecuter.run_with_capture}
+    #
+    # @api public
+    #
+    class RunWithCaptureOptions < RunOptions
+      # The default encoding used for stdout and stderr
+      # if no other encoding is specified.
+      #
+      # @return [Encoding]
+      #
+      DEFAULT_ENCODING = Encoding::UTF_8
+
+      # Determines the character encoding to use for stdout
+      #
+      # It prioritizes `stdout_encoding` if set, otherwise falls back to
+      # `encoding`, and finally defaults to `DEFAULT_ENCODING` if neither
+      # is available.
+      #
+      # @return [Encoding]
+      #
+      # @api private
+      #
+      def effective_stdout_encoding
+        stdout_encoding || encoding || DEFAULT_ENCODING
+      end
+
+      # Determines the character encoding to use for stderr
+      #
+      # It prioritizes `stderr_encoding` if set, otherwise falls back to
+      # `encoding`, and finally defaults to `DEFAULT_ENCODING` if neither
+      # is available.
+      #
+      # @return [Encoding]
+      #
+      # @api private
+      #
+      def effective_stderr_encoding
+        stderr_encoding || encoding || DEFAULT_ENCODING
+      end
+
+      private
+
+      # The options allowed for objects of this class
+      # @return [Array<OptionDefinition>]
+      # @api private
+      def define_options
+        [
+          *super,
+          OptionDefinition.new(:merge_output, default: false, validator: method(:validate_merge_output)),
+          OptionDefinition.new(:encoding, default: DEFAULT_ENCODING, validator: method(:validate_encoding_option)),
+          OptionDefinition.new(:stdout_encoding, default: nil, validator: method(:validate_encoding_option)),
+          OptionDefinition.new(:stderr_encoding, default: nil, validator: method(:validate_encoding_option))
+        ].freeze
+      end
+
+      # Note any errors in the merge_output option
+      #
+      # Possible errors include:
+      # - if the merge_output value is not a Boolean
+      # - if merge_output: true and a stderr redirection is given
+      # - if merge_output: true and stdout and stderr encodings are different
+      #
+      # @param _key [Symbol] the option key (not used)
+      # @param _value [Object] the option value (not used)
+      # @return [Void]
+      # @api private
+      def validate_merge_output(_key, _value)
+        unless [true, false].include?(merge_output)
+          errors << "merge_output must be true or false but was #{merge_output.inspect}"
+        end
+
+        return unless merge_output == true
+
+        errors << 'Cannot give merge_output: true AND a stderr redirection' if stderr_redirection_source
+
+        return if effective_stdout_encoding == effective_stderr_encoding
+
+        errors << 'Cannot give merge_output: true AND give different encodings for stdout and stderr'
+      end
+
+      # Note an error if the encoding option is not valid
+      # @param key [Symbol] the option key
+      # @param value [Object] the option value
+      # @return [Void]
+      # @api private
+      def validate_encoding_option(key, value)
+        return unless valid_encoding_type?(key, value)
+
+        return if value.nil? || value.is_a?(Encoding)
+
+        validate_encoding_symbol(key, value) if value.is_a?(Symbol)
+
+        validate_encoding_string(key, value) if value.is_a?(String)
+      end
+
+      # False if the value is not a valid encoding type, true otherwise
+      #
+      # @param key [Symbol] the option key
+      #
+      # @param value [Object] the option value
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      #
+      def valid_encoding_type?(key, value)
+        return true if value.nil? || value.is_a?(Encoding) || value.is_a?(Symbol) || value.is_a?(String)
+
+        errors << "#{key} must be an Encoding object, String, Symbol (:binary, :default_external), " \
+                  "or nil, but was #{value.inspect}"
+
+        false
+      end
+
+      # Note an error if the encoding symbol is not valid
+      #
+      # @param key [Symbol] the option key
+      #
+      # @param value [Symbol] the option value
+      #
+      # @return [Void]
+      #
+      # @api private
+      #
+      def validate_encoding_symbol(key, value)
+        return if %i[binary default_external].include?(value)
+
+        errors << "#{key} when given as a symbol must be :binary or :default_external, " \
+                  "but was #{value.inspect}"
+      end
+
+      # Note an error if the encoding string is not valid
+      #
+      # @param key [Symbol] the option key
+      #
+      # @param value [String] the option value
+      #
+      # @return [void]
+      #
+      # @api private
+      #
+      def validate_encoding_string(key, value)
+        Encoding.find(value)
+      rescue ::ArgumentError
+        errors << "#{key} specifies an unknown encoding name: #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/process_executer/options/spawn_options.rb

@@ -5,16 +5,22 @@ require_relative 'option_definition'
 
 module ProcessExecuter
   module Options
-    # Validate Process.spawn options and return Process.spawn options
+    # Defines and validates options accepted by `Process.spawn`
     #
-    # Allow subclasses to add additional options that are not passed to `Process.spawn`
+    # Allows subclasses to add additional options that are not passed to `Process.spawn`.
     #
-    # Valid options are those accepted by Process.spawn.
+    # Provides a method (#spawn_options) to retrieve only those options directly
+    # applicable to Process.spawn.
     #
     # @api public
     #
     class SpawnOptions < Base
-      # :nocov: SimpleCov on JRuby reports hashes declared on multiple lines as not covered
+      # Options that are passed to Process.spawn
+      #
+      # They are not passed if the value is :not_set
+      #
+      # @return [Array<OptionDefinition>]
+      #
       SPAWN_OPTIONS = [
         OptionDefinition.new(:unsetenv_others, default: :not_set),
         OptionDefinition.new(:pgroup, default: :not_set),
@@ -24,19 +30,21 @@ module ProcessExecuter
         OptionDefinition.new(:close_others, default: :not_set),
         OptionDefinition.new(:chdir, default: :not_set)
       ].freeze
-      # :nocov:
 
       # Returns the options to be passed to Process.spawn
       #
+      # Any options added by subclasses that are not part of the SPAWN_OPTIONS or
+      # are not a redirection option will not be included in the returned hash.
+      #
       # @example
-      #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout_after: 10)
-      #   options.spawn_options # => { out: $stdout, err: $stderr }
+      #   options = ProcessExecuter::Options::SpawnOptions.new(out: $stdout, chdir: '/tmp')
+      #   options.spawn_options # => { out: $stdout, chdir: '/tmp' }
       #
       # @return [Hash]
       #
       def spawn_options
         {}.tap do |spawn_options|
-          options.each do |option_key, value|
+          options_hash.each do |option_key, value|
             spawn_options[option_key] = value if include_spawn_option?(option_key, value)
           end
         end
@@ -71,15 +79,15 @@ module ProcessExecuter
       # Determine the option key that indicates a redirection option for stdout
       # @return [Symbol, Integer, IO, Array, nil] nil if not found
       # @api private
-      def stdout_redirection_key
-        options.keys.find { |option_key| option_key if stdout_redirection?(option_key) }
+      def stdout_redirection_source
+        options_hash.keys.find { |option_key| option_key if stdout_redirection?(option_key) }
       end
 
-      # Determine the value of the redirection option for stdout
-      # @return [Object]
+      # Return the redirection destination for stdout
+      # @return [Symbol, Integer, IO, Array, nil] nil if stdout is not redirected
       # @api private
-      def stdout_redirection_value
-        options[stdout_redirection_key]
+      def stdout_redirection_destination
+        (key = stdout_redirection_source) ? options_hash[key] : nil
       end
 
       # Determine if the given option key indicates a redirection option for stderr
@@ -91,29 +99,22 @@ module ProcessExecuter
       # Determine the option key that indicates a redirection option for stderr
       # @return [Symbol, Integer, IO, Array, nil] nil if not found
       # @api private
-      def stderr_redirection_key
-        options.keys.find { |option_key| option_key if stderr_redirection?(option_key) }
+      def stderr_redirection_source
+        options_hash.keys.find { |option_key| option_key if stderr_redirection?(option_key) }
       end
 
-      # Determine the value of the redirection option for stderr
-      # @return [Object]
+      # Determine redirection destination for stderr if it exists
+      # @return [Symbol, Integer, IO, Array, nil] nil if stderr is not redirected
       # @api private
-      def stderr_redirection_value
-        options[stderr_redirection_key]
+      def stderr_redirection_destination
+        (key = stderr_redirection_source) ? options_hash[key] : nil
       end
 
       private
 
       # Define the allowed options
       #
-      # @example Adding new options in a subclass
-      #   class MyOptions < SpawnOptions
-      #     def define_options
-      #       super.merge(timeout_after: { default: nil, validator: nil })
-      #     end
-      #   end
-      #
-      # @return [Hash<Symbol, Hash>]
+      # @return [Array<OptionDefinition>]
       #
       # @api private
       def define_options
@@ -121,7 +122,7 @@ module ProcessExecuter
       end
 
       # Determine if the given option should be passed to `Process.spawn`
-      # @param option_key [Symbol, Integer, IO] the option to be tested
+      # @param option_key [Object] the option to be tested
       # @param value [Object] the value of the option
       # @return [Boolean] true if the given option should be passed to `Process.spawn`
       # @api private
@@ -132,7 +133,7 @@ module ProcessExecuter
       end
 
       # Spawn allows IO object and integers as options
-      # @param option_key [Symbol] the option to be tested
+      # @param option_key [Object] the option to be tested
       # @return [Boolean] true if the given option is a valid option
       # @api private
       def valid_option?(option_key)

data/lib/process_executer/options/{spawn_and_wait_options.rb → spawn_with_timeout_options.rb}

@@ -5,30 +5,34 @@ require_relative 'option_definition'
 
 module ProcessExecuter
   module Options
-    # Define options for the `ProcessExecuter.spawn_and_wait`
+    # Defines options for {ProcessExecuter.spawn_with_timeout}
     #
     # @api public
     #
-    class SpawnAndWaitOptions < SpawnOptions
+    class SpawnWithTimeoutOptions < SpawnOptions
       private
 
       # The options allowed for objects of this class
       # @return [Array<OptionDefinition>]
       # @api private
       def define_options
-        # :nocov: SimpleCov on JRuby reports the last with the last argument line is not covered
         [
           *super,
           OptionDefinition.new(:timeout_after, default: nil, validator: method(:validate_timeout_after))
         ].freeze
-        # :nocov:
       end
 
-      # Raise an error unless timeout_after is nil or a non-negative real number
+      # Note an error if timeout_after is not nil or a non-negative real number
+      #
+      # @param _key [Symbol] the option key (not used)
+      #
+      # @param _value [Object] the option value (not used)
+      #
       # @return [void]
-      # @raise [ArgumentError] if timeout_after is not a non-negative real number
+      #
       # @api private
-      def validate_timeout_after
+      #
+      def validate_timeout_after(_key, _value)
         return if timeout_after.nil?
         return if timeout_after.is_a?(Numeric) && timeout_after.real? && !timeout_after.negative?
 

data/lib/process_executer/options.rb

@@ -2,11 +2,13 @@
 
 require_relative 'options/base'
 require_relative 'options/spawn_options'
-require_relative 'options/spawn_and_wait_options'
+require_relative 'options/spawn_with_timeout_options'
 require_relative 'options/run_options'
+require_relative 'options/run_with_capture_options'
 require_relative 'options/option_definition'
 
 module ProcessExecuter
   # Options related to spawning or running a command
+  # @api public
   module Options; end
 end

data/lib/process_executer/result.rb

@@ -7,9 +7,7 @@ module ProcessExecuter
   #
   # * `command`: the command that was used to spawn the process
   # * `options`: the options that were used to spawn the process
-  # * `elapsed_time`: the secs the command ran
-  # * `stdout`: the captured stdout output
-  # * `stderr`: the captured stderr output
+  # * `elapsed_time`: the seconds the command ran
   # * `timed_out?`: true if the process timed out
   #
   # @api public
@@ -17,31 +15,25 @@ module ProcessExecuter
   class Result < SimpleDelegator
     # Create a new Result object
     #
-    # @param status [Process::Status] the status to delegate to
-    # @param command [Array] the command that was used to spawn the process
-    # @param options [ProcessExecuter::Options] the options that were used to spawn the process
-    # @param timed_out [Boolean] true if the process timed out
-    # @param elapsed_time [Numeric] the secs the command ran
-    #
     # @example
     #   command = ['sleep 1']
-    #   options = ProcessExecuter::Options.new(timeout_after: 0.5)
-    #   start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    #   timed_out = false
-    #   status = nil
+    #   options = ProcessExecuter::Options::SpawnOptions.new
     #   pid = Process.spawn(*command, **options.spawn_options)
-    #   Timeout.timeout(options.timeout_after) do
-    #     _pid, status = Process.wait2(pid)
-    #   rescue Timeout::Error
-    #     Process.kill('KILL', pid)
-    #     timed_out = true
-    #     _pid, status = Process.wait2(pid)
-    #   end
-    #   elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+    #   _pid, status = Process.wait2(pid)
+    #   timed_out = false
+    #   elapsed_time = 0.01
     #
     #   ProcessExecuter::Result.new(status, command:, options:, timed_out:, elapsed_time:)
     #
-    # @api public
+    # @param status [Process::Status] the status to delegate to
+    #
+    # @param command [Array] the command that was used to spawn the process
+    #
+    # @param options [ProcessExecuter::Options::Base] the options that were used to spawn the process
+    #
+    # @param timed_out [Boolean] true if the process timed out
+    #
+    # @param elapsed_time [Numeric] the seconds the command ran
     #
     def initialize(status, command:, options:, timed_out:, elapsed_time:)
       super(status)
@@ -59,39 +51,42 @@ module ProcessExecuter
     attr_reader :command
 
     # The options that were used to spawn the process
+    #
     # @see Process.spawn
+    #
     # @example
+    #   # Looks like a hash, but is actually an object that derives from
+    #   # ProcessExecuter::Options::Base
     #   result.options #=> { chdir: '/path/to/repo', timeout_after: 0.5 }
-    # @return [Hash]
-    # @api public
+    #
+    # @return [ProcessExecuter::Options::Base]
+    #
     attr_reader :options
 
-    # The secs the command ran
+    # The seconds the command ran
     # @example
-    #   result.elapsed_time #=> 10
-    # @return [Numeric, nil]
-    # @api public
+    #   result.elapsed_time #=> 10.0
+    # @return [Numeric]
     attr_reader :elapsed_time
 
     # @!attribute [r] timed_out?
     # True if the process timed out and was sent the SIGKILL signal
     # @example
-    #   result = ProcessExecuter.spawn('sleep 10', timeout_after: 0.01)
+    #   result = ProcessExecuter.spawn_with_timeout('sleep 10', timeout_after: 0.01)
     #   result.timed_out? # => true
     # @return [Boolean]
     #
-    def timed_out?
-      @timed_out
-    end
+    attr_reader :timed_out
+    alias timed_out? timed_out
 
-    # Overrides the default success? method to return nil if the process timed out
+    # 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
-    #   result = ProcessExecuter.spawn('sleep 10', timeout_after: 0.01)
+    #   result = ProcessExecuter.spawn_with_timeout('sleep 10', timeout_after: 0.01)
     #   result.success? # => nil
-    # @return [true, nil]
+    # @return [true, false, nil]
     #
     def success?
       return nil if timed_out? # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
@@ -101,50 +96,13 @@ module ProcessExecuter
 
     # Return a string representation of the result
     # @example
-    #   result.to_s #=> "pid 70144 SIGKILL (signal 9) timed out after 10s"
+    #   result = ProcessExecuter.spawn_with_timeout('sleep 10', timeout_after: 1)
+    #   # This message is platform dependent, but will look like this on Linux:
+    #   result.to_s #=> "pid 70144 SIGKILL (signal 9) timed out after 1s"
     # @return [String]
-    def to_s
-      "#{super}#{timed_out? ? " timed out after #{options.timeout_after}s" : ''}"
-    end
-
-    # Return the captured stdout output
     #
-    # This output is only returned if the `:out` option value is a
-    # `ProcessExecuter::MonitoredPipe`.
-    #
-    # @example
-    #   # Note that `ProcessExecuter.run` will wrap the given out: object in a
-    #   # ProcessExecuter::MonitoredPipe
-    #   result = ProcessExecuter.run('echo hello': out: StringIO.new)
-    #   result.stdout #=> "hello\n"
-    #
-    # @return [String, nil]
-    #
-    def stdout
-      pipe = options.stdout_redirection_value
-      return nil unless pipe.is_a?(ProcessExecuter::MonitoredPipe)
-
-      pipe.destination.string
-    end
-
-    # Return the captured stderr output
-    #
-    # This output is only returned if the `:err` option value is a
-    # `ProcessExecuter::MonitoredPipe`.
-    #
-    # @example
-    #   # Note that `ProcessExecuter.run` will wrap the given err: object in a
-    #   # ProcessExecuter::MonitoredPipe
-    #   result = ProcessExecuter.run('echo ERROR 1>&2', err: StringIO.new)
-    #   resuilt.stderr #=> "ERROR\n"
-    #
-    # @return [String, nil]
-    #
-    def stderr
-      pipe = options.stderr_redirection_value
-      return nil unless pipe.is_a?(ProcessExecuter::MonitoredPipe)
-
-      pipe.destination.string
+    def to_s
+      "#{super}#{" timed out after #{options.timeout_after}s" if timed_out?}"
     end
   end
 end

data/lib/process_executer/result_with_capture.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module ProcessExecuter
+  # A decorator for ProcessExecuter::Result that adds the following attributes:
+  #
+  # * `stdout`: the captured stdout of the command
+  # * `stderr`: the captured stderr of the command
+  #
+  # @api public
+  #
+  class ResultWithCapture < SimpleDelegator
+    # Create a new ResultWithCapture object
+    #
+    # @param result [ProcessExecuter::Result] the result to delegate to
+    # @param stdout_buffer [StringIO] the captured stdout
+    # @param stderr_buffer [StringIO] the captured stderr
+    #
+    # @example manually create a ResultWithCapture instance
+    #   stdout_buffer = StringIO.new
+    #   stderr_buffer = StringIO.new
+    #   command = ['echo HELLO; echo ERROR >&2']
+    #   result = ProcessExecuter.run(*command, out: stdout_buffer, err: stderr_buffer)
+    #   result_with_capture = ProcessExecuter::ResultWithCapture.new(result, stdout_buffer:, stderr_buffer:)
+    #
+    #   # Normally, you would use the `run_with_capture` method to create a
+    #   # ResultWithCapture instance. The above code is equivalent to:
+    #
+    #   result_with_capture = ProcessExecuter.run_with_capture('echo HELLO; echo ERROR >&2')
+    #
+    def initialize(result, stdout_buffer:, stderr_buffer:)
+      super(result)
+      @stdout_buffer = stdout_buffer
+      @stderr_buffer = stderr_buffer
+    end
+
+    # The buffer used to capture stdout
+    # @example
+    #   result.stdout_buffer #=> #<StringIO:0x00007f8c1b0a2d80>
+    # @return [StringIO]
+    attr_reader :stdout_buffer
+
+    # The captured stdout of the command
+    # @example
+    #   result.stdout #=> "HELLO\n"
+    # @return [String]
+    def stdout = @stdout_buffer.string
+
+    # The buffer used to capture stderr
+    # @example
+    #   result.stderr_buffer #=> #<StringIO:0x00007f8c1b0a2d80>
+    # @return [StringIO]
+    attr_reader :stderr_buffer
+
+    # The captured stderr of the command
+    # @example
+    #   result.stderr #=> "ERROR\n"
+    # @return [String]
+    def stderr = @stderr_buffer.string
+  end
+end

data/lib/process_executer/version.rb

@@ -2,5 +2,6 @@
 
 module ProcessExecuter
   # The current Gem version
-  VERSION = '3.2.4'
+  # @return [String]
+  VERSION = '4.0.0'
 end