cuprum 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 838e5d593a57d931c54b2ce0831699999bdddf6de2599fb2d074e0d31a0f80e0
-  data.tar.gz: 721a9e2add543ec5e5f704bc6ed6b8e0f353ef7f6a1da0c3e67b4139d81f9d89
+  metadata.gz: dab108b9d6630d5ebb692b2a918654cc9a6a2cb6256a5aad7331b40bd2ea7f1d
+  data.tar.gz: 55e8f74553df29e8b244e69257c9178b3b8ea0b931c4f8b7a58ae4f587d17e27
 SHA512:
-  metadata.gz: e7d4073ddf03b470f65e123bd196a778af7eb04ed0cdd3ec032d2ba06eb701ba19bf3b8fd92f3cfdc89fcaaed066f892e75b200a9040ff64261cbcb2b7d7c5d4
-  data.tar.gz: aa8c21b9b7ad0dc0757304bfb580faa836b02b1ab152806324f3526a67bfcedab3ca70c141a6de55cf5f48cc47e29da8fffad7301dd10dadeaa279619f7bffab
+  metadata.gz: 3f520bbc963d86937b02b8f7849bb064afafa32e43d47e8e5b394f5ff598e05665ba366bf2bffc44f7a3964982c28dba90d7621ab11b6b5a981217a092b62e15
+  data.tar.gz: b3b1b63fa90af7d8f2edfd1d7db6ce5b14e2f10397907fd9dcd07138d4c0d5f70a0d1b538c5c7bd2cb1c9b0a10dfd94997c673ba293dbedfcb0855dda413c43d

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.2.0
+
+The "Straight On Till Morning" Update
+
+As of version 1.2.0, Cuprum will no longer support Ruby 2.7.
+
+### Results
+
+Added the `#properties` method (aliased as `#to_h`) that wraps the result's `#value`, `#status`, and `#error`. Collecting the properties in one method supports defining results with additional or custom properties, such as a checksum or metadata.
+
+The `Cuprum::Result#==` method was updated to compare the result's properties.
+
+- A result can now be matched against a hash with `:value`, `:status`, and `:error` keys.
+- Matching a result against a non-result object with its own `#value`, `#status`, and `#error` methods is now deprecated. Define a `#to_h` method on that object to wrap its properties for comparison with a result.
+
+### RSpec
+
+Updated the `Cuprum::RSpec::BeAResultMatcher` to accept an optional result class.
+
 ## 1.1.0
 
 The "Second Star To The Right" 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) 2.7 through 3.2.
+Cuprum is tested against Ruby (MRI) 3.0 through 3.2.
 
 ## Documentation
 

data/lib/cuprum/result.rb

@@ -8,10 +8,10 @@ module Cuprum
     # Enumerates the default permitted values for a Result#status.
     STATUSES = %i[success failure].freeze
 
-    # @param value [Object] The value returned by calling the command.
-    # @param error [Object] The error (if any) generated when the command was
+    # @param value [Object] the value returned by calling the command.
+    # @param error [Object] the error (if any) generated when the command was
     #   called. Can be a Cuprum::Error, a model errors object, etc.
-    # @param status [String, Symbol] The status of the result. Must be :success,
+    # @param status [String, Symbol] the status of the result. Must be :success,
     #   :failure, or nil.
     def initialize(value: nil, error: nil, status: nil)
       @value  = value
@@ -31,18 +31,19 @@ module Cuprum
 
     # Compares the other object to the result.
     #
-    # @param other [#value, #success?] An object responding to, at minimum,
-    #   #value and #success?. If present, the #failure? and #error values
-    #   will also be compared.
+    # In order to match the result, the object must respond to the #to_h method,
+    # and the value of object.to_h must be equal to the value of
+    # result.properties.
     #
-    # @return [Boolean] True if all present values match the result, otherwise
-    #   false.
+    # @param other [#to_h] the result or object to compare.
+    #
+    # @return [Boolean] true if all values match the result, otherwise false.
     def ==(other)
-      return false unless other.respond_to?(:value)  && other.value  == value
-      return false unless other.respond_to?(:status) && other.status == status
-      return false unless other.respond_to?(:error)  && other.error  == error
+      other = other.to_cuprum_result if other.respond_to?(:to_cuprum_result)
+
+      return properties == other.to_h if other.respond_to?(:to_h)
 
