cuprum 0.9.1 → 0.11.0

data/lib/cuprum.rb

@@ -1,14 +1,20 @@
+# frozen_string_literal: true
+
 # A lightweight, functional-lite toolkit for making business logic a first-class
 # citizen of your application.
 module Cuprum
-  autoload :Command,   'cuprum/command'
-  autoload :Operation, 'cuprum/operation'
-  autoload :Result,    'cuprum/result'
+  autoload :Command,    'cuprum/command'
+  autoload :Error,      'cuprum/error'
+  autoload :Matcher,    'cuprum/matcher'
+  autoload :Middleware, 'cuprum/middleware'
+  autoload :Operation,  'cuprum/operation'
+  autoload :Result,     'cuprum/result'
+  autoload :Steps,      'cuprum/steps'
 
   class << self
     # @return [String] The current version of the gem.
     def version
       VERSION
-    end # method version
-  end # eigenclass
-end # module
+    end
+  end
+end

data/lib/cuprum/built_in.rb

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

data/lib/cuprum/built_in/identity_command.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/built_in'
 require 'cuprum/command'
 
@@ -24,8 +26,8 @@ module Cuprum::BuiltIn
   class IdentityCommand < Cuprum::Command
     private
 
-    def process value = nil
+    def process(value = nil)
       value
-    end # method process
-  end # class
-end # module
+    end
+  end
+end

data/lib/cuprum/built_in/identity_operation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/built_in/identity_command'
 require 'cuprum/operation'
 
@@ -23,5 +25,5 @@ module Cuprum::BuiltIn
   #   #=> ['errors.messages.unknown']
   class IdentityOperation < Cuprum::BuiltIn::IdentityCommand
     include Cuprum::Operation::Mixin
-  end # class
-end # module
+  end
+end

data/lib/cuprum/built_in/null_command.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/built_in'
 require 'cuprum/command'
 
@@ -13,6 +15,6 @@ module Cuprum::BuiltIn
   class NullCommand < Cuprum::Command
     private
 
-    def process *_args; end
-  end # class
-end # module
+    def process(*_args); end
+  end
+end

data/lib/cuprum/built_in/null_operation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/built_in/null_command'
 require 'cuprum/operation'
 
@@ -12,5 +14,5 @@ module Cuprum::BuiltIn
   #   #=> true
   class NullOperation < Cuprum::BuiltIn::NullCommand
     include Cuprum::Operation::Mixin
-  end # class
-end # module
+  end
+end

data/lib/cuprum/command.rb

@@ -1,5 +1,8 @@
-require 'cuprum/chaining'
+# frozen_string_literal: true
+
+require 'cuprum/currying'
 require 'cuprum/processing'
+require 'cuprum/steps'
 
 module Cuprum
   # Functional object that encapsulates a business logic operation with a
@@ -18,14 +21,14 @@ module Cuprum
   #   class MultiplyCommand < Cuprum::Command
   #     def initialize multiplier
   #       @multiplier = multiplier
-  #     end # constructor
+  #     end
   #
   #     private
   #
   #     def process int
   #       int * @multiplier
-  #     end # method process
-  #   end # class
+  #     end
+  #   end
   #
   #   triple_command = MultiplyCommand.new(3)
   #   result         = command_command.call(5)
@@ -36,7 +39,7 @@ module Cuprum
   #   class DivideCommand < Cuprum::Command
   #     def initialize divisor
   #       @divisor = divisor
-  #     end # constructor
+  #     end
   #
   #     private
   #
@@ -46,8 +49,8 @@ module Cuprum
   #       end
   #
   #       int / @divisor
-  #     end # method process
-  #   end # class
+  #     end
+  #   end
   #
   #   halve_command = DivideCommand.new(2)
   #   result        = halve_command.call(10)
@@ -61,57 +64,11 @@ module Cuprum
   #   result.error #=> 'errors.messages.divide_by_zero'
   #   result.value #=> nil
   #
