cuprum 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '0797c743296d8ae77c0cebf8db95ed48bb7701ac'
-  data.tar.gz: 78eef973b33c1ae167ac74f7e04169142ef69e45
+  metadata.gz: 4420d672d1c4560ed615b9d40100423cffba35bc
+  data.tar.gz: 76697dbef40ba29900b3cfc53716f244f8c007c5
 SHA512:
-  metadata.gz: 356d580bea16226d831453bcb98cfe32bc6d38b264b53c6935cb91adccfc9f627ed416269374c42dc513187d34add5aa5a3298cfc8b4ef897dd785a58436bfdb
-  data.tar.gz: 0e181b037184bdd6e0ea774cc1861cea9997ba6d01bee5cba4b92e99ce5348d9a1b66f536b634e91269cc9dfc4a4b0c68172d7be76f32f33ff663d65eef008a9
+  metadata.gz: 5e9afc3c3bb45b356098825bb077e7d1e0764cec2b1bc1e75e8fb1ea334f3707041b187fadc69ddbb556135f03d8b474d417615620c71b89048d19436d8e532a
+  data.tar.gz: 69acd4b378b7828f656d53e5293ea01bf6a174f2247cabfde5e3b86400c121e6f7026f60985a3ffd5c8b2ae5eb94728295f3b32e563c7c1afac9c5e0c416a97b

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.5.0
+
+The "Name Not Found For NullFunction" Update.
+
+Added the `Cuprum::warn` helper, which prints a warning message. By default, `::warn` delegates to `Kernel#warn`, but can be configured (e.g. to call a Logger) by setting `Cuprum::warning_proc=` with a Proc that accepts one argument (the message to display).
+
+## Operations
+
+The implementation of `Cuprum::Operation` has been extracted to a module at `Cuprum::Operation::Mixin`, allowing users to easily convert an existing function class or instance to an operation.
+
+## Results
+
+Implemented `Cuprum::Result#==` as a fuzzy comparison, allowing a result to be equal to any object with the same value and status.
+
+Implemented `Cuprum::Result#empty?`, which returns true for a new result and false for a result with a value, with non-empty errors, a result with set status, or a halted result.
+
+## Utilities
+
+Added the `Cuprum::Utils::InstanceSpy` module to empower testing of code that calls a function without providing a reference, such as some chained functions.
+
+## Built In Functions
+
+Added the `NullFunction` and `NullOperation` predefined classes, which do nothing when called and return a result with no errors and a value of nil.
+
+Added the `IdentityFunction` and `IdentityOperation` predefined classes, which return the value or result which which they were called.
+
 ## 0.4.0
 
 The "Halt And Catch Fire" Update.

data/DEVELOPMENT.md

@@ -1,13 +1,18 @@
 # Development
 
+- Rename Cuprum::Function to Cuprum::Command.
+- Extract Cuprum::BasicCommand (excludes chaining functionality).
+
+## Core
+
 ## Function
 
-- #build_errors method
 - Predefined functions/operations:
-  - NullFunction
   - IdentityFunction
   - MapFunction
   - RetryFunction
+- allow_result_argument? - defaults to false. if false, there is one argument,
+  and the argument is a Result, process the value instead.
 
 ## Operation
 
@@ -28,3 +33,5 @@ Chaining Case Study: |
   Create Content
   Create ContentVersion
   Tags.each { FindOrCreate Tag }
+
+## Testing

data/README.md

@@ -25,6 +25,8 @@ Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use thes
 
 ## Functions
 
+    require 'cuprum/function'
+
 [Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FFunction)
 
 Functions are the core feature of Cuprum. In a nutshell, each Cuprum::Function is a functional object that encapsulates a business logic operation. A Function provides a consistent interface and tracking of result value and status. This minimizes boilerplate and allows for interchangeability between different implementations or strategies for managing your data and processes.
@@ -323,6 +325,8 @@ If the `#halt` method is called as part of a Function block or `#process` method
 
 ## Operations
 
