cuprum 0.5.0 → 0.6.0

data/lib/cuprum/basic_command.rb

@@ -0,0 +1,212 @@
+require 'cuprum/not_implemented_error'
+
+module Cuprum
+  # Functional object that encapsulates a business logic operation with a
+  # standardized interface and returns a result object.
+  class BasicCommand
+    # Returns a new instance of Cuprum::BasicCommand.
+    #
+    # @yield [*arguments, **keywords, &block] If a block is given, the
+    #   #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
+      define_singleton_method :process, &implementation if implementation
+    end # method initialize
+
+    # @overload call(*arguments, **keywords, &block)
+    #   Executes the logic encoded in the constructor block, or the #process
+    #   method if no block was passed to the constructor, and returns a
+    #   Cuprum::Result object with the return value of the block or #process,
+    #   the success or failure status, and any errors generated.
+    #
+    #   @param arguments [Array] Arguments to be passed to the implementation.
+    #
+    #   @param keywords [Hash] Keywords to be passed to the implementation.
+    #
+    #   @return [Cuprum::Result] The result object for the command.
+    #
+    #   @yield If a block argument is given, it will be passed to the
+    #     implementation.
+    #
+    #   @raise [Cuprum::NotImplementedError] Unless a block was passed to the
+    #     constructor or the #process method was overriden by a Command
+    #     subclass.
+    def call *args, &block
+      wrap_result { |result| merge_results(result, process(*args, &block)) }
+    end # method call
+
+    private
+
+    # @!visibility public
+    #
+    # Generates an empty errors object. When the function is called, the result
+    # will have its #errors property initialized to the value returned by
+    # #build_errors. By default, this is an array. If you want to use a custom
+    # errors object type, override this method in a subclass.
+    #
+    # @return [Array] An empty errors object.
+    def build_errors
+      []
+    end # method build_errors
+
+    def convert_value_to_result value
+      return nil unless value_is_result?(value)
+
+      if value.respond_to?(:result) && value_is_result?(value.result)
+        return value.result
+      end # if
+
+      value
+    end # method convert_value_to_result
+
+    # @!visibility public
+    #
+    # Provides a reference to the current result's errors object. Messages or
+    # error objects added to this will be included in the #errors method of the
+    # returned result object.
+    #
+    # @return [Array, Object] The errors object.
+    #
+    # @see Cuprum::Result#errors.
+    #
+    # @note This is a private method, and only available when executing the
+    #   function implementation as defined in the constructor block or the
+    #   #process method.
+    def errors
+      @result&.errors
+    end # method errors
+
+    # @!visibility public
+    #
+    # Marks the current result as failed. Calling #failure? on the returned
+    # result object will evaluate to true, whether or not the result has any
+    # errors.
+    #
+    # @see Cuprum::Result#failure!.
+    #
+    # @note This is a private method, and only available when executing the
+    #   function implementation as defined in the constructor block or the
+    #   #process method.
+    def failure!
+      @result&.failure!
+    end # method failure!
+
+    # @!visibility public
+    #
+    # Marks the current result as halted.
+    #
+    # @see Cuprum::Result#halt!.
+    #
+    # @note This is a private method, and only available when executing the
+    #   function implementation as defined in the constructor block or the
+    #   #process method.
+    def halt!
+      @result&.halt!
+    end # method halt!
+
+    # :nocov:
+    def humanize_list list, empty_value: ''
+      return empty_value if list.size.zero?
+
+      return list.first.to_s if list.size == 1
+
+      return "#{list.first} and #{list.last}" if list.size == 2
+
+      "#{list[0...-1].join ', '}, and #{list.last}"
+    end # method humanize_list
+    # :nocov:
+
+    def merge_results result, other
+      if value_is_result?(other)
+        Cuprum.warn(result_not_empty_warning) unless result.empty?
+
+        convert_value_to_result(other)
+      else
+        result.value = other
+
+        result
+      end # if-else
+    end # method merge_results
+
+    # @!visibility public
+    # @overload process(*arguments, **keywords, &block)
+    #   The implementation of the function, to be executed when the #call method
+    #   is called. Can add errors to or set the status of the result, and the
+    #   value of the result will be set to the value returned by #process. Do
+    #   not call this method directly.
+    #
+    #   @param arguments [Array] The arguments, if any, passed from #call.
+    #
+    #   @param keywords [Hash] The keywords, if any, passed from #call.
+    #
+    #   @yield The block, if any, passed from #call.
+    #
+    #   @return [Object] the value of the result object to be returned by #call.
+    #
+    #   @raise [Cuprum::NotImplementedError] Unless a block was passed to the
+    #     constructor or the #process method was overriden by a Command
+    #     subclass.
+    #
+    # @note This is a private method.
+    def process *_args
+      raise Cuprum::NotImplementedError, nil, caller(1..-1)
+    end # method process
+
+    def result_not_empty_warning # rubocop:disable Metrics/MethodLength
+      warnings = []
+
+      unless @result.errors.empty?
+        warnings << "there were already errors #{@result.errors.inspect}"
+      end # unless
+
+      status = @result.send(:status)
+      unless status.nil?
+        warnings << "the status was set to #{status.inspect}"
+      end # unless
+
+      if @result.halted?
+        warnings << 'the function was halted'
+      end # if
+
+      message = '#process returned a result, but '
+      message <<
+        humanize_list(warnings, :empty_value => 'the result was not empty')
+
+      message
+    end # method result_not_empty_warning
+
+    # @!visibility public
+    #
+    # Marks the current result as passing. Calling #success? on the returned
+    # result object will evaluate to true, whether or not the result has any
+    # errors.
+    #
+    # @see Cuprum::Result#success!.
+    #
+    # @note This is a private method, and only available when executing the
+    #   function implementation as defined in the constructor block or the
+    #   #process method.
+    def success!
+      @result&.success!
+    end # method success!
+
+    def value_is_result? value
+      value.respond_to?(:value) && value.respond_to?(:success?)
+    end # method value
+
+    def wrap_result
+      result = Cuprum::Result.new(:errors => build_errors)
+
+      begin
+        @result = result
+
+        result = yield result
+      ensure
+        @result = nil
+      end # begin-ensure
+
+      result
+    end # method wrap_result
+  end # class
+end # module

