cuprum 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4420d672d1c4560ed615b9d40100423cffba35bc
-  data.tar.gz: 76697dbef40ba29900b3cfc53716f244f8c007c5
+  metadata.gz: 6c749e3c0c387227604f9ca4be639d3cabf06dcc
+  data.tar.gz: 779b36680827fb53d901fbe44436e679cf703cfd
 SHA512:
-  metadata.gz: 5e9afc3c3bb45b356098825bb077e7d1e0764cec2b1bc1e75e8fb1ea334f3707041b187fadc69ddbb556135f03d8b474d417615620c71b89048d19436d8e532a
-  data.tar.gz: 69acd4b378b7828f656d53e5293ea01bf6a174f2247cabfde5e3b86400c121e6f7026f60985a3ffd5c8b2ae5eb94728295f3b32e563c7c1afac9c5e0c416a97b
+  metadata.gz: 95cb4d600263513ef199f4c578f45569eb62052fcd9806fe3f8195ee707fa8fddbaf3704b136192e66186751febefac90050deb51cfaeb502c39eecc75817ea4
+  data.tar.gz: c4571461ea2b47e78598fa46ae21273d439ea8c3b06bb1129b54135850197d5fbc80dc583547464b4d1fcbef89333dc1a042d3aba9c5323887c8abcedef6b05b

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.6.0
+
+The "By Your Command" Update.
+
+### Commands
+
+Refactored `Cuprum::Function` to `Cuprum::Command` to better reflect its role as an implementation of the Command pattern.
+
+Extracted `Cuprum::BasicCommand` as a base class for all commands, implementing `#call` and its associated methods but not including methods or functionality related to command chains.
+
+Extracted the `Cuprum::Chaining` mixin, which encapsulates all of the methods and functionality necessary to implement command chaining.
+
+### Built In Commands
+
+Refactored `Cuprum::BuiltIn::IdentityFunction` to `Cuprum::BuiltIn::IdentityCommand`.
+
+Refactored `Cuprum::BuiltIn::NullFunction` to `Cuprum::BuiltIn::NullCommand`.
+
 ## 0.5.0
 
 The "Name Not Found For NullFunction" Update.

data/DEVELOPMENT.md

@@ -1,18 +1,52 @@
 # Development
 
-- Rename Cuprum::Function to Cuprum::Command.
-- Extract Cuprum::BasicCommand (excludes chaining functionality).
+- Update documentation.
 
 ## Core
 
-## Function
+## Command
 
-- Predefined functions/operations:
-  - 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.
+- Chaining Methods:
+  - #chain:
+    - with a command, sets the command's #result to the last result and calls
+      #process with the last result's #value; returns result of calling chained
+      command.
+    - with a block creates anonymous command, then see above
+    - if the command does not accept any arguments (or keywords if #value is a
+      Hash), does not pass #value. Requires #arity, #apply_chained?
+    - one argument (on), values nil (default), :success, :failure, :always
+  - #success - as chain(:success)
+  - #failure - as chain(:failure)
+  - #tap_result:
+    - block form only, block is yielded and returns the last result
+    - same argument as #chain
+  - #yield_result:
+    - block form only, block is yielded the last result, returns the return
+      value of the block (wrapped in a result if needed)
+    - same argument as #chain
+- Protected Chaining Methods:
+  - #chain!, #success!, #failure!, #tap_chain!, #yield_result!
+  - adds chained command to current command instead of a clone.
+- private #build_result
+
+### Built In
+
+- MapCommand - wraps a command (or proc) and returns Result with value, errors
+  as array
+- RetryCommand
+
+### DSL
+
+- class-level methods
+  - ::chain (::success, ::failure):
+    on #initialize, chains the given command. Can be given a command class
+    (if ::new takes no arguments) or a block that returns a command.
+  - ::process - shortcut for defining #process
+  - ::rescue - `rescue StandardError do ... end`, rescues matched errors in #process
+
+### Hooks
+
+- :before, :around, :after hooks
 
 ## Operation
 

data/README.md

@@ -1,441 +1,644 @@
 # Cuprum
 
-A lightweight, functional-lite toolkit for making business logic a first-class
-citizen of your application.
+An opinionated implementation of the Command pattern for Ruby applications. Cuprum wraps your business logic in a consistent, object-oriented interface and features status and error management, composability and control flow management.
 
-## Support
+It defines the following concepts:
 