+    require 'cuprum/operation'
+
 [Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
 
 An Operation is like a Function, 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 `Cuprum::Result` in any code that expects or returns a result. Second, the `#call` method returns the operation instance, rather than the result itself.
@@ -379,6 +383,12 @@ Clears the most recent result and resets `#called?` to false. This frees the res
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#reset!-instance_method)
 
+### The Operation Mixin
+
+[Module Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation%2FMixin)
+
+The implementation of `Cuprum::Operation` is defined by the `Cuprum::Operation::Mixin` module, which provides the methods defined above. Any function class or instance can be converted to an operation by including (for a class) or extending (for an instance) the operation mixin.
+
 ## Results
 
 [Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FResult)
@@ -426,3 +436,131 @@ True if the function did not generate any errors, otherwise false.
 True if the function generated one or more errors, otherwise false.
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure%3F-instance_method)
+
+#### `#==`
+
+    ==(other) #=> true, false
+
+Performs a fuzzy comparison with the other object. At a minimum, the other object must respond to `#value` and `#success?`, and the values of `other.value` and `other.success?` must be equal to the corresponding value on the result. In addition, if the `#failure?`, `#errors`, or `#halted?` methods are defined on the other object, then the value of each defined method is compared to the value on the result. Returns true if all values match, otherwise returns false.
+
+#### `#empty?`
+
+    empty?() #=> true, false
+
+Helper method that returns true for a new result. The method returns false if `result.value` is not nil, if `result.errors` is not empty, if the status has been manually set with `#success!` or `#failure!`, or if the result has been halted.
+
+## Utilities
+
+Cuprum provides these utility modules to grant additional functionality under specific circumstances.
+
+### InstanceSpy
+
+    require 'cuprum/utils/instance_spy'
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FUtils%2FInstanceSpy)
+
+Utility module for instrumenting calls to the #call method of any instance of a function class. This can be used to unobtrusively test the functionality of code that calls a function without providing a reference to the function instance, such as chained functions or methods that create and call a function instance.
+
+#### `::spy_on`
+
+    spy_on(function_class) #=> InstanceSpy
+    spy_on(function_class) { |spy| ... } #=> nil
+
+Finds or creates a spy object for the given module or class. Each time that the #call method is called for an object of the given type, the spy's #call method will be invoked with the same arguments and block. If `#spy_on` is called with a block, the instance spy will be yielded to the block; otherwise, the spy will be returned.
+
+    # Observing calls to instances of a function.
+    spy = Cuprum::Utils::InstanceSpy.spy_on(CustomFunction)
+
+    expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
+
+    CustomFunction.new.call(1, 2, 3, :four => '4')
+
+    # Observing calls to a chained function.
+    spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedFunction)
+
+    expect(spy).to receive(:call)
+
+    Cuprum::Function.new {}.
+      chain { |result| ChainedFunction.new.call(result) }.
+      call
+
+    # Block syntax
+    Cuprum::Utils::InstanceSpy.spy_on(CustomFunction) do |spy|
+      expect(spy).to receive(:call)
+
+      CustomFunction.new.call
+    end # spy_on
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#spy_on%3F-instance_method)
+
+#### `::clear_spies`
+
+    clear_spies() #=> nil
+
+Retires all spies. Subsequent calls to the #call method on function instances will not be mirrored to existing spy objects. Calling this method after each test or example that uses an instance spy is recommended.
+
+    after(:example) { Cuprum::Utils::InstanceSpy.clear_spies }
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#clear_spies%3F-instance_method)
+
+## Built In Functions
+
+Cuprum includes a small number of predefined functions and their equivalent operations.
+
+### IdentityFunction
+
+    require 'cuprum/built_in/identity_function'
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityFunction)
+
+A pregenerated function that returns the value or result with which it was called.
+
+    function = Cuprum::BuiltIn::IdentityFunction.new
+    result   = function.call('expected value')
+    result.value
+    #=> 'expected value'
+    result.success?
+    #=> true
+
+### IdentityOperation
+
+    require 'cuprum/built_in/identity_operation'
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityOperation)
+
+A pregenerated operation that sets its result to the value or result with which it was called.
+
+    operation = Cuprum::BuiltIn::IdentityFunction.new.call('expected value')
+    operation.value
+    #=> 'expected value'
+    operation.success?
+    #=> true
+
+### NullFunction
+
+    require 'cuprum/built_in/null_function'
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullFunction)
+
+A pregenerated function that does nothing when called.
+
+    function = Cuprum::BuiltIn::NullFunction.new
+    result   = function.call
+    result.value
+    #=> nil
+    result.success?
+    #=> true
+
+### NullOperation
+
+    require 'cuprum/built_in/null_operation'
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullFunction)
+
+A pregenerated operation that does nothing when called.
+
+    operation = Cuprum::BuiltIn::NullOperation.new.call
+    operation.value
+    #=> nil
+    operation.success?
+    #=> true

