cuprum 0.10.0 → 0.11.0.rc.0

data/lib/cuprum/rspec/be_callable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'cuprum/rspec'
+
+module Cuprum::RSpec
+  module Matchers # rubocop:disable Style/Documentation
+    # Asserts that the command defines a :process method.
+    #
+    # @return [RSpec::Matchers::BuiltIn::RespondTo] the generated matcher.
+    def be_callable
+      respond_to(:process, true)
+    end
+  end
+end

data/lib/cuprum/steps.rb

@@ -63,6 +63,9 @@ module Cuprum
   module Steps
     include Cuprum::ResultHelpers
 
+    UNDEFINED = Object.new.freeze
+    private_constant :UNDEFINED
+
     class << self
       # @!visibility private
       def execute_method(receiver, method_name, *args, **kwargs, &block)
@@ -110,109 +113,62 @@ module Cuprum
       # rubocop:enable Metrics/MethodLength
     end
 
-    # @overload step()
-    #   Executes the block and returns the value, or halts on a failure.
-    #
-    #   @yield Called with no parameters.
-    #
-    #   @return [Object] the #value of the result, or the returned object.
-    #
-    #   The #step method is used to evaluate a sequence of processes, and to
-    #   fail fast and halt processing if any of the steps returns a failing
-    #   result. Each invocation of #step should be wrapped in a #steps block,
-    #   or used inside the #process method of a Command.
-    #
-    #   If the object returned by the block is a Cuprum result or compatible
-    #   object (such as a called operation), the value is converted to a Cuprum
-    #   result via the #to_cuprum_result method. Otherwise, the object is
-    #   returned directly from #step.
-    #
-    #   If the returned object is a passing result, the #value of the result is
-    #   returned by #step.
-    #
-    #   If the returned object is a failing result, then #step will throw
-    #   :cuprum_failed_result and the failing result. This is caught by the
-    #   #steps block, and halts execution of any subsequent steps.
-    #
-    #   @example Calling a Step
-    #     # The #do_something method returns the string 'some value'.
-    #     step { do_something() } #=> 'some value'
-    #
-    #     value = step { do_something() }
-    #     value #=> 'some value'
+    # Executes the block and returns the value, or halts on a failure.
     #
-    #   @example Calling a Step with a Passing Result
-    #     # The #do_something_else method returns a Cuprum result with a value
-    #     # of 'another value'.
-    #     step { do_something_else() } #=> 'another value'
-    #
-    #     # The result is passing, so the value is extracted and returned.
-    #     value = step { do_something_else() }
-    #     value #=> 'another value'
-    #
-    #   @example Calling a Step with a Failing Result
-    #     # The #do_something_wrong method returns a failing Cuprum result.
-    #     step { do_something_wrong() } # Throws the :cuprum_failed_step symbol.
-    #
-    # @overload step(method_name, *arguments, **keywords)
-    #   Calls the method and returns the value, or halts on a failure.
-    #
-    #   @param method_name [String, Symbol] The name of the method to call. Must
-    #     be the name of a method on the current object.
-    #   @param arguments [Array] Positional arguments to pass to the method.
-    #   @param keywords [Hash] Keyword arguments to pass to the method.
-    #
-    #   @yield A block to pass to the method.
+    # @yield Called with no parameters.
     #
-    #   @return [Object] the #value of the result, or the returned object.
+    # @return [Object] the #value of the result, or the returned object.
     #
-    #   The #step method is used to evaluate a sequence of processes, and to
-    #   fail fast and halt processing if any of the steps returns a failing
-    #   result. Each invocation of #step should be wrapped in a #steps block,
-    #   or used inside the #process method of a Command.
+    # The #step method is used to evaluate a sequence of processes, and to
+    # fail fast and halt processing if any of the steps returns a failing
+    # result. Each invocation of #step should be wrapped in a #steps block,
+    # or used inside the #process method of a Command.
     #
-    #   If the object returned by the block is a Cuprum result or compatible
-    #   object (such as a called operation), the value is converted to a Cuprum
-    #   result via the #to_cuprum_result method. Otherwise, the object is
-    #   returned directly from #step.
+    # If the object returned by the block is a Cuprum result or compatible
+    # object (such as a called operation), the value is converted to a Cuprum
+    # result via the #to_cuprum_result method. Otherwise, the object is
+    # returned directly from #step.
     #
-    #   If the returned object is a passing result, the #value of the result is
-    #   returned by #step.
+    # If the returned object is a passing result, the #value of the result is
+    # returned by #step.
     #
-    #   If the returned object is a failing result, then #step will throw
-    #   :cuprum_failed_result and the failing result. This is caught by the
-    #   #steps block, and halts execution of any subsequent steps.
+    # If the returned object is a failing result, then #step will throw
+    # :cuprum_failed_result and the failing result. This is caught by the
+    # #steps block, and halts execution of any subsequent steps.
     #
-    #   @example Calling a Step
-    #     # The #zero method returns the integer 0.
-    #     step :zero #=> 0
+    # @example Calling a Step
+    #   # The #do_something method returns the string 'some value'.
+    #   step { do_something() } #=> 'some value'
     #
