cuprum 1.2.0.rc.0 → 1.3.0.rc.0

data/lib/cuprum/parameter_validation.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools'
+
+require 'cuprum'
+require 'cuprum/utils/parameters_mapping'
+
+module Cuprum
+  # Mixin for declaring validations for command parameters.
+  module ParameterValidation
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    autoload :ValidationRule, 'cuprum/parameter_validation/validation_rule'
+    autoload :Validator,      'cuprum/parameter_validation/validator'
+
+    # Class methods for parameter validation.
+    module ClassMethods
+      # @private
+      def each_validation(&)
+        return enum_for(:each_validation) unless block_given?
+
+        ancestors.reverse_each do |ancestor|
+          next unless ancestor.respond_to?(:validation_rules, true)
+
+          ancestor.validation_rules.each(&)
+        end
+      end
+
+      # @overload validate(name, **options)
+      #   Defines a validation for the specified parameter.
+      #
+      #   This validation will call the #validate_$name method on the command
+      #   with the value of the named parameter. If the method returns a failure
+      #   message, that message is added to the failed validations.
+      #
+      #   @param name [String, Symbol] the parameter to validate.
+      #   @param options [Hash] additional options to pass to the validation
+      #     method.
+      #
+      #   @option options as [String, Symbol] the name of the parameter as
+      #     displayed in the failure message, if any. Defaults to the value of
+      #     the name parameter.
+      #
+      #   @return void
+      #
+      # @overload validate(name, using:, **options)
+      #   Defines a validation for the specified parameter.
+      #
+      #   This validation will call the named method on the command with the
+      #   value of the named parameter. If the method returns a failure message,
+      #   that message is added to the failed validations.
+      #
+      #   @param name [String, Symbol] the parameter to validate.
+      #   @param using [String, Symbol] the name of the method used to validate
+      #     the parameter.
+      #   @param options [Hash] additional options to pass to the validation
+      #     method.
+      #
+      #   @option options as [String, Symbol] the name of the parameter as
+      #     displayed in the failure message, if any. Defaults to the value of
+      #     the name parameter.
+      #
+      #   @return void
+      #
+      # @overload validate(name, **options, &block)
+      #   Defines a validation for the specified parameter.
+      #
+      #   This validation will call the given block with the value of the named
+      #   parameter. If the block returns nil or false, a failure message is
+      #   added to the failed validations
+      #
+      #   @param name [String, Symbol] the parameter to validate.
+      #   @param options [Hash] additional options for the validation.
+      #
+      #   @option options as [String, Symbol] the name of the parameter as
+      #     displayed in the failure message, if any. Defaults to the value of
+      #     the name parameter.
+      #   @option options message [String] the failure message to display.
+      #     Defaults to "$name is invalid".
+      #
+      #   @yield the block to validate the parameter.
+      #   @yieldparam value [Object] the value of the named parameter.
+      #   @yieldreturn [true, false] true if the given value is valid for the
+      #     parameter; otherwise false.
+      #
+      #   @return void
+      #
+      # @overload validate(name, type, **options)
+      #   Defines a validation for the specified parameter.
+      #
+      #   This validation will call the #validate_$type method on the command
+      #   with the value of the named parameter. If the method returns a failure
+      #   message, that message is added to the failed validations.
+      #
+      #   If the command does not define the method, it will call the
+      #   SleepingKingStudios::Tools::Assertions instance method with the same
+      #   name. If the validation fails, the failure message is added to the
+      #   failed validations.
+      #
+      #   @param name [String, Symbol] the parameter to validate.
+      #   @param type [String, Symbol] the validation method to run.
+      #   @param options [Hash] additional options to pass to the validation
+      #     method.
+      #
+      #   @option options as [String, Symbol] the name of the parameter as
+      #     displayed in the failure message, if any. Defaults to the value of
+      #     the name parameter.
+      #   @option options message [String] the message to display on a failed
+      #     validation.
+      #
+      #   @raise [Cuprum::ParameterValidation::Validator::UnknownValidationError]
+      #     if neither the command nor the standard tools defines the method.
+      def validate(name, type = nil, using: nil, **options, &)
+        tools.assertions.validate_name(name, as: 'name')
+
+        if type && !type.is_a?(Module)
+          tools.assertions.validate_name(type, as: 'type')
+        end
+
+        tools.assertions.validate_name(using, as: 'using') if using
+
+        validation_rules <<
+          build_validation_rule(name:, options:, type:, using:, &)
+      end
+
+      # @private
+      def validate_parameters(command, ...)
+        parameters = parameters_mapping.call(...)
+        rules      = each_validation
+
+        Validator.new.call(command:, parameters:, rules:)
+      rescue NameError => exception
+        raise unless exception.name == :process
+
+        error = Cuprum::Errors::CommandNotImplemented.new(command:)
+
+        Cuprum::Result.new(error:)
+      end
+
+      protected
+
+      def validation_rules
+        @validation_rules ||= []
+      end
+
+      private
+
+      def build_block_validation(name, **options, &)
+        type = ValidationRule::BLOCK_VALIDATION_TYPE
+
+        ValidationRule.new(name:, type:, as: name.to_s, **options, &)
+      end
+
+      def build_method_validation(name, method_name, **options)
+        type = ValidationRule::NAMED_VALIDATION_TYPE
+
+        ValidationRule.new(name:, type:, as: name.to_s, method_name:, **options)
+      end
+
+      def build_named_validation(name, **options)
+        type = ValidationRule::NAMED_VALIDATION_TYPE
+
+        ValidationRule.new(name:, type:, as: name.to_s, **options)
+      end
+
+      def build_type_validation(name, type, **options)
+        unless type.is_a?(Module)
+          return ValidationRule.new(name:, type:, as: name.to_s, **options)
+        end
+
+        ValidationRule.new(
+          name:,
+          type:     :instance_of,
+          as:       name.to_s,
+          expected: type,
+          **options
+        )
+      end
+
+      def build_validation_rule(name:, options:, type:, using:, &)
+        return build_type_validation(name, type, **options) if type
+
+        return build_method_validation(name, using, **options) if using
+
+        return build_block_validation(name, **options, &) if block_given?
+
+        build_named_validation(name, **options)
+      end
+
+      def parameters_mapping
+        @parameters_mapping ||=
+          Cuprum::Utils::ParametersMapping.build(instance_method(:process))
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+    end
+
+    # @overload call(*arguments, **keywords, &block)
+    #   Validates the parameters and passes them to super.
+    #
+    #   @param arguments [Array] the arguments to validate.
+    #   @param keywords [Hash] the keywords to validate.
+    #   @param block [Proc] the block to validate, if any,
+    #
+    #   @return [Cuprum::Result] a failing result with a
+    #     Cuprum::Errors::InvalidParameters error if the validation fails;
+    #     otherwise the normal result of calling the command.
+    #
+    #   @see Cuprum::Processing#call.
+    def call(...)
+      result = self.class.validate_parameters(self, ...)
+
+      return result if result.failure?
+
+      super
+    end
+  end
+end

