cuprum 0.7.0 → 0.8.0

data/lib/cuprum/chaining.rb

@@ -11,6 +11,7 @@ module Cuprum
   #   # the value of the previous command.
   #
   #   class GenerateUrlCommand
+  #     include Cuprum::Chaining
   #     include Cuprum::Processing
   #
   #     private
@@ -47,6 +48,7 @@ module Cuprum
   #   # the command is failing. This can be used to perform error handling.
   #
   #   class CreateTaggingCommand
+  #     include Cuprum::Chaining
   #     include Cuprum::Processing
   #
   #     private
@@ -111,6 +113,7 @@ module Cuprum
   #   # ignored.
   #
   #   class UpdatePostCommand
+  #     include Cuprum::Chaining
   #     include Cuprum::Processing
   #
   #     private
@@ -148,6 +151,25 @@ module Cuprum
   #     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
     # Creates a copy of the first command, and then chains the given command or
@@ -193,15 +215,7 @@ module Cuprum
     #
     #   @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
+      clone.chain!(command, :on => on, &block)
     end # method chain
 
     # Shorthand for command.chain(:on => :failure). Creates a copy of the first
@@ -223,7 +237,7 @@ module Cuprum
     #
     #   @yieldparam value [Object] The value of the previous result.
     def failure command = nil, &block
-      chain(command, :on => :failure, &block)
+      clone.chain!(command, :on => :failure, &block)
     end # method failure
 
     # Shorthand for command.chain(:on => :success). Creates a copy of the first
@@ -245,7 +259,7 @@ module Cuprum
     #
     #   @yieldparam value [Object] The value of the previous result.
     def success command = nil, &block
-      chain(command, :on => :success, &block)
+      clone.chain!(command, :on => :success, &block)
     end # method success
 
     # As #yield_result, but always returns the previous result when the block is
@@ -259,15 +273,7 @@ module Cuprum
     #
     # @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
+      clone.tap_result!(:on => on, &block)
     end # method tap_result
 
     # Creates a copy of the command, and then chains the block to execute after
@@ -291,17 +297,63 @@ module Cuprum
     #
     # @see #tap_result
     def yield_result on: nil, &block
-      clone.tap do |fn|
-        fn.chained_procs <<
-          {
-            :proc => block,
-            :on   => on
-          } # end hash
-      end # tap
+      clone.yield_result!(:on => on, &block)
     end # method yield_result
 
     protected
 
+    # @!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 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)
+
+      chained_procs <<
+        {
+          :proc => chain_command(command),
+          :on   => on
+        } # end hash
+
+      self
+    end # method chain!
+
     def chained_procs
       @chained_procs ||= []
     end # method chained_procs
@@ -310,6 +362,54 @@ module Cuprum
       yield_chain(super)
     end # method call
 
+    # @!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
+      tapped = ->(result) { result.tap { block.call(result) } }
+
+      chained_procs <<
+        {
+          :proc => tapped,
+          :on   => on
+        } # end hash
+
+      self
+    end # method tap_result!
+
+    # @!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
+      chained_procs <<
+        {
+          :proc => block,
+          :on   => on
+        } # end hash
+
+      self
+    end # method yield_result!
+
     private
 
     def chain_command command
@@ -342,7 +442,7 @@ module Cuprum
         if value_is_result?(value)
           value.to_result
         else
-          build_result(value, :errors => build_errors)
+          build_result(value)
         end # if-else
       end # reduce
     end # method yield_chain

data/lib/cuprum/command.rb

@@ -1,6 +1,5 @@
 require 'cuprum/chaining'
 require 'cuprum/processing'
-require 'cuprum/result_helpers'
 
 module Cuprum
   # Functional object that encapsulates a business logic operation with a
@@ -112,11 +111,9 @@ module Cuprum
   #
   # @see Cuprum::Chaining
   # @see Cuprum::Processing
-  # @see Cuprum::ResultHelpers
   class Command
     include Cuprum::Processing
     include Cuprum::Chaining
-    include Cuprum::ResultHelpers
 
     # Returns a new instance of Cuprum::Command.
     #

data/lib/cuprum/command_factory.rb