-Cuprum is tested against Ruby 2.4.
+- [Commands](#label-Commands) - A function-like object that responds to `#call` and returns a `Result`.
+- [Operations](#label-Operations) - A stateful `Command` that wraps and delegates to its most recent `Result`.
+- [Results](#label-Results) - A data object with a `#value`, an `#errors` object, and `#success?` and `#failure?` status methods.
 
-## Documentation
+## About
+
+[comment]: # "Status Badges will go here."
+
+Traditional frameworks such as Rails focus on the objects of your application - the "nouns" such as User, Post, or Item. Using Cuprum or a similar library allows you the developer to make your business logic - the "verbs" such as Create User, Update Post or Ship Item - a first-class citizen of your project. This provides several advantages:
+
+- **Consistency:** Use the same Commands to underlie controller actions, worker processes and test factories.
+- **Encapsulation:** Each Command is defined and run in isolation, and dependencies must be explicitly provided to the command when it is initialized or run. This makes it easier to reason about the command's behavior and keep it insulated from changes elsewhere in the code.
+- **Testability:** Because the logic is extracted from unnecessary context, testing its behavior is much cleaner and easier.
+- **Composability:** Complex logic such as "find the object with this ID, update it with these attributes, and log the transaction to the reporting service" can be extracted into a series of simple Commands and composed together. The [Chaining](#label-Chaining) feature allows for complex control flows.
+- **Reusability:** Logic common to multiple data models or instances in your code, such as "persist an object to the database" or "find all records with a given user and created in a date range" can be refactored into parameterized commands.
+
+### Alternatives
+
+If you want to extract your logic but Cuprum is not the right solution for you, here are several alternatives:
+
+- Service objects. A common pattern used when first refactoring an application that has outgrown its abstractions. Service objects are simple and let you group related functionality, but they are harder to compose and require firm conventions to tame.
+- The [Interactor](https://github.com/collectiveidea/interactor) gem. Provides an `Action` module to implement logic and an `Organizer` module to manage control flow. Supports before, around, and after hooks.
+- The [Waterfall](https://github.com/apneadiving/waterfall) gem. Focused more on control flow.
+- [Trailblazer](http://trailblazer.to/) Operations. A pipeline-based approach to control flow, and can integrate tightly with other Trailblazer elements.
+
+### Compatibility
+
+Cuprum is tested against Ruby (MRI) 2.4.
+
+### Documentation
 
 Method and class documentation is available courtesy of [RubyDoc](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master).
 
 Documentation is generated using [YARD](https://yardoc.org/), and can be generated locally using the `yard` gem.
 
-## Contribute
+### License
+
+Copyright (c) 2017 Rob Smith
 
-### GitHub
+Cuprum is released under the [MIT License](https://opensource.org/licenses/MIT).
+
+### Contribute
 
 The canonical repository for this gem is located at https://github.com/sleepingkingstudios/cuprum.
 
-### A Note From The Developer
+To report a bug or submit a feature request, please use the [Issue Tracker](https://github.com/sleepingkingstudios/cuprum/issues).
 
-Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use these tools every day, but they're not just written for me. If you find this project helpful in your own work, or if you have any questions, suggestions or critiques, please feel free to get in touch! I can be reached on GitHub (see above, and feel encouraged to submit bug reports or merge requests there) or via email at merlin@sleepingkingstudios.com. I look forward to hearing from you!
+To contribute code, please fork the repository, make the desired updates, and then provide a [Pull Request](https://github.com/sleepingkingstudios/cuprum/pulls). Pull requests must include appropriate tests for consideration, and all code must be properly formatted.
 
-## Functions
+### Credits
 
-    require 'cuprum/function'
+Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use these tools every day, but they're not just written for me. If you find this project helpful in your own work, or if you have any questions, suggestions or critiques, please feel free to get in touch! I can be reached [on GitHub](https://github.com/sleepingkingstudios/cuprum) or [via email](mailto:merlin@sleepingkingstudios.com). I look forward to hearing from you!
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FFunction)
+## Concepts
 
-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.
+### Commands
 
-Each Function implements a `#call` method that wraps your defined business logic and returns an instance of Cuprum::Result. The result wraps the returned data (with the `#value` method), any `#errors` generated when running the Function, and the overall status with the `#success?` and `#failure` methods. For more details about Cuprum::Result, see below.
+    require 'cuprum'
 
-### Methods
+Commands are the core feature of Cuprum. In a nutshell, each Cuprum::Command is a functional object that encapsulates a business logic operation. A Command 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.
 
-A Cuprum::Function defines the following methods:
+Each Command implements a `#call` method that wraps your defined business logic and returns an instance of Cuprum::Result. The result wraps the returned data (with the `#value` method), any `#errors` generated when running the Command, and the overall status with the `#success?` and `#failure` methods. For more details about Cuprum::Result, [see below](#label-Results).
 
-#### #initialize
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommand)
 
-    initialize { |*arguments, **keywords, &block| ... } #=> Cuprum::Function
+#### Defining Commands
 
-Returns a new instance of Cuprum::Function. 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.
+The recommended way to define commands is to create a subclass of `Cuprum::Command` and override the `#process` method.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#initialize-instance_method)
+```ruby
+class BuildBookCommand < Cuprum::Command
+  def process attributes
+    Book.new(attributes)
+  end # method process
+end # class
 
-#### #call
+command = BuildPostCommand.new
+result  = command.call(:title => 'The Hobbit') # an instance of Cuprum::Result
+result.value #=> an instance of Book with title 'The Hobbit'
+```
 
-    call(*arguments, **keywords) { ... } #=> Cuprum::Result
+There are several takeaways from this example. First, we are defining a custom command class that inherits from `Cuprum::Command`. We are defining the `#process` method, which takes a single `attributes` parameter and returns an instance of `Book`. Then, we are creating an instance of the command, and invoking the `#call` method with an attributes hash. These attributes are passed to our `#process` implementation. Invoking `#call` returns a result, and the `#value` of the result is our new Book.
 
-Executes the logic encoded in the constructor block, or the #process method if no block was passed to the constructor.
+Because a command is just a Ruby object, we can also pass values to the constructor.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#call-instance_method)
+```ruby
+class SaveBookCommand < Cuprum::Command
+  def initialize repository
+    @repository = repository
+  end # constructor
 
-#### #chain
+  def process book
+    @repository.persist(book)
+  end # method process
+end # class
 
-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. See Chaining Functions, below.
+books = [
+  Book.new(:title => 'The Fellowship of the Ring'),
+  Book.new(:title => 'The Two Towers'),
+  Book.new(:title => 'The Return of the King')
+]
+command = SaveBookCommand.new(books_repository)
+books.each { |book| command.call(book) }
+```
 
-    chain(function, on: nil) #=> Cuprum::Function
+Here, we are reusing the same command three times, rather than creating a new save command for each book. Each book is persisted to the `books_repository`. This is also an example of how using commands can simplify code - notice that nothing about the `SaveBookCommand` is specific to the `Book` model. Thus, we could refactor this into a generic `SaveModelCommand`.
 
-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).
+A command can also be defined by passing block to `Cuprum::Command.new`.
 
-    chain(on: nil) { |result| ... } #=> Cuprum::Function
+```ruby
+increment_command = Cuprum::Command.new { |int| int + 1 }
 
-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.
+increment_command.call(2).value #=> 3
+```
 
-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.
+Commands defined using `Cuprum::Command.new` are quick to use, but more difficult to read and to reuse. Defining your own command class is recommended if a command definition takes up more than one line, or if the command will be used in more than one place.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#chain-instance_method)
+#### Success, Failure, and Errors
 
-#### `#then`
+Whether defined with a block or in the `#process` method, the Command implementation can access an `#errors` object while in the `#call` method. Any errors added to the errors object will be exposed by the `#errors` method on the result object.
 
-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.
+```ruby
+class PublishBookCommand < Cuprum::Command
+  private
 
-    then(function) #=> Cuprum::Function
+  def process book
+    if book.cover.nil?
+      errors << 'This book does not have a cover.'
 
-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).
+      return
+    end # if
 
-    then() { |result| ... } #=> Cuprum::Function
+    book.published = true
 
-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.
+    book
+  end # method process
+end # class
+```
 
-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.
+In addition, the result object defines `#success?` and `#failure?` predicates. If the result has no errors, then `#success?` will return true and `#failure?` will return false.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#then-instance_method)
+```ruby
+book = Book.new(:title => 'The Silmarillion', :cover => Cover.new)
+book.published? #=> false
 
-#### `#else`
+result = PublishBookCommand.new.call(book)
+result.errors   #=> []
+result.success? #=> true
+result.failure? #=> false
+result.value    #=> book
+book.published? #=> true
+```
 
-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.
+If the result does have errors, `#success?` will return false and `#failure?` will return true.
 
-    else(function) #=> Cuprum::Function
+```ruby
+book = Book.new(:title => 'The Silmarillion', :cover => nil)
+book.published? #=> false
 
-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).
+result = PublishBookCommand.new.call(book)
+result.errors   #=> ['This book does not have a cover.']
+result.success? #=> false
+result.failure? #=> true
+result.value    #=> book
+book.published? #=> false
+```
 
-    else() { |result| ... } #=> Cuprum::Function
+### Chaining Commands
 
-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.
+Because Cuprum::Command instances are proper objects, they can be composed like any other object. Cuprum::Command also defines methods for chaining commands together. When a chain of commands is called, each command in the chain is called in sequence and passed the value of the previous command. The result of the last command in the chain is returned from the chained call.
 
-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.
+    class AddCommand < Cuprum::Command
+      def initialize addend
+        @addend = addend
+      end # constructor
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#else-instance_method)
+      private
 
-#### `#build_errors`
+      def process int
+        int + @addend
+      end # method process
+    end # class
 
-*Private method*. 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.
+    double_and_add_one = MultiplyCommand.new(2).chain(AddCommand.new(1))
+    result             = double_and_add_one(5)
 
-    build_errors() #=> Array
+    result.value #=> 5
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#build_errors-instance_method)
+For finer control over the returned result, `#chain` can instead be called with a block that yields the most recent result. If the block returns a Cuprum::Result, that result is returned or passed to the next command.
 
-### Implementation Hooks
+    MultiplyCommand.new(3).
+      chain { |result| Cuprum::Result.new(result + 1) }.
+      call(3)
+    #=> Returns a Cuprum::Result with a value of 10.
 
-These methods are only available while the Function is being called, and allow the implementation to update the errors of and override the results of the result object.
+Otherwise, the block is still called but the previous result is returned or passed to the next command in the chain.
 
-#### `#errors`
+    AddCommand.new(2).
+      chain { |result| puts "There are #{result.value} lights!" }.
+      call(2)
+    #=> Writes "There are 4 lights!" to STDOUT.
+    #=> Returns a Cuprum::Result with a value of 4.
 
-Only available while the Function is being called. Provides access to the errors object of the generated Cuprum::Result, which is by default an instance of Array.
+#### Conditional Chaining
 
-    errors() #=> Array
+The `#chain` method can be passed an optional `:on` keyword, with values of `:success` and `:failure` accepted. If `#chain` is called with `:on => :success`, then the chained command or block will **only** be called if the previous result `#success?` returns true. Conversely, if `#chain` is called with `:on => :failure`, then the chained command will only be called if the previous result `#failure?` returns true.
 
-Inside of the Function block or the `#process` method, you can add errors to the result.
+In either case, execution will then pass to the next command in the chain, which may itself be called or not if it was conditionally chained. Calling a conditional command chain will return the result of the last called command.
 
-    function =
-      Cuprum::Function.new do
-        errors << "I'm sorry, something went wrong."
+The methods `#then` and `#else` serve as shortcuts for `#chain` with `:on => :success` and `:on => :failure`, respectively.
 
-        nil
-      end # function
+    class EvenCommand < Cuprum::Command
+      private
 
-    result = function.call
-    result.failure?
-    #=> true
-    result.errors
-    #=> ["I'm sorry, something went wrong."]
+      def process int
+        errors << 'errors.messages.not_even' unless int.even?
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Function#errors-instance_method)
+        int
+      end # method process
+    end # class
 
-#### `#success!`
+    # 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.
+        then(DivideCommand.new(2)).
+        else(MultiplyCommand.new(3).chain(AddCommand.new(1)))
 
-Only available while the Function is being called. If called, marks the result object as passing, even if the result has errors.
+    result = collatz_command.new(5)
+    result.value #=> 16
 
-    success!() #=> NilClass
+    result = collatz_command.new(16)
+    result.value #=> 8
 
-#### `#failure!`
+#### Halting A Command Chain
 
-Only available while the Function is being called. If called, marks the result object as failing, even if the result does not have errors.
+If the `#halt` method is called as part of a Command block or `#process` method, the command chain is halted. Any subsequent chained commands will not be called unless they were chained with the `:on => :always` option. This allows you to terminate a Command chain early without having to raise and rescue an exception.
 
-    failure!() #=> NilClass
+    panic_command =
+      Cuprum::Command.new do |value|
+        halt!
 
-#### `#halt!`
+        value
+      end # command
 
-Only available while the Function is being called. If called, halts the function chain (see Chaining Functions, below). Subsequent chained functions will not be called unless they were chained with the `:on => :always` option.
+    result =
+      double_command.
+        then(panic_command).
+        then(AddCommand.new(1)). #=> This is never executed.
+        chain(:on => :always) { |count| puts "There are #{count} lights!" }.
+        call(2)
+    #=> Writes "There are 4 lights!" to STDOUT.
 
-    halt!() #=> NilClass
+    result.value   #= 4
+    result.halted? #=> true
 
-### Defining With a Block
+### Results
 
-Functions can be used right out of the box by passing a block to the Cuprum::Function constructor, as follows:
+    require 'cuprum'
 
-    # A Function with a block
-    double_function = Cuprum::Function.new { |int| 2 * int }
-    result          = double_function.call(5)
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FResult)
 
-    result.value #=> 10
+A Cuprum::Result is a data object that encapsulates the result of calling a Cuprum command. Each result has a `#value`, an `#errors` object (defaults to an Array), and status methods `#success?`, `#failure?`, and `#halted?`.
 
-The constructor block will be called each time `Function#call` is executed, and will be passed all of the arguments given to `#call`. You can even define a block parameter, which will be passed along to the constructor block when `#call` is called with a block argument.
+```ruby
+value  = 'A result value'.freeze
+result = Cuprum::Result.new(value)
 
-### Defining With a Subclass
+result.value    #=> 'A result value'
+result.errors   #=> []
+result.success? #=> true
+result.failure? #=> false
+result.halted?  #=> false
+```
 
-Larger applications will want to create Function subclasses that encapsulate their business logic in a reusable, composable fashion. The implementation for each subclass is handled by the `#process` private method. If a subclass or its ancestors does not implement `#process`, a `Cuprum::Function::NotImplementedError` will be raised.
+Adding errors to the `#errors` object will change the status of the result.
 
-    # A Function subclass
-    class MultiplyFunction < Cuprum::Function
-      def initialize multiplier
-        @multiplier = multiplier
-      end # constructor
+```ruby
+result.errors << "I'm sorry, something went wrong."
+result.success? #=> false
+result.failure? #=> true
+```
 
-      private
+The status can also be overriden with the `#success!` and `#failure!` methods, which will set the status regardless of the presence or absence of errors.
 
-      def process int
-        int * @multiplier
-      end # method process
-    end # class
+```ruby
+result.success!
+result.errors   #=> ["I'm sorry, something went wrong."]
+result.success? #=> true
+result.failure? #=> false
+```
 
-    triple_function = MultiplyFunction.new(3)
-    result          = triple_function.call(5)
+### Operations
 
-    result.value #=> 15
+    require 'cuprum'
 
-As with the block syntax, a Function whose implementation is defined via the `#process` method will call `#process` each time that `#call` is executed, and will pass all arguments from `#call` on to `#process`. The value returned by `#process` will be assigned to the result `#value`.
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
 
-### Success, Failure, and Errors
+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 `Cuprum::Result` in any code that expects or returns a result. Second, the `#call` method returns the operation instance, rather than the result itself.
 
-Whether defined with a block or in the `#process` method, the Function implementation can access an `#errors` object while in the `#call` method. Any errors added to the errors object will be exposed by the `#errors` method on the result object.
+These two features allow developers to simplify logic around calling and using the results of operations, and reduce the need for boilerplate code (particularly when using an operation as part of an existing framework, such as inside of an asynchronous worker or a Rails controller action).
 
-    # A Function with errors
-    class DivideFunction < Cuprum::Function
-      def initialize divisor
-        @divisor = divisor
-      end # constructor
+```ruby
+class CreateBookOperation < Cuprum::Operation
+  def process
+    # Implementation here.
+  end # method process
+end # class
 
-      private
+# Defining a controller action using an operation.
+def create
+  operation = CreateBookOperation.new.call(book_params)
 
-      def process int
-        if @divisor.zero?
-          errors << 'errors.messages.divide_by_zero'
+  if operation.success?
+    redirect_to(operation.value)
+  else
+    @book = operation.value
 
-          return
-        end # if
+    render :new
+  end # if-else
+end # create
+```
 
-        int / @divisor
-      end # method process
-    end # class
+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.
 
-In addition, the result object defines `#success?` and `#failure?` predicates. If the result has no errors, then `#success?` will return true and `#failure?` will return false.
+An operation inherits the `#call` method from Cuprum::Command (see above), and delegates the `#value`, `#errors`, `#success?`, and `#failure` methods to the most recent result. If the operation has not been called, these methods will return default values.
 
-    halve_function = DivideFunction.new(2)
-    result         = halve_function.call(10)
+#### The Operation Mixin
 
-    result.errors   #=> []
-    result.success? #=> true
-    result.failure? #=> false
-    result.value    #=> 5
+[Module Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation%2FMixin)
 
- If the result does have errors, `#success?` will return false and `#failure?` will return true.
+The implementation of `Cuprum::Operation` is defined by the `Cuprum::Operation::Mixin` module, which provides the methods defined above. Any command class or instance can be converted to an operation by including (for a class) or extending (for an instance) the operation mixin.
 
-    function_with_errors = DivideFunction.new(0)
-    result               = function_with_errors.call(10)
+Finally, the result can be halted using the `#halt` method, which indicates that further chained commands should not be executed.
 
-    result.errors   #=> ['errors.messages.divide_by_zero']
-    result.success? #=> false
-    result.failure? #=> true
-    result.value    #=> nil
+```ruby
+result.halt!
+result.halted? #=> true
+```
 
-### Chaining Functions
+### Built In Commands
 
-Because Cuprum::Function instances are proper objects, they can be composed like any other object. Cuprum::Function also defines methods for chaining functions together. When a chain of functions is called, each function in the chain is called in sequence and passed the value of the previous function. The result of the last function in the chain is returned from the chained call.
+Cuprum includes a small number of predefined commands and their equivalent operations.
 
-    class AddFunction < Cuprum::Function
-      def initialize addend
-        @addend = addend
-      end # constructor
+#### IdentityCommand
 
-      private
+    require 'cuprum/built_in/identity_command'
 
-      def process int
-        int + @addend
-      end # method process
-    end # class
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityCommand)
 
-    double_and_add_one = MultiplyFunction.new(2).chain(AddFunction.new(1))
-    result             = double_and_add_one(5)
+A pregenerated command that returns the value or result with which it was called.
 
-    result.value #=> 5
+```ruby
+command = Cuprum::BuiltIn::IdentityCommand.new
+result  = command.call('expected value')
+result.value    #=> 'expected value'
+result.success? #=> true
+```
 
-For finer control over the returned result, `#chain` can instead be called with a block that yields the most recent result. If the block returns a Cuprum::Result, that result is returned or passed to the next function.
+#### IdentityOperation
 
-    MultiplyFunction.new(3).
-      chain { |result| Cuprum::Result.new(result + 1) }.
-      call(3)
-    #=> Returns a Cuprum::Result with a value of 10.
+    require 'cuprum/built_in/identity_operation'
 
-Otherwise, the block is still called but the previous result is returned or passed to the next function in the chain.
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityOperation)
 
-    AddFunction.new(2).
-      chain { |result| puts "There are #{result.value} lights!" }.
-      call(2)
-    #=> Writes "There are 4 lights!" to STDOUT.
-    #=> Returns a Cuprum::Result with a value of 4.
+A pregenerated operation that sets its result to the value or result with which it was called.
 
-#### Conditional Chaining
+```ruby
+operation = Cuprum::BuiltIn::IdentityOperation.new.call('expected value')
+operation.value    #=> 'expected value'
+operation.success? #=> true
+```
 
-The `#chain` method can be passed an optional `:on` keyword, with values of `:success` and `:failure` accepted. If `#chain` is called with `:on => :success`, then the chained function or block will **only** be called if the previous result `#success?` returns true. Conversely, if `#chain` is called with `:on => :failure`, then the chained function will only be called if the previous result `#failure?` returns true.
+#### NullCommand
 
-In either case, execution will then pass to the next function in the chain, which may itself be called or not if it was conditionally chained. Calling a conditional function chain will return the result of the last called function.
+    require 'cuprum/built_in/null_command'
 
-The methods `#then` and `#else` serve as shortcuts for `#chain` with `:on => :success` and `:on => :failure`, respectively.
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullCommand)
 
-    class EvenFunction < Cuprum::Function
-      private
+A pregenerated command that does nothing when called. Accepts any arguments.
 
-      def process int
-        errors << 'errors.messages.not_even' unless int.even?
+```ruby
+command = Cuprum::BuiltIn::NullCommand.new
+result  = command.call
+result.value    #=> nil
+result.success? #=> true
+```
 
-        int
-      end # method process
-    end # class
+#### NullOperation
 
-    # 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 =
-      EvenFunction.new.
-        then(DivideFunction.new(2)).
-        else(MultiplyFunction.new(3).chain(AddFunction.new(1)))
+    require 'cuprum/built_in/null_operation'
 
-    result = collatz_function.new(5)
-    result.value #=> 16
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullOperation)
 
-    result = collatz_function.new(16)
-    result.value #=> 8
+A pregenerated operation that does nothing when called. Accepts any arguments.
 
-#### Halting A Function Chain
+```ruby
+operation = Cuprum::BuiltIn::NullOperation.new.call
+operation.value    #=> nil
+operation.success? #=> true
+```
 
-If the `#halt` method is called as part of a Function block or `#process` method, the function chain is halted. Any subsequent chained functions will not be called unless they were chained with the `:on => :always` option. This allows you to terminate a Function chain early without having to raise and rescue an exception.
+## Reference
 
-    panic_function =
-      Cuprum::Function.new do |value|
-        halt!
+### Cuprum::BuiltIn::IdentityCommand
 
-        value
-      end # function
+    require 'cuprum/built_in/identity_command'
 
-    result =
-      double_function.
-        then(panic_function).
-        then(AddFunction.new(1)). #=> This is never executed.
-        chain(:on => :always) { |count| puts "There are #{count} lights!" }.
-        call(2)
-    #=> Writes "There are 4 lights!" to STDOUT.
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityCommand)
 
-    result.value   #= 4
-    result.halted? #=> true
+Cuprum::BuiltIn::IdentityCommand defines the following methods:
 
-## Operations
+#### `#call`
 
-    require 'cuprum/operation'
+    call(value) #=> Cuprum::Result
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
+Returns a result, whose `#value` is equal to the given value.
 
-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.
+### Cuprum::BuiltIn::IdentityOperation
 
-These two features allow developers to simplify logic around calling and using the results of operations, and reduce the need for boilerplate code (particularly when using an operation as part of an existing framework, such as inside of an asynchronous worker or a Rails controller action).
+    require 'cuprum/built_in/identity_operation'
 
-    class CreateBookOperation < Cuprum::Operation
-      def process
-        # Implementation here.
-      end # method process
-    end # class
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityOperation)
 
-    def create
-      operation = CreateBookOperation.new.call(book_params)
+Cuprum::BuiltIn::IdentityOperation defines the following methods:
 
-      if operation.success?
-        redirect_to(operation.value)
-      else
-        @book = operation.value
+#### `#call`
 
-        render :new
-      end # if-else
-    end # create
+    call(value) #=> Cuprum::BuiltIn::IdentityOperation
 
-Like a Function, an Operation can be defined directly by passing an implementation block to the constructor or by creating a subclass that overwrites the #process method.
+Sets the last result to a new result, whose `#value` is equal to the given value.
 
-An operation inherits the `#call` method from Cuprum::Function (see above), and delegates the `#value`, `#errors`, `#success?`, and `#failure` methods to the most recent result (see below). If the operation has not been called, the operation will return default values.
+### Cuprum::BuiltIn::NullCommand
 
-### Methods
+    require 'cuprum/built_in/null_command'
 
-A Cuprum::Operation inherits the methods from Cuprum::Function (see above), and defines the following additional methods:
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullCommand)
 
-#### `#result`
+Cuprum::BuiltIn::NullCommand defines the following methods:
 
-    result() #=> Cuprum::Result
+#### `#call`
 
-The most recent result, from the previous time `#call` was executed for the operation.
+    call(*args, **keywords) { ... } #=> Cuprum::Result
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#result-instance_method)
+Returns a result with nil value. Any arguments or keywords are ignored.
 
-#### `#called?`
+### Cuprum::BuiltIn::NullOperation
 
-    called?() #=> true, false
+    require 'cuprum/built_in/null_operation'
 
-True if the operation has been called and there is a result available by calling `#result` or one of the delegated methods, otherwise false.
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullOperation)
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#called%3F-instance_method)
+Cuprum::BuiltIn::NullOperation defines the following methods:
 