data/lib/cuprum/processing.rb

@@ -95,17 +95,17 @@ module Cuprum
     #
     #   @yield If a block argument is given, it will be passed to the
     #     implementation.
-    def call(*args, **kwargs, &block)
+    def call(*args, **kwargs, &)
       value =
         if kwargs.empty?
-          process(*args, &block)
+          process(*args, &)
         else
-          process(*args, **kwargs, &block)
+          process(*args, **kwargs, &)
         end
 
       return value.to_cuprum_result if value_is_result?(value)
 
-      build_result(value: value)
+      build_result(value:)
     end
 
     private
@@ -136,7 +136,7 @@ module Cuprum
     def process(*_args)
       error = Cuprum::Errors::CommandNotImplemented.new(command: self)
 
-      build_result(error: error)
+      build_result(error:)
     end
 
     def value_is_result?(value)

data/lib/cuprum/result.rb

@@ -54,9 +54,9 @@ module Cuprum
     # @return [Hash{Symbol => Object}] a Hash representation of the result.
     def properties
       {
-        error:  error,
-        status: status,
-        value:  value
+        error:,
+        status:,
+        value:
       }
     end
     alias_method :to_h, :properties

data/lib/cuprum/result_helpers.rb

@@ -8,15 +8,15 @@ module Cuprum
     private
 
     def build_result(error: nil, status: nil, value: nil)