data/lib/cuprum.rb

@@ -5,8 +5,35 @@ module Cuprum
   autoload :Operation, 'cuprum/operation'
   autoload :Result,    'cuprum/result'
 
-  # @return [String] The current version of the gem.
-  def self.version
-    VERSION
-  end # class method version
+  DEFAULT_WARNING_PROC = ->(message) { Kernel.warn message }
+  private_constant :DEFAULT_WARNING_PROC
+
+  class << self
+    # @return [Proc] The proc called to display a warning message. By default,
+    #   delegates to Kernel#warn. Set this to configure the warning behavior
+    #   (e.g. to call a Logger).
+    attr_writer :warning_proc
+
+    # @return [String] The current version of the gem.
+    def version
+      VERSION
+    end # method version
+
+    # Displays a warning message. By default, delegates to Kernel#warn. The
+    # warning behavior can be configured (e.g. to call a Logger) using the
+    # #warning_proc= method.
+    #
+    # @param message [String] The warning message to display.
+    #
+    # @see #warning_proc=
+    def warn message
+      warning_proc.call(message)
+    end # method warn
+
+    private
+
+    def warning_proc
+      @warning_proc ||= DEFAULT_WARNING_PROC
+    end # method warning_proc
+  end # eigenclass
 end # module

data/lib/cuprum/built_in.rb

@@ -0,0 +1,6 @@
+require 'cuprum'
+
+module Cuprum
+  # Namespace for predefined function and operation classes.
+  module BuiltIn; end
+end # module

data/lib/cuprum/built_in/identity_function.rb

@@ -0,0 +1,31 @@
+require 'cuprum/built_in'
+require 'cuprum/function'
+
+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.value
+  #   #=> 'custom value'
+  #   result.success?
+  #   #=> true
+  #
+  # @example With a result.
+  #   errors = ['errors.messages.unknown']
+  #   value  = Cuprum::Result.new('result value', :errors => errors)
+  #   result = IdentityFunction.new.call(value)
+  #   result.value
+  #   #=> 'result value'
+  #   result.success?
+  #   #=> false
+  #   result.errors
+  #   #=> ['errors.messages.unknown']
+  class IdentityFunction < Cuprum::Function
+    private
+
+    def process value = nil
+      value
+    end # method process
+  end # class
+end # module

data/lib/cuprum/built_in/identity_operation.rb

@@ -0,0 +1,27 @@
+require 'cuprum/built_in/identity_function'
+require 'cuprum/operation'
+
+module Cuprum::BuiltIn
+  # A predefined operation that returns the value or result it was called with.
+  #
+  # @example With a value.
+  #   operation = IdentityOperation.new.call('custom value')
+  #   operation.value
+  #   #=> 'custom value'
+  #   operation.success?
+  #   #=> true
+  #
+  # @example With a result.
+  #   errors    = ['errors.messages.unknown']
+  #   value     = Cuprum::Result.new('result value', :errors => errors)
+  #   operation = IdentityOperation.new.call(value)
+  #   operation.value
+  #   #=> 'result value'
+  #   operation.success?
+  #   #=> false
+  #   operation.errors
+  #   #=> ['errors.messages.unknown']
+  class IdentityOperation < Cuprum::BuiltIn::IdentityFunction
+    include Cuprum::Operation::Mixin
+  end # class
+end # module

data/lib/cuprum/built_in/null_function.rb

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

data/lib/cuprum/built_in/null_operation.rb

