cuprum 0.7.0 → 0.10.0.rc.0

data/lib/cuprum/command.rb

@@ -1,6 +1,7 @@
 require 'cuprum/chaining'
+require 'cuprum/currying'
 require 'cuprum/processing'
-require 'cuprum/result_helpers'
+require 'cuprum/steps'
 
 module Cuprum
   # Functional object that encapsulates a business logic operation with a
@@ -33,7 +34,7 @@ module Cuprum
   #
   #   result.value #=> 15
   #
-  # @example A Command with errors
+  # @example A Command with an error state
   #   class DivideCommand < Cuprum::Command
   #     def initialize divisor
   #       @divisor = divisor
@@ -43,10 +44,8 @@ module Cuprum
   #
   #     def process int
   #       if @divisor.zero?
-  #         errors << 'errors.messages.divide_by_zero'
-  #
-  #         return
-  #       end # if
+  #         return Cuprum::Result.new(error: 'errors.messages.divide_by_zero')
+  #       end
   #
   #       int / @divisor
   #     end # method process
@@ -55,14 +54,14 @@ module Cuprum
   #   halve_command = DivideCommand.new(2)
   #   result        = halve_command.call(10)
   #
-  #   result.errors #=> []
-  #   result.value  #=> 5
+  #   result.error #=> nil
+  #   result.value #=> 5
   #
-  #   command_with_errors = DivideCommand.new(0)
-  #   result              = command_with_errors.call(10)
+  #   divide_command = DivideCommand.new(0)
+  #   result         = divide_command.call(10)
   #
-  #   result.errors #=> ['errors.messages.divide_by_zero']
-  #   result.value  #=> nil
+  #   result.error #=> 'errors.messages.divide_by_zero'
+  #   result.value #=> nil
   #
   # @example Command Chaining
   #   class AddCommand < Cuprum::Command
@@ -87,9 +86,9 @@ module Cuprum
   #     private
   #
   #     def process int
-  #       errors << 'errors.messages.not_even' unless int.even?
+  #       return int if int.even?
   #
-  #       int
+  #       Cuprum::Errors.new(error: 'errors.messages.not_even')
   #     end # method process
   #   end # class
   #
@@ -112,11 +111,10 @@ module Cuprum
   #
   # @see Cuprum::Chaining
   # @see Cuprum::Processing
-  # @see Cuprum::ResultHelpers
   class Command
     include Cuprum::Processing
-    include Cuprum::Chaining
-    include Cuprum::ResultHelpers
+    include Cuprum::Currying
+    include Cuprum::Steps
 
     # Returns a new instance of Cuprum::Command.
     #
@@ -125,7 +123,15 @@ module Cuprum
     #   value of the block. This overrides the implementation in #process, if
     #   any.
     def initialize &implementation
-      define_singleton_method :process, &implementation if implementation
+      return unless implementation
+
+      define_singleton_method :process, &implementation
+
+      singleton_class.send(:private, :process)
     end # method initialize
+
+    def call(*args, **kwargs, &block)
+      steps { super }
+    end
   end # class
 end # module

data/lib/cuprum/command_factory.rb