data/lib/cuprum/built_in/{identity_function.rb → identity_command.rb}

@@ -1,11 +1,11 @@
 require 'cuprum/built_in'
-require 'cuprum/function'
+require 'cuprum/command'
 
 module Cuprum::BuiltIn
   # A predefined function that returns the value or result it was called with.
   #
   # @example With a value.
-  #   result = IdentityFunction.new.call('custom value')
+  #   result = IdentityCommand.new.call('custom value')
   #   result.value
   #   #=> 'custom value'
   #   result.success?
@@ -14,14 +14,14 @@ module Cuprum::BuiltIn
   # @example With a result.
   #   errors = ['errors.messages.unknown']
   #   value  = Cuprum::Result.new('result value', :errors => errors)
-  #   result = IdentityFunction.new.call(value)
+  #   result = IdentityCommand.new.call(value)
   #   result.value
   #   #=> 'result value'
   #   result.success?
   #   #=> false
   #   result.errors
   #   #=> ['errors.messages.unknown']
-  class IdentityFunction < Cuprum::Function
+  class IdentityCommand < Cuprum::Command
     private
 
     def process value = nil

data/lib/cuprum/built_in/identity_operation.rb

@@ -1,4 +1,4 @@
-require 'cuprum/built_in/identity_function'
+require 'cuprum/built_in/identity_command'
 require 'cuprum/operation'
 
 module Cuprum::BuiltIn
@@ -21,7 +21,7 @@ module Cuprum::BuiltIn
   #   #=> false
   #   operation.errors
   #   #=> ['errors.messages.unknown']
-  class IdentityOperation < Cuprum::BuiltIn::IdentityFunction
+  class IdentityOperation < Cuprum::BuiltIn::IdentityCommand
     include Cuprum::Operation::Mixin
   end # class
 end # module

data/lib/cuprum/built_in/{null_function.rb → null_command.rb}

@@ -1,16 +1,16 @@
 require 'cuprum/built_in'
-require 'cuprum/function'
+require 'cuprum/command'
 
 module Cuprum::BuiltIn
-  # A predefined function that does nothing when called.
+  # A predefined command that does nothing when called.
   #
   # @example
-  #   result = NullFunction.new.call
+  #   result = NullCommand.new.call
   #   result.value
   #   #=> nil
   #   result.success?
   #   #=> true
-  class NullFunction < Cuprum::Function
+  class NullCommand < Cuprum::Command
     private
 
     def process *_args; end

data/lib/cuprum/built_in/null_operation.rb

@@ -1,4 +1,4 @@
-require 'cuprum/built_in/null_function'
+require 'cuprum/built_in/null_command'
 require 'cuprum/operation'
 
 module Cuprum::BuiltIn
@@ -10,7 +10,7 @@ module Cuprum::BuiltIn
   #   #=> nil
   #   operation.success?
   #   #=> true
-  class NullOperation < Cuprum::BuiltIn::NullFunction
+  class NullOperation < Cuprum::BuiltIn::NullCommand
     include Cuprum::Operation::Mixin
   end # class
 end # module

data/lib/cuprum/chaining.rb

