cuprum 0.9.0 → 0.11.0.rc.0

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, &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,14 +101,20 @@ 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.
+      def status
+        called? ? result.status : nil
+      end
 
       # @return [Boolean] true if the most recent result had no error, or false
       #   if the most recent result had an error or if the operation has not
       #   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.
@@ -124,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
@@ -150,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/processing.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'cuprum/errors/command_not_implemented'
+require 'cuprum/result_helpers'
 
 module Cuprum
   # Functional implementation for creating a command object. Cuprum::Processing
@@ -57,6 +58,8 @@ module Cuprum
   #
   # @see Cuprum::Command
   module Processing
+    include Cuprum::ResultHelpers
+
     # Returns a nonnegative integer for commands that take a fixed number of
     # arguments. For commands that take a variable number of arguments, returns
     # -n-1, where n is the number of required arguments.
@@ -87,8 +90,13 @@ module Cuprum
     #
     #   @yield If a block argument is given, it will be passed to the
     #     implementation.
-    def call(*args, &block)
-      value = process(*args, &block)
+    def call(*args, **kwargs, &block)
+      value =
+        if kwargs.empty?
+          process(*args, &block)
+        else
+          process(*args, **kwargs, &block)
+        end
 
       return value.to_cuprum_result if value_is_result?(value)
 
@@ -97,14 +105,6 @@ module Cuprum
 
     private
 
-    def build_result(error: nil, status: nil, value: nil)
-      Cuprum::Result.new(error: error, status: status, value: value)
-    end
-
-    def failure(error)
-      build_result(error: error)
-    end
-
     # @!visibility public
     # @overload process(*arguments, **keywords, &block)
     #   The implementation of the command, to be executed when the #call method
@@ -128,10 +128,6 @@ module Cuprum
       build_result(error: error)
     end
 
-    def success(value)
-      build_result(value: value)
-    end
-
     def value_is_result?(value)
       value.respond_to?(:to_cuprum_result)
     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?
@@ -71,7 +69,7 @@ module Cuprum
     def normalize_status(status)
       return status unless status.is_a?(String) || status.is_a?(Symbol)
 
-      tools.string.underscore(status).intern
+      tools.string_tools.underscore(status).intern
     end
 
     def resolve_status(status)

data/lib/cuprum/result_helpers.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Helper methods for generating Cuprum result objects.
+  module ResultHelpers
+    private
+
+    def build_result(error: nil, status: nil, value: nil)
+      Cuprum::Result.new(error: error, status: status, value: value)
+    end
+
+    def failure(error)
+      build_result(error: error)
+    end
+
+    def success(value)
+      build_result(value: value)
+    end
+  end
+end

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)
+      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

@@ -10,6 +10,9 @@ module Cuprum::RSpec
     DEFAULT_VALUE = Object.new.freeze
     private_constant :DEFAULT_VALUE
 
+    RSPEC_MATCHER_METHODS = %i[description failure_message matches?].freeze
+    private_constant :RSPEC_MATCHER_METHODS
+
     def initialize
       @expected_error = DEFAULT_VALUE
       @expected_value = DEFAULT_VALUE
@@ -43,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
@@ -151,7 +154,9 @@ module Cuprum::RSpec
     end
 
     def expected_properties?
-      expected_error? || expected_status? || expected_value?
+      (expected_error? && !expected_error.nil?) ||
+        expected_status? ||
+        expected_value?
     end
 
     def expected_error?
@@ -167,7 +172,7 @@ module Cuprum::RSpec
     end
 
     def inspect_expected(expected)
-      return expected.description if expected.respond_to?(:description)
+      return expected.description if rspec_matcher?(expected)
 
       expected.inspect
     end
@@ -177,14 +182,15 @@ module Cuprum::RSpec
       ' positives, since any other result will match.'
     end
 
-    def properties_description # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/AbcSize
+    def properties_description
       msg = ''
       ary = []
       ary << 'value' if expected_value?
-      ary << 'error' if expected_error?
+      ary << 'error' if expected_error? && !expected_error.nil?
 
       unless ary.empty?
-        msg = "with the expected #{tools.array.humanize_list(ary)}"
+        msg = "with the expected #{tools.array_tools.humanize_list(ary)}"
       end
 
       return msg unless expected_status?
@@ -193,6 +199,7 @@ module Cuprum::RSpec
 
       msg + " and status: #{expected_status.inspect}"
     end
+    # rubocop:enable Metrics/AbcSize
 
     def properties_failure_message
       properties_short_message +
@@ -211,8 +218,8 @@ module Cuprum::RSpec
       ary << 'value'  unless value_matches?
       ary << 'error'  unless error_matches?
 