-      true
+      deprecated_compare(other)
     end
 
     # @return [Boolean] true if the result status is :failure, otherwise false.
@@ -50,6 +51,16 @@ module Cuprum
       @status == :failure
     end
 
+    # @return [Hash{Symbol => Object}] a Hash representation of the result.
+    def properties
+      {
+        error:  error,
+        status: status,
+        value:  value
+      }
+    end
+    alias_method :to_h, :properties
+
     # @return [Boolean] true if the result status is :success, otherwise false.
     def success?
       @status == :success
@@ -66,6 +77,19 @@ module Cuprum
       self.class::STATUSES
     end
 
+    def deprecated_compare(other)
+      unless %i[value status error].all? { |sym| other.respond_to?(sym) }
+        return false
+      end
+
+      tools.core_tools.deprecate 'Cuprum::Result#==',
+        message: 'The compared object must respond to #to_h.'
+
+      other.value == value &&
+        other.status == status &&
+        other.error  == error
+    end
+
     def normalize_status(status)
       return status unless status.is_a?(String) || status.is_a?(Symbol)
 

data/lib/cuprum/rspec/be_a_result.rb

@@ -4,25 +4,31 @@ require 'cuprum/rspec/be_a_result_matcher'
 
 module Cuprum::RSpec
   module Matchers # rubocop:disable Style/Documentation
-    # Asserts that the object is a Cuprum::Result with status: :failure.
+    # Asserts that the object is a result with status: :failure.
+    #
+    # @param expected_class [Class] the expected class of result. Defaults to
+    #   Cuprum::Result.
     #
     # @return [Cuprum::RSpec::BeAResultMatcher] the generated matcher.
-    def be_a_failing_result
-      be_a_result.with_status(:failure)
+    def be_a_failing_result(expected_class = nil)
+      be_a_result(expected_class).with_status(:failure)
     end
 
     # Asserts that the object is a Cuprum::Result with status: :success.
     #
+    # @param expected_class [Class] the expected class of result. Defaults to
+    #   Cuprum::Result.
+    #
     # @return [Cuprum::RSpec::BeAResultMatcher] the generated matcher.
-    def be_a_passing_result
-      be_a_result.with_status(:success).and_error(nil)
+    def be_a_passing_result(expected_class = nil)
+      be_a_result(expected_class).with_status(:success).and_error(nil)
     end
 
     # Asserts that the object is a Cuprum::Result.
     #
     # @return [Cuprum::RSpec::BeAResultMatcher] the generated matcher.
-    def be_a_result
-      Cuprum::RSpec::BeAResultMatcher.new
+    def be_a_result(expected_class = nil)
+      Cuprum::RSpec::BeAResultMatcher.new(expected_class)
     end
   end
 end

data/lib/cuprum/rspec/be_a_result_matcher.rb

@@ -4,8 +4,68 @@ require 'cuprum/errors/operation_not_called'
 require 'cuprum/rspec'
 
 module Cuprum::RSpec