@@ -0,0 +1,300 @@
+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 # rubocop:disable Metrics/ClassLength
+    # 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?
+
+        method_name = normalize_command_name(name)
+
+        (@command_definitions ||= {})[method_name] =
+          metadata.merge(__const_defn__: defn)
+
+        define_lazy_command_method(method_name)
+      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, **kwargs|
+          if kwargs.empty?
+            instance_exec(*args, &builder)
+          else
+            instance_exec(*args, **kwargs, &builder)
+          end
+        end
+      end
+
+      def define_command_from_class(command_class, name:, metadata: {})
+        guard_invalid_definition!(command_class)
+
+        method_name = normalize_command_name(name)
+
+        (@command_definitions ||= {})[method_name] =
+          metadata.merge(__const_defn__: command_class)
+
+        define_command_method(method_name, command_class)
+      end
+
+      def define_command_method(method_name, command_class)
+        define_method(method_name) do |*args, **kwargs, &block|
+          if kwargs.empty?
+            build_command(command_class, *args, &block)
+          else
+            build_command(command_class, *args, **kwargs, &block)
+          end
+        end
+      end
+
+      def define_lazy_command_method(method_name)
+        const_name = tools.string_tools.camelize(method_name)
+
+        define_method(method_name) do |*args, **kwargs, &block|
+          command_class = const_get(const_name)
+
+          if kwargs.empty?
+            build_command(command_class, *args, &block)
+          else
+            build_command(command_class, *args, **kwargs, &block)
+          end
+        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_tools.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, **kwargs, &block)
+      if kwargs.empty?
+        command_class.new(*args, &block)
+      else
+        command_class.new(*args, **kwargs, &block)
+      end
+    end
+
+    def normalize_command_name(command_name)
+      self.class.send(:normalize_command_name, command_name)
+    end
+  end
+end

data/lib/cuprum/currying.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Implements partial application for command objects.
+  #
+  # Partial application (more commonly referred to, if imprecisely, as currying)
+  # refers to fixing some number of arguments to a function, resulting in a
+  # function with a smaller number of arguments.
+  #
+  # In Cuprum's case, a curried (partially applied) command takes an original
+  # command and pre-defines some of its arguments. When the curried command is
+  # called, the predefined arguments and/or keywords will be combined with the
+  # arguments passed to #call.
+  #
+  # @example Currying Arguments
+  #   # Our base command takes two arguments.
+  #   say_command = Cuprum::Command.new do |greeting, person|
+  #     "#{greeting}, #{person}!"
+  #   end
+  #   say_command.call('Hello', 'world')
+  #   #=> returns a result with value 'Hello, world!'
+  #
+  #   # Next, we create a curried command. This sets the first argument to
+  #   # always be 'Greetings', so our curried command only takes one argument,
+  #   # namely the name of the person being greeted.
+  #   greet_command = say_command.curry('Greetings')
+  #   greet_command.call('programs')
+  #   #=> returns a result with value 'Greetings, programs!'
+  #
+  #   # Here, we are creating a curried command that passes both arguments.
+  #   # Therefore, our curried command does not take any arguments.
+  #   recruit_command = say_command.curry('Greetings', 'starfighter')
+  #   recruit_command.call
+  #   #=> returns a result with value 'Greetings, starfighter!'
+  #
+  # @example Currying Keywords
+  #   # Our base command takes two keywords: a math operation and an array of
+  #   # integers.
+  #   math_command = Cuprum::Command.new do |operands:, operation:|
+  #     operations.reduce(&operation)
+  #   end
+  #   math_command.call(operands: [2, 2], operation: :+)
+  #   #=> returns a result with value 4
+  #
+  #   # Our curried command still takes two keywords, but now the operation
+  #   # keyword is optional. It now defaults to :*, for multiplication.
+  #   multiply_command = math_command.curry(operation: :*)
+  #   multiply_command.call(operands: [3, 3])
+  #   #=> returns a result with value 9
+  module Currying
+    autoload :CurriedCommand, 'cuprum/currying/curried_command'
+
+    # Returns a CurriedCommand that wraps this command with pre-set arguments.
+    #
+    # When the curried command is called, the predefined arguments and/or
+    # keywords will be combined with the arguments passed to #call.
+    #
+    # The original command is unchanged.
+    #
+    # @param arguments [Array] The arguments to pass to the curried command.
+    # @param keywords [Hash] The keywords to pass to the curried command.
+    #
+    # @return [Cuprum::Currying::CurriedCommand] the curried command.
+    #
+    # @see Cuprum::Currying::CurriedCommand#call
+    def curry(*arguments, **keywords)
+      return self if arguments.empty? && keywords.empty?
+
+      Cuprum::Currying::CurriedCommand.new(
+        arguments: arguments,
+        command:   self,
+        keywords:  keywords
+      )
+    end
+  end
+end