-      ", but the #{tools.array.humanize_list(ary)}" \
-      " #{tools.integer.pluralize(ary.size, 'does', 'do')} not match:"
+      ", but the #{tools.array_tools.humanize_list(ary)}" \
+      " #{tools.integer_tools.pluralize(ary.size, 'does', 'do')} not match:"
     end
 
     def properties_warning
@@ -234,6 +241,12 @@ module Cuprum::RSpec
       @result ||= actual.to_cuprum_result
     end
 
+    def rspec_matcher?(value)
+      RSPEC_MATCHER_METHODS.all? do |method_name|
+        value.respond_to?(method_name)
+      end
+    end
+
     def status_failure_message
       return '' if status_matches?
 

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

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require 'cuprum/result_helpers'
+
+module Cuprum
+  # The Steps supports step by step processes that halt on a failed step.
+  #
+  # After including Cuprum::Steps, use the #steps instance method to wrap a
+  # series of instructions. Each instruction is then defined using the #step
+  # method. Steps can be defined either as a block or as a method invocation.
+  #
+  # When the steps block is evaluated, each step is called in sequence. If the
+  # step resolves to a passing result, the result value is returned and
+  # execution continues to the next step. If all of the steps pass, then the
+  # result of the final step is returned from the #steps block.
+  #
+  # Conversely, if any step resolves to a failing result, that failing result is
+  # immediately returned from the #steps block. No further steps will be called.
+  #
+  # For example, consider updating a database record using a primary key and an
+  # attributes hash. Broken down into its basics, this requires the following
+  # instructions:
+  #
+  # - Using the primary key, find the existing record in the database.
+  # - Update the record object with the given attributes.
+  # - Save the updated record back to the database.
+  #
+  # Note that each of these steps can fail for different reasons. For example,
+  # if a record with the given primary key does not exist in the database, then
+  # the first instruction will fail, and the follow up steps should not be
+  # executed. Further, whatever context is executing these steps probably wants
+  # to know which step failed, and why.
+  #
+  # @example Defining Methods As Steps
+  #   def assign_attributes(record, attributes); end
+  #
+  #   def find_record(primary_key); end
+  #
+  #   def save_record(record); end
+  #
+  #   def update_record(primary_key, attributes)
+  #     steps do
+  #       record = step :find_record,       primary_key
+  #       record = step :assign_attributes, record, attributes
+  #       step :save_record, record
+  #     end
+  #   end
+  #
+  # @example Defining Blocks As Steps
+  #   class AssignAttributes < Cuprum::Command; end
+  #
+  #   class FindRecord < Cuprum::Command; end
+  #
+  #   class SaveRecord < Cuprum::Command; end
+  #
+  #   def update_record(primary_key, attributes)
+  #     steps do
+  #       record = step { FindRecord.new.call(primary_key) }
+  #       record = step { AssignAttributes.new.call(record, attributes) }
+  #       step { SaveRecord.new.call(record) }
+  #     end
+  #   end
+  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)
+        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
+
+    # 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'
+    #
+    # @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.
+    def step(method_name = UNDEFINED, *args, **kwargs, &block) # rubocop:disable Metrics/MethodLength
+      result =
+        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
+
+      Cuprum::Steps.extract_result_value(result)
+    end
+
+    # Returns the first failing #step result, or the final result if none fail.
+    #
+    # The #steps method is used to wrap a series of #step calls. Each step is
+    # executed in sequence. If any of the steps returns a failing result, that
+    # result is immediately returned from #steps. Otherwise, #steps wraps the
+    # value returned by a block in a Cuprum result.
+    #
+    # @yield Called with no parameters.
+    #
+    # @yieldreturn A Cuprum result, or an object to be wrapped in a result.
+    #
+    # @return [Cuprum::Result] the result or object returned by the block,
+    #   wrapped in a Cuprum result.
+    #
+    # @example With A Passing Step
+    #   result = steps do
+    #     step { success('some value') }
+    #   end
+    #   result.class    #=> Cuprum::Result
+    #   result.success? #=> true
+    #   result.value    #=> 'some value'
+    #
+    # @example With A Failing Step
+    #   result = steps do
+    #     step { failure('something went wrong') }
+    #   end
+    #   result.class    #=> Cuprum::Result
+    #   result.success? #=> false
+    #   result.error    #=> 'something went wrong'
+    #
+    # @example With Multiple Steps
+    #   result = steps do
+    #     # This step is passing, so execution continues on to the next step.
+    #     step { success('first step') }
+    #
+    #     # This step is failing, so execution halts and returns this result.
+    #     step { failure('second step') }
+    #
+    #     # This step will never be called.
+    #     step { success('third step') }
+    #   end
+    #   result.class    #=> Cuprum::Result
+    #   result.success? #=> false
+    #   result.error    #=> 'second step'
+    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)
+
+      success(result)
+    end
+  end
+end