-#### `#reset!`
+#### `#call`
 
-    reset!()
+    call(*args, **keywords) { ... } #=> Cuprum::BuiltIn::NullOperation
 
-Clears the most recent result and resets `#called?` to false. This frees the result and any linked data for garbage collection. It also clears any internal state from the operation.
+Sets the last result to a result with nil value. Any arguments or keywords are ignored.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#reset!-instance_method)
+### Cuprum::Command
 
-### The Operation Mixin
+    require 'cuprum'
 
-[Module Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation%2FMixin)
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommand)
 
-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.
+A Cuprum::Command defines the following methods:
 
-## Results
+#### `#initialize`
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FResult)
+    initialize { |*arguments, **keywords, &block| ... } #=> Cuprum::Command
 
-A Cuprum::Result is a data object that encapsulates the result of calling a Cuprum function - the returned value, the success or failure status, and any errors generated by the function.
+Returns a new instance of Cuprum::Command. 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.
 
-    value  = 'A result value'.freeze
-    result = Cuprum::Result.new(value)
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#initialize-instance_method)
 
-    result.value
-    #=> 'A result value'
+#### `#build_errors`
 
-### Methods
+*(Private Method)*
 
-A Cuprum::Result defines the following methods:
+    build_errors() #=> Array
 
-#### `#value`
+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.
 
