cuprum 1.2.0 → 1.3.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab108b9d6630d5ebb692b2a918654cc9a6a2cb6256a5aad7331b40bd2ea7f1d
-  data.tar.gz: 55e8f74553df29e8b244e69257c9178b3b8ea0b931c4f8b7a58ae4f587d17e27
+  metadata.gz: 878254bafd0929c73d6762f9fe732bbf647ae7d595c52733a53b1cd4115a308d
+  data.tar.gz: 4612a002c3523ea886274e4463e15d0d7139185cbebb5752e7ab4a0289d2d776
 SHA512:
-  metadata.gz: 3f520bbc963d86937b02b8f7849bb064afafa32e43d47e8e5b394f5ff598e05665ba366bf2bffc44f7a3964982c28dba90d7621ab11b6b5a981217a092b62e15
-  data.tar.gz: b3b1b63fa90af7d8f2edfd1d7db6ce5b14e2f10397907fd9dcd07138d4c0d5f70a0d1b538c5c7bd2cb1c9b0a10dfd94997c673ba293dbedfcb0855dda413c43d
+  metadata.gz: 537237e0cb5d7013af24907c0f2a7daf4d2967b5ad22bbfe078a76d7fc975df623f0119428ed0a6a962033e7d50ab8b9544b5bc590814ea65cbcc05d1fc5ea0d
+  data.tar.gz: 12fbd72264936ffaba10313fdc5a20ddd0c3003532c83ef47bb4accecf5652864d7dc99975ae96c86caaf00bfe7f8b1a2d206d46ea2626579ff9dcaf661ab019

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.3.0
+
+The "A Dream Given Form" Update
+
+As of version 1.3.0, Cuprum will no longer support Ruby 3.0.
+
+### Commands
+
+Updated `Cuprum::ExceptionHandling` to re-raise the exception if the `ENV['CUPRUM_RERAISE_EXCEPTIONS']` flag is set.
+
+Implemented `Command.subclass`, allowing partial application of constructor parameters (including the implementation block).
+
+Refactored `Command.new(&block)`, which no longer overwrites the `#process` method directly. Commands can now use `super` in the `#process` method to wrap a block implementation (or the parent class implementation if the parent class overrides `#process`).
+
+**Breaking Change:** The private method `Command#process_block` is now reserved and used to handle commands with block implementations.
+
+#### Parameter Validation
+
+Implemented `Cuprum::ParameterValidation`, which provides a DSL for validating a command's parameters prior to evaluating `#process`.
+
+### Errors
+
+**Breaking Change:** Corrected the namespace for `Cuprum::Errors::UncaughtException::TYPE` to remove a reference to `cuprum-collections`. If this causes an issue, update your application to reference the constant, rather than a hard-coded value.
+
+### RSpec
+
+Implemented `Cuprum::RSpec::Deferred::ParameterValidationExamples`, which provide a shortcut for testing commands that use parameter validation.
+
 ## 1.2.0
 
 The "Straight On Till Morning" Update

data/README.md

