cuprum 1.3.1 → 1.4.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14265461b44d0a9546c04be4d5a66605d285e35ead5740e346875287b88e38b7
-  data.tar.gz: 3730d8d83bf5382cdedd1fb8cb88684f615e2e3082ae4ae00cc61d77caa392d5
+  metadata.gz: 9f6ec18e2fe571f668e7b78c03e29a741ce51ce5bc41371e71b067000eb873e9
+  data.tar.gz: ce36aa169b233f3ffd50fa65b69f3f58d042319a92d345ab3727876d2343a36a
 SHA512:
-  metadata.gz: 0fd517bac27cad11527308fbb2aa1a65b85b42e9ae10e870583eb5f52be807b913a3931dc15ce2d11ef576824b9220a46ba23466a402080d6e15d3832c55f59a
-  data.tar.gz: 0e5330ab7482b7ed596a09159fff5ad2bd8600410e9a8381759d965a2f6ee902295220748d6e1d335dcca025d8c40d20bca313abb0119eb814b8cf61d3fbfed0
+  metadata.gz: 998790ba05c7e95186c45a2df84375e112c6113f7723c91e25818dd5a9759fad59dcbd7ac445dd041e598500401234d9af6e4f99cf1a0e2d2bcff73e01ee89ce
+  data.tar.gz: a12caa0abe108b96463dc1998eedca0c1325bffe22e649d0c38af583bb624139bda5dd0ed6c37eef72584de6a8cc48fb1d44ea86953cab1279140a00e3e19772

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.4.0
+
+The "Signs And Portents" Update
+
+As of version 1.3.0, Cuprum will no longer support Ruby 3.1 or 3.2.
+
+Added `Cuprum.initializer` to initialize dependencies and error messages. Call `Cuprum.initializer.call` in the entry point or initializers of your application to avoid missing error messages.
+
+### Errors
+
+Errors now support defining messages using `SleepingKingStudios::Tools::Messages` or by defining a `:MESSAGE` constant, including support for named parameters (see `Kernel#format`).
+
+You can now store `Exception`-like backtraces for `Cuprum::Error` objects. There are two ways to generate a backtrace for an error:
+
+- Pass `backtrace: true` when calling `Error.new` for a specific error.
+- Set the `CUPRUM_ERROR_BACKTRACE=true` environment flag to store backtraces for all errors.
+
+### Results
+
+Added `Result.success` and `Result.failure`, which provide singleton results with respective `:success` and `:failure` statuses.
+
+Updated `Cuprum::ResultList` to inherit from `Cuprum::Result`.
+
+### RSpec
+
+Updated `ParameterValidationExamples` to support lazy evaluation of the `message:` parameter, as well as any additional parameters passed along with `type:`. Parameters passed as a `Proc` will be evaluated in the context of the current example group.
+
 ## 1.3.1
 
 Added support for Ruby 4.0.

data/README.md

