cuprum 0.6.0 → 0.7.0.rc.0

data/lib/cuprum.rb

@@ -1,7 +1,7 @@
 # A lightweight, functional-lite toolkit for making business logic a first-class
 # citizen of your application.
 module Cuprum
-  autoload :Function,  'cuprum/function'
+  autoload :Command,   'cuprum/command'
   autoload :Operation, 'cuprum/operation'
   autoload :Result,    'cuprum/result'
 

data/lib/cuprum/built_in.rb

@@ -1,6 +1,6 @@
 require 'cuprum'
 
 module Cuprum
-  # Namespace for predefined function and operation classes.
+  # Namespace for predefined command and operation classes.
   module BuiltIn; end
 end # module

data/lib/cuprum/built_in/identity_command.rb

@@ -2,7 +2,7 @@ require 'cuprum/built_in'
 require 'cuprum/command'
 
 module Cuprum::BuiltIn
-  # A predefined function that returns the value or result it was called with.
+  # A predefined command that returns the value or result it was called with.
   #
   # @example With a value.
   #   result = IdentityCommand.new.call('custom value')

data/lib/cuprum/chaining.rb

@@ -5,128 +5,322 @@ module Cuprum
   # Chaining commands allows you to define complex logic by composing it from
   # simpler commands, including branching logic and error handling.
   #
+  # @example Chaining Commands
+  #   # By chaining commands together with the #chain instance method, we set up
+  #   # a series of commands to run in sequence. Each chained command is passed
+  #   # the value of the previous command.
+  #
+  #   class GenerateUrlCommand
+  #     include Cuprum::Processing
+  #
+  #     private
+  #
+  #     # Acts as a pipeline, taking a value (the title of the given post) and
+  #     # calling the underscore, URL safe, and prepend date commands. By
+  #     # passing parameters to PrependDateCommand, we can customize the command
+  #     # in the pipeline to the current context (in this case, the Post).
+  #     def process post
+  #       UnderscoreCommand.new.
+  #         chain(UrlSafeCommand.new).
+  #         chain(PrependDateCommand.new(post.created_at)).
+  #         call(post.title)
+  #     end # method process
+  #   end # class
+  #
+  #   title = 'Greetings, programs!'
+  #   date  = '1982-07-09'
+  #   post  = Post.new(:title => title, :created_at => date)
+  #   url   = GenerateUrlCommand.new.call(post).value
+  #   #=> '1982_07_09_greetings_programs'
+  #
+  #   title = 'Plasma-based Einhanders in Popular Media'
+  #   date  = '1977-05-25'
+  #   post  = Post.new(:title => title, :created_at => date)
+  #   url   = GenerateUrlCommand.new.call(post).value
+  #   #=> '1977_05_25_plasma_based_einhanders_in_popular_media'
+  #
+  # @example Conditional Chaining
+  #   # Commands can be conditionally chained based on the success or failure of
+  #   # the previous command using the on: keyword. If the command is chained
+  #   # using on: :success, it will only be called if the result is passing.
+  #   # If the command is chained using on: :failure, it will only be called if
+  #   # the command is failing. This can be used to perform error handling.
+  #
+  #   class CreateTaggingCommand
+  #     include Cuprum::Processing
+  #
+  #     private
+  #
+  #     # 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|
+  #           tag.create_tagging(taggable)
+  #         end
+  #     end # method process
+  #   end # method class
+  #
+  #   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.value    #=> an instance of Tagging
+  #   post.tags.map(&:name)
+  #   #=> ['Example Tag']
+  #
+  #   result = CreateTaggingCommand.new.call(post, 'Another Tag')
+  #   result.success? #=> true
+  #   result.errors   #=> []
+  #   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'] }}]
+  #   post.tags.map(&:name)
+  #   #=> ['Example Tag', 'Another Tag']
+  #
+  # @example Yield Result and Tap Result
+  #   # The #yield_result method allows for advanced control over a step in the
+  #   # command chain. The block will be yielded the result at that point in the
+  #   # chain, and will wrap the returned value in a result to the next chained
+  #   # command (or return it directly if the returned value is a result).
+  #   #
+  #   # The #tap_result method inserts arbitrary code into the command chain
+  #   # without interrupting it. The block will be yielded the result at that
+  #   # point in the chain and will pass that same result to the next chained
+  #   # command after executing the block. The return value of the block is
+  #   # ignored.
+  #
+  #   class UpdatePostCommand
+  #     include Cuprum::Processing
+  #
+  #     private
+  #
+  #     def process id, attributes
+  #       # First, find the referenced post.
+  #       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|
+  #           # Assign our attributes and save the post.
+  #           UpdateAttributes.new.call(result.value, attributes)
+  #         end.
+  #         tap_result(:on => :success) do |result|
+  #           # Create our tags, but still return the result of our update.
+  #           attributes[:tags].each do |tag_name|
+  #             CreateTaggingCommand.new.call(result.value, tag_name)
+  #           end
+  #         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.
+  #           if result.failure?
+  #             log_errors(
+  #               :command => UpdatePostCommand,
+  #               :errors => result.errors
+  #             )
+  #           end
+  #         end
+  #     end
+  #   end
+  #
   # @see Cuprum::Command
   module Chaining
