process_executer 2.0.0 → 3.0.0

data/lib/process_executer/options/base.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require_relative 'option_definition'
+
+module ProcessExecuter
+  module Options
+    # Defines, validates, and holds a set of option values
+    #
+    # Options are defined by subclasses by overriding the `define_options` method.
+    #
+    # @example Define an options class with two options
+    #   class MyOptions < ProcessExecuter::Options::Base
+    #     def define_options
+    #       # Call super to include options defined in the parent class
+    #       [
+    #         *super,
+    #         ProcessExecuter::Options::OptionDefinition.new(:option1),
+    #         ProcessExecuter::Options::OptionDefinition.new(:option2)
+    #       ]
+    #     end
+    #   end
+    #   options_hash = { options1: 'value1', option2: 'value2' }
+    #   options = MyOptions.new(options_hash)
+    #   options.option1 # => 'value1'
+    #   options.option2 # => 'value2'
+    #
+    # @api public
+    class Base
+      # Create a new Options object
+      #
+      # @example
+      #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout_after: 10)
+      #
+      # @param options [Hash] Process.spawn options plus additional options listed below.
+      #
+      #   See [Process.spawn](https://ruby-doc.org/core/Process.html#method-c-spawn)
+      #   for a list of valid options that can be passed to `Process.spawn`.
+      #
+      # @option options [Integer, Float, nil] :timeout_after
+      #   Number of seconds to wait for the process to terminate. Any number
+      #   may be used, including Floats to specify fractional seconds. A value of 0 or nil
+      #   will allow the process to run indefinitely.
+      #
+      def initialize(**options)
+        @options = allowed_options.transform_values(&:default).merge(options)
+        @errors = []
+        assert_no_unknown_options
+        define_accessor_methods
+        validate_options
+      end
+
+      # All the allowed options as a hash whose keys are the option names
+      #
+      # The returned hash what is returned from `define_options` but with the
+      # option names as keys. The values are instances of `OptionDefinition`.
+      #
+      # The returned hash is frozen and cannot be modified.
+      #
+      # @example
+      #   options.allowed_options # => { timeout_after: #<OptionDefinition>, ... }
+      #
+      # @return [Hash]
+      #
+      def allowed_options
+        @allowed_options ||=
+          define_options.each_with_object({}) do |option, hash|
+            hash[option.name] = option
+          end.freeze
+      end
+
+      # A string representation of the object that includes the options
+      # @example
+      #   options = ProcessExecuter::Options.new(option1: 'value1', option2: 'value2')
+      #   options.to_s # => #<ProcessExecuter::Options:0x00007f8f9b0b3d20 option1: "value1", option2: "value2">'
+      # @return [String]
+      def to_s
+        "#{super.to_s[0..-2]} #{inspect}>"
+      end
+
+      # A string representation of the options
+      # @example
+      #   options = ProcessExecuter::Options.new(option1: 'value1', option2: 'value2')
+      #   options.inspect # => '{:option1=>"value1", :option2=>"value2"}'
+      # @return [String]
+      def inspect
+        options.inspect
+      end
+
+      # A hash representation of the options
+      # @example
+      #   options = ProcessExecuter::Options.new(option1: 'value1', option2: 'value2')
+      #   options.to_h # => { option1: "value1", option2: "value2" }
+      # @return [Hash]
+      def to_h
+        @options.dup
+      end
+
+      # Iterate over each option with an object
+      # @example
+      #   options = ProcessExecuter::Options.new(option1: 'value1', option2: 'value2')
+      #   options.each_with_object({}) { |(option_key, option_value), obj| obj[option_key] = option_value }
+      #   # => { option1: "value1", option2: "value2" }
+      # @yield [option_key, option_value, obj]
+      # @return [void]
+      def each_with_object(obj, &)
+        @options.each_with_object(obj, &)
+      end
+
+      # Merge the given options into the current options
+      # @example
+      #   options = ProcessExecuter::Options.new(option1: 'value1', option2: 'value2')
+      #   options.merge!(option2: 'new_value2', option3: 'value3')
+      #   options.option2 # => 'new_value2'
+      #   options.option3 # => 'value3'
+      #
+      # @param other_options [Hash] the options to merge into the current options
+      # @return [void]
+      def merge!(**other_options)
+        @options.merge!(other_options)
+      end
+
+      # A shallow copy of self with options copied but not the values they reference
+      #
+      # If any keyword arguments are given, the copy will be created with the
+      # respective option values updated.
+      #
+      # @example
+      #   options_hash = { option1: 'value1', option2: 'value2' }
+      #   options = ProcessExecuter::MyOptions.new(options_hash)
+      #   copy = options.with(option1: 'new_value1')
+      #   copy.option1 # => 'new_value1'
+      #   copy.option2 # => 'value2'
+      #   options.option1 # => 'value1'
+      #   options.option2 # => 'value2'
+      #
+      # @options_hash [Hash] the options to merge into the current options
+      # @return [self.class]
+      #
+      def with(**options_hash)
+        self.class.new(**@options, **options_hash)
+      end
+
+      # The list of validation errors
+      #
+      # Validators should add an error messages to this array.
+      #
+      # @example
+      #   options = ProcessExecuter::Options::RunOptions.new(timeout_after: 'not_a_number', raise_errors: 'yes')
+      #   #=> raises an Argument error with the following message:
+      #       timeout_after must be nil or a non-negative real number but was "not_a_number"
+      #       raise_errors must be true or false but was "yes""
+      #    errors # => [
+      #      "timeout_after must be nil or a non-negative real number but was \"not_a_number\"",
+      #      "raise_errors must be true or false but was \"yes\""
+      #    ]
+      #
+      # @return [Array<String>]
+      # @api private
+      attr_reader :errors
+
+      protected
+
+      # An array of OptionDefinition objects that define the allowed options
+      #
+      # Subclasses MUST override this method to define the allowed options.
+      #
+      # @return [Array<OptionDefinition>]
+      #
+      # @api private
+      #
+      def define_options
+        [].freeze
+      end
+
+      # Determine if the given option is a valid option
+      #
+      # May be overridden by subclasses to add additional validation.
+      #
+      # @param option [Symbol] the option to be tested
+      # @return [Boolean] true if the given option is a valid option
+      # @api private
+      def valid_option?(option)
+        allowed_options.keys.include?(option)
+      end
+
+      private
+
+      # @!attribute [r]
+      #
+      # A hash of all options keyed by the option name
+      #
+      # @return [Hash{Symbol => Object}]
+      #
+      # @api private
+      #
+      attr_reader :options
+
+      # Raise an argument error for invalid option values
+      # @return [void]
+      # @raise [ArgumentError] if any invalid option values are found
+      # @api private
+      def validate_options
+        options.each_key do |option_key|
+          validator = allowed_options[option_key]&.validator
+          instance_exec(&validator.to_proc) unless validator.nil?
+        end
+
+        raise ArgumentError, errors.join("\n") unless errors.empty?
+      end
+
+      # Define accessor methods for each option
+      # @return [void]
+      # @api private
+      def define_accessor_methods
+        allowed_options.each_key do |option|
+          define_singleton_method(option) do
+            @options[option]
+          end
+        end
+      end
+
+      # Determine if the options hash contains any unknown options
+      # @return [void]
+      # @raise [ArgumentError] if the options hash contains any unknown options
+      # @api private
+      def assert_no_unknown_options
+        unknown_options = options.keys.reject { |key| valid_option?(key) }
+
+        return if unknown_options.empty?
+
+        # :nocov: SimpleCov on JRuby reports the last with the last argument line is not covered
+        raise(
+          ArgumentError,
+          "Unknown option#{unknown_options.count > 1 ? 's' : ''}: #{unknown_options.join(', ')}"
+        )
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/process_executer/options/option_definition.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ProcessExecuter
+  module Options
+    # Defines an option that can be used by an Options object
+    #
+    # @api public
+    #
+    class OptionDefinition
+      # The name of the option
+      #
+      # @example
+      #   option = ProcessExecuter::Options::OptionDefinition.new(:timeout_after)
+      #   option.name # => :timeout_after
+      #
+      # @return [Symbol]
+      #
+      attr_reader :name
+
+      # The default value of the option
+      #
+      # @example
+      #   option = ProcessExecuter::Options::OptionDefinition.new(:timeout_after, default: 10)
+      #   option.default # => 10
+      #
+      # @return [Object]
+      #
+      attr_reader :default
+
+      # A method or proc that validates the option
+      #
+      # @example
+      #   option = ProcessExecuter::Options::OptionDefinition.new(
+      #     :timeout_after, validator: method(:validate_timeout_after)
+      #   )
+      #   option.validator # => #<Method: ProcessExecuter#validate_timeout_after>
+      #
+      # @return [Method, Proc, nil]
+      #
+      attr_reader :validator
+
+      # Create a new option definition
+      #
+      # @example
+      #   option = ProcessExecuter::Options::OptionDefinition.new(
+      #     :timeout_after, default: 10, validator: -> { timeout_after.is_a?(Numeric) }
+      #   )
+      #
+      def initialize(name, default: nil, validator: nil)
+        @name = name
+        @default = default
+        @validator = validator
+      end
+    end
+  end
+end