@@ -0,0 +1,16 @@
+require 'cuprum/built_in/null_function'
+require 'cuprum/operation'
+
+module Cuprum::BuiltIn
+  # A predefined operation that does nothing when called.
+  #
+  # @example
+  #   operation = NullOperation.new.call
+  #   operation.value
+  #   #=> nil
+  #   operation.success?
+  #   #=> true
+  class NullOperation < Cuprum::BuiltIn::NullFunction
+    include Cuprum::Operation::Mixin
+  end # class
+end # module

data/lib/cuprum/function.rb

@@ -104,7 +104,7 @@ module Cuprum
   #
   #   result = collatz_function.new(16)
   #   result.value #=> 8
-  class Function
+  class Function # rubocop:disable Metrics/ClassLength
     # Error class for calling a Function that was not given a definition block
     # or have a #process method defined.
     class NotImplementedError < StandardError
@@ -146,13 +146,9 @@ module Cuprum
     #     subclass.
     def call *args, &block
       call_chained_functions do
-        Cuprum::Result.new(:errors => build_errors).tap do |result|
-          @result = result
-
+        wrap_result do |result|
           merge_results(result, process(*args, &block))
-
-          @result = nil
-        end # tap
+        end # method wrap_result
       end # call_chained_functions
     end # method call
 
@@ -195,9 +191,9 @@ module Cuprum
     #
     # @return [Cuprum::Function] The chained function.
     def chain function = nil, on: nil, &block
-      proc = convert_function_or_proc_to_proc(block || function)
-
-      chain_function(proc, :on => on)
+      clone.tap do |fn|
+        fn.chained_functions << build_chain_link(block || function, :on => on)
+      end # tap
     end # method chain
 
     # Shorthand for function.chain(:on => :failure). Registers a function or
@@ -218,9 +214,7 @@ module Cuprum
     #
     # @see #chain
     def else function = nil, &block
-      proc = convert_function_or_proc_to_proc(block || function)
-
-      chain_function(proc, :on => :failure)
+      chain(function, :on => :failure, &block)
     end # method else
 
     # Shorthand for function.chain(:on => :success). Registers a function or
@@ -241,28 +235,24 @@ module Cuprum
     #
     # @see #chain
     def then function = nil, &block
-      proc = convert_function_or_proc_to_proc(block || function)
-
-      chain_function(proc, :on => :success)
+      chain(function, :on => :success, &block)
     end # method then
 
     protected
 
-    def chain_function proc, on: nil
-      hsh = { :proc => proc }
-      hsh[:on] = on if on
-
-      clone.tap do |fn|
-        fn.chained_functions << hsh
-      end # tap
-    end # method chain_function
-
     def chained_functions
       @chained_functions ||= []
     end # method chained_functions
 
     private
 
+    def build_chain_link function_or_proc, on: nil
+      {
+        :proc => convert_function_or_proc_to_proc(function_or_proc),
+        :on   => on
+      } # end hash
+    end # method build_chain_link
+
     # @!visibility public
     #
     # Generates an empty errors object. When the function is called, the result
@@ -337,22 +327,28 @@ module Cuprum
       @result&.halt!
     end # method halt!
 
-    def merge_errors result, other
-      return unless other.respond_to?(:errors)
+    # :nocov:
+    def humanize_list list, empty_value: ''
+      return empty_value if list.size.zero?
+
+      return list.first.to_s if list.size == 1
 
-      result.errors += other.errors
-    end # method merge_errors
+      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)
-        result.value = other.value
+        Cuprum.warn(result_not_empty_warning) unless result.empty?
 
-        merge_errors(result, other)
+        convert_value_to_result(other)
       else
         result.value = other
-      end # if-else
 
-      result
+        result
+      end # if-else
     end # method merge_results
 
     # @!visibility public
@@ -377,6 +373,29 @@ module Cuprum
       raise 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
+
     def skip_chained_function? last_result, on:
       return false if on == :always
 
@@ -408,5 +427,21 @@ module Cuprum
     def value_is_result? value
       value.respond_to?(:value) && value.respond_to?(:success?)
     end # method value
+
+    def wrap_result
+      value = nil
+
+      Cuprum::Result.new(:errors => build_errors).tap do |result|
+        begin
+          @result = result
+
+          value = yield result
+        ensure
+          @result = nil
+        end # begin-ensure
+      end # tap
+
+      value
+    end # method wrap_result
   end # class
 end # module