-      Cuprum::Result.new(error: error, status: status, value: value)
+      Cuprum::Result.new(error:, status:, value:)
     end
 
     def failure(error)
-      build_result(error: error)
+      build_result(error:)
     end
 
     def success(value)
-      build_result(value: value)
+      build_result(value:)
     end
   end
 end

data/lib/cuprum/result_list.rb

@@ -143,7 +143,7 @@ module Cuprum
     # @see #status
     # @see #value
     def to_cuprum_result
-      Cuprum::Result.new(error: error, status: status, value: value)
+      Cuprum::Result.new(error:, status:, value:)
     end
 
     # @return [Array<Object, nil>] the value, if any, for each result.
@@ -156,7 +156,7 @@ module Cuprum
     def build_error
       return if errors.compact.empty?
 
-      Cuprum::Errors::MultipleErrors.new(errors: errors)
+      Cuprum::Errors::MultipleErrors.new(errors:)
     end
 
     def build_status

data/lib/cuprum/rspec/be_a_result_matcher.rb

@@ -104,7 +104,7 @@ module Cuprum::RSpec
     # @param actual [Object] the actual object to match.
     #
     # @return [Boolean] false if the actual object is a result; otherwise true.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicateName
       @actual = actual
 
       raise ArgumentError, negated_matcher_warning if expected_properties?

data/lib/cuprum/rspec/deferred/parameter_validation_examples.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/deferred'
+
+require 'cuprum/errors/invalid_parameters'
+require 'cuprum/rspec/be_a_result'
+require 'cuprum/rspec/deferred'
+
+module Cuprum::RSpec::Deferred
+  # Deferred examples for testing parameter validation.
+  #
+  # @example With A Validation Type
+  #   RSpec.describe LaunchRocket do
+  #     include Cuprum::RSpec::Deferred::ParameterValidationExamples
+  #
+  #     describe '#call' do
+  #       let(:launch_site) { 'KSC' }
+  #
+  #       def call_command
+  #         subject.call(launch_site:)
+  #       end
+  #
+  #       describe 'with invalid parameters' do
+  #         let(:launch_site) { nil }
+  #
+  #         include_deferred 'should validate the parameter',
+  #           :launch_site,
+  #           'sleeping_king_studios.tools.assertions.presence',
+  #           as: 'launch site'
+  #       end
+  #     end
+  #   end
+  #
+  # @example With A Message
+  #   RSpec.describe LaunchRocket do
+  #     include Cuprum::RSpec::Deferred::ParameterValidationExamples
+  #
+  #     describe '#call' do
+  #       let(:launch_site) { 'KSC' }
+  #
+  #       def call_command
+  #         subject.call(launch_site:)
+  #       end
+  #
+  #       describe 'with invalid parameters' do
+  #         let(:launch_site) { nil }
+  #
+  #         include_deferred 'should validate the parameter',
+  #           :launch_site,
+  #           message: "launch site can't be blank"
+  #       end
+  #     end
+  #   end
+  module ParameterValidationExamples
+    include Cuprum::RSpec::Matchers
+    include RSpec::SleepingKingStudios::Deferred::Provider
+
+    deferred_examples 'should validate the parameter' \
+    do |name, type = nil, message: nil, **options|
+      it 'should return a failing result with InvalidParameters error' do
+        expected_failure =
+          message ||
+          tools.assertions.error_message_for(type, as: name, **options)
+        expected_error   = Cuprum::Errors::InvalidParameters.new(
+          command_class: subject.class,
+          failures:      [expected_failure]
+        )
+
+        expect(call_command)
+          .to be_a_failing_result
+          .with_error(expected_error)
+      end
+    end
+
+    private
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/rspec/deferred.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/rspec'
+
+module Cuprum::RSpec
+  # Namespace for deferred example groups for validating Cuprum commands.
+  module Deferred; end
+end