-  # Custom matcher that asserts the actual object is a Cuprum result object with
-  # the specified properties.
+  # Asserts the actual object is a result object with the specified properties.
+  #
+  # If initialized with a class, the matcher will assert that the actual object
+  # is an instance of that class. This can be useful for asserting that the
+  # result is an instance of a result subclass. If no class is given, the
+  # matcher asserts that the result is an object responding to
+  # #to_cuprum_result.
+  #
+  # The matcher also defines fluent methods for asserting on the result's
+  # properties:
+  #
+  # - The #with_value method asserts that the result has the specified value.
+  #   Also aliased as #and_value.
+  # - The #with_error method asserts that the result has the specified error.
+  #   Also aliased as #and_error.
+  # - The #with_status method asserts that the result has the specified status.
+  #   Also aliased as #and_status.
+  #
+  # Generally speaking, you should use the #be_a_result, #be_a_passing_result,
+  # and #be_a_failing_result macros, rather than instantiating a
+  # BeAResultMatcher directly.
+  #
+  # @example Matching Any Result
+  #   # Or use expect().to be_a_result
+  #   matcher = Cuprum::RSpec::BeAResultMatcher.new
+  #
+  #   matcher.matches?(nil)                #=> false
+  #   matcher.matches?(Cuprum::Result.new) #=> true
+  #
+  # @example Matching A Result Status
+  #   # Or use expect().to be_a_passing_result
+  #   matcher = Cuprum::RSpec::BeAResultMatcher.new.with_status(:success)
+  #
+  #   matcher.matches?(Cuprum::Result.new(status: :failure)) #=> false
+  #   matcher.matches?(Cuprum::Result.new(status: :success)) #=> false
+  #
+  # @example Matching A Result Value
+  #   matcher = Cuprum::RSpec::BeAResultMatcher.new.with_value({ ok: true })
+  #
+  #   matcher.matches?(Cuprum::Result.new(value: { ok: false })) #=> false
+  #   matcher.matches?(Cuprum::Result.new(value: { ok: true }))  #=> true
+  #
+  # @example Matching A Result Error
+  #   error   = Cuprum::Error.new(message: 'Something went wrong')
+  #   matcher = Cuprum::RSpec::BeAResultMatcher.new.with_error(error)
+  #
+  #   other_error = Cuprum::Error.new(message: 'Oh no')
+  #   matcher.matches?(Cuprum::Result.new(error: other_error) #=> false
+  #   matcher.matches?(Cuprum::Result.new(error: error)       #=> true
+  #
+  # @example Matching A Result Class
+  #   matcher = Cuprum::RSpec::BeAResultMatcher.new(CustomResult)
+  #
+  #   matcher.matches?(Cuprum::Result.new) #=> false
+  #   matcher.matches?(CustomResult.new)   #=> true
+  #
+  # @example Matching Multiple Properties
+  #   matcher =
+  #     Cuprum::RSpec::BeAResultMatcher
+  #     .with_status(:failure)
+  #     .and_value({ ok: false })
+  #     .and_error(Cuprum::Error.new(message: 'Something went wrong'))
   class BeAResultMatcher # rubocop:disable Metrics/ClassLength
     DEFAULT_VALUE = Object.new.freeze
     private_constant :DEFAULT_VALUE
@@ -13,15 +73,26 @@ module Cuprum::RSpec
     RSPEC_MATCHER_METHODS = %i[description failure_message matches?].freeze
     private_constant :RSPEC_MATCHER_METHODS
 
-    def initialize
+    # @param expected_class [Class] the expected class of result. Defaults to
+    #   Cuprum::Result.
+    def initialize(expected_class = nil)
+      @expected_class = expected_class
       @expected_error = DEFAULT_VALUE
       @expected_value = DEFAULT_VALUE
     end
 
+    # @return [Class] the expected class of result.
+    attr_reader :expected_class
+
     # @return [String] a short description of the matcher and expected
     #   properties.
     def description
-      message = 'be a Cuprum result'
+      message =
+        if expected_class
+          "be an instance of #{expected_class}"
+        else
+          'be a Cuprum result'
+        end
 
       return message unless expected_properties?
 
@@ -30,7 +101,7 @@ module Cuprum::RSpec
 
     # Checks that the given actual object is not a Cuprum result.
     #
-    # @param actual [Object] The actual object to match.
+    # @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)
@@ -42,10 +113,12 @@ module Cuprum::RSpec
     end
 
     # @return [String] a summary message describing a failed expectation.
-    def failure_message
+    def failure_message # rubocop:disable Metrics/MethodLength
       message = "expected #{actual.inspect} to #{description}"
 
-      if !actual_is_result?
+      if !actual_is_result? && expected_class
+        "#{message}, but the object is not an instance of #{expected_class}"
+      elsif !actual_is_result?
         "#{message}, but the object is not a result"
       elsif actual_is_uncalled_operation?
         "#{message}, but the object is an uncalled operation"
@@ -72,7 +145,8 @@ module Cuprum::RSpec
     # @return [Boolean] true if the actual object is a result with the expected
     #   properties; otherwise false.
     def matches?(actual)
-      @actual = actual
+      @actual                  = actual
+      @non_matching_properties = nil
 
       actual_is_result? && !actual_is_uncalled_operation? && properties_match?
     end
@@ -125,7 +199,11 @@ module Cuprum::RSpec
       :expected_value
 
     def actual_is_result?
-      actual.respond_to?(:to_cuprum_result)
+      return false unless actual.respond_to?(:to_cuprum_result)
+
+      return true unless expected_class
+
+      actual.to_cuprum_result.is_a?(expected_class)
     end
 
     def actual_is_uncalled_operation?
@@ -141,8 +219,8 @@ module Cuprum::RSpec
     def error_failure_message
       return '' if error_matches?
 