data/lib/cuprum/operation.rb

@@ -34,84 +34,121 @@ module Cuprum
   #
   # @see Cuprum::Function
   class Operation < Cuprum::Function
-    # @return [Cuprum::Result] The result from the most recent call of the
-    #   operation.
-    attr_reader :result
-
-    # @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 the
-    #   operation object.
+    # Module-based implementation of the Operation methods. Use this to convert
+    # an already-defined function into an operation.
     #
-    #   @param arguments [Array] Arguments to be passed to the implementation.
-    #
-    #   @param keywords [Hash] Keywords to be passed to the implementation.
-    #
-    #   @return [Cuprum::Operation] the called operation.
-    #
-    #   @yield If a block argument is given, it will be passed to the
-    #     implementation.
-    #
-    #   @raise [NotImplementedError] Unless a block was passed to the
-    #     constructor or the #process method was overriden by a Function
-    #     subclass.
-    #
-    # @see Cuprum::Function#call
-    def call *args, &block
-      reset! if called? # Clear reference to most recent result.
-
-      @result = super
-
-      self
-    end # method call
-
-    # @return [Boolean] true if the operation has been called and has a
-    #   reference to the most recent result; otherwise false.
-    def called?
-      !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
-      super || (called? ? result.errors : nil)
-    end # method errors
-
-    # @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.
-    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?
-
-    # 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.
-    # Use this method to clear any instance variables or state internal to the
-    # operation (an operation should never have external state apart from the
-    # last result).
-    #
-    # If the operation cannot be run more than once, this method should raise an
-    # error.
-    def reset!
-      @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.
-    def success?
-      called? ? result.success? : false
-    end # method success?
-
-    # @return [Object] the value of the most recent result, or nil if the
-    #   operation has not been called.
-    def value
-      called? ? result.value : nil
-    end # method value
+    # @example
+    #   class CustomOperation < CustomFunction
+    #     include Cuprum::Operation::Mixin
+    #   end # class
+    module Mixin
+      # @return [Cuprum::Result] The result from the most recent call of the
+      #   operation.
+      attr_reader :result
+
+      # @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 the
+      #   operation object.
+      #
+      #   @param arguments [Array] Arguments to be passed to the implementation.
+      #
+      #   @param keywords [Hash] Keywords to be passed to the implementation.
+      #
+      #   @return [Cuprum::Operation] the called operation.
+      #
+      #   @yield If a block argument is given, it will be passed to the
+      #     implementation.
+      #
+      #   @raise [NotImplementedError] Unless a block was passed to the
+      #     constructor or the #process method was overriden by a Function
+      #     subclass.
+      #
+      # @see Cuprum::Function#call
+      def call *args, &block
+        reset! if called? # Clear reference to most recent result.
+
+        @result = super
+
+        self
+      end # method call
+
+      # @return [Boolean] true if the operation has been called and has a
+      #   reference to the most recent result; otherwise false.
+      def called?
+        !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
+        super || (called? ? result.errors : nil)
+      end # method errors
+
+      # @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.
+      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?
+
+      # 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.
+      # Use this method to clear any instance variables or state internal to the
+      # operation (an operation should never have external state apart from the
+      # last result).
+      #
+      # If the operation cannot be run more than once, this method should raise
+      # an error.
+      def reset!
+        @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.
+      def success?
+        called? ? result.success? : false
+      end # method success?
+
+      # @return [Object] the value of the most recent result, or nil if the
+      #   operation has not been called.
+      def value
+        called? ? result.value : nil
+      end # method value
+    end # module
+    include Mixin
+
+    # @!method call
+    #   (see Cuprum::Operation::Mixin#call)
+
+    # @!method called?
+    #   (see Cuprum::Operation::Mixin#called?)
+
+    # @!method errors
+    #   (see Cuprum::Operation::Mixin#errors)
+
+    # @!method failure?
+    #   (see Cuprum::Operation::Mixin#failure?)
+
+    # @!method halted?
+    #   (see Cuprum::Operation::Mixin#halted?)
+
+    # @!method reset!
+    #   (see Cuprum::Operation::Mixin#reset!)
+
+    # @!method result
+    #   (see Cuprum::Operation::Mixin#result)
+
+    # @!method success?
+    #   (see Cuprum::Operation::Mixin#success?)
+
+    # @!method value
+    #   (see Cuprum::Operation::Mixin#value)
   end # class
 end # module