-    value() #=> Object
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#build_errors-instance_method)
 
-The value returned by the function. For example, for an increment function that added 1 to a given integer, the `#value` of the result object would be the incremented integer.
+#### #call
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#value-instance_method)
+    call(*arguments, **keywords) { ... } #=> Cuprum::Result
+
+Executes the logic encoded in the constructor block, or the #process method if no block was passed to the constructor.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#call-instance_method)
+
+#### #chain
+
+    chain(on: nil) { |result| ... } #=> Cuprum::Command
+
+Registers a command or block to run after the current command, or after the last chained command if the current command already has one or more chained command(s). This creates and modifies a copy of the current command. See Chaining Commands, below.
+
+    chain(command, on: nil) #=> Cuprum::Command
+
+The command will be passed the `#value` of the previous command result as its parameter, and the result of the chained command will be returned (or passed to the next chained command, if any).
+
+The block will be passed the #result of the previous command as its parameter. If your use case depends on the status of the previous command 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 command, if any). If the block returns any other value (including nil), the #result of the previous command will be returned or passed to the next command.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#chain-instance_method)
+
+#### `#else`
+
+    else(command) #=> Cuprum::Command
+
+Shorthand for `command.chain(:on => :failure)`. Registers a command or block to run after the current command. The chained command will only run if the previous command was unsuccessfully run.
+
+The command will be passed the `#value` of the previous command result as its parameter, and the result of the chained command will be returned (or passed to the next chained command, if any).
+
+    else() { |result| ... } #=> Cuprum::Command
+
+The block will be passed the #result of the previous command as its parameter. If your use case depends on the status of the previous command 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 command, if any). If the block returns any other value (including nil), the #result of the previous command will be returned or passed to the next command.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#else-instance_method)
 
 #### `#errors`
 