data/lib/cuprum/utils/instance_spy.rb

@@ -30,7 +30,7 @@ module Cuprum::Utils
     # Minimal class double implementing the #call method.
     class Spy
       # Empty method that accepts any parameters and an optional block.
-      def call(*_args, **_kwargs, &block); end
+      def call(*_args, **_kwargs, &); end
     end
 
     class << self
@@ -96,8 +96,8 @@ module Cuprum::Utils
         Cuprum::Utils::InstanceSpy::Spy.new
       end
 
-      def call_spies_for(command, *args, &block)
-        spies_for(command).each { |spy| spy.call(*args, &block) }
+      def call_spies_for(command, ...)
+        spies_for(command).each { |spy| spy.call(...) }
       end
 
       def guard_spy_class!(command_class)
@@ -127,13 +127,13 @@ module Cuprum::Utils
     end
 
     # (see Cuprum::Processing#call)
-    def call(*args, **kwargs, &block)
+    def call(*args, **kwargs, &)
       if kwargs.empty?
-        Cuprum::Utils::InstanceSpy.send(:call_spies_for, self, *args, &block)
+        Cuprum::Utils::InstanceSpy.send(:call_spies_for, self, *args, &)
       else
         # :nocov:
         Cuprum::Utils::InstanceSpy
-          .send(:call_spies_for, self, *args, **kwargs, &block)
+          .send(:call_spies_for, self, *args, **kwargs, &)
         # :nocov:
       end
 

data/lib/cuprum/utils/parameters_mapping.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require 'cuprum/utils'
+
+module Cuprum::Utils
+  # Utility class mapping a method's parameters by parameter name.
+  class ParametersMapping
+    # Generates a parameters mapping for the given method or Proc.
+    #
+    # @param callable [#parameters] the method or Proc for which to map
+    #   parameters.
+    #
+    # @return [ParametersMapping] the mapping for the callable object.
+    def self.build(callable) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+      arguments          = []
+      block              = nil
+      keywords           = []
+      variadic_arguments = nil
+      variadic_keywords  = nil
+
+      callable.parameters.each do |(type, name)|
+        next if name.nil?
+
+        case type
+        when :opt, :req
+          arguments << name
+        when :key, :keyreq
+          keywords << name
+        when :rest
+          variadic_arguments = name
+        when :keyrest
+          variadic_keywords = name
+        when :block
+          block = name
+        end
+      end
+
+      new(
+        arguments:,
+        block:,
+        keywords:,
+        variadic_arguments:,
+        variadic_keywords:
+      )
+    end
+
+    # @param arguments [Array<Symbol>] the named arguments to the method, both
+    #   required and optional, but excluding variadic args).
+    # @param block [Symbol, nil] the name of the block parameter, if any.
+    # @param keywords [Array<Symbol>] the keywords for the method, both
+    #   required and optional, but excluding variadic keywords.
+    # @param variadic_arguments [Symbol] the name of the variadic arguments
+    #   parameter, if any.
+    # @param variadic_keywords [Symbol] the name of the variadic keywords
+    #   parameter, if any.
+    def initialize(
+      arguments:          [],
+      keywords:           [],
+      block:              nil,
+      variadic_arguments: nil,
+      variadic_keywords:  nil
+    )
+      @arguments          = arguments.map(&:to_sym).freeze
+      @block              = block&.to_sym
+      @keywords           = Set.new(keywords.map(&:to_sym)).freeze
+      @variadic_arguments = variadic_arguments&.to_sym
+      @variadic_keywords  = variadic_keywords&.to_sym
+    end
+
+    # @return [Hash{Symbol=>Integer}] the named arguments to the method, both
+    #   required and optional, but excluding variadic args).
+    attr_reader :arguments
+
+    # @return [Symbol, nil] the name of the block parameter, if any.
+    attr_reader :block
+
+    # @return [Set<Symbol>] the keywords for the method, both required and
+    #   optional, but excluding variadic keywords.
+    attr_reader :keywords
+
+    # @return [Symbol] the name of the variadic arguments parameter, if any.
+    attr_reader :variadic_arguments
+
+    # @return [Symbol] the name of the variadic keywords parameter, if any.
+    attr_reader :variadic_keywords
+
+    # @return [Integer] the number of named arguments.
+    def arguments_count
+      @arguments_count ||= arguments.size
+    end
+
+    # @return [true, false] true if the method has a block parameter; otherwise
+    #   false.
+    def block?
+      !@block.nil?
+    end
+
+    # @overload call(*arguments, **keywords, &block)
+    #   Maps the given parameters to a Hash of parameter names and values.
+    #
+    #   @param arguments [Array] the positional parameters to map.
+    #   @param keywords [Hash] the keyword parameters to map.
+    #   @param block [Proc] the block parameter to map, if any.
+    #
+    #   @return [Hash{Symbol=>Object}] the mapped parameters.
+    def call(*args, **kwargs, &block_arg) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      params = {}
+      extras = {}
+
+      arguments.each.with_index { |name, index| params[name] = args[index] }
+
+      if variadic_arguments?
+        params[variadic_arguments] = args[arguments_count..] || []
+      end
+
+      keywords.each { |name| params[name] = nil }
+
+      kwargs.each do |(name, value)|
+        (keywords.include?(name) ? params : extras)[name] = value
+      end
+
+      params[variadic_keywords] = extras if variadic_keywords?
+
+      params[block] = block_arg if block?
+
+      params
+    end
+
+    # @return [true, false] true if the method has a variadic arguments
+    #   parameter; otherwise false.
+    def variadic_arguments?
+      !@variadic_arguments.nil?
+    end
+
+    # @return [true, false] true if the method has a variadic keywords
+    #   parameter; otherwise false.
+    def variadic_keywords?
+      !@variadic_keywords.nil?
+    end
+  end
+end