data/lib/cuprum/result.rb

@@ -21,6 +21,51 @@ module Cuprum
     #   called.
     attr_accessor :errors
 
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/PerceivedComplexity
+
+    # Compares the other object to the result.
+    #
+    # @param other [#value, #success?] An object responding to, at minimum,
+    #   #value and #success?. If present, the #failure?, #errors and #halted?
+    #   values will also be compared.
+    #
+    # @return [Boolean] True if all present values match the result, otherwise
+    #   false.
+    def == other
+      return false unless other.respond_to?(:value) && other.value == value
+
+      unless other.respond_to?(:success?) && other.success? == success?
+        return false
+      end # unless
+
+      if other.respond_to?(:failure?) && other.failure? != failure?
+        return false
+      end # if
+
+      if other.respond_to?(:errors) && other.errors != errors
+        return false
+      end # if
+
+      if other.respond_to?(:halted?) && other.halted? != halted?
+        return false
+      end # if
+
+      true
+    end # method ==
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/PerceivedComplexity
+
+    # @return [Boolean] true if the result is empty, i.e. has no value or errors
+    #   and does not have its status set or is halted.
+    def empty?
+      value.nil? && errors.empty? && @status.nil? && !halted?
+    end # method empty?
+
     # Marks the result as a failure, whether or not the function generated any
     # errors.
     #
@@ -68,5 +113,38 @@ module Cuprum
     def success?
       @status == :success || (@status.nil? && errors.empty?)
     end # method success?
+
+    # @api private
+    def update other_result
+      return self if other_result.nil?
+
+      self.value = other_result.value
+
+      update_status(other_result)
+
+      update_errors(other_result)
+
+      halt! if other_result.halted?
+
+      self
+    end # method update
+
+    protected
+
+    attr_reader :status
+
+    private
+
+    def update_errors other_result
+      return if other_result.errors.empty?
+
+      @errors += other_result.errors
+    end # method update_errors
+
+    def update_status other_result
+      return if status || !errors.empty?
+
+      @status = other_result.status
+    end # method update_status
   end # class
 end # module

data/lib/cuprum/utils.rb

@@ -0,0 +1,6 @@
+require 'cuprum'
+
+module Cuprum
+  # Namespace for utility modules.
+  module Utils; end
+end # module

data/lib/cuprum/utils/instance_spy.rb