+*(Private Method)*
+
     errors() #=> Array
 
-The errors generated by the function, or an empty array if no errors were generated.
+Only available while the Command is being called. Provides access to the errors object of the generated Cuprum::Result, which is by default an instance of Array.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#errors-instance_method)
+Inside of the Command block or the `#process` method, you can add errors to the result.
 
-#### `#success?`
+    command =
+      Cuprum::Command.new do
+        errors << "I'm sorry, something went wrong."
 
-    success?() #=> true, false
+        nil
+      end # command
 
-True if the function did not generate any errors, otherwise false.
+    result = command.call
+    result.failure?
+    #=> true
+    result.errors
+    #=> ["I'm sorry, something went wrong."]
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#success%3F-instance_method)
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#errors-instance_method)
 
-#### `#failure?`
+#### `#failure!`
 
-    failure?() #=> true, false
+    failure!() #=> NilClass
 
-True if the function generated one or more errors, otherwise false.
+*(Private Method)*
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure%3F-instance_method)
+Only available while the Command is being called. If called, marks the result object as failing, even if the result does not have errors.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#failure!-instance_method)
+
+#### `#halt!`
+
+    halt!() #=> NilClass
+
+*(Private Method)*
+
+Only available while the Command is being called. If called, halts the command chain (see Chaining Commands, below). Subsequent chained commands will not be called unless they were chained with the `:on => :always` option.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#halt!-instance_method)
+
+#### `#success!`
+
+    success!() #=> NilClass
+
+*(Private Method)*
+
+Only available while the Command is being called. If called, marks the result object as passing, even if the result has errors.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#success!-instance_method)
+
+#### `#then`
+
+    then(command) #=> Cuprum::Command
+
+Shorthand for `command.chain(:on => :success)`. Registers a command or block to run after the current command. The chained command will only run if the previous command was successfully run.
+
+The command will be passed the `#value` of the previous command result as its parameter, and the result of the chained command will be returned (or passed to the next chained command, if any).
+
+    then() { |result| ... } #=> Cuprum::Command
+
+The block will be passed the #result of the previous command as its parameter. If your use case depends on the status of the previous command 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 command, if any). If the block returns any other value (including nil), the #result of the previous command will be returned or passed to the next command.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#then-instance_method)
+
+### Cuprum::Operation
+
+    require 'cuprum'
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
+
+A Cuprum::Operation inherits the methods from Cuprum::Command (see above), and defines the following additional methods:
+
+#### `#called?`
+
+    called?() #=> true, false
+
+True if the operation has been called and there is a result available by calling `#result` or one of the delegated methods, otherwise false.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#called%3F-instance_method)
+
+#### `#reset!`
+
+    reset!()
+
+Clears the most recent result and resets `#called?` to false. This frees the result and any linked data for garbage collection. It also clears any internal state from the operation.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#reset!-instance_method)
+
+#### `#result`
+
+    result() #=> Cuprum::Result
+
+The most recent result, from the previous time `#call` was executed for the operation.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#result-instance_method)
+
+### Cuprum::Result
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FResult)
+
+A Cuprum::Result defines the following methods:
 
 #### `#==`
 