@@ -37,7 +37,7 @@ On the opposite end of the scale, frameworks such as [Dry::Monads](https://dry-r
 
 ## Compatibility
 
-Cuprum is tested against Ruby (MRI) 3.1 through 3.4.
+Cuprum is tested against Ruby (MRI) 3.3 through 4.0.
 
 ## Documentation
 

data/config/messages.yml

@@ -0,0 +1,7 @@
+---
+cuprum:
+  errors:
+    command_not_implemented: 'no implementation defined for %<class_name>s'
+    invalid_parameters: 'invalid parameters for %<class_name>s - %<failure_messages>s'
+    multiple_errors: 'the command encountered one or more errors'
+    operation_not_called: '%<class_name>s was not called and does not have a result'

data/lib/cuprum/currying/curried_command.rb

@@ -106,13 +106,12 @@ module Cuprum::Currying
       args   = [*arguments, *args]
       kwargs = keywords.merge(kwargs)
 
-      # rubocop:disable Style/RedundantParentheses
+      # rubocop:disable-next 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/error.rb

@@ -52,22 +52,32 @@ module Cuprum
   class Error
     # Short string used to identify the type of error.
     #
-    # Primarily used for serialization. This value can be overriden by passing
+    # Primarily used for serialization. This value can be overridden by passing
     # in the :type parameter to the constructor.
     #
     # Subclasses of Cuprum::Error should define their own default TYPE constant.
     TYPE = 'cuprum.error'
 
+    # @param backtrace [true, false] if true, captures a backtrace from
+    #   Kernel.caller. Defaults to false unless the
+    #   ENV['CUPRUM_ERROR_BACKTRACE'] flag is set to true.
     # @param message [String] Optional message describing the nature of the
     #   error.
     # @param properties [Hash] Additional properties used to compare errors.
     # @param type [String] Short string used to identify the type of error.
-    def initialize(message: nil, type: nil, **properties)
-      @message               = message
-      @type                  = type || self.class::TYPE
+    def initialize(backtrace: false, message: nil, type: nil, **properties)
+      @type                  = type    || self.class::TYPE
+      @message               = message || default_message_for(**properties)
+      @backtrace             = caller if backtrace || capture_backtrace?
       @comparable_properties = properties.merge(message:, type:)
     end
 
+    # @return [Array<String>, nil] the captured backtrace when the error was
+    #   created, if any.
+    #
+    # @see Kernel#caller
+    attr_reader :backtrace
+
     # @return [String] optional message describing the nature of the error.
     attr_reader :message
 
@@ -86,9 +96,9 @@ module Cuprum
     # Generates a serializable representation of the error object.
     #
     # By default, contains the #type and #message properties and an empty :data
-    # Hash. This can be overriden in subclasses by overriding the private method
-    # #as_json_data; this should always return a Hash with String keys and whose
-    # values are basic objects or data structures of the same.
+    # Hash. This can be overridden in subclasses by overriding the private
+    # method #as_json_data; this should always return a Hash with String keys
+    # and whose values are basic objects or data structures of the same.
     #
     # @return [Hash<String, Object>] a serializable hash representation of the
     #   error.
@@ -109,5 +119,29 @@ module Cuprum
     def as_json_data
       {}
     end
+
+    def capture_backtrace?
+      ENV.fetch('CUPRUM_ERROR_BACKTRACE', 'false') == 'true'
+    end
+
+    def default_message_for(**parameters)
+      if type && !(type.respond_to?(:empty?) && type.empty?)
+        message = tools.messages.message(type, default: nil, parameters:)
+
+        return message if message
+      end
+
+      format_default_message(parameters)
+    end
+
+    def format_default_message(parameters)
+      return unless self.class.const_defined?(:MESSAGE)
+
+      format(self.class::MESSAGE, parameters)
+    rescue KeyError => exception
+      "Message missing parameters: #{type} #{exception.message}"
+    end
+
+    def tools = SleepingKingStudios::Tools::Toolbelt.instance
   end
 end

data/lib/cuprum/errors/command_not_implemented.rb

@@ -9,20 +9,18 @@ module Cuprum::Errors
     COMPARABLE_PROPERTIES = %i[command].freeze
     private_constant :COMPARABLE_PROPERTIES
 
-    MESSAGE_FORMAT = 'no implementation defined for %s'
-    private_constant :MESSAGE_FORMAT
-
     # Short string used to identify the type of error.
     TYPE = 'cuprum.errors.command_not_implemented'
 
-    # @param command [Cuprum::Command] The command called without a definition.
-    def initialize(command:)
+    # @param command [Cuprum::Command] the command called without a definition.
+    # @param backtrace [true, false] if true, captures a backtrace from
+    #   Kernel.caller.
+    def initialize(command:, backtrace: nil)
       @command = command
 
       class_name = command&.class&.name || 'command'
-      message    = MESSAGE_FORMAT % class_name
 
-      super(command:, message:)
+      super(backtrace:, class_name:, command:)
     end
 
     # @return [Cuprum::Command] The command called without a definition.

data/lib/cuprum/errors/invalid_parameters.rb

@@ -11,14 +11,20 @@ module Cuprum::Errors
 
     # @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
+    # @param backtrace [true, false] if true, captures a backtrace from
+    #   Kernel.caller.
+    def initialize(command_class:, failures:, backtrace: nil) # rubocop:disable Metrics/MethodLength
+      @command_class   = command_class
+      @failures        = failures
+      class_name       = command_class.name
+      failure_messages = failures.join(', ')
 
       super(
+        backtrace:,
+        class_name:,
         command_class:,
         failures:,
-        message:       generate_message
+        failure_messages:
       )
     end
 
@@ -36,9 +42,5 @@ module Cuprum::Errors
         '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

@@ -9,16 +9,15 @@ module Cuprum::Errors
     # Short string used to identify the type of error.
     TYPE = 'cuprum.errors.multiple_errors'
 
-    # @param errors [Array<Cuprum::Error>] The wrapped errors.
-    # @param message [String] Optional message describing the nature of the
+    # @param errors [Array<Cuprum::Error>] the wrapped errors.
+    # @param backtrace [true, false] if true, captures a backtrace from
+    #   Kernel.caller.
+    # @param message [String] optional message describing the nature of the
     #   error.
-    def initialize(errors:, message: nil)
+    def initialize(errors:, backtrace: nil, message: nil)
       @errors = errors
 
-      super(
-        errors:,
-        message: message || default_message
-      )
+      super
     end
 
     # @return [Array<Cuprum::Error>] the wrapped errors.
@@ -31,9 +30,5 @@ module Cuprum::Errors
         'errors' => errors.map { |error| error&.as_json }
       }
     end