@@ -0,0 +1,139 @@
+require 'cuprum/built_in/null_function'
+require 'cuprum/utils'
+
+module Cuprum::Utils
+  # Utility module for instrumenting calls to the #call method of any instance
+  # of a function class. This can be used to unobtrusively test the
+  # functionality of code that calls a function without providing a reference to
+  # the function instance, such as chained functions or methods that create and
+  # call a function instance.
+  #
+  # @example Observing calls to instances of a function.
+  #   spy = Cuprum::Utils::InstanceSpy.spy_on(CustomFunction)
+  #
+  #   expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
+  #
+  #   CustomFunction.new.call(1, 2, 3, :four => '4')
+  #
+  # @example Observing calls to a chained function.
+  #   spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedFunction)
+  #
+  #   expect(spy).to receive(:call)
+  #
+  #   Cuprum::Function.new {}.
+  #     chain { |result| ChainedFunction.new.call(result) }.
+  #     call
+  #
+  # @example Block syntax
+  #   Cuprum::Utils::InstanceSpy.spy_on(CustomFunction) do |spy|
+  #     expect(spy).to receive(:call)
+  #
+  #     CustomFunction.new.call
+  #   end # spy_on
+  module InstanceSpy
+    # Minimal class that implements a #call method to mirror method calls to
+    # instances of an instrumented function class.
+    class Spy
+      # Empty method that accepts any arguments and an optional block.
+      def call *_args, █ end
+    end # class
+
+    class << self
+      # Retires all spies. Subsequent calls to the #call method on function
+      # instances will not be mirrored to existing spy objects.
+      def clear_spies
+        Thread.current[:cuprum_instance_spies] = nil
+
+        nil
+      end # method clear_spies
+
+      # Finds or creates a spy object for the given module or class. Each time
+      # that the #call method is called for an object of the given type, the
+      # spy's #call method will be invoked with the same arguments and block.
+      #
+      # @param function_class [Class, Module] The type of function to spy on.
+      #   Must be either a Module, or a Class that extends Cuprum::Function.
+      #
+      # @raise [ArgumentError] If the argument is neither a Module nor a Class
+      #   that extends Cuprum::Function.
+      #
+      # @note Calling this method for the first time will prepend the
+      #   Cuprum::Utils::InstanceSpy module to Cuprum::Function.
+      #
+      # @overload spy_on(function_class)
+      #   @return [Cuprum::Utils::InstanceSpy::Spy] The instance spy.
+      #
+      # @overload spy_on(function_class, &block)
+      #   Yields the instance spy to the block, and returns nil.
+      #
+      #   @yield [Cuprum::Utils::InstanceSpy::Spy] The instance spy.
+      #
+      #   @return [nil] nil.
+      def spy_on function_class
+        guard_spy_class!(function_class)
+
+        instrument_call!
+
+        if block_given?
+          begin
+            instance_spy = assign_spy(function_class)
+
+            yield instance_spy
+          end # begin-ensure
+        else
+          assign_spy(function_class)
+        end # if-else
+      end # method spy_on
+
+      private
+
+      def assign_spy function_class
+        existing_spy = spies[function_class]
+
+        return existing_spy if existing_spy
+
+        spies[function_class] = build_spy
+      end # method assign_spy
+
+      def build_spy
+        Cuprum::Utils::InstanceSpy::Spy.new
+      end # method build_spy
+
+      def call_spies_for function, *args, &block
+        spies_for(function).each { |spy| spy.call(*args, &block) }
+      end # method call_spies_for
+
+      def guard_spy_class! function_class
+        return if function_class.is_a?(Module) && !function_class.is_a?(Class)
+
+        return if function_class.is_a?(Class) &&
+                  function_class <= Cuprum::Function
+
+        raise ArgumentError,
+          'must be a class inheriting from Cuprum::Function',
+          caller(1..-1)
+      end # method guard_spy_class!
+
+      def instrument_call!
+        return if Cuprum::Function < Cuprum::Utils::InstanceSpy
+
+        Cuprum::Function.prepend(Cuprum::Utils::InstanceSpy)
+      end # method instrument_call!
+
+      def spies
+        Thread.current[:cuprum_instance_spies] ||= {}
+      end # method spies
+
+      def spies_for function
+        spies.select { |mod, _| function.is_a?(mod) }.map { |_, spy| spy }
+      end # method spies_for
+    end # eigenclass
+
+    # (see Cuprum::Function#call)
+    def call *args, &block
+      Cuprum::Utils::InstanceSpy.send(:call_spies_for, self, *args, &block)
+
+      super
+    end # method call
+  end # module
+end # module

data/lib/cuprum/version.rb

@@ -8,7 +8,7 @@ module Cuprum
     # Major version.
     MAJOR = 0
     # Minor version.
-    MINOR = 4
+    MINOR = 5
     # Patch version.
     PATCH = 0
     # Prerelease version.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-04 00:00:00.000000000 Z
+date: 2017-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -93,9 +93,16 @@ files:
 - LICENSE
 - README.md
 - lib/cuprum.rb
+- lib/cuprum/built_in.rb
+- lib/cuprum/built_in/identity_function.rb
+- lib/cuprum/built_in/identity_operation.rb
+- lib/cuprum/built_in/null_function.rb
+- lib/cuprum/built_in/null_operation.rb
 - lib/cuprum/function.rb
 - lib/cuprum/operation.rb
 - lib/cuprum/result.rb
+- lib/cuprum/utils.rb
+- lib/cuprum/utils/instance_spy.rb
 - lib/cuprum/version.rb
 homepage: http://sleepingkingstudios.com
 licenses: