cuprum 0.10.0 → 1.0.0.rc.1

data/lib/cuprum/operation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/command'
 require 'cuprum/errors/operation_not_called'
 
@@ -26,8 +28,8 @@ module Cuprum
   #       @book = operation.value
   #
   #       render :new
-  #     end # if-else
-  #   end # create
+  #     end
+  #   end
   #
   # Like a Command, an Operation can be defined directly by passing an
   # implementation block to the constructor or by creating a subclass that
@@ -41,7 +43,7 @@ module Cuprum
     # @example
     #   class CustomOperation < CustomCommand
     #     include Cuprum::Operation::Mixin
-    #   end # class
+    #   end
     module Mixin
       # @return [Cuprum::Result] The result from the most recent call of the
       #   operation.
@@ -62,32 +64,32 @@ module Cuprum
       #     implementation.
       #
       # @see Cuprum::Command#call
-      def call *args, **kwargs, &block
+      def call(*args, **kwargs, &block)
         reset! if called? # Clear reference to most recent result.
 
         @result = super
 
         self
-      end # method call
+      end
 
       # @return [Boolean] true if the operation has been called and has a
       #   reference to the most recent result; otherwise false.
       def called?
         !result.nil?
-      end # method called?
+      end
 
       # @return [Object] the error (if any) from the most recent result, or nil
       #   if the operation has not been called.
       def error
         called? ? result.error : nil
-      end # method error
+      end
 
       # @return [Boolean] true if the most recent result had an error, or false
       #   if the most recent result had no error or if the operation has not
       #   been called.
       def failure?
         called? ? result.failure? : false
-      end # method failure?
+      end
 
       # Clears the reference to the most recent call of the operation, if any.
       # This allows the result and any referenced data to be garbage collected.
@@ -99,7 +101,7 @@ module Cuprum
       # an error.
       def reset!
         @result = nil
-      end # method reset
+      end
 
       # @return [Symbol, nil] the status of the most recent result, or nil if
       #   the operation has not been called.
@@ -112,7 +114,7 @@ module Cuprum
       #   been called.
       def success?
         called? ? result.success? : false
-      end # method success?
+      end
 
       # Returns the most result if the operation was previously called.
       # Otherwise, returns a failing result.
@@ -130,8 +132,8 @@ module Cuprum
       #   operation has not been called.
       def value
         called? ? result.value : nil
-      end # method value
-    end # module
+      end
+    end
     include Mixin
 
     # @!method call
@@ -156,9 +158,9 @@ module Cuprum
     #   (see Cuprum::Operation::Mixin#success?)
 
     # @!method to_cuprum_result
-    #   (see Cuprum::Operation::Mixin#to_cuprum_result?)
+    #   (see Cuprum::Operation::Mixin#to_cuprum_result)
 
     # @!method value
     #   (see Cuprum::Operation::Mixin#value)
-  end # class
-end # module
+  end
+end

data/lib/cuprum/result.rb

@@ -5,6 +5,7 @@ require 'cuprum'
 module Cuprum
   # Data object that encapsulates the result of calling a Cuprum command.
   class Result
+    # Enumerates the default permitted values for a Result#status.
     STATUSES = %i[success failure].freeze
 
     # @param value [Object] The value returned by calling the command.
@@ -28,8 +29,6 @@ module Cuprum
     # @return [Symbol] the status of the result, either :success or :failure.
     attr_reader :status
 
-    # rubocop:disable Metrics/CyclomaticComplexity
-
     # Compares the other object to the result.
     #
     # @param other [#value, #success?] An object responding to, at minimum,
@@ -45,7 +44,6 @@ module Cuprum
 
       true
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     # @return [Boolean] true if the result status is :failure, otherwise false.
     def failure?

data/lib/cuprum/rspec/be_a_result.rb

@@ -2,16 +2,25 @@
 
 require 'cuprum/rspec/be_a_result_matcher'
 
-module RSpec
+module Cuprum::RSpec
   module Matchers # rubocop:disable Style/Documentation
+    # Asserts that the object is a Cuprum::Result with status: :failure.
+    #
+    # @return [Cuprum::RSpec::BeAResultMatcher] the generated matcher.
     def be_a_failing_result
       be_a_result.with_status(:failure)
     end
 
+    # Asserts that the object is a Cuprum::Result with status: :success.
+    #
+    # @return [Cuprum::RSpec::BeAResultMatcher] the generated matcher.
     def be_a_passing_result
       be_a_result.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
     end

data/lib/cuprum/rspec/be_a_result_matcher.rb

