cuprum 0.7.0 → 0.10.0.rc.0

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/error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Wrapper class for encapsulating an error state for a failed Cuprum result.
+  # Additional details can be passed by setting the #message or by using a
+  # subclass of Cuprum::Error.
+  class Error
+    COMPARABLE_PROPERTIES = %i[message].freeze
+    private_constant :COMPARABLE_PROPERTIES
+
+    # @param message [String] Optional message describing the nature of the
+    #   error.
+    def initialize(message: nil)
+      @message = message
+    end
+
+    # @return [String] Optional message describing the nature of the error.
+    attr_reader :message
+
+    # @param other [Cuprum::Error] The other object to compare.
+    #
+    # @return [Boolean] true if the other object has the same class and message;
+    #   otherwise false.
+    def ==(other)
+      other.instance_of?(self.class) &&
+        comparable_properties.all? { |prop| send(prop) == other.send(prop) }
+    end
+
+    private
+
+    def comparable_properties
+      self.class.const_get(:COMPARABLE_PROPERTIES)
+    end
+  end
+end

data/lib/cuprum/errors.rb

@@ -0,0 +1,6 @@
+require 'cuprum'
+
+module Cuprum
+  # Namespace for custom Cuprum error classes.
+  module Errors; end
+end

data/lib/cuprum/errors/command_not_implemented.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+require 'cuprum/errors'
+
+module Cuprum::Errors
+  # Error class to be used when a Command is called without defining a #process
+  # method.
+  class CommandNotImplemented < Cuprum::Error
+    COMPARABLE_PROPERTIES = %i[command].freeze
+    private_constant :COMPARABLE_PROPERTIES
+
+    # Format for generating error message.
+    MESSAGE_FORMAT = 'no implementation defined for %s'
+
+    # @param command [Cuprum::Command] The command called without a definition.
+    def initialize(command:)
+      @command = command
+
+      class_name = command&.class&.name || 'command'
+      message    = MESSAGE_FORMAT % class_name
+
+      super(message: message)
+    end
+
+    # @return [Cuprum::Command] The command called without a definition.
+    attr_reader :command
+
+    private
+
+    def comparable_properties
+      COMPARABLE_PROPERTIES
+    end
+  end
+end

data/lib/cuprum/errors/operation_not_called.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+require 'cuprum/errors'
+
+module Cuprum::Errors
+  # Error class to be used when trying to access the result of an uncalled
+  # Operation.
+  class OperationNotCalled < Cuprum::Error
+    COMPARABLE_PROPERTIES = %i[operation].freeze
+    private_constant :COMPARABLE_PROPERTIES
+
+    # Format for generating error message.
+    MESSAGE_FORMAT = '%s was not called and does not have a result'
+
+    # @param operation [Cuprum::Operation] The uncalled operation.
+    def initialize(operation:)
+      @operation = operation
+
+      class_name = operation&.class&.name || 'operation'
+      message    = MESSAGE_FORMAT % class_name
+
+      super(message: message)
+    end
+
+    # @return [Cuprum::Operation] The uncalled operation.
+    attr_reader :operation
+
+    private
+
+    def comparable_properties
+      COMPARABLE_PROPERTIES
+    end
+  end
+end

data/lib/cuprum/operation.rb

@@ -1,4 +1,5 @@
 require 'cuprum/command'
+require 'cuprum/errors/operation_not_called'
 
 module Cuprum
   # Functional object with syntactic sugar for tracking the last result.
@@ -45,7 +46,6 @@ 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
@@ -61,12 +61,8 @@ module Cuprum
       #   @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.
-      #
       # @see Cuprum::Command#call
-      def call *args, &block
+      def call *args, **kwargs, &block
         reset! if called? # Clear reference to most recent result.
 
         @result = super
@@ -80,23 +76,18 @@ module Cuprum
         !result.nil?
       end # method called?
 
-      # @return [Array] the errors from the most recent result, or nil if the
-      #   operation has not been called.
-      def errors
-        called? ? result.errors : nil
-      end # method errors
+      # @return [Object] the error (if any) from the most recent result, or nil
+      #   if the operation has not been called.
+      def error
+        called? ? result.error : nil
+      end # method error
 
-      # @return [Boolean] true if the most recent result had errors, or false if
-      #   the most recent result had no errors or if the operation has not been
-      #   called.
+      # @return [Boolean] true if the most recent result had an error, or false
+      #   if the most recent result had no error or if the operation has not
+      #   been called.
       def failure?
         called? ? result.failure? : false
-      end # method success?
-
-      # @return [Boolean] true if the most recent was halted, otherwise false.
-      def halted?
-        called? ? result.halted? : false
-      end # method halted?
+      end # method failure?
 
       # Clears the reference to the most recent call of the operation, if any.
       # This allows the result and any referenced data to be garbage collected.
@@ -110,13 +101,31 @@ module Cuprum
         @result = nil
       end # method reset
 
-      # @return [Boolean] true if the most recent result had no errors, or false
-      #   if the most recent result had errors or if the operation has not been
-      #   called.
+      # @return [Symbol, nil] the status of the most recent result, or nil if
+      #   the operation has not been called.
+      def status
+        called? ? result.status : nil
+      end
+
+      # @return [Boolean] true if the most recent result had no error, or false
+      #   if the most recent result had an error or if the operation has not
+      #   been called.
       def success?
         called? ? result.success? : false
       end # method success?
 