-  # @example Command Chaining
-  #   class AddCommand < Cuprum::Command
-  #     def initialize addend
-  #       @addend = addend
-  #     end # constructor
-  #
-  #     private
-  #
-  #     def process int
-  #       int + @addend
-  #     end # method process
-  #   end # class
-  #
-  #   double_and_add_one = MultiplyCommand.new(2).chain(AddCommand.new(1))
-  #   result             = double_and_add_one(5)
-  #
-  #   result.value #=> 5
-  #
-  # @example Conditional Chaining
-  #   class EvenCommand < Cuprum::Command
-  #     private
-  #
-  #     def process int
-  #       return int if int.even?
-  #
-  #       Cuprum::Errors.new(error: 'errors.messages.not_even')
-  #     end # method process
-  #   end # class
-  #
-  #   # The next step in a Collatz sequence is determined as follows:
-  #   # - If the number is even, divide it by 2.
-  #   # - If the number is odd, multiply it by 3 and add 1.
-  #   collatz_command =
-  #     EvenCommand.new.
-  #       chain(DivideCommand.new(2), :on => :success).
-  #       chain(
-  #         MultiplyCommand.new(3).chain(AddCommand.new(1),
-  #         :on => :failure
-  #       )
-  #
-  #   result = collatz_command.new(5)
-  #   result.value #=> 16
-  #
-  #   result = collatz_command.new(16)
-  #   result.value #=> 8
-  #
-  # @see Cuprum::Chaining
   # @see Cuprum::Processing
   class Command
     include Cuprum::Processing
-    include Cuprum::Chaining
+    include Cuprum::Currying
+    include Cuprum::Steps
 
     # Returns a new instance of Cuprum::Command.
     #
@@ -119,12 +76,33 @@ module Cuprum
     #   #call method will wrap the block and set the result #value to the return
     #   value of the block. This overrides the implementation in #process, if
     #   any.
-    def initialize &implementation
+    def initialize(&implementation)
       return unless implementation
 
       define_singleton_method :process, &implementation
 
       singleton_class.send(:private, :process)
-    end # method initialize
-  end # class
-end # module
+    end
+
+    # (see Cuprum::Processing#call)
+    def call(*args, **kwargs, &block)
+      steps { super }
+    end
+
+    # Wraps the command in a proc.
+    #
+    # Calling the proc will call the command with the given arguments, keywords,
+    # and block.
+    #
+    # @return [Proc] the wrapping proc.
+    def to_proc
+      @to_proc ||= lambda do |*args, **kwargs, &block|
+        if kwargs.empty?
+          call(*args, &block)
+        else
+          call(*args, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/command_factory.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 require 'sleeping_king_studios/tools/toolbelt'
@@ -28,7 +30,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
@@ -147,20 +149,14 @@ module Cuprum
       def command_class(name, **metadata, &defn)
         guard_abstract_factory!
 
-        raise ArgumentError, 'must provide a block'.freeze unless block_given?
+        raise ArgumentError, 'must provide a block' 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 +180,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
 
@@ -207,21 +229,21 @@ module Cuprum
 
         raise NotImplementedError,
           'Cuprum::CommandFactory is an abstract class. Create a subclass to ' \
-          'define commands for a factory.'.freeze
+          'define commands for a factory.'
       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
+        raise ArgumentError, 'definition must be a command class'
       end
 
       def normalize_command_name(command_name)
-        tools.string.underscore(command_name).intern
+        tools.string_tools.underscore(command_name).intern
       end
 
       def require_definition!
-        raise ArgumentError, 'must provide a command class or a block'.freeze
+        raise ArgumentError, 'must provide a command class or a block'
       end
 
       def tools
@@ -243,7 +265,7 @@ module Cuprum
     end
 
     # @private
-    def const_defined?(const_name, inherit = true)
+    def const_defined?(const_name, inherit = true) # rubocop:disable Style/OptionalBooleanParameter
       command?(const_name) || super
     end
 
@@ -265,8 +287,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,79 @@
+# 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, &block)
+      return self if arguments.empty? && keywords.empty? && block.nil?
+
+      Cuprum::Currying::CurriedCommand.new(
+        arguments: arguments,
+        block:     block,
+        command:   self,
+        keywords:  keywords
+      )
+    end
+  end
+end