cuprum 0.7.0 → 0.10.0.rc.0

data/lib/cuprum.rb

@@ -4,36 +4,12 @@ module Cuprum
   autoload :Command,   'cuprum/command'
   autoload :Operation, 'cuprum/operation'
   autoload :Result,    'cuprum/result'
-
-  DEFAULT_WARNING_PROC = ->(message) { Kernel.warn message }
-  private_constant :DEFAULT_WARNING_PROC
+  autoload :Steps,     'cuprum/steps'
 
   class << self
-    # @return [Proc] The proc called to display a warning message. By default,
-    #   delegates to Kernel#warn. Set this to configure the warning behavior
-    #   (e.g. to call a Logger).
-    attr_writer :warning_proc
-
     # @return [String] The current version of the gem.
     def version
       VERSION
     end # method version
-
-    # Displays a warning message. By default, delegates to Kernel#warn. The
-    # warning behavior can be configured (e.g. to call a Logger) using the
-    # #warning_proc= method.
-    #
-    # @param message [String] The warning message to display.
-    #
-    # @see #warning_proc=
-    def warn message
-      warning_proc.call(message)
-    end # method warn
-
-    private
-
-    def warning_proc
-      @warning_proc ||= DEFAULT_WARNING_PROC
-    end # method warning_proc
   end # eigenclass
 end # module

data/lib/cuprum/built_in/identity_command.rb

@@ -12,15 +12,15 @@ module Cuprum::BuiltIn
   #   #=> true
   #
   # @example With a result.
-  #   errors = ['errors.messages.unknown']
-  #   value  = Cuprum::Result.new('result value', :errors => errors)
+  #   error  = 'errors.messages.unknown'
+  #   value  = Cuprum::Result.new(value: 'result value', error: error)
   #   result = IdentityCommand.new.call(value)
   #   result.value
   #   #=> 'result value'
   #   result.success?
   #   #=> false
-  #   result.errors
-  #   #=> ['errors.messages.unknown']
+  #   result.error
+  #   #=> 'errors.messages.unknown'
   class IdentityCommand < Cuprum::Command
     private
 

data/lib/cuprum/chaining.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 module Cuprum
@@ -11,6 +13,7 @@ module Cuprum
   #   # the value of the previous command.
   #
   #   class GenerateUrlCommand
+  #     include Cuprum::Chaining
   #     include Cuprum::Processing
   #
   #     private
@@ -24,8 +27,8 @@ module Cuprum
   #         chain(UrlSafeCommand.new).
   #         chain(PrependDateCommand.new(post.created_at)).
   #         call(post.title)
-  #     end # method process
-  #   end # class
+  #     end
+  #   end
   #
   #   title = 'Greetings, programs!'
   #   date  = '1982-07-09'
@@ -47,54 +50,81 @@ module Cuprum
   #   # the command is failing. This can be used to perform error handling.
   #
   #   class CreateTaggingCommand
+  #     include Cuprum::Chaining
   #     include Cuprum::Processing
   #
   #     private
   #
+  #     def create_tag
+  #       Command.new do |tag_name|
+  #         tag = Tag.new(name: tag_name)
+  #
+  #         return tag if tag.save
+  #
+  #         Cuprum::Result.new(error: tag.errors)
+  #       end
+  #     end
+  #
+  #     def create_tagging(taggable)
+  #       Command.new do |tag|
+  #         tagging = tag.build_tagging(taggable)
+  #
+  #         return tagging if tagging.save
+  #
+  #         Cuprum::Result.new(error: tagging.errors)
+  #       end
+  #     end
+  #
+  #     def find_tag
+  #       Command.new do |tag_name|
+  #         tag = Tag.where(name: tag_name).first
+  #
+  #         tag || Cuprum::Result.new(error: 'tag not found')
+  #       end
+  #     end
+  #
   #     # Tries to find the tag with the given name. If that fails, creates a
   #     # new tag with the given name. If the tag is found, or if the new tag is
   #     # successfully created, then creates a tagging using the tag. If the tag
   #     # is not found and cannot be created, then the tagging is not created
   #     # and the result of the CreateTaggingCommand is a failure with the
   #     # appropriate error messages.