-    # (see Cuprum::BasicCommand#call)
-    def call *args, &block
-      call_chained_functions(super)
-    end # method call
+    # 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
+    # value, and its result property will be set to the previous result. The
+    # return value will be wrapped in a result and returned or yielded to the
+    # next block.
+    #
+    # @return [Cuprum::Chaining] A copy of the command, with the chained
+    #   command.
+    #
+    # @see #yield_result
+    #
+    # @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 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.
+    #
+    # @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 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)
 
-    # Registers a function or block to run after the current function, or after
-    # the last chained function if the current function already has one or more
-    # chained function(s). This creates and modifies a copy of the current
-    # function.
-    #
-    # @param on [Symbol] Sets a condition on when the chained function can run,
-    #   based on the status of the previous function. Valid values are :success,
-    #   :failure, and :always. A value of :success will constrain the function
-    #   to run only if the previous function succeeded. A value of :failure will
-    #   constrain the function to run only if the previous function failed. A
-    #   value of :always will ensure the function is always run, even if the
-    #   function chain has been halted. If no value is given, the function will
-    #   run whether the previous function was a success or a failure, but not if
-    #   the function chain has been halted.
-    #
-    # @overload chain(function, on: nil)
-    #   The function will be passed the #value of the previous function result
-    #   as its parameter, and the result of the chained function will be
-    #   returned (or passed to the next chained function, if any).
-    #
-    #   @param function [Cuprum::Command] The function to call after the
-    #     current or last chained function.
-    #
-    # @overload chain(on: :nil, &block)
-    #   The block will be passed the #result of the previous function as its
-    #   parameter. If your use case depends on the status of the previous
-    #   function or on any errors generated, use the block form of #chain.
-    #
-    #   If the block returns a Cuprum::Result (or an object responding to #value
-    #   and #success?), the block result will be returned (or passed to the next
-    #   chained function, if any). If the block returns any other value
-    #   (including nil), the #result of the previous function will be returned
-    #   or passed to the next function.
-    #
-    #   @yieldparam result [Cuprum::Result] The #result of the previous
-    #     function.
-    #
-    # @return [Cuprum::Command] The chained function.
-    def chain function = nil, on: nil, &block
       clone.tap do |fn|
-        fn.chained_functions <<
+        fn.chained_procs <<
           {
-            :proc => convert_function_or_proc_to_proc(block || function),
+            :proc => chain_command(command),
             :on   => on
           } # end hash
       end # tap
     end # method chain
 
-    # Shorthand for function.chain(:on => :failure). Registers a function or
-    # block to run after the current function. The chained function will only
-    # run if the previous function was unsuccessfully run.
+    # 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.
     #
-    # @overload else(function)
+    # @return [Cuprum::Chaining] A copy of the command, with the chained
+    #   command.
     #
-    #   @param function [Cuprum::Command] The function to call after the
-    #     current or last chained function.
+    # @see #chain
+    #
+    # @overload failure(command)
+    #   @param command [Cuprum::Command] The command to chain.
     #
