cuprum 0.7.0 → 0.10.0.rc.0

data/lib/cuprum/steps.rb

@@ -0,0 +1,275 @@
+# 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
+
+    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.
+    #
+    #   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.
+    #
+    #   @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 #zero method returns the integer 0.
+    #     step :zero #=> 0
+    #
+    #     value = step :zero
+    #     value #=> 0
+    #
+    #   @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
+    #
+    #     # The result is passing, so the value is extracted and returned.
+    #     value = step :add, 2, 2
+    #     value #=> 4
+    #
+    #   @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)
+
+          Cuprum::Steps
+            .execute_method(self, method_name, *args, **kwargs, &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
+      result = catch(:cuprum_failed_step) { yield }
+
+      return result if result.respond_to?(:to_cuprum_result)
+
+      success(result)
+    end
+  end
+end

data/lib/cuprum/utils/instance_spy.rb

@@ -129,8 +129,15 @@ module Cuprum::Utils
     end # eigenclass
 
     # (see Cuprum::Command#call)
-    def call *args, &block
-      Cuprum::Utils::InstanceSpy.send(:call_spies_for, self, *args, &block)
+    def call *args, **kwargs, &block
+      if kwargs.empty?
+        Cuprum::Utils::InstanceSpy.send(:call_spies_for, self, *args, &block)
+      else
+        # :nocov:
+        Cuprum::Utils::InstanceSpy
+          .send(:call_spies_for, self, *args, **kwargs, &block)
+        # :nocov:
+      end
 
       super
     end # method call

data/lib/cuprum/version.rb

@@ -8,13 +8,13 @@ module Cuprum
     # Major version.
     MAJOR = 0
     # Minor version.
-    MINOR = 7
+    MINOR = 10
     # 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.

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.10.0.rc.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-30 00:00:00.000000000 Z
+date: 2020-08-01 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: sleeping_king_studios-tools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -101,14 +115,23 @@ files:
 - lib/cuprum/built_in/null_operation.rb
 - lib/cuprum/chaining.rb
 - lib/cuprum/command.rb
-- lib/cuprum/not_implemented_error.rb
+- lib/cuprum/command_factory.rb
+- lib/cuprum/currying.rb
+- lib/cuprum/currying/curried_command.rb
+- lib/cuprum/error.rb
+- lib/cuprum/errors.rb
+- lib/cuprum/errors/command_not_implemented.rb
+- lib/cuprum/errors/operation_not_called.rb
 - lib/cuprum/operation.rb
 - lib/cuprum/processing.rb
 - lib/cuprum/result.rb
 - lib/cuprum/result_helpers.rb
+- lib/cuprum/rspec.rb
+- lib/cuprum/rspec/be_a_result.rb
+- lib/cuprum/rspec/be_a_result_matcher.rb
+- lib/cuprum/steps.rb
 - lib/cuprum/utils.rb
 - lib/cuprum/utils/instance_spy.rb
-- lib/cuprum/utils/result_not_empty_warning.rb
 - lib/cuprum/version.rb
 homepage: http://sleepingkingstudios.com
 licenses:
@@ -125,12 +148,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: An opinionated implementation of the Command pattern.

data/lib/cuprum/not_implemented_error.rb

@@ -1,14 +0,0 @@
-require 'cuprum'
-
-module Cuprum
-  # Error class for calling a Command that was not given a definition block
-  # or have a #process method defined.
-  class NotImplementedError < StandardError
-    # Error message for a NotImplementedError.
-    DEFAULT_MESSAGE = 'no implementation defined for command'.freeze
-
-    def initialize message = nil
-      super(message || DEFAULT_MESSAGE)
-    end # constructor
-  end # class
-end # module

data/lib/cuprum/utils/result_not_empty_warning.rb

@@ -1,72 +0,0 @@
-require 'cuprum/utils'
-
-module Cuprum::Utils
-  # Helper class for building a warning message when a command returns a result,
-  # but the command's current result already has errors, a set status, or is
-  # halted.
-  class ResultNotEmptyWarning
-    MESSAGE = '#process returned a result, but '.freeze
-    private_constant :MESSAGE
-
-    # @param result [Cuprum::Result] The result for which to generate the
-    #   warning message.
-    def initialize result
-      @result = result
-    end # constructor
-
-    # @return [String] The warning message for the given result.
-    def message
-      return ''.freeze if warnings.empty?
-
-      MESSAGE + humanize_list(warnings).freeze
-    end # method message
-
-    # @return [Boolean] True if a warning is generated, otherwise false.
-    def warning?
-      !warnings.empty?
-    end # method warning?
-
-    private
-
-    attr_reader :result
-
-    def errors_not_empty_warning
-      return nil if result.errors.empty?
-
-      "there were already errors #{@result.errors.inspect}".freeze
-    end # method errors_not_empty_warning
-
-    def halted_warning
-      return nil unless result.halted?
-
-      'the command was halted'.freeze
-    end # method halted_warning
-
-    def humanize_list list, empty_value: ''
-      return empty_value if list.size.zero?
-
-      return list.first.to_s if list.size == 1
-
-      return "#{list.first} and #{list.last}" if list.size == 2
-
-      "#{list[0...-1].join ', '}, and #{list.last}"
-    end # method humanize_list
-
-    def status_set_warning
-      status = result.send(:status)
-
-      return nil if status.nil?
-
-      "the status was set to #{status.inspect}".freeze
-    end # method status_set_warning
-
-    def warnings
-      @warnings ||=
-        [
-          errors_not_empty_warning,
-          status_set_warning,
-          halted_warning
-        ].compact
-    end # method warnings
-  end # class
-end # module