@@ -449,118 +652,114 @@ Performs a fuzzy comparison with the other object. At a minimum, the other objec
 
 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
+#### `#errors`
 
-Cuprum provides these utility modules to grant additional functionality under specific circumstances.
+    errors() #=> Array
 
-### InstanceSpy
+The errors generated by the command, or an empty array if no errors were generated.
 
-    require 'cuprum/utils/instance_spy'
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#errors-instance_method)
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FUtils%2FInstanceSpy)
+#### `#failure!`
 
-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.
+    failure!() #=> Cuprum::Result
 
-#### `::spy_on`
+Marks the result as failing and returns the result. Calling `#failure?` will return true, even if the result has no errors.
 
-    spy_on(function_class) #=> InstanceSpy
-    spy_on(function_class) { |spy| ... } #=> nil
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure!-instance_method)
 
-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.
+#### `#failure?`
 
-    # Observing calls to instances of a function.
-    spy = Cuprum::Utils::InstanceSpy.spy_on(CustomFunction)
+    failure?() #=> true, false
 
-    expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
+True if the command generated one or more errors or was marked as failing. Otherwise false.
 
-    CustomFunction.new.call(1, 2, 3, :four => '4')
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure%3F-instance_method)
 
-    # Observing calls to a chained function.
-    spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedFunction)
+#### `#halt!`
 