-      "\n   expected error: #{inspect_expected(expected_error)}" \
-        "\n     actual error: #{result.error.inspect}"
+      "#{pad_key('expected error')}#{inspect_expected(expected_error)}" \
+        "#{pad_key('actual error')}#{result.error.inspect}"
     end
 
     def error_matches?
@@ -153,10 +231,18 @@ module Cuprum::RSpec
       @error_matches = compare_items(expected_error, result.error)
     end
 
+    def expected_properties
+      expected = {}
+
+      expected['error']  = expected_error  if expected_error?
+      expected['status'] = expected_status if expected_status?
+      expected['value']  = expected_value  if expected_value?
+
+      expected
+    end
+
     def expected_properties?
-      (expected_error? && !expected_error.nil?) ||
-        expected_status? ||
-        expected_value?
+      expected_properties.any?
     end
 
     def expected_error?
@@ -182,12 +268,23 @@ module Cuprum::RSpec
         ' positives, since any other result will match.'
     end
 
-    # rubocop:disable Metrics/AbcSize
+    def non_matching_properties
+      @non_matching_properties ||=
+        expected_properties
+        .each_key
+        .reject { |key| send(:"#{key}_matches?") }
+    end
+
+    def pad_key(str)
+      # Value 11 from "  expected " prefix.
+      len = 11 + non_matching_properties.map(&:length).max
+
+      "\n#{format("%#{len}s", str)}: "
+    end
+
     def properties_description
       msg = ''
-      ary = []
-      ary << 'value' if expected_value?
-      ary << 'error' if expected_error? && !expected_error.nil?
+      ary = expected_properties.except('status').keys
 
       unless ary.empty?
         msg = "with the expected #{tools.array_tools.humanize_list(ary)}"
@@ -199,34 +296,28 @@ module Cuprum::RSpec
 
       msg + " and status: #{expected_status.inspect}"
     end
-    # rubocop:enable Metrics/AbcSize
 
     def properties_failure_message
-      properties_short_message +
-        status_failure_message +
-        value_failure_message +
-        error_failure_message
+      expected_properties
+        .each_key
+        .map { |key| send(:"#{key}_failure_message") }
+        .unshift(properties_short_message)
+        .join
     end
 
     def properties_match?
-      error_matches? && status_matches? && value_matches?
+      non_matching_properties.empty?
     end
 
     def properties_short_message
-      ary = []
-      ary << 'status' unless status_matches?
-      ary << 'value'  unless value_matches?
-      ary << 'error'  unless error_matches?
+      ary = non_matching_properties
 
       ", but the #{tools.array_tools.humanize_list(ary)}" \
         " #{tools.integer_tools.pluralize(ary.size, 'does', 'do')} not match:"
     end
 
     def properties_warning
-      ary = []
-      ary << 'value'  if expected_value?
-      ary << 'status' if expected_status?
-      ary << 'error'  if expected_error?
+      ary = expected_properties.keys
 
       return '' if ary.empty?
 
@@ -250,8 +341,8 @@ module Cuprum::RSpec
     def status_failure_message
       return '' if status_matches?
 
-      "\n  expected status: #{expected_status.inspect}" \
-        "\n    actual status: #{result.status.inspect}"
+      "#{pad_key('expected status')}#{expected_status.inspect}" \
+        "#{pad_key('actual status')}#{result.status.inspect}"
     end
 
     def status_matches?
@@ -269,8 +360,8 @@ module Cuprum::RSpec
     def value_failure_message
       return '' if value_matches?
 
-      "\n   expected value: #{inspect_expected(expected_value)}" \
-        "\n     actual value: #{result.value.inspect}"
+      "#{pad_key('expected value')}#{inspect_expected(expected_value)}" \
+        "#{pad_key('actual value')}#{result.value.inspect}"
     end
 
     def value_matches?

data/lib/cuprum/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-01 00:00:00.000000000 Z
+date: 2023-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sleeping_king_studios-tools
@@ -24,76 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.10'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.10'
-- !ruby/object:Gem::Dependency
-  name: rspec-sleeping_king_studios
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.31'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.31'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.11'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.11'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.21'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.21'
 description: |-
   An opinionated implementation of the Command pattern for Ruby applications.
   Cuprum wraps your business logic in a consistent, object-oriented interface
@@ -159,16 +89,16 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
 summary: An opinionated implementation of the Command pattern.