cuprum 0.6.0 → 0.7.0.rc.0

data/lib/cuprum/command.rb

@@ -1,7 +1,6 @@
-require 'cuprum/basic_command'
 require 'cuprum/chaining'
-require 'cuprum/not_implemented_error'
-require 'cuprum/result'
+require 'cuprum/processing'
+require 'cuprum/result_helpers'
 
 module Cuprum
   # Functional object that encapsulates a business logic operation with a
@@ -11,8 +10,8 @@ module Cuprum
   # 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)
+  #   double_command = Cuprum::Command.new { |int| 2 * int }
+  #   result         = double_command.call(5)
   #
   #   result.value #=> 10
   #
@@ -29,8 +28,8 @@ module Cuprum
   #     end # method process
   #   end # class
   #
-  #   triple_function = MultiplyCommand.new(3)
-  #   result          = triple_function.call(5)
+  #   triple_command = MultiplyCommand.new(3)
+  #   result         = command_command.call(5)
   #
   #   result.value #=> 15
   #
@@ -53,14 +52,14 @@ module Cuprum
   #     end # method process
   #   end # class
   #
-  #   halve_function = DivideCommand.new(2)
-  #   result         = halve_function.call(10)
+  #   halve_command = DivideCommand.new(2)
+  #   result        = halve_command.call(10)
   #
   #   result.errors #=> []
   #   result.value  #=> 5
   #
-  #   function_with_errors = DivideCommand.new(0)
-  #   result               = function_with_errors.call(10)
+  #   command_with_errors = DivideCommand.new(0)
+  #   result              = command_with_errors.call(10)
   #
   #   result.errors #=> ['errors.messages.divide_by_zero']
   #   result.value  #=> nil
@@ -83,7 +82,7 @@ module Cuprum
   #
   #   result.value #=> 5
   #
-  # @example Conditional Chaining With #then And #else
+  # @example Conditional Chaining
   #   class EvenCommand < Cuprum::Command
   #     private
   #
@@ -97,17 +96,36 @@ module Cuprum
   #   # 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 =
+  #   collatz_command =
   #     EvenCommand.new.
-  #       then(DivideCommand.new(2)).
-  #       else(MultiplyCommand.new(3).chain(AddCommand.new(1)))
+  #       chain(DivideCommand.new(2), :on => :success).
+  #       chain(
+  #         MultiplyCommand.new(3).chain(AddCommand.new(1),
+  #         :on => :failure
+  #       )
   #
-  #   result = collatz_function.new(5)
+  #   result = collatz_command.new(5)
   #   result.value #=> 16
   #
-  #   result = collatz_function.new(16)
+  #   result = collatz_command.new(16)
   #   result.value #=> 8
-  class Command < Cuprum::BasicCommand
+  #
+  # @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.
+    #
+    # @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
   end # class
 end # module

data/lib/cuprum/operation.rb

@@ -1,9 +1,9 @@
 require 'cuprum/command'
 
 module Cuprum
-  # Functional object that with syntactic sugar for tracking the last result.
+  # Functional object with syntactic sugar for tracking the last result.
   #
-  # An Operation is like a Function, but with two key differences. First, an
+  # An Operation is like a Command, but with two key differences. First, an
   # Operation retains a reference to the result object from the most recent time
   # the operation was called and delegates the methods defined by Cuprum::Result
   # to the most recent result. This allows a called Operation to replace a
@@ -28,14 +28,14 @@ module Cuprum
   #     end # if-else
   #   end # create
   #
-  # Like a Function, an Operation can be defined directly by passing an
+  # Like a Command, an Operation can be defined directly by passing an
   # implementation block to the constructor or by creating a subclass that
   # overwrites the #process method.
   #
   # @see Cuprum::Command
   class Operation < Cuprum::Command
     # Module-based implementation of the Operation methods. Use this to convert
-    # an already-defined function into an operation.
+    # an already-defined command into an operation.
     #
     # @example
     #   class CustomOperation < CustomCommand
@@ -45,6 +45,7 @@ module Cuprum
       # @return [Cuprum::Result] The result from the most recent call of the
       #   operation.
       attr_reader :result
+      alias_method :to_result, :result
 
       # @overload call(*arguments, **keywords, &block)
       #   Executes the logic encoded in the constructor block, or the #process
@@ -82,7 +83,7 @@ module Cuprum
       # @return [Array] the errors from the most recent result, or nil if the
       #   operation has not been called.
       def errors