-    expect(spy).to receive(:call)
+    halt!() #=> Cuprum::Result
 
-    Cuprum::Function.new {}.
-      chain { |result| ChainedFunction.new.call(result) }.
-      call
+Marks the result as halted and returns the result. Calling `#halted?` will return true.
 
-    # Block syntax
-    Cuprum::Utils::InstanceSpy.spy_on(CustomFunction) do |spy|
-      expect(spy).to receive(:call)
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#halt!-instance_method)
 
-      CustomFunction.new.call
-    end # spy_on
+#### `#halted?`
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#spy_on%3F-instance_method)
+    halted?() #=> true, false
 
-#### `::clear_spies`
+True if the result is halted, which prevents chained commands from executing.
 
-    clear_spies() #=> nil
+#### `#success!`
 
-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.
+    success!() #=> Cuprum::Result
 
-    after(:example) { Cuprum::Utils::InstanceSpy.clear_spies }
+Marks the result as passing and returns the result. Calling `#success?` will return true, even if the result has errors.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#clear_spies%3F-instance_method)
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#success!-instance_method)
 
-## Built In Functions
+#### `#success?`
 
-Cuprum includes a small number of predefined functions and their equivalent operations.
+    success?() #=> true, false
 
-### IdentityFunction
+True if the command did not generate any errors, or the result has errors but was marked as passing. Otherwise false.
 