@@ -0,0 +1,142 @@
+require 'cuprum'
+
+module Cuprum
+  # Mixin to implement command chaining functionality for a command class.
+  # Chaining commands allows you to define complex logic by composing it from
+  # simpler commands, including branching logic and error handling.
+  #
+  # @see Cuprum::Command
+  module Chaining
+    # (see Cuprum::BasicCommand#call)
+    def call *args, &block
+      call_chained_functions(super)
+    end # method call
+
+    # 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 <<
+          {
+            :proc => convert_function_or_proc_to_proc(block || function),
+            :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.
+    #
+    # @overload else(function)
+    #
+    #   @param function [Cuprum::Command] The function to call after the
+    #     current or last chained function.
+    #
+    # @overload else(&block)
+    #
+    #   @yieldparam result [Cuprum::Result] The #result of the previous
+    #     function.
+    #
+    # @return [Cuprum::Command] The chained function.
+    #
+    # @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)
+    #
+    #   @param function [Cuprum::Command] The function to call after the
+    #     current or last chained function.
+    #
+    # @overload then(&block)
+    #
+    #   @yieldparam result [Cuprum::Result] The #result of the previous
+    #     function.
+    #
+    # @return [Cuprum::Command] The chained function.
+    #
+    # @see #chain
+    def then function = nil, &block
+      chain(function, :on => :success, &block)
+    end # method then
+
+    protected
+
+    def chained_functions
+      @chained_functions ||= []
+    end # method chained_functions
+
+    private
+
+    def call_chained_functions first_result
+      chained_functions.reduce(first_result) do |result, hsh|
+        next result if skip_chained_function?(result, :on => hsh[:on])
+
+        value = hsh.fetch(:proc).call(result)
+
+        convert_value_to_result(value) || result
+      end # reduce
+    end # method call_chained_functions
+
+    def convert_function_or_proc_to_proc function_or_proc
+      return function_or_proc if function_or_proc.is_a?(Proc)
+
+      ->(result) { function_or_proc.call(result) }
+    end # method convert_function_or_proc_to_proc
+
+    def skip_chained_function? last_result, on:
+      return false if on == :always
+
+      return true if last_result.respond_to?(:halted?) && last_result.halted?
+
+      case on
+      when :success
+        !last_result.success?
+      when :failure
+        !last_result.failure?
+      end # case
+    end # method skip_chained_function?
+  end # module
+end # modue

data/lib/cuprum/command.rb

@@ -0,0 +1,113 @@
+require 'cuprum/basic_command'
+require 'cuprum/chaining'
+require 'cuprum/not_implemented_error'
+require 'cuprum/result'
+
+module Cuprum
+  # Functional object that encapsulates a business logic operation with a
+  # consistent interface and tracking of result value and status.
+  #
+  # A Command can be defined either by passing a block to the constructor, or
+  # by defining a subclass of Command and implementing the #process method.
+  #
+  # @example A Command with a block
+  #   double_function = Cuprum::Command.new { |int| 2 * int }
+  #   result          = double_function.call(5)
+  #
+  #   result.value #=> 10
+  #
+  # @example A Command subclass
+  #   class MultiplyCommand < Cuprum::Command
+  #     def initialize multiplier
+  #       @multiplier = multiplier
+  #     end # constructor
+  #
+  #     private
+  #
+  #     def process int
+  #       int * @multiplier
+  #     end # method process
+  #   end # class
+  #
+  #   triple_function = MultiplyCommand.new(3)
+  #   result          = triple_function.call(5)
+  #
+  #   result.value #=> 15
+  #
+  # @example A Command with errors
+  #   class DivideCommand < Cuprum::Command
+  #     def initialize divisor
+  #       @divisor = divisor
+  #     end # constructor
+  #
+  #     private
+  #
+  #     def process int
+  #       if @divisor.zero?
+  #         errors << 'errors.messages.divide_by_zero'
+  #
+  #         return
+  #       end # if
+  #
+  #       int / @divisor
+  #     end # method process
+  #   end # class
+  #
+  #   halve_function = DivideCommand.new(2)
+  #   result         = halve_function.call(10)
+  #
+  #   result.errors #=> []
+  #   result.value  #=> 5
+  #
+  #   function_with_errors = DivideCommand.new(0)
+  #   result               = function_with_errors.call(10)
+  #
+  #   result.errors #=> ['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 With #then And #else
+  #   class EvenCommand < Cuprum::Command
+  #     private
+  #
+  #     def process int
+  #       errors << 'errors.messages.not_even' unless int.even?
+  #
+  #       int
+  #     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_function =
+  #     EvenCommand.new.
+  #       then(DivideCommand.new(2)).
+  #       else(MultiplyCommand.new(3).chain(AddCommand.new(1)))
+  #
+  #   result = collatz_function.new(5)
+  #   result.value #=> 16
+  #
+  #   result = collatz_function.new(16)
+  #   result.value #=> 8
+  class Command < Cuprum::BasicCommand
+    include Cuprum::Chaining
+  end # class
+end # module