-
-    def default_message
-      'the command encountered one or more errors'
-    end
   end
 end

data/lib/cuprum/errors/operation_not_called.rb

@@ -6,20 +6,17 @@ require 'cuprum/errors'
 module Cuprum::Errors
   # Error returned when trying to access the result of an uncalled Operation.
   class OperationNotCalled < Cuprum::Error
-    MESSAGE_FORMAT = '%s was not called and does not have a result'
-    private_constant :MESSAGE_FORMAT
-
     # Short string used to identify the type of error.
     TYPE = 'cuprum.errors.operation_not_called'
 
     # @param operation [Cuprum::Operation] The uncalled operation.
-    def initialize(operation:)
+    # @param backtrace [true, false] if true, captures a backtrace from
+    #   Kernel.caller.
+    def initialize(operation:, backtrace: nil)
       @operation = operation
-
       class_name = operation&.class&.name || 'operation'
-      message    = MESSAGE_FORMAT % class_name
 
-      super(message:, operation:)
+      super(backtrace:, class_name:, message:, operation:)
     end
 
     # @return [Cuprum::Operation] The uncalled operation.

data/lib/cuprum/errors/uncaught_exception.rb

@@ -10,13 +10,15 @@ module Cuprum::Errors
     TYPE = 'cuprum.errors.uncaught_exception'
 
     # @param exception [StandardError] The exception that was raised.
+    # @param backtrace [true, false] if true, captures a backtrace from
+    #   Kernel.caller.
     # @param message [String] A message to display. Will be annotated with
     #   details on the exception and the exception's cause (if any).
-    def initialize(exception:, message: 'uncaught exception')
+    def initialize(exception:, backtrace: nil, message: 'uncaught exception')
       @exception = exception
       @cause     = exception.cause
 
-      super(message: generate_message(message))
+      super(backtrace:, message: generate_message(message))
     end
 
     # @return [StandardError] the exception that was raised.

data/lib/cuprum/parameter_validation/validation_rule.rb

@@ -6,7 +6,7 @@ module Cuprum::ParameterValidation
   # @api private
   #
   # Value class representing a single validation for a parameter.