-    #     value = step :zero
-    #     value #=> 0
+    #   value = step { do_something() }
+    #   value #=> 'some value'
     #
-    #   @example Calling a Step with a Passing Result
-    #     # The #add method adds the numbers and returns a Cuprum result with a
-    #     # value equal to the sum.
-    #     step :add, 2, 2
-    #     #=> 4
+    # @example Calling a Step with a Passing Result
+    #   # The #do_something_else method returns a Cuprum result with a value
+    #   # of 'another value'.
+    #   step { do_something_else() } #=> 'another value'
     #
-    #     # The result is passing, so the value is extracted and returned.
-    #     value = step :add, 2, 2
-    #     value #=> 4
+    #   # The result is passing, so the value is extracted and returned.
+    #   value = step { do_something_else() }
+    #   value #=> 'another value'
     #
-    #   @example Calling a Step with a Failing Result
-    #     # The #divide method returns a failing Cuprum result when the second
-    #     # argument is zero.
-    #     step :divide, 1, 0
-    #     # Throws the :cuprum_failed_step symbol, which should be caught by the
-    #     # enclosing #steps block.
-    def step(method_name = nil, *args, **kwargs, &block)
+    # @example Calling a Step with a Failing Result
+    #   # The #do_something_wrong method returns a failing Cuprum result.
+    #   step { do_something_wrong() } # Throws the :cuprum_failed_step symbol.
+    def step(method_name = UNDEFINED, *args, **kwargs, &block) # rubocop:disable Metrics/MethodLength
       result =
-        if !block_given? || method_name || !args.empty? || !kwargs.empty?
+        if method_name != UNDEFINED || !args.empty? || !kwargs.empty?
+          SleepingKingStudios::Tools::CoreTools.deprecate(
+            "#{self.class}#step(method_name)",
+            message: 'Use the block form: step { method_name(*args, **kwargs) }'
+          )
+
           Cuprum::Steps.validate_method_name(method_name)
 
           Cuprum::Steps
             .execute_method(self, method_name, *args, **kwargs, &block)
+        elsif !block_given?
+          raise ArgumentError, 'expected a block'
         else
           block.call
         end
@@ -264,8 +220,10 @@ module Cuprum
     #   result.class    #=> Cuprum::Result
     #   result.success? #=> false
     #   result.error    #=> 'second step'
-    def steps
-      result = catch(:cuprum_failed_step) { yield }
+    def steps(&block)
+      raise ArgumentError, 'no block given' unless block_given?
+
+      result = catch(:cuprum_failed_step) { block.call }
 
       return result if result.respond_to?(:to_cuprum_result)
 

data/lib/cuprum/utils.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 module Cuprum
   # Namespace for utility modules.
   module Utils; end
-end # module
+end

data/lib/cuprum/utils/instance_spy.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/utils'
 
 module Cuprum::Utils
@@ -28,14 +30,14 @@ module Cuprum::Utils
   #     expect(spy).to receive(:call)
   #
   #     CustomCommand.new.call
-  #   end # spy_on
+  #   end
   module InstanceSpy
     # Minimal class that implements a #call method to mirror method calls to
     # instances of an instrumented command class.
     class Spy
       # Empty method that accepts any arguments and an optional block.
-      def call *_args, █ end
-    end # class
+      def call(*_args, &block); end
+    end
 
     class << self
       # Retires all spies. Subsequent calls to the #call method on command
@@ -44,7 +46,7 @@ module Cuprum::Utils
         Thread.current[:cuprum_instance_spies] = nil
 
         nil
-      end # method clear_spies
+      end
 
       # Finds or creates a spy object for the given module or class. Each time
       # that the #call method is called for an object of the given type, the
@@ -68,41 +70,39 @@ module Cuprum::Utils
       #   @yield [Cuprum::Utils::InstanceSpy::Spy] The instance spy.
       #
       #   @return [nil] nil.
-      def spy_on command_class
+      def spy_on(command_class)
         guard_spy_class!(command_class)
 
         instrument_call!
 
         if block_given?
-          begin
-            instance_spy = assign_spy(command_class)
+          instance_spy = assign_spy(command_class)
 
-            yield instance_spy
-          end # begin-ensure
+          yield instance_spy
         else
           assign_spy(command_class)
-        end # if-else
-      end # method spy_on
+        end
+      end
 
       private
 
-      def assign_spy command_class
+      def assign_spy(command_class)
         existing_spy = spies[command_class]
 
         return existing_spy if existing_spy
 
         spies[command_class] = build_spy
-      end # method assign_spy
+      end
 
       def build_spy
         Cuprum::Utils::InstanceSpy::Spy.new
-      end # method build_spy
+      end
 
-      def call_spies_for command, *args, &block
+      def call_spies_for(command, *args, &block)
         spies_for(command).each { |spy| spy.call(*args, &block) }
-      end # method call_spies_for
+      end
 
-      def guard_spy_class! command_class
+      def guard_spy_class!(command_class)
         return if command_class.is_a?(Module) && !command_class.is_a?(Class)
 
         return if command_class.is_a?(Class) &&