-        super || (called? ? result.errors : nil)
+        called? ? result.errors : nil
       end # method errors
 
       # @return [Boolean] true if the most recent result had errors, or false if

data/lib/cuprum/processing.rb

@@ -0,0 +1,180 @@
+require 'cuprum/not_implemented_error'
+require 'cuprum/utils/result_not_empty_warning'
+
+module Cuprum
+  # Functional implementation for creating a command object. Cuprum::Processing
+  # defines a #call method, which performs the implementation defined by
+  # #process and returns an instance of Cuprum::Result.
+  #
+  # @example Defining a command with Cuprum::Processing.
+  #   class AdderCommand
+  #     include Cuprum::Processing
+  #
+  #     def initialize addend
+  #       @addend = addend
+  #     end # constructor
+  #
+  #     private
+  #
+  #     def process int
+  #       int + addend
+  #     end # method process
+  #   end # class AdderCommand
+  #
+  #   adder  = AdderCommand.new(2)
+  #   result = adder.call(3)
+  #   #=> an instance of Cuprum::Result
+  #   result.value    #=> 5
+  #   result.success? #=> true
+  #
+  # @example Defining a command with error handling.
+  #   class SquareRootCommand
+  #     include Cuprum::Processing
+  #
+  #     private
+  #
+  #     def process value
+  #       if value.negative?
+  #         result.errors << 'value cannot be negative'
+  #
+  #         return nil
+  #       end # if
+  #
+  #       Math.sqrt(value)
+  #     end # method process
+  #   end # class
+  #
+  #   result = SquareRootCommand.new.call(2)
+  #   result.value    #=> 1.414
+  #   result.success? #=> true
+  #   result.failure? #=> false
+  #   result.errors   #=> []
+  #
+  #   result = SquareRootCommand.new.call(-1)
+  #   result.value    #=> nil
+  #   result.success? #=> false
+  #   result.failure? #=> true
+  #   result.errors   #=> ['value cannot be negative']
+  #
+  # @see Cuprum::Command
+  module Processing
+    VALUE_METHODS = %i[to_result value success?].freeze
+    private_constant :VALUE_METHODS
+
+    # 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.
+    #
+    # @return [Integer] The number of arguments.
+    def arity
+      method(:process).arity
+    end # method arity
+
+    # @overload call(*arguments, **keywords, &block)
+    #   Executes the command implementation and returns a Cuprum::Result or
+    #   compatible object.
+    #
+    #   Each time #call is invoked, the object performs the following steps:
+    #
+    #   1. Creates a result object, typically an instance of Cuprum::Result.
+    #      The result is assigned to the command as the private #result reader.
+    #   2. The #process method is called, passing the arguments, keywords, and
+    #      block that were passed to #call. The #process method can set errors,
+    #      set the status, or halt the result via the #result reader method.
+    #   3. If #process returns a result, that result is returned by #call.
+    #      Otherwise, the return value of #process is assigned to the #value
+    #      property of the result, and the result is returned by #call.
+    #
+    #   @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 the #process method was
+    #     overriden.
+    def call *args, &block
+      result = build_result(nil, :errors => build_errors)
+
+      process_with_result(result, *args, &block)
+    end # method call
+
+    private
+
+    # @return [Cuprum::Result] The current result. Only available while #process
+    #   is being called.
+    attr_reader :result
+
+    # @!visibility public
+    #
+    # Generates an empty errors object. When the command 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 build_result value, errors:
+      Cuprum::Result.new(value, :errors => errors)
+    end # method build_result
+
+    def merge_results result, other
+      if value_is_result?(other)
+        return result if result == other
+
+        if result.respond_to?(:empty?) && !result.empty?
+          Cuprum.warn(Cuprum::Utils::ResultNotEmptyWarning.new(result).message)
+        end # if
+
+        other.to_result
+      else
+        result.value = other
+
+        result
+      end # if-else
+    end # method merge_results
+
+    # @!visibility public
+    # @overload process(*arguments, **keywords, &block)
+    #   The implementation of the command, 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 process_with_result result, *args, &block
+      @result = result
+      value   = process(*args, &block)
+
+      merge_results(result, value)
+    ensure
+      @result = nil
+    end # method process_with_result
+
+    def value_is_result? value
+      VALUE_METHODS.all? { |method_name| value.respond_to?(method_name) }
+    end # method value
+  end # module
+end # module

data/lib/cuprum/result.rb

@@ -1,11 +1,10 @@
 require 'cuprum'
 
 module Cuprum