@@ -30,7 +30,7 @@ On the opposite end of the scale, frameworks such as [Dry::Monads](https://dry-r
 
 ## Compatibility
 
-Cuprum is tested against Ruby (MRI) 3.0 through 3.2.
+Cuprum is tested against Ruby (MRI) 3.1 through 3.4.
 
 ## Documentation
 
@@ -38,9 +38,11 @@ Code documentation is generated using [YARD](https://yardoc.org/), and can be ge
 
 The full documentation is available via [GitHub Pages](http://sleepingkingstudios.github.io/cuprum), and includes the code documentation as well as a deeper explanation of Cuprum's features and design philosophy. It also includes documentation for prior versions of the gem.
 
+To generate documentation locally, see the [SleepingKingStudios::Docs](https://github.com/sleepingkingstudios/sleeping_king_studios-docs) gem.
+
 ## License
 
-Copyright (c) 2017-2022 Rob Smith
+Copyright (c) 2017-2025 Rob Smith
 
 Cuprum is released under the [MIT License](https://opensource.org/licenses/MIT).
 

data/lib/cuprum/command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'sleeping_king_studios/tools/toolbox/subclass'
+
 require 'cuprum/currying'
 require 'cuprum/processing'
 require 'cuprum/steps'
@@ -69,10 +71,30 @@ module Cuprum
   #
   # @see Cuprum::Processing
   class Command
+    extend  SleepingKingStudios::Tools::Toolbox::Subclass
     include Cuprum::Processing
     include Cuprum::Currying
     include Cuprum::Steps
 
+    # @!scope class
+
+    # @!method subclass(*class_arguments, **class_keywords, &block)
+    #   Creates a subclass with partially applied constructor parameters.
+    #
+    #   @param class_arguments [Array] the arguments, if any, to apply to the
+    #     constructor. These arguments will be added before any args passed
+    #     directly to the constructor.
+    #   @param class_keywords [Hash] the keywords, if any, to apply to the
+    #     constructor. These keywords will be added before any kwargs passed
+    #     directly to the constructor.
+    #
+    #   @yield the block, if any, to pass to the constructor. This will be
+    #     overriden by a block passed directly to the constructor.
+    #
+    #   @return [Class] the generated subclass.
+
+    # @!scope instance
+
     # Returns a new instance of Cuprum::Command.
     #
     # @yield If a block is given, the block is used to define a private #process
@@ -88,13 +110,15 @@ module Cuprum
     def initialize(&implementation)
       return unless implementation
 
-      define_singleton_method :process, &implementation
+      define_singleton_method :process_block, &implementation
 
-      singleton_class.send(:private, :process)
+      singleton_class.send(:private, :process_block)
+
+      @process_block = true
     end
 
     # (see Cuprum::Processing#call)
-    def call(*args, **kwargs, &block)
+    def call(*args, **kwargs, &)
       steps { super }
     end
 
@@ -115,5 +139,18 @@ module Cuprum
         end
       end
     end
+
+    private
+
+    # (see Cuprum::Processing#process)
+    #
+    # @!visibility public
+    def process(...)
+      process_block? ? process_block(...) : super
+    end
+
+    def process_block?
+      @process_block
+    end
   end
 end

data/lib/cuprum/command_factory.rb

@@ -98,9 +98,9 @@ module Cuprum
         guard_abstract_factory!
 
         if klass
-          define_command_from_class(klass, name: name, metadata: metadata)
+          define_command_from_class(klass, name:, metadata:)
         elsif block_given?
-          define_command_from_block(defn, name: name, metadata: metadata)
+          define_command_from_block(defn, name:, metadata:)
         else
           require_definition!
         end
@@ -287,11 +287,11 @@ module Cuprum
 
     private
 
-    def build_command(command_class, *args, **kwargs, &block)
+    def build_command(command_class, *args, **kwargs, &)
       if kwargs.empty?
-        command_class.new(*args, &block)
+        command_class.new(*args, &)
       else
-        command_class.new(*args, **kwargs, &block)
+        command_class.new(*args, **kwargs, &)
       end
     end
 

data/lib/cuprum/currying/curried_command.rb

@@ -106,11 +106,13 @@ module Cuprum::Currying
       args   = [*arguments, *args]
       kwargs = keywords.merge(kwargs)
 
+      # rubocop:disable Style/RedundantParentheses
       if kwargs.empty?
         command.call(*args, &(override || block))
       else
         command.call(*args, **kwargs, &(override || block))
       end
+      # rubocop:enable Style/RedundantParentheses
     end
   end
 end

data/lib/cuprum/currying.rb

@@ -69,10 +69,10 @@ module Cuprum
       return self if arguments.empty? && keywords.empty? && block.nil?
 
       Cuprum::Currying::CurriedCommand.new(
-        arguments: arguments,
-        block:     block,
+        arguments:,
+        block:,
         command:   self,
-        keywords:  keywords
+        keywords:
       )
     end
   end

data/lib/cuprum/error.rb

@@ -65,7 +65,7 @@ module Cuprum
     def initialize(message: nil, type: nil, **properties)
       @message               = message
       @type                  = type || self.class::TYPE
-      @comparable_properties = properties.merge(message: message, type: type)
+      @comparable_properties = properties.merge(message:, type:)
     end
 
     # @return [String] optional message describing the nature of the error.

data/lib/cuprum/errors/command_not_implemented.rb

@@ -22,7 +22,7 @@ module Cuprum::Errors
       class_name = command&.class&.name || 'command'
       message    = MESSAGE_FORMAT % class_name
 
-      super(command: command, message: message)
+      super(command:, message:)
     end
 
     # @return [Cuprum::Command] The command called without a definition.

data/lib/cuprum/errors/invalid_parameters.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+require 'cuprum/errors'
+
+module Cuprum::Errors
+  # Error returned when a command's parameters fail validation.
+  class InvalidParameters < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.errors.invalid_parameters'
+
+    # @param command_class [Class] the class of the failed command.
+    # @param failures [Array<String>] the messages for the failed validations.
+    def initialize(command_class:, failures:)
+      @command_class = command_class
+      @failures      = failures
+
+      super(
+        command_class:,
+        failures:,
+        message:       generate_message
+      )
+    end
+
+    # @return [Class] the class of the failed command.
+    attr_reader :command_class
+
+    # @return [Array<String>] the messages for the failed validations.
+    attr_reader :failures
+
+    private
+
+    def as_json_data
+      {
+        'command_class' => command_class.name,
+        'failures'      => failures.map(&:to_s)
+      }
+    end
+
+    def generate_message
+      "invalid parameters for #{command_class.name} - #{failures.join(', ')}"
+    end
+  end
+end

data/lib/cuprum/errors/multiple_errors.rb

@@ -16,7 +16,7 @@ module Cuprum::Errors
       @errors = errors
 
       super(
-        errors:  errors,
+        errors:,
         message: message || default_message
       )
     end

data/lib/cuprum/errors/operation_not_called.rb

@@ -19,7 +19,7 @@ module Cuprum::Errors
       class_name = operation&.class&.name || 'operation'
       message    = MESSAGE_FORMAT % class_name
 
-      super(message: message, operation: operation)
+      super(message:, operation:)
     end
 
     # @return [Cuprum::Operation] The uncalled operation.

data/lib/cuprum/errors/uncaught_exception.rb

@@ -7,7 +7,7 @@ module Cuprum::Errors
   # Error returned when a command encounters an unhandled exception.
   class UncaughtException < Cuprum::Error
     # Short string used to identify the type of error.
-    TYPE = 'cuprum.collections.errors.uncaught_exception'
+    TYPE = 'cuprum.errors.uncaught_exception'
 
     # @param exception [StandardError] The exception that was raised.
     # @param message [String] A message to display. Will be annotated with

data/lib/cuprum/errors.rb

@@ -6,6 +6,7 @@ module Cuprum
   # Namespace for custom Cuprum error classes.
   module Errors
     autoload :CommandNotImplemented, 'cuprum/errors/command_not_implemented'
+    autoload :InvalidParameters,     'cuprum/errors/invalid_parameters'
     autoload :MultipleErrors,        'cuprum/errors/multiple_errors'
     autoload :OperationNotCalled,    'cuprum/errors/operation_not_called'
     autoload :UncaughtException,     'cuprum/errors/uncaught_exception'

data/lib/cuprum/exception_handling.rb

@@ -5,6 +5,10 @@ require 'cuprum/errors/uncaught_exception'
 module Cuprum
   # Utility module for handling uncaught exceptions in commands.
   #
+  # This functionality can be temporarily disabled by setting the
+  # ENV['CUPRUM_RERAISE_EXCEPTIONS'] flag; this can be used to debug issues when
+  # testing commands.
+  #
   # @example
   #   class UnsafeCommand < Cuprum::Command
   #     private
@@ -39,11 +43,16 @@ module Cuprum
     #   a failing result if a StandardError is raised.
     #
     # @see Cuprum::Processing#call
-    def call(*args, **kwargs, &block)
+    #
+    # @raise StandardError if an exception is raised and the
+    #   ENV['CUPRUM_RERAISE_EXCEPTIONS'] flag is set.
+    def call(*args, **kwargs, &)
       super
     rescue StandardError => exception
+      raise exception if ENV['CUPRUM_RERAISE_EXCEPTIONS']
+
       error = Cuprum::Errors::UncaughtException.new(
-        exception: exception,
+        exception:,
         message:   "uncaught exception in #{self.class.name} - "
       )
       failure(error)

data/lib/cuprum/map_command.rb

@@ -221,6 +221,10 @@ module Cuprum
     def splat_items?
       return @splat_items unless @splat_items.nil?
 
+      if respond_to?(:process_block, true)
+        return @splat_items = method(:process_block).arity > 1
+      end
+
       @splat_items = method(:process).arity > 1
     end
   end

data/lib/cuprum/matcher.rb

@@ -69,10 +69,10 @@ module Cuprum
     #
     # @yield Executes the block in the context of the singleton class. This is
     #   used to define match clauses when instantiating a Matcher instance.
-    def initialize(match_context = nil, &block)
+    def initialize(match_context = nil, &)
       @match_context = match_context
 
-      singleton_class.instance_exec(&block) if block_given?
+      singleton_class.instance_exec(&) if block_given?
     end
 
     # Returns a copy of the matcher with the given execution context.

data/lib/cuprum/matcher_list.rb

@@ -113,20 +113,20 @@ module Cuprum
 
     def find_exact_match(result)
       matchers.find do |matcher|
-        exact_match?(matcher: matcher, result: result)
+        exact_match?(matcher:, result:)
       end
     end
 
     def find_generic_match(result)
       matchers.find do |matcher|
-        generic_match?(matcher: matcher, result: result)
+        generic_match?(matcher:, result:)
       end
     end
 
     def find_partial_match(result)
       matchers.find do |matcher|
-        error_match?(matcher: matcher, result: result) ||
-          value_match?(matcher: matcher, result: result)
+        error_match?(matcher:, result:) ||
+          value_match?(matcher:, result:)
       end
     end
 

data/lib/cuprum/matching.rb

@@ -40,21 +40,21 @@ module Cuprum
       # @private
       def match_result(result:)
         status_clauses(result.status).find do |clause|
-          clause.matches_result?(result: result)
+          clause.matches_result?(result:)
         end
       end
 
       # @private
       def matches_result?(result:)
         status_clauses(result.status).reverse_each.any? do |clause|
-          clause.matches_result?(result: result)
+          clause.matches_result?(result:)
         end
       end
 
       # @private
       def matches_status?(error:, status:, value:)
         status_clauses(status).reverse_each.any? do |clause|
-          clause.matches_details?(error: error, value: value)
+          clause.matches_details?(error:, value:)
         end
       end
 
@@ -174,11 +174,11 @@ module Cuprum
       end
 
       result = result.to_cuprum_result
-      clause = singleton_class.match_result(result: result)
+      clause = singleton_class.match_result(result:)
 
       raise NoMatchError, "no match found for #{result.inspect}" if clause.nil?
 
-      call_match(block: clause.block, result: result)
+      call_match(block: clause.block, result:)
     end
 
     # @return [Boolean] true if an execution context is defined for a matching
@@ -214,9 +214,9 @@ module Cuprum
         )
       elsif result_or_status.is_a?(Symbol)
         return singleton_class.matches_status?(
-          error:  error,
+          error:,
           status: result_or_status,
-          value:  value
+          value:
         )
       end
 

data/lib/cuprum/operation.rb

@@ -63,7 +63,7 @@ module Cuprum
       #     implementation.
       #
       #   @see Cuprum::Command#call
-      def call(*args, **kwargs, &block)
+      def call(*args, **kwargs, &)
         reset! if called? # Clear reference to most recent result.
 
         @result = super
@@ -123,7 +123,7 @@ module Cuprum
 
         error = Cuprum::Errors::OperationNotCalled.new(operation: self)
 
-        Cuprum::Result.new(error: error)
+        Cuprum::Result.new(error:)
       end
 
       # @return [Object] the value of the most recent result, or nil if the

data/lib/cuprum/parameter_validation/validation_rule.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'cuprum/parameter_validation'
+
+module Cuprum::ParameterValidation
+  # @api private
+  #
+  # Value class representing a single validation for a parameter.
+  class ValidationRule < Struct.new( # rubocop:disable Style/StructInheritance
+    :name,
+    :type,
+    :method_name,
+    :options,
+    :block,
+    keyword_init: true
+  )
+    # Custom validation type for a block validation.
+    BLOCK_VALIDATION_TYPE = :_block_validation
+
+    # Custom validation type for a named method validation.
+    NAMED_VALIDATION_TYPE = :_named_method_validation
+
+    # @param name [Symbol] the name of the parameter to validate.
+    # @param type [Symbol] the type of validation to perform.
+    # @param method_name [Symbol] the name for the validation method.
+    # @param options [Hash] additional options to pass to the validator.
+    # @param block [Proc] a block to pass to the validator, if any.
+    def initialize(name:, type:, method_name: nil, **options, &block)
+      super(
+        block:,
+        method_name: method_name&.to_sym || method_name_for(name:, type:),
+        name:        name.to_sym,
+        options:,
+        type:        type.to_sym
+      )
+    end
+
+    private
+
+    def method_name_for(name:, type:)
+      case type
+      when BLOCK_VALIDATION_TYPE
+        :validate
+      when NAMED_VALIDATION_TYPE
+        :"validate_#{name}"
+      else
+        :"validate_#{type}"
+      end
+    end
+  end
+end

data/lib/cuprum/parameter_validation/validator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/assertions'
+
+require 'cuprum/errors/invalid_parameters'
+require 'cuprum/parameter_validation'
+
+module Cuprum::ParameterValidation
+  # Utility class for validating mapped parameters.
+  class Validator
+    # Exception raised when performing an unknown validation type.
+    class UnknownValidationError < StandardError; end
+
+    def initialize
+      @failures = []
+    end
+
+    # Validates the given parameters.
+    #
+    # @param command [Object] the command whose parameters are validated.
+    # @param parameters [Hash{Symbol=>Object}] the parameters to validate.
+    # @param rules [Array<ValidationRule>] the rules used to validate the
+    #   parameters.
+    #
+    # @return [Cuprum::Result] a result with the validation errors, if any.
+    def call(command:, parameters:, rules:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      validator.clear
+
+      rules.each do |rule|
+        value = parameters[rule.name]
+
+        if rule.type == ValidationRule::BLOCK_VALIDATION_TYPE
+          evaluate_block_validation(rule:, value:)
+        elsif command.respond_to?(rule.method_name, true)
+          evaluate_command_validation(command:, rule:, value:)
+        elsif validator.respond_to?(rule.method_name)
+          evaluate_validation(rule:, value:)
+        else
+          raise UnknownValidationError, error_message_for(command:, rule:)
+        end
+      end
+
+      handle_failures_for(command)
+    end
+
+    private
+
+    def error_message_for(command:, rule:)
+      unless rule.type == ValidationRule::NAMED_VALIDATION_TYPE
+        return "unknown validation type #{rule.type.inspect}"
+      end
+
+      "undefined method '#{rule.method_name}' for an instance of " \
+        "#{command.class.name}"
+    end
+
+    def evaluate_block_validation(rule:, value:)
+      return if rule.block.call(value)
+
+      message = rule.options.fetch(
+        :message,
+        "#{rule.options.fetch(:as, rule.name)} is invalid"
+      )
+      validator << message
+    end
+
+    def evaluate_command_validation(command:, rule:, value:) # rubocop:disable Metrics/MethodLength
+      message = command.send(
+        rule.method_name,
+        value,
+        as: rule.name,
+        **rule.options
+      )
+
+      if message.is_a?(Array)
+        message.each { |item| validator << item }
+      elsif message
+        validator << message
+      end
+    end
+
+    def evaluate_validation(rule:, value:)
+      validator.send(
+        rule.method_name,
+        value,
+        as: rule.name,
+        **rule.options
+      )
+    end
+
+    def handle_failures_for(command)
+      return Cuprum::Result.new if validator.empty?
+
+      error = Cuprum::Errors::InvalidParameters.new(
+        command_class: command.class,
+        failures:      validator.each.to_a
+      )
+      Cuprum::Result.new(error:)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validator
+      @validator ||= tools.assertions.aggregator_class.new
+    end
+  end
+end