-    require 'cuprum/built_in/identity_function'
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#success%3F-instance_method)
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityFunction)
+#### `#value`
 
-A pregenerated function that returns the value or result with which it was called.
+    value() #=> Object
 
-    function = Cuprum::BuiltIn::IdentityFunction.new
-    result   = function.call('expected value')
-    result.value
-    #=> 'expected value'
-    result.success?
-    #=> true
+The value returned by the command. For example, for an increment command that added 1 to a given integer, the `#value` of the result object would be the incremented integer.
 
-### IdentityOperation
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#value-instance_method)
 
-    require 'cuprum/built_in/identity_operation'
+### Cuprum::Utilities::InstanceSpy
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityOperation)
+    require 'cuprum/utils/instance_spy'
 
-A pregenerated operation that sets its result to the value or result with which it was called.
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FUtils%2FInstanceSpy)
 
-    operation = Cuprum::BuiltIn::IdentityFunction.new.call('expected value')
-    operation.value
-    #=> 'expected value'
-    operation.success?
-    #=> true
+Utility module for instrumenting calls to the #call method of any instance of a command class. This can be used to unobtrusively test the functionality of code that calls a command without providing a reference to the command instance, such as chained commands or methods that create and call a command instance.
 
-### NullFunction
+#### `::clear_spies`
 
-    require 'cuprum/built_in/null_function'
+    clear_spies() #=> nil
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullFunction)
+Retires all spies. Subsequent calls to the #call method on command instances will not be mirrored to existing spy objects. Calling this method after each test or example that uses an instance spy is recommended.
 
-A pregenerated function that does nothing when called.
+    after(:example) { Cuprum::Utils::InstanceSpy.clear_spies }
 
-    function = Cuprum::BuiltIn::NullFunction.new
-    result   = function.call
-    result.value
-    #=> nil
-    result.success?
-    #=> true
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#clear_spies%3F-instance_method)
 
-### NullOperation
+#### `::spy_on`
 
-    require 'cuprum/built_in/null_operation'
+    spy_on(command_class) #=> InstanceSpy
+    spy_on(command_class) { |spy| ... } #=> nil
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullFunction)
+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.
 
-A pregenerated operation that does nothing when called.
+    # Observing calls to instances of a command.
+    spy = Cuprum::Utils::InstanceSpy.spy_on(CustomCommand)
 
-    operation = Cuprum::BuiltIn::NullOperation.new.call
-    operation.value
-    #=> nil
-    operation.success?
-    #=> true
+    expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
+
+    CustomCommand.new.call(1, 2, 3, :four => '4')
+
+    # Observing calls to a chained command.
+    spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedCommand)
+
+    expect(spy).to receive(:call)
+
+    Cuprum::Command.new {}.
+      chain { |result| ChainedCommand.new.call(result) }.
+      call
+
+    # Block syntax
+    Cuprum::Utils::InstanceSpy.spy_on(CustomCommand) do |spy|
+      expect(spy).to receive(:call)
+
+      CustomCommand.new.call
+    end # spy_on
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#spy_on%3F-instance_method)