@@ -46,9 +46,9 @@ module Cuprum::RSpec
       message = "expected #{actual.inspect} to #{description}"
 
       if !actual_is_result?
-        message + ', but the object is not a result'
+        "#{message}, but the object is not a result"
       elsif actual_is_uncalled_operation?
-        message + ', but the object is an uncalled operation'
+        "#{message}, but the object is an uncalled operation"
       elsif !properties_match?
         message + properties_failure_message
       else
@@ -182,7 +182,6 @@ module Cuprum::RSpec
       ' positives, since any other result will match.'
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
     # rubocop:disable Metrics/AbcSize
     def properties_description
       msg = ''
@@ -200,7 +199,6 @@ module Cuprum::RSpec
 
       msg + " and status: #{expected_status.inspect}"
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/AbcSize
 
     def properties_failure_message

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,161 +63,60 @@ module Cuprum
   module Steps
     include Cuprum::ResultHelpers
 
-    class << self
-      # @!visibility private
-      def execute_method(receiver, method_name, *args, **kwargs, &block)
-        if block_given? && kwargs.empty?
-          receiver.send(method_name, *args, &block)
-        elsif block_given?
-          receiver.send(method_name, *args, **kwargs, &block)
-        elsif kwargs.empty?
-          receiver.send(method_name, *args)
-        else
-          receiver.send(method_name, *args, **kwargs)
-        end
-      end
-
-      # @!visibility private
-      def extract_result_value(result)
-        return result unless result.respond_to?(:to_cuprum_result)
-
-        result = result.to_cuprum_result
-
-        return result.value if result.success?
-
-        throw :cuprum_failed_step, result
-      end
-
-      # rubocop:disable Metrics/MethodLength
-      # @!visibility private
-      def validate_method_name(method_name)
-        if method_name.nil?
-          raise ArgumentError,
-            'expected a block or a method name',
-            caller(1..-1)
-        end
-
-        unless method_name.is_a?(String) || method_name.is_a?(Symbol)
-          raise ArgumentError,
-            'expected method name to be a String or Symbol',
-            caller(1..-1)
-        end
-
-        return unless method_name.empty?
-
-        raise ArgumentError, "method name can't be blank", caller(1..-1)
-      end
-      # 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.
+    # Executes the block and returns the value, or halts on a failure.
     #
-    #   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'
-    #
-    #   @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)
-      result =
-        if !block_given? || method_name || !args.empty? || !kwargs.empty?
-          Cuprum::Steps.validate_method_name(method_name)
+    # @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
+      raise ArgumentError, 'expected a block' unless block_given?
+
+      result = yield
 
-          Cuprum::Steps
-            .execute_method(self, method_name, *args, **kwargs, &block)
-        else
-          block.call
-        end
+      return result unless result.respond_to?(:to_cuprum_result)
 
-      Cuprum::Steps.extract_result_value(result)
+      result = result.to_cuprum_result
+
+      return result.value if result.success?
+
+      throw :cuprum_failed_step, result
     end
 
     # Returns the first failing #step result, or the final result if none fail.
@@ -264,8 +163,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/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/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/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Cuprum
   # @api private
   #
@@ -6,15 +8,15 @@ module Cuprum
   # @see http://semver.org/
   module Version
     # Major version.
-    MAJOR = 0
+    MAJOR = 1
     # Minor version.
-    MINOR = 10
+    MINOR = 0
     # Patch version.
     PATCH = 0
     # Prerelease version.
-    PRERELEASE = nil
+    PRERELEASE = :rc
     # Build metadata.
-    BUILD = nil
+    BUILD = 1
 
     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

data/lib/cuprum.rb

@@ -1,15 +1,20 @@
+# frozen_string_literal: true
+
 # A lightweight, functional-lite toolkit for making business logic a first-class
 # citizen of your application.
 module Cuprum
-  autoload :Command,   'cuprum/command'
-  autoload :Operation, 'cuprum/operation'
-  autoload :Result,    'cuprum/result'
-  autoload :Steps,     'cuprum/steps'
+  autoload :Command,    'cuprum/command'
+  autoload :Error,      'cuprum/error'
+  autoload :Matcher,    'cuprum/matcher'
+  autoload :Middleware, 'cuprum/middleware'
+  autoload :Operation,  'cuprum/operation'
+  autoload :Result,     'cuprum/result'
+  autoload :Steps,      'cuprum/steps'
 
   class << self
     # @return [String] The current version of the gem.
     def version
       VERSION
-    end # method version
-  end # eigenclass
-end # module
+    end
+  end
+end