-  #     def process taggable, tag_name
-  #       FindTag.new.call(tag_name).
-  #         # The chained command is called with the value of the previous
-  #         # command, in this case the Tag or nil returned by FindTag.
-  #         chain(:on => :failure) do |tag|
-  #           # Chained commands share a result object, including errors. To
-  #           # rescue a command chain and return the execution to the "happy
-  #           # path", use on: :failure and clear the errors.
-  #           result.errors.clear
-  #
-  #           Tag.create(tag_name)
-  #         end.
-  #         chain(:on => :success) do |tag|
+  #     def process(taggable, tag_name)
+  #       find_tag
+  #         .chain(on: :failure) do
+  #           # If the finding the tag fails, this step is called, returning a
+  #           # result with a newly created tag.
+  #           create_tag.call(tag_name)
+  #         end
+  #         .chain(:on => :success) do |tag|
+  #           # Finally, the tag has been either found or created, so we can
+  #           # create the tagging relation.
   #           tag.create_tagging(taggable)
   #         end
-  #     end # method process
-  #   end # method class
+  #         .call(tag_name)
+  #     end
+  #   end
   #
   #   post        = Post.create(:title => 'Tagging Example')
   #   example_tag = Tag.create(:name => 'Example Tag')
   #
   #   result = CreateTaggingCommand.new.call(post, 'Example Tag')
   #   result.success? #=> true
-  #   result.errors   #=> []
+  #   result.error    #=> nil
   #   result.value    #=> an instance of Tagging
   #   post.tags.map(&:name)
   #   #=> ['Example Tag']
   #
   #   result = CreateTaggingCommand.new.call(post, 'Another Tag')
   #   result.success? #=> true
-  #   result.errors   #=> []
+  #   result.error    #=> nil
   #   result.value    #=> an instance of Tagging
   #   post.tags.map(&:name)
   #   #=> ['Example Tag', 'Another Tag']
   #
   #   result = CreateTaggingCommand.new.call(post, 'An Invalid Tag Name')
   #   result.success? #=> false
-  #   result.errors   #=> [{ tag: { name: ['is invalid'] }}]
+  #   result.error    #=> [{ tag: { name: ['is invalid'] }}]
   #   post.tags.map(&:name)
   #   #=> ['Example Tag', 'Another Tag']
   #
@@ -111,6 +141,7 @@ module Cuprum
   #   # ignored.
   #
   #   class UpdatePostCommand
+  #     include Cuprum::Chaining
   #     include Cuprum::Processing
   #
   #     private
@@ -120,12 +151,8 @@ module Cuprum
   #       Find.new(Post).call(id).
   #         yield_result(:on => :failure) do |result|
   #           redirect_to posts_path
-  #
-  #           # A halted result prevents further :on => :failure commands from
-  #           # being called.
-  #           result.halt!
   #         end.
-  #         yield_result do |result|
+  #         yield_result(on: :success) do |result|
   #           # Assign our attributes and save the post.
   #           UpdateAttributes.new.call(result.value, attributes)
   #         end.
@@ -137,19 +164,43 @@ module Cuprum
   #         end.
   #         tap_result(:on => :always) do |result|
   #           # Chaining :on => :always ensures that the command will be run,
-  #           # even if the previous result is failing or halted.
+  #           # even if the previous result is failing.
   #           if result.failure?
   #             log_errors(
   #               :command => UpdatePostCommand,
-  #               :errors => result.errors
+  #               :error   => result.error
   #             )
   #           end
   #         end
   #     end
   #   end
   #