-  class ValidationRule < Struct.new( # rubocop:disable Style/StructInheritance
+  class ValidationRule < Struct.new(
     :name,
     :type,
     :method_name,

data/lib/cuprum/result.rb

@@ -5,6 +5,14 @@ require 'cuprum'
 module Cuprum
   # Data object that encapsulates the result of calling a Cuprum command.
   class Result
+    class << self
+      # @return [Cuprum::Result] a result with a status of :failure.
+      def failure = @failure ||= new(status: :failure)
+
+      # @return [Cuprum::Result] a result with a status of :success.
+      def success = @success ||= new(status: :success)
+    end
+
     # Enumerates the default permitted values for a Result#status.
     STATUSES = %i[success failure].freeze
 

data/lib/cuprum/result_list.rb

@@ -4,6 +4,7 @@ require 'forwardable'
 
 require 'cuprum'
 require 'cuprum/errors/multiple_errors'
+require 'cuprum/result'
 
 module Cuprum
   # Collection object that encapsulates a set of Cuprum results.
@@ -16,11 +17,11 @@ module Cuprum
   # endpoint that performs a bulk operation.
   #
   # @see Cuprum::Result.
-  class ResultList
+  class ResultList < Cuprum::Result
     extend  Forwardable
     include Enumerable
 
-    UNDEFINED = Object.new.freeze
+    UNDEFINED = SleepingKingStudios::Tools::UNDEFINED
     private_constant :UNDEFINED
 
     # @!method each
@@ -47,55 +48,24 @@ module Cuprum
     def initialize(
       *results,
       allow_partial: false,
-      error: UNDEFINED,
+      error:  UNDEFINED,
       status: UNDEFINED,
-      value: UNDEFINED
+      value:  UNDEFINED
     )
       @allow_partial = allow_partial
       @results       = normalize_results(results)
-      @error         = error  == UNDEFINED ? build_error  : error
-      @status        = status == UNDEFINED ? build_status : status
-      @value         = value  == UNDEFINED ? values : value
+
+      error  = build_error  if error  == UNDEFINED
+      status = build_status if status == UNDEFINED
+      value  = values       if value  == UNDEFINED
+
+      super(error:, status:, value:)
     end
 
     # @return [Array<Cuprum::Result>] the wrapped results.
     attr_reader :results
     alias_method :to_a, :results
 
-    # Returns the error for the result list.
-    #
-    # If the result list was initialized with an error, returns that error.
-    #
-    # If any of the results have errors, aggregates the result errors into a
-    # Cuprum::MultipleErrors object.
-    #
-    # If none of the results have errors, returns nil.
-    #
-    # @return [Cuprum::Errors::MultipleErrors, Cuprum::Error, nil] the error for
-    #   the result list.
-    attr_reader :error
-
-    # Determines the status of the combined results.
-    #
-    # If the result list was initialize with a status, returns that status.
-    #
-    # If there are no failing results, i.e. the results array is empty or all of
-    # the results are passing, returns :success.
-    #
-    # If there is at least one failing result, it instead returns :failure.
-    #
-    # If the :allow_partial flag is set to true, returns :success if the results
-    # array is empty or there is at least one passing result. If there is at
-    # least one failing result and no passing results, it instead returns
-    # :failure.
-    #
-    # @return [:success, :failure] the status of the combined results.
-    attr_reader :status
-
-    # @return [Object] The value of the result. Defaults to the mapped values of
-    #   the results.
-    attr_reader :value
-
     def_delegators :@results, :each
 
     # @return [true, false] true if the other object is a ResultList with
@@ -120,32 +90,11 @@ module Cuprum
       @errors ||= results.map(&:error)
     end
 
-    # @return [Boolean] true if the result status is :failure, otherwise false.
-    def failure?
-      status == :failure
-    end
-
     # @return [Array<Symbol>] the status for each result.
     def statuses
       @statuses ||= results.map(&:status)
     end
 
-    # @return [Boolean] true if the result status is :success, otherwise false.
-    def success?
-      status == :success
-    end
-
-    # Converts the result list to a Cuprum::Result.
-    #
-    # @return [Cuprum::Result] the converted result.
-    #
-    # @see #error
-    # @see #status
-    # @see #value
-    def to_cuprum_result
-      Cuprum::Result.new(error:, status:, value:)
-    end
-
     # @return [Array<Object, nil>] the value, if any, for each result.
     def values
       @values ||= results.map(&:value)

data/lib/cuprum/rspec/be_a_result_matcher.rb

@@ -125,9 +125,9 @@ module Cuprum::RSpec
       elsif !properties_match?
         message + properties_failure_message
       else
-        # :nocov:
+        # simplecov:disable
         message
-        # :nocov:
+        # simplecov:enable
       end
     end
 

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

@@ -57,10 +57,19 @@ module Cuprum::RSpec::Deferred
 
     deferred_examples 'should validate the parameter' \
     do |name, type = nil, message: nil, **options|
+      let(:expected_message) do
+        message.is_a?(Proc) ? instance_exec(&message) : message
+      end
+      let(:expected_options) do
+        options.transform_values do |value|
+          value.is_a?(Proc) ? instance_exec(&value) : value
+        end
+      end
+
       it 'should return a failing result with InvalidParameters error' do
         expected_failure =
-          message ||
-          tools.assertions.error_message_for(type, as: name, **options)
+          expected_message ||
+          tools.assertions.error_message_for(type, as: name, **expected_options)
         expected_error   = Cuprum::Errors::InvalidParameters.new(
           command_class: subject.class,
           failures:      [expected_failure]
@@ -71,11 +80,5 @@ module Cuprum::RSpec::Deferred
           .with_error(expected_error)
       end
     end
-
-    private
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
-    end
   end
 end

data/lib/cuprum/utils/instance_spy.rb

@@ -131,10 +131,10 @@ module Cuprum::Utils
       if kwargs.empty?
         Cuprum::Utils::InstanceSpy.send(:call_spies_for, self, *args, &)
       else
-        # :nocov:
+        # simplecov:disable
         Cuprum::Utils::InstanceSpy
           .send(:call_spies_for, self, *args, **kwargs, &)
-        # :nocov:
+        # simplecov:enable
       end
 
       super

data/lib/cuprum/version.rb

@@ -10,13 +10,13 @@ module Cuprum
     # Major version.
     MAJOR = 1
     # Minor version.
-    MINOR = 3
+    MINOR = 4
     # Patch version.
-    PATCH = 1
+    PATCH = 0
     # Prerelease version.
-    PRERELEASE = nil
+    PRERELEASE = :rc
     # Build metadata.
-    BUILD = nil
+    BUILD = 0
 
     class << self
       # Generates the gem version string from the Version constants.

data/lib/cuprum.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+require 'sleeping_king_studios/tools/toolbox/initializer'
+
 # Toolkit for implementing business logic as function objects.
 module Cuprum
   autoload :Command,             'cuprum/command'
   autoload :CommandFactory,      'cuprum/command_factory'
   autoload :Currying,            'cuprum/currying'
   autoload :Error,               'cuprum/error'
+  autoload :Errors,              'cuprum/errors'
   autoload :ExceptionHandling,   'cuprum/exception_handling'
   autoload :MapCommand,          'cuprum/map_command'
   autoload :Matcher,             'cuprum/matcher'
@@ -16,7 +19,30 @@ module Cuprum
   autoload :ResultList,          'cuprum/result_list'
   autoload :Steps,               'cuprum/steps'
 
+  @initializer = SleepingKingStudios::Tools::Toolbox::Initializer.new do
+    SleepingKingStudios::Tools.initializer.call
+
+    SleepingKingStudios::Tools::Messages::Registry
+      .global
+      .register(
+        file:  File.join(Cuprum.gem_path, 'config', 'messages.yml'),
+        scope: 'cuprum.errors'
+      )
+  end
+
   class << self
+    # @return [SleepingKingStudios::Tools::Toolbox::Initializer] the initializer
+    #   for the module.
+    attr_reader :initializer
+
+    # @return [String] the absolute path to the gem directory.
+    def gem_path
+      sep     = File::SEPARATOR
+      pattern = /#{sep}lib#{sep}?\z/
+
+      __dir__.sub(pattern, '')
+    end
+
     # @return [String] the current version of the gem.
     def version
       VERSION

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0.rc.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
@@ -15,20 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: '1.3'
 description: |-
   An opinionated implementation of the Command pattern for Ruby applications.
   Cuprum wraps your business logic in a consistent, object-oriented interface
@@ -45,6 +39,7 @@ files:
 - DEVELOPMENT.md
 - LICENSE
 - README.md
+- config/messages.yml
 - lib/cuprum.rb
 - lib/cuprum/built_in.rb
 - lib/cuprum/built_in/identity_command.rb
@@ -112,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.20
 specification_version: 4
 summary: An opinionated implementation of the Command pattern.
 test_files: []