data/lib/cuprum/version.rb

@@ -10,7 +10,7 @@ module Cuprum
     # Major version.
     MAJOR = 1
     # Minor version.
-    MINOR = 2
+    MINOR = 3
     # Patch version.
     PATCH = 0
     # Prerelease version.

data/lib/cuprum.rb

@@ -2,20 +2,26 @@
 
 # Toolkit for implementing business logic as function objects.
 module Cuprum
-  autoload :Command,    'cuprum/command'
-  autoload :Error,      'cuprum/error'
-  autoload :MapCommand, 'cuprum/map_command'
-  autoload :Matcher,    'cuprum/matcher'
-  autoload :Middleware, 'cuprum/middleware'
-  autoload :Operation,  'cuprum/operation'
-  autoload :Result,     'cuprum/result'
-  autoload :ResultList, 'cuprum/result_list'
-  autoload :Steps,      'cuprum/steps'
+  autoload :Command,             'cuprum/command'
+  autoload :CommandFactory,      'cuprum/command_factory'
+  autoload :Currying,            'cuprum/currying'
+  autoload :Error,               'cuprum/error'
+  autoload :ExceptionHandling,   'cuprum/exception_handling'
+  autoload :MapCommand,          'cuprum/map_command'
+  autoload :Matcher,             'cuprum/matcher'
+  autoload :Middleware,          'cuprum/middleware'
+  autoload :Operation,           'cuprum/operation'
+  autoload :ParameterValidation, 'cuprum/parameter_validation'
+  autoload :Result,              'cuprum/result'
+  autoload :ResultList,          'cuprum/result_list'
+  autoload :Steps,               'cuprum/steps'
 
   class << self
-    # @return [String] The current version of the gem.
+    # @return [String] the current version of the gem.
     def version
       VERSION
     end
   end
 end
+
+require 'cuprum/version'