+  # @example Protected Chaining Methods
+  #   # Using the protected chaining methods #chain!, #tap_result!, and
+  #   # #yield_result!, you can create a command class that composes other
+  #   # commands.
+  #
+  #   # We subclass the build command, which will be executed first.
+  #   class CreateCommentCommand < BuildCommentCommand
+  #     include Cuprum::Chaining
+  #     include Cuprum::Processing
+  #
+  #     def initialize
+  #       # After the build step is run, we validate the comment.
+  #       chain!(ValidateCommentCommand.new)
+  #
+  #       # If the validation passes, we then save the comment.
+  #       chain!(SaveCommentCommand.new, on: :success)
+  #     end
+  #   end
+  #
   # @see Cuprum::Command
   module Chaining
+    # (see Cuprum::Processing#call)
+    def call(*args, **kwargs, &block)
+      yield_chain(super)
+    end
+
     # Creates a copy of the first command, and then chains the given command or
     # block to execute after the first command's implementation. When #call is
     # executed, each chained command will be called with the previous result
@@ -168,13 +219,11 @@ module Cuprum
     #   @param on [Symbol] Sets a condition on when the chained block can run,
     #     based on the previous result. Valid values are :success, :failure, and
     #     :always. If the value is :success, the block will be called only if
-    #     the previous result succeeded and is not halted. If the value is
-    #     :failure, the block will be called only if the previous result failed
-    #     and is not halted. If the value is :always, the block will be called
-    #     regardless of the previous result status, even if the previous result
-    #     is halted. If no value is given, the command will run whether the
-    #     previous command was a success or a failure, but not if the command
-    #     chain has been halted.
+    #     the previous result succeeded. If the value is :failure, the block
+    #     will be called only if the previous result failed. If the value is
+    #     :always, the block will be called regardless of the previous result
+    #     status. If no value is given, the command will run whether the
+    #     previous command was a success or a failure.
     #
     # @overload chain(on: nil) { |value| }
     #   Creates an anonymous command from the given block. The command will be
@@ -183,70 +232,16 @@ module Cuprum
     #   @param on [Symbol] Sets a condition on when the chained block can run,
     #     based on the previous result. Valid values are :success, :failure, and
     #     :always. If the value is :success, the block will be called only if
-    #     the previous result succeeded and is not halted. If the value is
-    #     :failure, the block will be called only if the previous result failed
-    #     and is not halted. If the value is :always, the block will be called
-    #     regardless of the previous result status, even if the previous result
-    #     is halted. If no value is given, the command will run whether the
-    #     previous command was a success or a failure, but not if the command
-    #     chain has been halted.
-    #
-    #   @yieldparam value [Object] The value of the previous result.
-    def chain command = nil, on: nil, &block
-      command ||= Cuprum::Command.new(&block)
-
-      clone.tap do |fn|
-        fn.chained_procs <<
-          {
-            :proc => chain_command(command),
-            :on   => on
-          } # end hash
-      end # tap
-    end # method chain
-
-    # Shorthand for command.chain(:on => :failure). Creates a copy of the first
-    # command, and then chains the given command or block to execute after the
-    # first command's implementation, but only if the previous command is
-    # failing.
-    #
-    # @return [Cuprum::Chaining] A copy of the command, with the chained
-    #   command.
-    #
-    # @see #chain
-    #
-    # @overload failure(command)
-    #   @param command [Cuprum::Command] The command to chain.
-    #
-    # @overload failure() { |value| }
-    #   Creates an anonymous command from the given block. The command will be
-    #   passed the value of the previous result.
-    #
-    #   @yieldparam value [Object] The value of the previous result.
-    def failure command = nil, &block
-      chain(command, :on => :failure, &block)
-    end # method failure
-
-    # Shorthand for command.chain(:on => :success). Creates a copy of the first
-    # command, and then chains the given command or block to execute after the
-    # first command's implementation, but only if the previous command is
-    # failing.
-    #
-    # @return [Cuprum::Chaining] A copy of the command, with the chained
-    #   command.
-    #
-    # @see #chain
-    #
-    # @overload success(command)
-    #   @param command [Cuprum::Command] The command to chain.
-    #
-    # @overload success() { |value| }
-    #   Creates an anonymous command from the given block. The command will be
-    #   passed the value of the previous result.
+    #     the previous result succeeded. If the value is :failure, the block
+    #     will be called only if the previous result failed. If the value is
+    #     :always, the block will be called regardless of the previous result
+    #     status. If no value is given, the command will run whether the
+    #     previous command was a success or a failure.
     #
     #   @yieldparam value [Object] The value of the previous result.