+      # Returns the most result if the operation was previously called.
+      # Otherwise, returns a failing result.
+      #
+      # @return [Cuprum::Result] the most recent result or failing result.
+      def to_cuprum_result
+        return result if result
+
+        error = Cuprum::Errors::OperationNotCalled.new(operation: self)
+
+        Cuprum::Result.new(error: error)
+      end
+
       # @return [Object] the value of the most recent result, or nil if the
       #   operation has not been called.
       def value
@@ -131,15 +140,12 @@ module Cuprum
     # @!method called?
     #   (see Cuprum::Operation::Mixin#called?)
 
-    # @!method errors
-    #   (see Cuprum::Operation::Mixin#errors)
+    # @!method error
+    #   (see Cuprum::Operation::Mixin#error)
 
     # @!method failure?
     #   (see Cuprum::Operation::Mixin#failure?)
 
-    # @!method halted?
-    #   (see Cuprum::Operation::Mixin#halted?)
-
     # @!method reset!
     #   (see Cuprum::Operation::Mixin#reset!)
 
@@ -149,6 +155,9 @@ module Cuprum
     # @!method success?
     #   (see Cuprum::Operation::Mixin#success?)
 
+    # @!method to_cuprum_result
+    #   (see Cuprum::Operation::Mixin#to_cuprum_result?)
+
     # @!method value
     #   (see Cuprum::Operation::Mixin#value)
   end # class

data/lib/cuprum/processing.rb

@@ -1,5 +1,7 @@
-require 'cuprum/not_implemented_error'
-require 'cuprum/utils/result_not_empty_warning'
+# 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
@@ -12,14 +14,14 @@ module Cuprum
   #
   #     def initialize addend
   #       @addend = addend
-  #     end # constructor
+  #     end
   #
   #     private
   #
   #     def process int
   #       int + addend
-  #     end # method process
-  #   end # class AdderCommand
+  #     end
+  #   end
   #
   #   adder  = AdderCommand.new(2)
   #   result = adder.call(3)
@@ -35,31 +37,28 @@ module Cuprum
   #
   #     def process value
   #       if value.negative?
-  #         result.errors << 'value cannot be negative'
-  #
-  #         return nil
-  #       end # if
+  #         return Cuprum::Result.new(error: 'value cannot be negative')
+  #       end
   #
   #       Math.sqrt(value)
-  #     end # method process
-  #   end # class
+  #     end
+  #   end
   #
   #   result = SquareRootCommand.new.call(2)
   #   result.value    #=> 1.414
   #   result.success? #=> true
   #   result.failure? #=> false
-  #   result.errors   #=> []
+  #   result.error    #=> nil
   #
   #   result = SquareRootCommand.new.call(-1)
   #   result.value    #=> nil
   #   result.success? #=> false
   #   result.failure? #=> true
-  #   result.errors   #=> ['value cannot be negative']
+  #   result.error    #=> 'value cannot be negative'
   #
   # @see Cuprum::Command
   module Processing
-    VALUE_METHODS = %i[to_result value success?].freeze
-    private_constant :VALUE_METHODS
+    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
@@ -68,7 +67,7 @@ module Cuprum
     # @return [Integer] The number of arguments.
     def arity
       method(:process).arity
-    end # method arity
+    end
 
     # @overload call(*arguments, **keywords, &block)
     #   Executes the command implementation and returns a Cuprum::Result or
@@ -76,14 +75,12 @@ module Cuprum
     #
     #   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.
+    #   1. The #process method is called, passing the arguments, keywords, and
+    #      block that were passed to #call.
+    #   2. If the value returned by #process is a Cuprum::Result or compatible
+    #      object, that result is directly returned by #call.
+    #   3. Otherwise, the value returned by #process will be wrapped in a
+    #      successful result, which will be returned by #call.
     #
     #   @param arguments [Array] Arguments to be passed to the implementation.
     #
@@ -93,57 +90,28 @@ module Cuprum
     #
     #   @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
+    def call(*args, **kwargs, &block)
+      value =
+        if kwargs.empty?
+          process(*args, &block)
+        else
+          process(*args, **kwargs, &block)
+        end
 
-    # @!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
+      return value.to_cuprum_result if value_is_result?(value)
 
-    def build_result value, errors:
-      Cuprum::Result.new(value, :errors => errors)
-    end # method build_result
+      build_result(value: value)
+    end
 
-    def merge_results result, other
-      if value_is_result?(other)
-        return result if result == other
-
-        warn_unless_empty!(result)
-
-        other.to_result
-      else
-        result.value = other
-
-        result
-      end # if-else
-    end # method merge_results
+    private
 
     # @!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.
+    #   is called. If #process returns a result, that result will be returned by
+    #   #call; otherwise, the value returned by #process will be wrapped in a
+    #   successful Cuprum::Result object. This method should not be called
+    #   directly.
     #
     #   @param arguments [Array] The arguments, if any, passed from #call.
     #
@@ -153,34 +121,15 @@ module Cuprum
     #
     #   @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
-
-    def warn_unless_empty! result
-      return unless result.respond_to?(:empty?) && !result.empty?
+    def process(*_args)
+      error = Cuprum::Errors::CommandNotImplemented.new(command: self)
 
-      not_empty = Cuprum::Utils::ResultNotEmptyWarning.new(result)
+      build_result(error: error)
+    end
 
-      Cuprum.warn(not_empty.message) if not_empty.warning?
-    end # method warn_unless_empty!
-  end # module
-end # module
+    def value_is_result?(value)
+      value.respond_to?(:to_cuprum_result)
+    end
+  end
+end