-    # @overload else(&block)
+    # @overload failure() { |value| }
+    #   Creates an anonymous command from the given block. The command will be
+    #   passed the value of the previous result.
     #
-    #   @yieldparam result [Cuprum::Result] The #result of the previous
-    #     function.
+    #   @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::Command] The chained function.
+    # @return [Cuprum::Chaining] A copy of the command, with the chained
+    #   command.
     #
     # @see #chain
-    def else function = nil, &block
-      chain(function, :on => :failure, &block)
-    end # method else
-
-    # Shorthand for function.chain(:on => :success). Registers a function or
-    # block to run after the current function. The chained function will only
-    # run if the previous function was successfully run.
     #
-    # @overload then(function)
+    # @overload success(command)
+    #   @param command [Cuprum::Command] The command to chain.
     #
-    #   @param function [Cuprum::Command] The function to call after the
-    #     current or last chained function.
+    # @overload success() { |value| }
+    #   Creates an anonymous command from the given block. The command will be
+    #   passed the value of the previous result.
     #
-    # @overload then(&block)
+    #   @yieldparam value [Object] The value of the previous result.
+    def success command = nil, &block
+      chain(command, :on => :success, &block)
+    end # method success
+
+    # As #yield_result, but always returns the previous result when the block is
+    # called. The return value of the block is discarded.
     #
-    #   @yieldparam result [Cuprum::Result] The #result of the previous
-    #     function.
+    # @param (see #yield_result)
     #
-    # @return [Cuprum::Command] The chained function.
+    # @yieldparam result [Cuprum::Result] The #result of the previous command.
     #
-    # @see #chain
-    def then function = nil, &block
-      chain(function, :on => :success, &block)
-    end # method then
-
-    protected
+    # @return (see #yield_result)
+    #
+    # @see #yield_result
+    def tap_result on: nil, &block
+      tapped = ->(result) { result.tap { block.call(result) } }
 
-    def chained_functions
-      @chained_functions ||= []
-    end # method chained_functions
+      clone.tap do |fn|
+        fn.chained_procs <<
+          {
+            :proc => tapped,
+            :on   => on
+          } # end hash
+      end # tap
+    end # method tap_result
 
-    private
+    # Creates a copy of the command, and then chains the block to execute after
+    # the command implementation. When #call is executed, each chained block
+    # will be yielded the previous result, and the return value wrapped in a
+    # result and returned or yielded to the next block.
+    #
+    # @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 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 call_chained_functions first_result
-      chained_functions.reduce(first_result) do |result, hsh|
-        next result if skip_chained_function?(result, :on => hsh[:on])
+    protected
 
-        value = hsh.fetch(:proc).call(result)
+    def chained_procs
+      @chained_procs ||= []
+    end # method chained_procs
 
-        convert_value_to_result(value) || result
-      end # reduce
-    end # method call_chained_functions
+    def process_with_result *args, &block
+      yield_chain(super)
+    end # method call
 
-    def convert_function_or_proc_to_proc function_or_proc
-      return function_or_proc if function_or_proc.is_a?(Proc)
+    private
 
-      ->(result) { function_or_proc.call(result) }
-    end # method convert_function_or_proc_to_proc
+    def chain_command command
+      if command.arity.zero?
+        ->(result) { command.process_with_result(result) }
+      else
+        ->(result) { command.process_with_result(result, result.value) }
+      end # if-else
+    end # method chain_command
 
-    def skip_chained_function? 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?
@@ -137,6 +331,20 @@ module Cuprum
       when :failure
         !last_result.failure?
       end # case
-    end # method skip_chained_function?
+    end # method skip_chained_proc?
+
+    def yield_chain first_result
+      chained_procs.reduce(first_result) do |result, hsh|
+        next result if skip_chained_proc?(result, :on => hsh[:on])
+
+        value = hsh.fetch(:proc).call(result)
+
+        if value_is_result?(value)
+          value.to_result
+        else
+          build_result(value, :errors => build_errors)
+        end # if-else
+      end # reduce
+    end # method yield_chain
   end # module
 end # modue