cuprum 0.9.1 → 0.10.0.rc.0

data/lib/cuprum.rb

@@ -4,6 +4,7 @@ module Cuprum
   autoload :Command,   'cuprum/command'
   autoload :Operation, 'cuprum/operation'
   autoload :Result,    'cuprum/result'
+  autoload :Steps,     'cuprum/steps'
 
   class << self
     # @return [String] The current version of the gem.

data/lib/cuprum/chaining.rb

@@ -197,7 +197,7 @@ module Cuprum
   # @see Cuprum::Command
   module Chaining
     # (see Cuprum::Processing#call)
-    def call(*args, &block)
+    def call(*args, **kwargs, &block)
       yield_chain(super)
     end
 
@@ -282,6 +282,8 @@ module Cuprum
 
     protected
 
+    # rubocop:disable Metrics/MethodLength
+
     # @!visibility public
     #
     # As #chain, but modifies the current command instead of creating a clone.
@@ -319,6 +321,11 @@ module Cuprum
     #
     #   @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 <<
@@ -329,11 +336,14 @@ module Cuprum
 
       self
     end
+    # rubocop:enable Metrics/MethodLength
 
     def chained_procs
       @chained_procs ||= []
     end
 
+    # rubocop:disable Metrics/MethodLength
+
     # @!visibility public
     #
     # As #tap_result, but modifies the current command instead of creating a
@@ -348,6 +358,11 @@ module Cuprum
     #
     # @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 <<
@@ -358,6 +373,7 @@ module Cuprum
 
       self
     end
+    # rubocop:enable Metrics/MethodLength
 
     # @!visibility public
     #
@@ -373,6 +389,11 @@ module Cuprum
     #
     # @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,

data/lib/cuprum/command.rb

@@ -1,5 +1,7 @@
 require 'cuprum/chaining'
+require 'cuprum/currying'
 require 'cuprum/processing'
+require 'cuprum/steps'
 
 module Cuprum
   # Functional object that encapsulates a business logic operation with a
@@ -111,7 +113,8 @@ module Cuprum
   # @see Cuprum::Processing
   class Command
     include Cuprum::Processing
-    include Cuprum::Chaining
+    include Cuprum::Currying
+    include Cuprum::Steps
 
     # Returns a new instance of Cuprum::Command.
     #
@@ -126,5 +129,9 @@ module Cuprum
 
       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

@@ -28,7 +28,7 @@ module Cuprum
   #
   #   factory::Dream #=> DreamCommand
   #   factory.dream  #=> an instance of DreamCommand
-  class CommandFactory < Module
+  class CommandFactory < Module # rubocop:disable Metrics/ClassLength
     # Defines the Domain-Specific Language and helper methods for dynamically
     # defined commands.
     class << self
@@ -149,18 +149,12 @@ module Cuprum
 
         raise ArgumentError, 'must provide a block'.freeze unless block_given?
 
-        name = normalize_command_name(name)
+        method_name = normalize_command_name(name)
 
-        (@command_definitions ||= {})[name] =
+        (@command_definitions ||= {})[method_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
+        define_lazy_command_method(method_name)
       end
 
       protected
@@ -184,21 +178,47 @@ module Cuprum
 
         (@command_definitions ||= {})[command_name] = metadata
 
-        define_method(command_name) do |*args|
-          instance_exec(*args, &builder)
+        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)
 
-        command_name = normalize_command_name(name)
+        method_name = normalize_command_name(name)
 
-        (@command_definitions ||= {})[command_name] =
+        (@command_definitions ||= {})[method_name] =
           metadata.merge(__const_defn__: command_class)
 
-        define_method(command_name) do |*args, &block|
-          build_command(command_class, *args, &block)
+        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
 
@@ -217,7 +237,7 @@ module Cuprum
       end
 
       def normalize_command_name(command_name)
-        tools.string.underscore(command_name).intern
+        tools.string_tools.underscore(command_name).intern
       end
 
       def require_definition!
@@ -265,8 +285,12 @@ module Cuprum
 
     private
 
-    def build_command(command_class, *args, &block)
-      command_class.new(*args, &block)
+    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)

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