@@ -111,25 +111,25 @@ module Cuprum::Utils
         raise ArgumentError,
           'must be a class inheriting from Cuprum::Command',
           caller(1..-1)
-      end # method guard_spy_class!
+      end
 
       def instrument_call!
         return if Cuprum::Command < Cuprum::Utils::InstanceSpy
 
         Cuprum::Command.prepend(Cuprum::Utils::InstanceSpy)
-      end # method instrument_call!
+      end
 
       def spies
         Thread.current[:cuprum_instance_spies] ||= {}
-      end # method spies
+      end
 
-      def spies_for command
+      def spies_for(command)
         spies.select { |mod, _| command.is_a?(mod) }.map { |_, spy| spy }
-      end # method spies_for
-    end # eigenclass
+      end
+    end
 
-    # (see Cuprum::Command#call)
-    def call *args, **kwargs, &block
+    # (see Cuprum::Processing#call)
+    def call(*args, **kwargs, &block)
       if kwargs.empty?
         Cuprum::Utils::InstanceSpy.send(:call_spies_for, self, *args, &block)
       else
@@ -140,6 +140,6 @@ module Cuprum::Utils
       end
 
       super
-    end # method call
-  end # module
-end # module
+    end
+  end
+end

data/lib/cuprum/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Cuprum
   # @api private
   #
@@ -8,13 +10,13 @@ module Cuprum
     # Major version.
     MAJOR = 0
     # Minor version.
-    MINOR = 10
+    MINOR = 11
     # Patch version.
     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.
@@ -28,17 +30,17 @@ module Cuprum
         str = "#{MAJOR}.#{MINOR}.#{PATCH}"
 
         prerelease = value_of(:PRERELEASE)
-        str << ".#{prerelease}" if prerelease
+        str = "#{str}.#{prerelease}" if prerelease
 
         build = value_of(:BUILD)
-        str << ".#{build}" if build
+        str = "#{str}.#{build}" if build
 
         str
-      end # class method to_version
+      end
 
       private
 
-      def value_of constant
+      def value_of(constant)
         return nil unless const_defined?(constant)
 
         value = const_get(constant)
@@ -46,9 +48,10 @@ module Cuprum
         return nil if value.respond_to?(:empty?) && value.empty?
 
         value
-      end # method value_of
-    end # eigenclass
-  end # module
+      end
+    end
+  end
 
+  # The current version of the gem.
   VERSION = Version.to_gem_version
-end # module
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0.rc.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-22 00:00:00.000000000 Z
+date: 2021-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sleeping_king_studios-tools
@@ -16,70 +16,70 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '3.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '3.10'
 - !ruby/object:Gem::Dependency
   name: rspec-sleeping_king_studios
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '2.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.49.1
+        version: 1.10.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.49.1
+        version: 1.10.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -94,9 +94,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.15'
-description: An opinionated implementation of the Command pattern for Ruby applications.
-  Cuprum wraps your business logic in a consistent, object-oriented interface and
-  features status and error management, composability and control flow management.
+description: |-
+  An opinionated implementation of the Command pattern for Ruby applications.
+  Cuprum wraps your business logic in a consistent, object-oriented interface
+  and features status and error management, composability and control flow
+  management.
 email:
 - merlin@sleepingkingstudios.com
 executables: []
@@ -113,7 +115,6 @@ files:
 - lib/cuprum/built_in/identity_operation.rb
 - lib/cuprum/built_in/null_command.rb
 - lib/cuprum/built_in/null_operation.rb
-- lib/cuprum/chaining.rb
 - lib/cuprum/command.rb
 - lib/cuprum/command_factory.rb
 - lib/cuprum/currying.rb
@@ -122,6 +123,13 @@ files:
 - lib/cuprum/errors.rb
 - lib/cuprum/errors/command_not_implemented.rb
 - lib/cuprum/errors/operation_not_called.rb
+- lib/cuprum/errors/uncaught_exception.rb
+- lib/cuprum/exception_handling.rb
+- lib/cuprum/matcher.rb
+- lib/cuprum/matcher_list.rb
+- lib/cuprum/matching.rb
+- lib/cuprum/matching/match_clause.rb
+- lib/cuprum/middleware.rb
 - lib/cuprum/operation.rb
 - lib/cuprum/processing.rb
 - lib/cuprum/result.rb
@@ -129,6 +137,7 @@ files:
 - lib/cuprum/rspec.rb
 - lib/cuprum/rspec/be_a_result.rb
 - lib/cuprum/rspec/be_a_result_matcher.rb
+- lib/cuprum/rspec/be_callable.rb
 - lib/cuprum/steps.rb
 - lib/cuprum/utils.rb
 - lib/cuprum/utils/instance_spy.rb
@@ -136,7 +145,9 @@ files:
 homepage: http://sleepingkingstudios.com
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/sleepingkingstudios/cuprum/issues
+  source_code_uri: https://github.com/sleepingkingstudios/cuprum
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -145,14 +156,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: An opinionated implementation of the Command pattern.