-    def success command = nil, &block
-      chain(command, :on => :success, &block)
-    end # method success
+    def chain(command = nil, on: nil, &block)
+      clone.chain!(command, on: on, &block)
+    end
 
     # As #yield_result, but always returns the previous result when the block is
     # called. The return value of the block is discarded.
@@ -258,17 +253,9 @@ module Cuprum
     # @return (see #yield_result)
     #
     # @see #yield_result
-    def tap_result on: nil, &block
-      tapped = ->(result) { result.tap { block.call(result) } }
-
-      clone.tap do |fn|
-        fn.chained_procs <<
-          {
-            :proc => tapped,
-            :on   => on
-          } # end hash
-      end # tap
-    end # method tap_result
+    def tap_result(on: nil, &block)
+      clone.tap_result!(on: on, &block)
+    end
 
     # Creates a copy of the command, and then chains the block to execute after
     # the command implementation. When #call is executed, each chained block
@@ -278,73 +265,177 @@ module Cuprum
     # @param on [Symbol] Sets a condition on when the chained block can run,
     #   based on the previous result. Valid values are :success, :failure, and
     #   :always. If the value is :success, the block will be called only if the
-    #   previous result succeeded and is not halted. If the value is :failure,
-    #   the block will be called only if the previous result failed and is not
-    #   halted. If the value is :always, the block will be called regardless of
-    #   the previous result status, even if the previous result is halted. If no
+    #   previous result succeeded. If the value is :failure, the block will be
+    #   called only if the previous result failed. If the value is :always, the
+    #   block will be called regardless of the previous result status. If no
     #   value is given, the command will run whether the previous command was a
-    #   success or a failure, but not if the command chain has been halted.
+    #   success or a failure.
     #
     # @yieldparam result [Cuprum::Result] The #result of the previous command.
     #
     # @return [Cuprum::Chaining] A copy of the command, with the chained block.
     #
     # @see #tap_result
-    def yield_result on: nil, &block
-      clone.tap do |fn|
-        fn.chained_procs <<
-          {
-            :proc => block,
-            :on   => on
-          } # end hash
-      end # tap
-    end # method yield_result
+    def yield_result(on: nil, &block)
+      clone.yield_result!(on: on, &block)
+    end
 
     protected
 
+    # rubocop:disable Metrics/MethodLength
+
+    # @!visibility public
+    #
+    # As #chain, but modifies the current command instead of creating a clone.
+    # This is a protected method, and is meant to be called by the command to be
+    # chained, such as during #initialize.
+    #
+    # @return [Cuprum::Chaining] The current command.
+    #
+    # @see #chain
+    #
+    # @overload chain!(command, on: nil)
+    #   @param command [Cuprum::Command] The command to chain.
+    #
+    #   @param on [Symbol] Sets a condition on when the chained block can run,
+    #     based on the previous result. Valid values are :success, :failure, and
+    #     :always. If the value is :success, the block will be called only if
+    #     the previous result succeeded. If the value is :failure, the block
+    #     will be called only if the previous result failed. If the value is
+    #     :always, the block will be called regardless of the previous result
+    #     status. If no value is given, the command will run whether the
+    #     previous command was a success or a failure.
+    #
+    # @overload chain!(on: nil) { |value| }
+    #   Creates an anonymous command from the given block. The command will be
+    #   passed the value of the previous result.
+    #
+    #   @param on [Symbol] Sets a condition on when the chained block can run,
+    #     based on the previous result. Valid values are :success, :failure, and
+    #     :always. If the value is :success, the block will be called only if
+    #     the previous result succeeded. If the value is :failure, the block
+    #     will be called only if the previous result failed. If the value is
+    #     :always, the block will be called regardless of the previous result
+    #     status. If no value is given, the command will run whether the
+    #     previous command was a success or a failure.
+    #
+    #   @yieldparam value [Object] The value of the previous result.
+    def chain!(command = nil, on: nil, &block)
+      SleepingKingStudios::Tools::CoreTools.deprecate(
+        "#{self.class}#chain",
+        message: 'Use the #step method to compose commands.'
+      )
+
+      command ||= Cuprum::Command.new(&block)
+
+      chained_procs <<
+        {
+          proc: chain_command(command),
+          on:   on
+        } # end hash
+
+      self
+    end
+    # rubocop:enable Metrics/MethodLength
+
     def chained_procs
       @chained_procs ||= []