data/lib/cuprum/currying/curried_command.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'cuprum/currying'
+
+module Cuprum::Currying
+  # A CurriedCommand wraps another command and passes preset args 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 =
+  #     Cuprum::CurriedCommand.new(
+  #       arguments: ['Greetings'],
+  #       command:   say_command
+  #     )
+  #   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 =
+  #     Cuprum::CurriedCommand.new(
+  #       arguments: ['Greetings', 'starfighter'],
+  #       command:   say_command
+  #     )
+  #   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 =
+  #     Cuprum::CurriedCommand.new(
+  #       command:  math_command,
+  #       keywords: { operation: :* }
+  #     )
+  #   multiply_command.call(operands: [3, 3])
+  #   #=> returns a result with value 9
+  class CurriedCommand < Cuprum::Command
+    # @param arguments [Array] The arguments to pass to the curried command.
+    # @param command [Cuprum::Command] The original command to curry.
+    # @param keywords [Hash] The keywords to pass to the curried command.
+    def initialize(arguments: [], command:, keywords: {})
+      @arguments = arguments
+      @command   = command
+      @keywords  = keywords
+    end
+
+    # @!method call(*args, **kwargs)
+    #   Merges the arguments and keywords and calls the wrapped command.
+    #
+    #   First, the arguments array is created starting with the :arguments
+    #   passed to #initialize. Any positional arguments passed directly to #call
+    #   are then appended.
+    #
+    #   Second, the keyword arguments are created by merging the keywords passed
+    #   directly into #call into the keywods passed to #initialize. This means
+    #   that if a key is passed in both places, the value passed into #call will
+    #   take precedence.
+    #
+    #   Finally, the merged arguments and keywords are passed into the original
+    #   command's #call method.
+    #
+    #   @param args [Array] Additional arguments to pass to the curried command.
+    #   @param kwargs [Hash] Additional keywords to pass to the curried command.
+    #
+    #   @return [Cuprum::Result]
+    #
+    #   @see Cuprum::Processing#call
+
+    # @return [Array] the arguments to pass to the curried command.
+    attr_reader :arguments
+
+    # @return [Cuprum::Command] the original command to curry.
+    attr_reader :command
+
+    # @return [Hash] the keywords to pass to the curried command.
+    attr_reader :keywords
+
+    private
+
+    def process(*args, **kwargs, &block)
+      args   = [*arguments, *args]
+      kwargs = keywords.merge(kwargs)
+
+      if kwargs.empty?
+        command.call(*args, &block)
+      else
+        command.call(*args, **kwargs, &block)
+      end
+    end
+  end
+end

data/lib/cuprum/operation.rb

@@ -62,7 +62,7 @@ module Cuprum
       #     implementation.
       #
       # @see Cuprum::Command#call
-      def call *args, &block
+      def call *args, **kwargs, &block
         reset! if called? # Clear reference to most recent result.
 
         @result = super

data/lib/cuprum/processing.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'cuprum/errors/command_not_implemented'
+require 'cuprum/result_helpers'
 
 module Cuprum
   # Functional implementation for creating a command object. Cuprum::Processing
@@ -57,6 +58,8 @@ module Cuprum
   #
   # @see Cuprum::Command
   module Processing
+    include Cuprum::ResultHelpers
+
     # Returns a nonnegative integer for commands that take a fixed number of
     # arguments. For commands that take a variable number of arguments, returns
     # -n-1, where n is the number of required arguments.
@@ -87,8 +90,13 @@ module Cuprum
     #
     #   @yield If a block argument is given, it will be passed to the
     #     implementation.
-    def call(*args, &block)
-      value = process(*args, &block)
+    def call(*args, **kwargs, &block)
+      value =
+        if kwargs.empty?
+          process(*args, &block)
+        else
+          process(*args, **kwargs, &block)
+        end
 
       return value.to_cuprum_result if value_is_result?(value)
 
@@ -97,14 +105,6 @@ module Cuprum
 
     private
 
-    def build_result(error: nil, status: nil, value: nil)
-      Cuprum::Result.new(error: error, status: status, value: value)
-    end
-
-    def failure(error)
-      build_result(error: error)
-    end
-
     # @!visibility public
     # @overload process(*arguments, **keywords, &block)
     #   The implementation of the command, to be executed when the #call method
@@ -128,10 +128,6 @@ module Cuprum
       build_result(error: error)
     end
 
-    def success(value)
-      build_result(value: value)
-    end
-
     def value_is_result?(value)
       value.respond_to?(:to_cuprum_result)
     end