data/lib/process_executer/options/run_options.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'spawn_and_wait_options'
+require_relative 'option_definition'
+
+module ProcessExecuter
+  module Options
+    # Define options for the `ProcessExecuter.run`
+    #
+    # @api public
+    #
+    class RunOptions < SpawnAndWaitOptions
+      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
+      def define_options
+        [
+          *super,
+          OptionDefinition.new(:raise_errors, default: true, validator: method(:validate_raise_errors)),
+          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
+      # @api private
+      def validate_raise_errors
+        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
+      # @api private
+      def validate_logger
+        return if logger.respond_to?(:info) && logger.respond_to?(:debug)
+
+        errors << "logger must respond to #info and #debug but was #{logger.inspect}"
+      end
+    end
+  end
+end

data/lib/process_executer/options/spawn_and_wait_options.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'spawn_options'
+require_relative 'option_definition'
+
+module ProcessExecuter
+  module Options
+    # Define options for the `ProcessExecuter.spawn_and_wait`
+    #
+    # @api public
+    #
+    class SpawnAndWaitOptions < 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
+      # @return [void]
+      # @raise [ArgumentError] if timeout_after is not a non-negative real number
+      # @api private
+      def validate_timeout_after
+        return if timeout_after.nil?
+        return if timeout_after.is_a?(Numeric) && timeout_after.real? && !timeout_after.negative?
+
+        errors << "timeout_after must be nil or a non-negative real number but was #{timeout_after.inspect}"
+      end
+    end
+  end
+end

data/lib/process_executer/options/spawn_options.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'option_definition'
+
+module ProcessExecuter
+  module Options
+    # Validate Process.spawn options and return Process.spawn options
+    #
+    # Allow subclasses to add additional options that are not passed to `Process.spawn`
+    #
+    # Valid options are those accepted by Process.spawn.
+    #
+    # @api public
+    #
+    class SpawnOptions < Base
+      # :nocov: SimpleCov on JRuby reports hashes declared on multiple lines as not covered
+      SPAWN_OPTIONS = [
+        OptionDefinition.new(:unsetenv_others, default: :not_set),
+        OptionDefinition.new(:pgroup, default: :not_set),
+        OptionDefinition.new(:new_pgroup, default: :not_set),
+        OptionDefinition.new(:rlimit_resourcename, default: :not_set),
+        OptionDefinition.new(:umask, default: :not_set),
+        OptionDefinition.new(:close_others, default: :not_set),
+        OptionDefinition.new(:chdir, default: :not_set)
+      ].freeze
+      # :nocov:
+
+      # Returns the options to be passed to Process.spawn
+      #
+      # @example
+      #   options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout_after: 10)
+      #   options.spawn_options # => { out: $stdout, err: $stderr }
+      #
+      # @return [Hash]
+      #
+      def spawn_options
+        {}.tap do |spawn_options|
+          options.each do |option_key, value|
+            spawn_options[option_key] = value if include_spawn_option?(option_key, value)
+          end
+        end
+      end
+
+      # Determine if the given option key indicates a redirection option
+      # @param option_key [Symbol, Integer, IO, Array] the option key to be tested
+      # @return [Boolean]
+      # @api private
+      def redirection?(option_key)
+        test = ->(key) { %i[in out err].include?(key) || key.is_a?(Integer) || (key.is_a?(IO) && !key.fileno.nil?) }
+        test.call(option_key) || (option_key.is_a?(Array) && option_key.all? { |key| test.call(key) })
+      end
+
+      # Does option_key indicate a standard redirection such as stdin, stdout, or stderr
+      # @param option_key [Symbol, Integer, IO, Array] the option key to be tested
+      # @param symbol [:in, :out, :err] the symbol to test for
+      # @param fileno [Integer] the file descriptor number to test for
+      # @return [Boolean]
+      # @api private
+      def std_redirection?(option_key, symbol, fileno)
+        test = ->(key) { key == symbol || key == fileno || (key.is_a?(IO) && key.fileno == fileno) }
+        test.call(option_key) || (option_key.is_a?(Array) && option_key.any? { |key| test.call(key) })
+      end
+
+      # Determine if the given option key indicates a redirection option for stdout
+      # @param option_key [Symbol, Integer, IO, Array] the option key to be tested
+      # @return [Boolean]
+      # @api private
+      def stdout_redirection?(option_key) = std_redirection?(option_key, :out, 1)
+
+      # 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) }
+      end
+
+      # Determine the value of the redirection option for stdout
+      # @return [Object]
+      # @api private
+      def stdout_redirection_value
+        options[stdout_redirection_key]
+      end
+
+      # Determine if the given option key indicates a redirection option for stderr
+      # @param option_key [Symbol, Integer, IO, Array] the option key to be tested
+      # @return [Boolean]
+      # @api private
+      def stderr_redirection?(option_key) = std_redirection?(option_key, :err, 2)
+
+      # 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) }
+      end
+
+      # Determine the value of the redirection option for stderr
+      # @return [Object]
+      # @api private
+      def stderr_redirection_value
+        options[stderr_redirection_key]
+      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>]
+      #
+      # @api private
+      def define_options
+        [*super, *SPAWN_OPTIONS].freeze
+      end
+
+      # Determine if the given option should be passed to `Process.spawn`
+      # @param option_key [Symbol, Integer, IO] 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
+      def include_spawn_option?(option_key, value)
+        return false if value == :not_set
+
+        redirection?(option_key) || SPAWN_OPTIONS.any? { |o| o.name == option_key }
+      end
+
+      # Spawn allows IO object and integers as options
+      # @param option_key [Symbol] the option to be tested
+      # @return [Boolean] true if the given option is a valid option
+      # @api private
+      def valid_option?(option_key)
+        super || redirection?(option_key)
+      end
+    end
+  end
+end