-  # Data object that encapsulates the result of calling a Cuprum function or
-  # operation.
+  # Data object that encapsulates the result of calling a Cuprum command.
   class Result
-    # @param value [Object] The value returned by calling the function.
-    # @param errors [Array] The errors (if any) generated when the function was
+    # @param value [Object] The value returned by calling the command.
+    # @param errors [Array] The errors (if any) generated when the command was
     #   called.
     def initialize value = nil, errors: []
       @value  = value
@@ -14,10 +13,10 @@ module Cuprum
       @halted = false
     end # constructor
 
-    # @return [Object] the value returned by calling the function.
+    # @return [Object] the value returned by calling the command.
     attr_accessor :value
 
-    # @return [Array] the errors (if any) generated when the function was
+    # @return [Array] the errors (if any) generated when the command was
     #   called.
     attr_accessor :errors
 
@@ -66,7 +65,7 @@ module Cuprum
       value.nil? && errors.empty? && @status.nil? && !halted?
     end # method empty?
 
-    # Marks the result as a failure, whether or not the function generated any
+    # Marks the result as a failure, whether or not the command generated any
     # errors.
     #
     # @return [Cuprum::Result] The result.
@@ -76,13 +75,13 @@ module Cuprum
       self
     end # method failure!
 
-    # @return [Boolean] false if the function did not generate any errors,
+    # @return [Boolean] false if the command did not generate any errors,
     #   otherwise true.
     def failure?
       @status == :failure || (@status.nil? && !errors.empty?)
     end # method failure?
 
-    # Marks the result as halted. Any subsequent chained functions will not be
+    # Marks the result as halted. Any subsequent chained commands will not be
     #   run.
     #
     # @return [Cuprum::Result] The result.
@@ -92,13 +91,13 @@ module Cuprum
       self
     end # method halt!
 
-    # @return [Boolean] true if the function has been halted, and will not run
-    #   any subsequent chained functions.
+    # @return [Boolean] true if the command has been halted, and will not run
+    #   any subsequent chained commands.
     def halted?
       @halted
     end # method halted?
 
-    # Marks the result as a success, whether or not the function generated any
+    # Marks the result as a success, whether or not the command generated any
     # errors.
     #
     # @return [Cuprum::Result] The result.
@@ -108,12 +107,17 @@ module Cuprum
       self
     end # method success!
 
-    # @return [Boolean] true if the function did not generate any errors,
+    # @return [Boolean] true if the command did not generate any errors,
     #   otherwise false.
     def success?
       @status == :success || (@status.nil? && errors.empty?)
     end # method success?
 
+    # @return [Cuprum::Result] The result.
+    def to_result
+      self
+    end # method to_result
+
     # @api private
     def update other_result
       return self if other_result.nil?

data/lib/cuprum/result_helpers.rb

@@ -0,0 +1,113 @@
+require 'cuprum'
+
+module Cuprum
+  # Helper methods that delegate result methods to the currently processed
+  # result.
+  #
+  # @example
+  #   class LogCommand
+  #     include Cuprum::Processing
+  #     include Cuprum::ResultHelpers
+  #
+  #     private
+  #
+  #     def process log
+  #       case log[:level]
+  #       when 'fatal'
+  #         halt!
+  #
+  #         'error'
+  #       when 'error' && log[:message]
+  #         errors << message
+  #
+  #         'error'
+  #       when 'error'
+  #         failure!
+  #
+  #         'error'
+  #       else
+  #         'ok'
+  #       end # case
+  #     end # method process
+  #   end # class
+  #
+  #   result = LogCommand.new.call(:level => 'info')
+  #   result.success? #=> true
+  #
+  #   string = 'something went wrong'
+  #   result = LogCommand.new.call(:level => 'error', :message => string)
+  #   result.success? #=> false
+  #   result.errors   #=> ['something went wrong']
+  #
+  #   result = LogCommand.new.call(:level => 'error')
+  #   result.success? #=> false
+  #   result.errors   #=> []
+  #
+  #   result = LogCommand.new.call(:level => 'fatal')
+  #   result.halted? #=> true
+  #
+  # @see Cuprum::Command
+  module ResultHelpers
+    private
+
+    # @!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
+    #   command 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
+    #   command 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
+    #   command implementation as defined in the constructor block or the
+    #   #process method.
+    def halt!
+      result&.halt!
+    end # method halt!
+
+    # @!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
+    #   command implementation as defined in the constructor block or the
+    #   #process method.
+    def success!
+      result&.success!
+    end # method success!
+  end # module
+end # module