@@ -0,0 +1,276 @@
+require 'cuprum'
+
+require 'sleeping_king_studios/tools/toolbelt'
+
+module Cuprum
+  # Builder class for instantiating command objects.
+  #
+  # @example
+  #   class SpaceFactory < Cuprum::CommandFactory
+  #     command :build, BuildCommand
+  #
+  #     command :fly { |launch_site:| FlyCommand.new(launch_site) }
+  #
+  #     command_class :dream { DreamCommand }
+  #   end
+  #
+  #   factory = SpaceFactory.new
+  #
+  #   factory::Build #=> BuildCommand
+  #   factory.build  #=> an instance of BuildCommand
+  #
+  #   rocket = factory.build.call({ size: 'big' }) #=> an instance of Rocket
+  #   rocket.size                                  #=> 'big'
+  #
+  #   command = factory.fly(launch_site: 'KSC') #=> an instance of FlyCommand
+  #   command.call(rocket)
+  #   #=> launches the rocket from KSC
+  #
+  #   factory::Dream #=> DreamCommand
+  #   factory.dream  #=> an instance of DreamCommand
+  class CommandFactory < Module
+    # Defines the Domain-Specific Language and helper methods for dynamically
+    # defined commands.
+    class << self
+      # Defines a command for the factory.
+      #
+      # @overload command(name, command_class)
+      #   Defines a command using the given factory class. For example, when a
+      #   command is defined with the name "whirlpool" and the WhirlpoolCommand
+      #   class:
+      #
+      #   A factory instance will define the constant ::Whirlpool, and accessing
+      #   factory::Whirlpool will return the WhirlpoolCommand class.
+      #
+      #   A factory instance will define the method #whirlpool, and calling
+      #   factory#whirlpool will return an instance of WhirlpoolCommand. Any
+      #   arguments passed to the #whirlpool method will be forwarded to the
+      #   constructor when building the command.
+      #
+      #   @param name [String, Symbol] The name of the command.
+      #   @param command_class [Class] The command class. Must be a subclass of
+      #     Cuprum::Command.
+      #
+      #   @example
+      #     class MoveFactory < Cuprum::CommandFactory
+      #       command :cut, CutCommand
+      #     end
+      #
+      #     factory = MoveFactory.new
+      #     factory::Cut #=> CutCommand
+      #     factory.cut  #=> an instance of CutCommand
+      #
+      # @overload command(name) { |*args| }
+      #   Defines a command using the given block, which must return an instance
+      #   of a Cuprum::Command subclass. For example, when a command is defined
+      #   with the name "dive" and a block that returns an instance of the
+      #   DiveCommand class:
+      #
+      #   A factory instance will define the method #dive, and calling
+      #   factory#dive will call the block and return the resulting command
+      #   instance. Any arguments passed to the #dive method will be forwarded
+      #   to the block when building the command.
+      #
+      #   The block will be evaluated in the context of the factory instance, so
+      #   it has access to any methods or instance variables defined for the
+      #   factory instance.
+      #
+      #   @param name [String, Symbol] The name of the command.
+      #
+      #   @yield The block will be executed in the context of the factory
+      #     instance.
+      #   @yieldparam *args [Array] Any arguments given to the method
+      #     factory.name() will be passed on the block.
+      #   @yieldreturn [Cuprum::Command] The block return an instance of a
+      #     Cuprum::Command subclass, or else raise an error.
+      #
+      #   @example
+      #     class MoveFactory < Cuprum::CommandFactory
+      #       command :fly { |destination| FlyCommand.new(destination) }
+      #     end
+      #
+      #     factory = MoveFactory.new
+      #     factory.fly_command('Indigo Plateau')
+      #     #=> an instance of FlyCommand with a destination of 'Indigo Plateau'
+      def command(name, klass = nil, **metadata, &defn)
+        guard_abstract_factory!
+
+        if klass
+          define_command_from_class(klass, name: name, metadata: metadata)
+        elsif block_given?
+          define_command_from_block(defn, name: name, metadata: metadata)
+        else
+          require_definition!
+        end
+      end
+
+      # Defines a command using the given block, which must return a subclass of
+      # Cuprum::Command. For example, when a command is defined with the name
+      # "rock_climb" and a block returning a subclass of RockClimbCommand:
+      #
+      # A factory instance will define the constant ::RockClimb, and accessing
+      # factory::RockClimb will call the block and return the resulting command
+      # class. This value is memoized, so subsequent factory::RockClimb accesses
+      # on the same factory instance will return the same command class.
+      #
+      # A factory instance will define the method #rock_climb, and calling
+      # factory#rock_climb will access the constant at ::RockClimb and return an
+      # instance of that subclass of RockClimbCommand. Any arguments passed to
+      # the #whirlpool method will be forwarded to the constructor when building
+      # the command.
+      #
+      # @param name [String, Symbol] The name of the command.
+      # @yield The block will be executed in the context of the factory
+      #   instance.
+      # @yieldparam *args [Array] Any arguments given to the method
+      #   factory.name() will be passed on the block.
+      # @yieldreturn [Cuprum::Command] The block return an instance of a
+      #   Cuprum::Command subclass, or else raise an error.
+      #
+      # @example
+      #   class MoveFactory < Cuprum::CommandFactory
+      #     command_class :flash do
+      #       Class.new(FlashCommand) do
+      #         def brightness
+      #           :intense
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      #   factory = MoveFactory.new
+      #   factory::Flash #=> a subclass of FlashCommand
+      #   factory.flash  #=> an instance of factory::Flash
+      #
+      #   command = factory.flash
+      #   command.brightness #=> :intense
+      def command_class(name, **metadata, &defn)
+        guard_abstract_factory!
+
+        raise ArgumentError, 'must provide a block'.freeze unless block_given?
+
+        name = normalize_command_name(name)
+
+        (@command_definitions ||= {})[name] =
+          metadata.merge(__const_defn__: defn)
+
+        const_name = tools.string.camelize(name)
+
+        define_method(name) do |*args, &block|
+          command_class = const_get(const_name)
+
+          build_command(command_class, *args, &block)
+        end
+      end
+
+      protected
+
+      def command_definitions
+        definitions = (@command_definitions ||= {})
+
+        return definitions unless superclass < Cuprum::CommandFactory
+
+        superclass.command_definitions.merge(definitions)
+      end
+
+      private
+
+      def abstract_factory?
+        self == Cuprum::CommandFactory
+      end
+
+      def define_command_from_block(builder, name:, metadata: {})
+        command_name = normalize_command_name(name)
+
+        (@command_definitions ||= {})[command_name] = metadata
+
+        define_method(command_name) do |*args|
+          instance_exec(*args, &builder)
+        end
+      end
+
+      def define_command_from_class(command_class, name:, metadata: {})
+        guard_invalid_definition!(command_class)
+
+        command_name = normalize_command_name(name)
+
+        (@command_definitions ||= {})[command_name] =
+          metadata.merge(__const_defn__: command_class)
+
+        define_method(command_name) do |*args, &block|
+          build_command(command_class, *args, &block)
+        end
+      end
+
+      def guard_abstract_factory!
+        return unless abstract_factory?
+
+        raise NotImplementedError,
+          'Cuprum::CommandFactory is an abstract class. Create a subclass to ' \
+          'define commands for a factory.'.freeze
+      end
+
+      def guard_invalid_definition!(command_class)
+        return if command_class.is_a?(Class) && command_class < Cuprum::Command
+
+        raise ArgumentError, 'definition must be a command class'.freeze
+      end
+
+      def normalize_command_name(command_name)
+        tools.string.underscore(command_name).intern
+      end
+
+      def require_definition!
+        raise ArgumentError, 'must provide a command class or a block'.freeze
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+    end
+
+    # @return [Boolean] true if the factory defines the given command, otherwise
+    #   false.
+    def command?(command_name)
+      command_name = normalize_command_name(command_name)
+
+      commands.include?(command_name)
+    end
+
+    # @return [Array<Symbol>] a list of the commands defined by the factory.
+    def commands
+      self.class.send(:command_definitions).keys
+    end
+
+    # @private
+    def const_defined?(const_name, inherit = true)
+      command?(const_name) || super
+    end
+
+    # @private
+    def const_missing(const_name)
+      definitions  = self.class.send(:command_definitions)
+      command_name = normalize_command_name(const_name)
+      command_defn = definitions.dig(command_name, :__const_defn__)
+
+      return super unless command_defn
+
+      command_class =
+        command_defn.is_a?(Proc) ? instance_exec(&command_defn) : command_defn
+
+      const_set(const_name, command_class)
+
+      command_class
+    end
+
+    private
+
+    def build_command(command_class, *args, &block)
+      command_class.new(*args, &block)
+    end
+
+    def normalize_command_name(command_name)
+      self.class.send(:normalize_command_name, command_name)
+    end
+  end
+end