-    end # method chained_procs
+    end
 
-    def process_with_result *args, &block
-      yield_chain(super)
-    end # method call
+    # rubocop:disable Metrics/MethodLength
+
+    # @!visibility public
+    #
+    # As #tap_result, but modifies the current command instead of creating a
+    # clone. This is a protected method, and is meant to be called by the
+    # command to be chained, such as during #initialize.
+    #
+    # @param (see #tap_result)
+    #
+    # @yieldparam result [Cuprum::Result] The #result of the previous command.
+    #
+    # @return (see #tap_result)
+    #
+    # @see #tap_result
+    def tap_result!(on: nil, &block)
+      SleepingKingStudios::Tools::CoreTools.deprecate(
+        "#{self.class}#tap_result",
+        message: 'Use the #step method to compose commands.'
+      )
+
+      tapped = ->(result) { result.tap { block.call(result) } }
+
+      chained_procs <<
+        {
+          proc: tapped,
+          on:   on
+        } # end hash
+
+      self
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # @!visibility public
+    #
+    # As #yield_result, but modifies the current command instead of creating a
+    # clone. This is a protected method, and is meant to be called by the
+    # command to be chained, such as during #initialize.
+    #
+    # @param (see #yield_result)
+    #
+    # @yieldparam result [Cuprum::Result] The #result of the previous command.
+    #
+    # @return (see #yield_result)
+    #
+    # @see #yield_result
+    def yield_result!(on: nil, &block)
+      SleepingKingStudios::Tools::CoreTools.deprecate(
+        "#{self.class}#yield_result",
+        message: 'Use the #step method to compose commands.'
+      )
+
+      chained_procs <<
+        {
+          proc: block,
+          on:   on
+        } # end hash
+
+      self
+    end
 
     private
 
-    def chain_command command
+    def chain_command(command)
       if command.arity.zero?
-        ->(result) { command.process_with_result(result) }
+        ->(_result) { command.call }
       else
-        ->(result) { command.process_with_result(result, result.value) }
-      end # if-else
-    end # method chain_command
+        ->(result) { command.call(result.value) }
+      end
+    end
 
-    def skip_chained_proc? last_result, on:
+    def skip_chained_proc?(last_result, on:)
       return false if on == :always
 
-      return true if last_result.respond_to?(:halted?) && last_result.halted?
-
       case on
       when :success
         !last_result.success?
       when :failure
         !last_result.failure?
-      end # case
-    end # method skip_chained_proc?
+      end
+    end
 
-    def yield_chain first_result
+    def yield_chain(first_result)
       chained_procs.reduce(first_result) do |result, hsh|
-        next result if skip_chained_proc?(result, :on => hsh[:on])
+        next result if skip_chained_proc?(result, on: hsh[:on])
 
         value = hsh.fetch(:proc).call(result)
 
         if value_is_result?(value)
-          value.to_result
+          value.to_cuprum_result
         else
-          build_result(value, :errors => build_errors)
-        end # if-else
-      end # reduce
-    end # method yield_chain
-  end # module
-end # modue
+          build_result(value: value)
+        end
+      end
+    end
+  end
+end