cuprum 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f867011719a69bd7080c77d450fedfee736ef6df5be2b8a2d11fe3b1006a3890
-  data.tar.gz: 48109c5460f817fedb8c6a46b84649a87d9c21e2d2dbadba31b31e32bdf20977
+  metadata.gz: 7f8976c5a3b4ebc7fd1704d8f796391ec961834492a79cbb65bcef01e0bca9e4
+  data.tar.gz: b01921b268068f191e2d96c43fb6b0a6c6fe924277f2ba696e66665079f4ed6b
 SHA512:
-  metadata.gz: b272e3d32edf7449a83a8513be56f8e68e2474872621d055f5947b6605ec5c29ecbd4acc7e7155d1efd5ee122689dc564eaab312b499ff129d996c6e6599ff90
-  data.tar.gz: 7ad63c437101991668b8a060fa355633f46b269ad55d609fad81bf5e993b998974f43ae61bc96d2c781a10e29d83178a7b2770ec2540a121f54bf6261530fcce
+  metadata.gz: 600cf6c8df2e8b78047e82049ed27e471f9f51946ae126234c091949657982a019cfb6c514840c2375e689a0a7dc4463e8b9157b1e18be0f03c2a69f4b50a2b6
+  data.tar.gz: 40cb494bae1201111b8042eb6e181bc63a82c520cadb2dfed53d9896041ee6934500e07eace1f386c31bc31a9e586065364c93f5fae0a43908d4bec51a50c321

data/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.11.0
+
+The "One Giant Leap" Update
+
+**Note:** This will be the last feature update before 1.0.
+
+### Commands
+
+Implemented the `#to_proc` method, which allows for constructs such as `array.map(&command)`.
+
+Removed the deprecated chaining mechanic.
+
+#### Currying
+
+Added support for currying block parameters.
+
+#### Exception Handling
+
+Defined `Cuprum::ExceptionHandling` to rescue uncaught errors in commands.
+
+Exception handling is *not* included by default - add `include Cuprum::ExceptionHandling` to your command classes to use this feature.
+
+#### Middleware
+
+Defined `Cuprum::Middleware` to define a wrapper that calls other commands.
+
+#### Steps
+
+Deprecated calling `#step` with a method name.
+
+The error type and message when calling `#steps` without a block has changed.
+
+### Errors
+
+Errors can now define their comparable properties by passing additional keywords to the constructor (or `super` for error subclasses).
+
+Added the `#type` method and property.
+
+Added serialization via the `#as_json` method.
+
+### Matchers
+
+Implemented `Cuprum::Matcher`, which provides a way to handle different result cases.
+
+### RSpec
+
+Added the `#be_callable` macro, which is a wrapper for `#respond_to` that references the `#process` method.
+
+RSpec matchers are no longer automatically included when the macro is required. To use the Cuprum matchers, add `config.include Cuprum::RSpec::Matchers` to your RSpec configuration, or add `include Cuprum::RSpec::Matchers` to your example groups.
+
+## 0.10.0
+
+The "One Small Step" Update
+
+**Note:** This update may have backwards incompatible changes for versions of Ruby before 2.7 when creating commands whose last parameter is an arguments Hash. See [separation of positional and keyword arguments](https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/) for more information.
+
+### Commands
+
+Implemented the `#curry` method, which performs partial application of arguments or keywords.
+
+#### Chaining
+
+Added deprecation warnings to all chaining methods, and `Cuprum::Command` no longer includes `Cuprum::Chaining` by default. The `Cuprum::Chaining` module will be removed in version 0.11.
+
+#### Steps
+
+Implemented the `#step` method, which extracts the value of the called command (on a success) or halts execution (on a failure).
+
+Implemented the `#steps` method, which wraps a series of steps and returns first failing result, or the the last result if all steps are passing.
+
 ## 0.9.1
 
 ### Operations

data/DEVELOPMENT.md

@@ -1,78 +1,35 @@
 # Development
 
-## Version 0.9.0
-
-The "'Tis Not Too Late To Seek A Newer World" Update
-
-## Version 0.10.0
+## Version 1.0.0
 
-The "One Small Step" Update
+The "Look On My Works, Ye Mighty, and Despair" Update
 
-### Commands
-
-- Implement #<<, #>> composition methods.
-  - Calls commands in order passing values.
-  - Return Result early on Failure (or not Success), otherwise final Result.
-- Implement #step method (used in #process).
-  - Called with command (block? method?) that returns a Result.
-  - Raise (and catch) exception on non-success Result (test custom status?)
-  - Otherwise return Result#value.
-- Deprecate #chain and its related methods
-
-### Documentation
+- Documentation pass.
 
 Steps Case Study: |
 
   CMS application - creating a new post.
   Directory has many Posts
   Post has a Content
-  Content has many ContentVersions
   Post has many Tags
 
   Find Directory
   Create Post
   Create Content
-  Create ContentVersion
   Tags.each { FindOrCreate Tag }
-
-### Matcher
-
-- Handle success(), failure(), failure(SomeError) cases.
-  - Custom matcher to handle additional cases - halted, pending, etc?
-
-### RSpec
-
-- be_callable matcher - delegates to respond_to(), but check arguments of
-  private #process method
-- call_command_step matcher
-- (optionally) alias be_a_result family as have_result for operations
-
-## Version 1.0.0
-
-'The "Look On My Works, Ye Mighty, and Despair" Update'
-
-- Integration specs.
-- Configuration option to raise, warn, ignore discarded results.
-- Code cleanup: Hash syntax, remove end comments, remove file headers
-
-### Commands
-
-- Command#to_proc
-- Remove #chain and its related methods
-
-### Commands - Built In
-
-- MapCommand - wraps a command (or proc) and returns Result with value, errors
-  as array
-- RetryCommand
+  Publish Post # Requires that post have content
 
 ## Future Versions
 
+Add `.rbs` files
+
 ### Commands
 
-- command currying
+- Implement #<<, #>> composition methods.
+  - Calls commands in order passing values.
+  - Return Result early on Failure (or not Success), otherwise final Result.
 
-#### Cuprum::DSL
+#### DSL
 
 - ::process - shortcut for defining #process
 - ::rescue - `rescue StandardError do ... end`, rescues matched errors in #process
@@ -89,3 +46,35 @@ Steps Case Study: |
 #### Dependency Injection
 
 - shorthand for referencing a sequence of operations
+
+### Commands - Built In
+
+- MapCommand - wraps a command (or proc) and returns Result with value, errors
+  as array
+- RetryCommand - takes command, retry count
+  - optional only:, except: - restrict what errors are retried
+
+### Middleware
+
+- Implement Command.subclass
+  - Curries constructor arguments
+- Implement Cuprum::AppliedMiddleware < Cuprum::Command
+  - has readers #root (Class), #middleware (Array<Class>)
+  - #initialize
+    - initializes root command (passing constructor parameters)
+    - initializes each middleware command
+      - if Class defining .instance, call .instance
+      - if Class, call .new
+      - if Proc, call #call with constructor parameters
+    - calls Middleware.apply and caches as private #applied
+  - #call
+    - delegates to #applied
+
+### RSpec
+
+- call_command_step matcher
+- (optionally) alias be_a_result family as have_result for operations
+
+### Steps::Strict
+
+- #step raises exception unless block or method returns a result

data/README.md

@@ -4,10 +4,11 @@ An opinionated implementation of the Command pattern for Ruby applications. Cupr
 
 It defines the following concepts:
 
-- [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) - An immutable data object with a status (either `:success` or `:failure`), and either a `#value` or an `#error` object.
-- [Errors](#label-Errors) - Encapsulates a failure state of a command.
+- [Commands](#Commands) - A function-like object that responds to `#call` and returns a `Result`.
+- [Operations](#Operations) - A stateful `Command` that wraps and delegates to its most recent `Result`.
+- [Results](#Results) - An immutable data object with a status (either `:success` or `:failure`), and optional `#value` and/or `#error` objects.
+- [Errors](#Errors) - Encapsulates a failure state of a command.
+- [Matchers](#Matchers) - Define handling for results based on status, error, and value.
 
 ## About
 
@@ -18,26 +19,24 @@ Traditional frameworks such as Rails focus on the objects of your application -
 - **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+Commands) feature allows for complex control flows.
+- **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 [step](#label-Command+Steps) 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.
+If you want to extract your logic but Cuprum is not the right solution for you, there are a number of alternatives, including
+[ActiveInteraction](https://github.com/AaronLasseigne/active_interaction),
+[Dry::Monads](https://dry-rb.org/gems/dry-monads/),
+[Interactor](https://github.com/collectiveidea/interactor),
+[Trailblazer](http://trailblazer.to/) Operations,
+and [Waterfall](https://github.com/apneadiving/waterfall).
 
 ### Compatibility
 
-Cuprum is tested against Ruby (MRI) 2.3 through 2.5.
+Cuprum is tested against Ruby (MRI) 2.6 through 3.0.
 
 ### 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.
 
 ### License
@@ -54,13 +53,9 @@ To report a bug or submit a feature request, please use the [Issue Tracker](http
 
 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.
 
-### Credits
-
-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!
-
-## Concepts
+<a id="Commands"></a>
 
-### Commands
+## Commands
 
     require 'cuprum'
 
@@ -68,9 +63,7 @@ Commands are the core feature of Cuprum. In a nutshell, each `Cuprum::Command` i
 
 Each Command implements a `#call` method that wraps your defined business logic and returns an instance of `Cuprum::Result`. The result has a status (either `:success` or `:failure`), and may have a `#value` and/or an `#error` object. For more details about Cuprum::Result, [see below](#label-Results).
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommand)
-
-#### Defining Commands
+### Defining Commands
 
 The recommended way to define commands is to create a subclass of `Cuprum::Command` and override the `#process` method.
 
@@ -141,7 +134,7 @@ inspect_command = Cuprum::Command.new(&:inspect) # Equivalent to above.
 
 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.
 
-#### Result Values
+### Result Values
 
 Calling the `#call` method on a `Cuprum::Command` instance will always return an instance of `Cuprum::Result`. The result's `#value` property is determined by the object returned by the `#process` method (if the command is defined as a class) or the block (if the command is defined by passing a block to `Cuprum::Command.new`).
 
@@ -165,7 +158,7 @@ result.class #=> Cuprum::Result
 result.value #=> 'Greetings, programs!'
 ```
 
-#### Success, Failure, and Errors
+### Success, Failure, and Errors
 
 Each Result has a status, either `:success` or `:failure`. A Result will have a status of `:failure` when it was created with an error object. Otherwise, a Result will have a status of `:success`. Returning a failing Result from a Command indicates that something went wrong while executing the Command.
 
@@ -213,7 +206,61 @@ result.value    #=> book
 book.published? #=> false
 ```
 
-#### Composing Commands
+### Command Currying
+
+Cuprum::Command defines the `#curry` method, which allows for partial application of command objects. Partial application (more commonly referred to, if imprecisely, as currying) refers to fixing some number of arguments to a function, resulting in a function with a smaller number of arguments.
+
+In Cuprum's case, a curried (partially applied) command takes an original command and pre-defines some of its arguments. When the curried command is called, the predefined arguments and/or keywords will be combined with the arguments passed to #call.
+
+#### Currying Arguments
+
+We start by defining the base command. In this case, our base command takes two string arguments - a greeting and a person to be greeted.
+
+```ruby
+say_command = Cuprum::Command.new do |greeting, person|
+  "#{greeting}, #{person}!"
+end
+say_command.call('Hello', 'world')
+#=> returns a result with value 'Hello, world!'
+```
+
+Next, we create a curried command. Here, we pass in one argument. This will set the first argument to always be "Greetings"; therefore, our curried command only takes one argument, the name of the person being greeted.
+
+```ruby
+greet_command = say_command.curry('Greetings')
+greet_command.call('programs')
+#=> returns a result with value 'Greetings, programs!'
+```
+
+Alternatively, we could pass both arguments to `#curry`. In this case, our curried argument does not take any arguments, and will always return the same string.
+
+```ruby
+recruit_command = say_command.curry('Greetings', 'starfighter')
+recruit_command.call
+#=> returns a result with value 'Greetings, starfighter!'
+```
+
+#### Currying Keywords
+
+We can also pass keywords to `#curry`. Again, we start by defining our base command. In this case, our base command takes a mathematical operation (addition, subtraction, multiplication, etc) and a list of operands.
+
+```ruby
+math_command = Cuprum::Command.new do |operands:, operation:|
+  operations.reduce(&operation)
+end
+math_command.call(operands: [2, 2], operation: :+)
+#=> returns a result with value 4
+```
+
+Our curried command still takes two keywords, but now the operation keyword is optional. It now defaults to :\*, for multiplication.
+
+```ruby
+multiply_command = math_command.curry(operation: :*)
+multiply_command.call(operands: [3, 3])
+#=> returns a result with value 9
+```
+
+### Composing Commands
 
 Because Cuprum::Command instances are proper objects, they can be composed like any other object. For example, we could define some basic mathematical operations by composing commands:
 
@@ -224,6 +271,8 @@ increment_command.call(2).value #=> 3
 increment_command.call(3).value #=> 4
 
 add_command = Cuprum::Command.new do |addend, i|
+  # Here, we are composing commands together by calling the increment_command
+  # instance from inside the add_command definition.
   addend.times { i = increment_command(i).value }
 
   i
@@ -270,295 +319,308 @@ add_two_command.call(1).value #=> 3
 add_two_command.call(8).value #=> 10
 ```
 
-### Chaining Commands
+You can achieve even more powerful composition by passing in a command as an argument to a method, or by creating a method that returns a command.
+
+#### Commands As Arguments
 
-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.
+Since commands are objects, they can be passed in as arguments to a method or to another command. For example, consider a command that calls another command a given number of times:
 
 ```ruby
-name_command       = Cuprum::Command.new { |klass| klass.name }
-pluralize_command  = Cuprum::Command.new { |str| str.pluralize }
-underscore_command = Cuprum::Command.new { |str| str.underscore }
+class RepeatCommand
+  def initialize(count)
+    @count = count
+  end
 
-table_name_command =
-  name_command
-    .chain(pluralize_command)
-    .chain(underscore_command)
+  private
 
-result = table_name_command.call(LibraryCard)
-result.class #=> Cuprum::Result
-result.value #=> 'library_cards'
+  def process(command)
+    @count.times { command.call }
+  end
+end
+
+greet_command  = Cuprum::Command.new { puts 'Greetings, programs!' }
+repeat_command = RepeatCommand.new(3)
+repeat_command.call(greet_command) #=> prints 'Greetings, programs!' 3 times
 ```
 
-When the `table_name_command` is called, the class (in our case `LibraryCard`) is passed to the first command in the chain, which is the `name_command`. This produces a Result with a value of 'LibraryCard'. This value is then passed to `pluralize_command`, which returns a Result with a value of 'LibraryCards'. Finally, `underscore_command` is called and returns a Result with a value of 'library_cards'. Since there are no more commands in the chain, this final result is then returned.
+This is an implementation of the Strategy pattern, which allows us to customize the behavior of a part of our system by passing in implementation code rather than burying conditionals in our logic.
 
-Chained commands can also be defined with a block. This creates an anonymous command, equivalent to `Cuprum::Command.new {}`. Thus, the `table_name_command` could have been defined as either of these:
+Consider a more concrete example. Suppose we are running an online bookstore that sells both physuical and electronic books, and serves both domestic and international customers. Depending on what the customer ordered and where they live, our business logic for fulfilling an order will have different shipping instructions.
+
+Traditionally this would be handled with a conditional inside the order fulfillment code, which adds complexity. However, we can use the Strategy pattern and pass in our shipping code as a command.
 
 ```ruby
-table_name_command =
-  Cuprum::Command.new { |klass| klass.name }
-    .chain { |str| str.pluralize }
-    .chain { |str| str.underscore }
+class DeliverEbook < Cuprum::Command; end
+
+class ShipDomestic < Cuprum::Command; end
+
+class ShipInternational < Cuprum::Command; end
+
+class FulfillOrder < Cuprum::Command
+  def initialize(delivery_command)
+    @delivery_command = delivery_command
+  end
 
-table_name_command =
-  Cuprum::Command.new(&:name).chain(&:pluralize).chain(&:underscore)
+  private
+
+  def process(book:, user:)
+    # Here we will check inventory, process payments, and so on. The final step
+    # is actually delivering the book to the user:
+    delivery_command.call(book: book, user: user)
+  end
+end
 ```
 
-#### Chaining Details
+This pattern is also useful for testing. When writing specs for the FulfillOrder command, simply pass in a mock double as the delivery command. This removes any need to stub out the implementation of whatever shipping method is used (or worse, calls to external services).
+
+#### Commands As Returned Values
+
+We can also return commands as an object from a method call or from another command. One use case for this is the Abstract Factory pattern.
+
+Consider our shipping example, above. The traditional way to generate a shipping command is to use an `if-then-else` or `case` construct, which would be embedded in whatever code is calling `FulfillOrder`. This adds complexity and increases the testing burden.
 
-The `#chain` method is defined for instances of `Cuprum::Command` (or object that extend `Cuprum::Chaining`). Calling `#chain` on a command will always create a copy of the command. The given command is then added to the command chain for the copied command. The original command is unchanged. Thus:
+Instead, let's create a factory command. This command will take a user and a book, and will return the command used to ship that item.
 
 ```ruby
-first_command = Cuprum::Command.new { puts 'First command!' }
-first_command.call #=> Outputs 'First command!' to STDOUT.
+class ShippingMethod < Cuprum::Command
+  private
 
-second_command = first_command.chain { puts 'Second command!' }
-second_command.call #=> Outputs 'First command!' then 'Second command!'.
+  def process(book:, user:)
+    return DeliverEbook.new(user.email) if book.ebook?
 
-# The original command is unchanged.
-first_command.call #=> Outputs 'First command!' to STDOUT.
-```
+    return ShipDomestic.new(user.address) if user.address&.domestic?
 
-When a chained command is called, the original command is called with whatever parameters are passed in to the `#call` method, and the command executes the `#process` method as normal. Rather than returning the result, however, the next command in the chain is called. If the next command does not take any arguments, it is not passed any arguments. If the next command takes one or more arguments, it is passed the `#value` of that previous result. When the final command in the chain is called, that result is returned.
+    return ShipInternational.new(user.address) if user.address&.international?
 
-```ruby
-double_command    = Cuprum::Command.new { |i| 2 * i }
-increment_command = Cuprum::Command.new { |i| 1 + i }
-square_command    = Cuprum::Command.new { |i| i * i }
-chained_command   =
-  double_command
-    .chain(increment_command)
-    .chain(square_command)
+    err = Cuprum::Error.new(message: 'user does not have a valid address')
 
-# First, the double_commmand is called with 2. This returns a Cuprum::Result
-# with a value of 4.
-#
-# Next, the increment_command is called with 4, returning a result with value 5.
-#
-# Finally, the square_command is called with 5, returning a result with a value
-# of 25. This final result is returned by #call.
-result = chained_command.call(2)
-result.class #=> Cuprum::Result
-result.value #=> 25
+    failure(err)
+  end
+end
 ```
 
-#### Conditional Chaining
+Notice that our factory includes error handling - if the user does not have a valid address, that is handled immediately rather than when trying to ship the item.
 
-The `#chain` method can be passed an optional `on: value` keyword. This keyword determines whether or not the chained command will execute, based on the previous result status. Possible values are `:success`, `:failure`, `:always`, or `nil`. The default value is `nil`.
+The [Command Factory](#label-Command+Factories) defined by Cuprum is another example of using the Abstract Factory pattern to return command instances. One use case for a command factory would be defining CRUD operations for data records. Depending on the class or the type of record passed in, the factory could return a generic command or a specific command tied to that specific record type.
 
-If the command is chained with `on: :always`, or if the `:on` keyword is omitted, the chained command will always be executed after the previous command.
+### Command Steps
 
-If the command is chained with `on: :success`, then the chained command will only execute if the previous result is passing, e.g. the `#success?` method returns true. A result is passing if there is no `#error`, or if the status is set to `:success`.
+Separating out business logic into commands is a powerful tool, but it does come with some overhead, particularly when checking whether a result is passing, or when converting between results and values. When a process has many steps, each of which can fail or return a value, this can result in a lot of boilerplate.
 
-If the command is chained with `on: :failure`, then the chained command will only execute if the previous result is failing, e.g. the `#success?` method returns false. A result is failing if there is an `#error`, or if the status is set to `:failure`.
+The solution Cuprum provides is the `#step` method, which calls either a named method or a given block. If the result of the block or method is passing, then the `#step` method returns the value of the result.
 
 ```ruby
-find_command =
-  Cuprum::Command.new do |attributes|
-    book = Book.where(id: attributes[:id]).first
-
-    return book if book
+triple_command = Cuprum::Command.new { |i| success(3 * i) }
 
-    Cuprum::Result.new(error: 'Book not found')
-  end
-create_command =
-  Cuprum::Command.new do |attributes|
-    book = Book.new(attributes)
-
-    return book if book.save
+int = 2
+int = step { triple_command.call(int) } #=> returns 6
+int = step { triple_command.call(int) } #=> returns 18
+```
 
-    Cuprum::Result.new(error: book.errors.full_messages)
-  end
+Notice that in each step, we are returning the *value* of the result from `#step`, not the result itself. This means we do not need explicit calls to the `#value` method.
 
-find_or_create_command = find_command.chain(create_command, on: :failure)
+Of course, not all commands return a passing result. If the result of the block or method is failing, then `#step` will throw `:cuprum_failed_result` and the result, immediately halting the execution chain. If the `#step` method is used inside a command definition (or inside a `#steps` block; [see below](#label-Using+Steps+Outside+Of+Commands)), that symbol will be caught and the failing result returned by `#call`.
 
-# With a book that exists in the database, the find_command is called and
-# returns a result with no error and a value of the found book. The
-# create_command is not called.
-hsh    = { id: 0, title: 'Journey to the West' }
-result = find_or_create_command.call(hsh)
-book   = result.value
-book.id         #=> 0
-book.title      #=> 'Journey to the West'
-result.success? #=> true
-result.error    #=> nil
+```ruby
+divide_command = Cuprum::Command.new do |dividend, divisor|
+  return failure('divide by zero') if divisor.zero?
 
-# With a book that does not exist but with valid attributes, the find command
-# returns a failing result with a value of nil. The create_command is called and
-# creates a new book with the attributes, returning a passing result.
-hsh    = { id: 1, title: 'The Ramayana' }
-result = find_or_create_command.call(hsh)
-book   = result.value
-book.id         #=> 1
-book.title      #=> 'The Ramayana'
-result.success? #=> true
-result.error    #=> nil
+  success(dividend / divisor)
+end
 
-# With a book that does not exist and with invalid attributes, the find command
-# returns a failing result with a value of nil. The create_command is called and
-# is unable to create a new book with the attributes, returning the
-# (non-persisted) book and adding the validation errors.
-hsh    = { id: 2, title: nil }
-result = find_or_create_command.call(hsh)
-book   = result.value
-book.id         #=> 2
-book.title      #=> nil
-result.success? #=> false
-result.error    #=> ["Title can't be blank"]
+value = step { divide_command.call(10, 5) } #=> returns 2
+value = step { divide_command.call(2, 0) }  #=> throws :cuprum_failed_result
 ```
 
-### Advanced Chaining
+Here, the `divide_command` can either return a passing result (if the divisor is not zero) or a failing result (if the divisor is zero). When wrapped in a `#step`, the failing result is then thrown, halting execution.
 
-The `#tap_result` and `#yield_result` methods provide advanced control over the flow of chained commands.
+This is important when using a sequence of steps. Let's consider a case study - reserving a book from the library. This entails several steps, each of which could potentially fail:
 
-#### Tap Result
+- Validating that the user can reserve books. Maybe the user has too many unpaid fines.
+- Finding the requested book in the library system. Maybe the requested title isn't in the system.
+- Placing a reservation on the book. Maybe there are no copies of the book available to reserve.
 
-The `#tap_result` method allows you to insert arbitrary code into a command chain without affecting later commands. The method takes a block and yields the previous result, which is then returned and passed to the next command, or returned by `#call` if `#tap_result` is the last item in the chain.
+Using `#step`, as soon as one of the subtasks fails then the command will immediately return the failed value. This prevents us from hitting later subtasks with invalid data, it returns the actual failing result for analytics and for displaying a useful error message to the user, and it avoids the overhead (and the boilerplate) of exception-based failure handling.
 
 ```ruby
-command =
-  Cuprum::Command.new do
-    Cuprum::Result.new(value: 'Example value', error: 'Example error')
+class CheckUserStatus < Cuprum::Command; end
+
+class CreateBookReservation < Cuprum::Command; end
+
+class FindBookByTitle < Cuprum::Command; end
+
+class ReserveBookByTitle < Cuprum::Command
+  private
+
+  def process(title:, user:)
+    # If CheckUserStatus fails, #process will immediately return that result.
+    # For this step, we already have the user, so we don't need to use the
+    # result value.
+    step { CheckUserStatus.new.call(user) }
+
+    # Here, we are looking up the requested title. In this case, we will need
+    # the book object, so we save it as a variable. Notice that we don't need
+    # an explicit #value call - #step handles that for us.
+    book = step { FindBookByTitle.new.call(title) }
+
+    # Finally, we want to reserve the book. Since this is the last subtask, we
+    # don't strictly need to use #step. However, it's good practice, especially
+    # if we might need to add more steps to the command in the future.
+    step { CreateBookReservation.new.call(book: book, user: user) }
   end
-chained_command =
-  command
-    .tap_result do |result|
-      puts "The result value was #{result.inspect}"
-    end
+end
+```
 
-# Prints 'The result value was "Example value"' to STDOUT.
-result = chained_command.call
+First, our user may not have borrowing privileges. In this case, `CheckUserStatus` will fail, and neither of the subsequent steps will be called. The `#call` method will return the failing result from `CheckUserStatus`.
+
+```ruby
+result = ReserveBookByTitle.new.call(
+  title: 'The C Programming Language',
+  user:  'Ed Dillinger'
+)
 result.class    #=> Cuprum::Result
-result.value    #=> 'Example value'
 result.success? #=> false
-result.error    #=> 'Example error'
+result.error    #=> 'not authorized to reserve book'
 ```
 
-Like `#chain`, `#tap_result` can be given an `on: value` keyword.
+Second, our user may be valid but our requested title may not exist in the system. In this case, `FindBookByTitle` will fail, and the final step will not be called. The `#call` method will return the failing result from `FindBookByTitle`.
 
 ```ruby
-find_book_command =
-  Cuprum::Command.new do |book_id|
-    book = Book.where(id: book_id).first
+result = ReserveBookByTitle.new.call(
+  title: 'Using GOTO For Fun And Profit',
+  user:  'Alan Bradley'
+)
+result.class    #=> Cuprum::Result
+result.success? #=> false
+result.error    #=> 'title not found'
+```
 
-    return book if book
+Third, our user and book may be valid, but all of the copies are checked out. In this case, each of the steps will be called, and the `#call` method will return the failing result from `CreateBookReservation`.
 
-    Cuprum::Result.new(error: "Unable to find book with id #{book_id}")
-  end
+```ruby
+result = ReserveBookByTitle.new.call(
+  title: 'Design Patterns: Elements of Reusable Object-Oriented Software',
+  user:  'Alan Bradley'
+)
+result.class    #=> Cuprum::Result
+result.success? #=> false
+result.error    #=> 'no copies available'
+```
 
-chained_command =
-  find_book_command
-    .tap_result(on: :success) do |result|
-      render :show, locals: { book: result.value }
-    end
-    .tap_result(on: :failure) do
-      redirect_to books_path
-    end
+Finally, if each of the steps succeeds, the `#call` method will return the result of the final step.
 
-# Calls find_book_command with the id, which queries for the book and returns a
-# result with a value of the book and no error. Then, the first tap_result
-# block is evaluated, calling the render method and passing it the book via the
-# result.value method. Because the result is passing, the next block is skipped.
-# Finally, the result of find_book_command is returned unchanged.
-result = chained_command.call(valid_id)
+```ruby
+result = ReserveBookByTitle.new.call(
+  title: 'The C Programming Language',
+  user:  'Alan Bradley'
+)
 result.class    #=> Cuprum::Result
-result.value    #=> an instance of Book
 result.success? #=> true
-result.error    #=> nil
+result.value    #=> an instance of BookReservation
+```
 
-# Calls find_book_command with the id, which queries for the book and returns a
-# result with a value of nil and the error message. Because the result is
-# failing, the first block is skipped. The second block is then evaluated,
-# calling the redirect_to method. Finally, the result of find_book_command is
-# returned unchanged.
-result = chained_command.call(invalid_id)
-result.class    #=> Cuprum::Result
-result.value    #=> nil
-result.success? #=> false
-result.error    #=> ['Unable to find book with id invalid_id']
+#### Using Steps Outside Of Commands
+
+Steps can also be used outside of a command. For example, a controller action might define a sequence of steps to run when the corresponding endpoint is called.
+
+To use steps outside of a command, include the `Cuprum::Steps` module. Then, each sequence of steps should be wrapped in a `#steps` block as follows:
+
+```ruby
+steps do
+  step { check_something }
+
+  obj = step { find_something }
+
+  step :do_something, with: obj
+end
 ```
 
-#### Yield Result
+Each step will be executed in sequence until a failing result is returned by the block or method. The `#steps` block will return that failing result. If no step returns a failing result, then the return value of the block will be wrapped in a result and returned by `#steps`.
 
-The `#yield_result` method offers advanced control over a chained command step. The method takes a block and yields the previous result. If the object returned by the block is not a result, a new result is created with a value equal to the returned object. In either case, the result is returned and passed to the next command, or returned by `#call` if `#tap_result` is the last item in the chain.
+Let's consider the example of a controller action for creating a new resource. This would have several steps, each of which can fail:
 
-Unlike `#chain`, the block in `#yield_result` yields the previous result, not the previous value.
+- First, we build a new instance of the resource with the provided attributes. This can fail if the attributes are incompatible with the resource, e.g. with extra attributes not included in the resource's table columns.
+- Second, we run validations on the resource itself. This can fail if the attributes do not match the expected format.
+- Finally, we persist the resource to the database. This can fail if the record violates any database constraints, or if the database itself is unavailable.
 
 ```ruby
-chained_command =
-  Cuprum::Command.new do
-    'Example value'
+class BooksController
+  include Cuprum::Steps
+
+  def create
+    attributes = params[:books]
+    result     = steps do
+      @book = step :build_book, attributes
+
+      step :run_validations, @book
+
+      step :persist_book, book
+    end
+
+    result.success ? redirect_to(@book) : render(:edit)
   end
-  .yield_result do |result|
-    Cuprum::Result.new(error: 'Example error')
+
+  private
+
+  def build_book(attributes)
+    success(Book.new(attributes))
+  rescue InvalidAttributes
+    failure('attributes are invalid')
   end
-  .yield_result do |result|
-    "The last result was a #{result.success? ? 'success' : 'failure'}."
+
+  def persist_book(book)
+    book.save ? success(book) : failure('unable to persist book')
   end
 
-# The first command creates a passing result with a value of 'Example value'.
-#
-# This is passed to the first yield_result block, which creates a new result
-# with the same value and the string 'Example error' as the error object. It is
-# then passed to the next command in the chain.
-#
-# Finally, the second yield_result block is called, which checks the status of
-# the passed result. Since the final block does not return the previous result,
-# the previous result is discarded and a new result is created with the string
-# value starting with 'The last result was ...'.
-result = chained_command.call
-result.class    #=> Cuprum::Result
-result.value    #=> 'The last result was a failure.'
-result.success? #=> true
-result.error    #=> nil
+  def run_validations(book)
+    book.valid? ? success : failure('book is invalid')
+  end
+end
 ```
 
-Like `#chain`, `#yield_result` can be given an `on: value` keyword.
+A few things to note about this example. First, we have a couple of examples of wrapping existing code in a result, both by rescuing exceptions (in `#build_book`) or by checking a returned status (in `#persist_book`). Second, note that each of our helper methods can be reused in other controller actions. For even more encapsulation and reusability, the next step might be to convert those methods to commands of their own.
 
-Under the hood, both `#chain` and `#tap_result` are implemented on top of `#yield_result`.
+You can define even more complex logic by defining multiple `#steps` blocks. Each block represents a series of tasks that will terminate on the first failure. Steps blocks can even be nested in one another, or inside a `#process` method.
 
-#### Protected Chaining Methods
+### Handling Exceptions
 
-Each Command also defines the `#chain!`, `#tap_result!`, and `#yield_result!` methods - note the imperative `!`. These methods behave identically to their non-imperative counterparts, but they modify the current command directly instead of creating a clone. They are also protected methods, so they cannot be called from outside the command itself. These methods are designed for use when defining commands.
+    require 'cuprum/exception_handling'
+
+Cuprum defines a utility module to rescue uncaught exceptions when calling a command.
 
 ```ruby
-# We subclass the build command, which will be executed first.
-class CreateCommentCommand < BuildCommentCommand
-  include Cuprum::Chaining
-  include Cuprum::Processing
-  #
-  def initialize
-    # After the build step is run, we validate the comment.
-    chain!(ValidateCommentCommand.new)
-  #
-    # If the validation passes, we then save the comment.
-    chain!(SaveCommentCommand.new, on: :success)
+class UnsafeCommand < Cuprum::Command
+  private
+
+  def process
+    raise 'Something went wrong.'
   end
 end
 
-Comment.count #=> 0
+class SafeCommand < UnsafeCommand
+  include Cuprum::ExceptionHandling
+end
 
-body   = 'Why do hot dogs come in packages of ten, and hot dog buns come in ' \
-         'packages of eight?'
-result = CreateCommentCommand.new.call({ user_id: '12345', body: body })
+UnsafeCommand.new.call
+#=> raises a StandardError
 
-result.value    #=> an instance of Comment with the given user_id and body.
-result.success? #=> true
-Comment.count   #=> 1 - the comment was added to the database
+result = SafeCommand.new.call
+#=> a Cuprum::Result
+result.error
+#=> a Cuprum::Errors::UncaughtException error.
+result.error.message
+#=> 'uncaught exception in SafeCommand -' \
+    ' StandardError: Something went wrong.'
+```
 
-result = CreateCommentCommand.new.call({ user_id: nil, body: body })
+Exception handling is *not* included by default - add `include Cuprum::ExceptionHandling` to your command classes to use this feature.
 
-result.value    #=> an instance of Comment with the given user_id and body.
-result.success? #=> false
-result.error    #=> ["User id can't be blank"]
-Comment.count   #=> 1 - the comment was not added to the database
-```
+<a id="Results"></a>
 
-### Results
+## Results
 
     require 'cuprum'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FResult)
-
 A `Cuprum::Result` is a data object that encapsulates the result of calling a Cuprum command. Each result has a `#value`, an `#error` object (defaults to `nil`), and a `#status` (either `:success` or `:failure`, and accessible via the `#success?` and `#failure?` predicates).
 
 ```ruby
@@ -624,42 +686,58 @@ result.success? #=> true
 result.failure? #=> false
 ```
 
-### Errors
+<a id="Errors"></a>
 
-    require 'cuprum/error'
+## Errors
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FError)
+    require 'cuprum/error'
 
-A `Cuprum::Error` encapsulates a specific failure state of a Command. Each Error has a `#message` property, which defaults to nil.
+A `Cuprum::Error` encapsulates a specific failure state of a Command. Each Error has a `#message` property which defaults to nil. Each Error also has a `#type` property which is determined by the Error class or subclass, although it can be overridden by passing a `:type` parameter to the constructor.
 
 ```ruby
 error = Cuprum::Error.new
 error.message => # nil
+error.type    => 'cuprum.error'
 
 error = Cuprum::Error.new(message: 'Something went wrong.')
 error.message => # 'Something went wrong.'
+
+error = Cuprum::Error.new(type: 'example.custom_type')
+error.type => 'example.custom_type'
 ```
 
 Each application should define its own failure states as errors. For example, a typical web application might define the following errors:
 
 ```ruby
 class NotFoundError < Cuprum::Error
+  TYPE = 'example.errors.not_found'
+
   def initialize(resource:, resource_id:)
     @resource    = resource
     @resource_id = resource_id
 
-    super(message: "#{resource} not found with id #{resource_id}")
+    super(
+      message:     "#{resource} not found with id #{resource_id}",
+      resource:    resource,
+      resource_id: resource_id
+    )
   end
 
   attr_reader :resource, :resource_id
 end
 
 class ValidationError < Cuprum::Error
+  TYPE = 'example.errors.validation'
+
   def initialize(resource:, errors:)
     @resource = resource
     @errors   = errors
 
-    super(message: "#{resource} was invalid")
+    super(
+      errors:   errors,
+      message:  "#{resource} was invalid",
+      resource: resource
+    )
   end
 
   attr_reader :resource, :errors
@@ -668,11 +746,185 @@ end
 
 It is optional but recommended to use a `Cuprum::Error` when returning a failed result from a command.
 
-### Operations
+### Comparing Errors
 
-    require 'cuprum'
+There are circumstances when it is useful to compare Error objects, such as when writing tests to specify the failure states of a command. To accommodate this, you can pass additional properties to `Cuprum::Error.new` (or to `super` when defining a subclass). These "comparable properties", plus the type and message (if any), are used to compare the errors.
+
+An instance of `Cuprum::Error` is equal to another (using the `#==` equality comparison) if and only if the two errors have the same `class` and the two errors have the same comparable properties.
+
+```ruby
+red     = Cuprum::Error.new(message: 'wrong color', color: 'red')
+blue    = Cuprum::Error.new(message: 'wrong color', color: 'blue')
+crimson = Cuprum::Error.new(message: 'wrong color', color: 'red')
+
+red == blue
+#=> false
+
+red == crimson
+#=> true
+```
+
+This can be particularly important when defining Error subclasses. By passing the constructor parameters to `super`, below, we will be able to compare different instances of the `NotFoundError`. The errors will only be equal if they have the same message, resource, and resource_id properties.
+
+```ruby
+class NotFoundError < Cuprum::Error
+  def initialize(resource:, resource_id:)
+    @resource    = resource
+    @resource_id = resource_id
+
+    super(
+      message:     "#{resource} not found with id #{resource_id}",
+      resource:    resource,
+      resource_id: resource_id,
+    )
+  end
+
+  attr_reader :resource, :resource_id
+end
+```
+
+Finally, by overriding the `#comparable_properties` method, you can customize how Error instances are compared.
+
+```ruby
+class WrongColorError < Cuprum::Error
+  def initialize(color:, shape:)
+    super(message: "the #{shape} is the wrong color")
+
+    @color = color
+    @shape = shape
+  end
+
+  attr_reader :color
+
+  protected
+
+  def comparable_properties
+    { color: color }
+  end
+end
+```
+
+### Serializing Errors
+
+Some use cases require serializing error objects - for example, rendering an error response as JSON. To handle this, `Cuprum::Error` defines an `#as_json` method, which generates a representation of the error as a `Hash` with `String` keys. By default, this includes the `#type` and `#message` (if any) as well as an empty `:data` Hash.
+
+Subclasses can override this behavior to include additional information in the `:data` Hash, which should always use `String` keys and have values composed of basic types and data structures. For example, if an error is passed a `Class`, consider serializing the name of the class to `:data`.
+
+```ruby
+error = Cuprum::Error.new
+error.as_json #=> { data: {}, message: nil, type: 'cuprum.error' }
+
+error = Cuprum::Error.new(message: 'Something went wrong.')
+error.as_json #=> { data: {}, message: 'Something went wrong.', type: 'cuprum.error' }
+
+error = Cuprum::Error.new(type: 'example.custom_error')
+error.as_json #=> { data: {}, message: nil, type: 'example.custom_error' }
+
+class ModuleError < Cuprum::Error
+  TYPE = 'example.module_error'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
+  def initialize(actual:)
+    @actual = actual
+    message = "Expected a Module, but #{actual.name} is a Class"
+
+    super(actual: actual, message: message)
+  end
+
+  attr_reader :actual
+
+  private
+
+  def as_json_data
+    { actual: actual.name }
+  end
+end
+
+error = ModuleError.new(actual: String)
+error.as_json #=>
+# {
+#   data:    { actual: 'String' },
+#   message: 'Expected a Module, but String is a Class',
+#   type:    'example.module_error'
+# }
+```
+
+**Important Note:** Be careful when serializing error data - this may expose sensitive information or internal details about your system that you don't want to display to users. Recommended practice is to have a whitelist of serializable errors; all other errors will display a generic error message instead.
+
+<a id="Middleware"></a>
+
+## Middleware
+
+```ruby
+require 'cuprum/middleware'
+```
+
+A middleware command wraps the execution of another command, allowing the developer to compose functionality without an explicit wrapper command. Because the middleware is responsible for calling the wrapped command, it has control over when that command is called, with what parameters, and how the command result is handled.
+
+To use middleware, start by defining a middleware command. This can either be a class that includes Cuprum::Middleware, or a command instance that extends Cuprum::Middleware. Each middleware command's #process method takes as its first argument the wrapped command. By convention, any additional arguments and any keywords or a block are passed to the wrapped command, but some middleware will override ths behavior.
+
+```ruby
+class ExampleCommand < Cuprum::Command
+  private def process(**options)
+    return failure(options[:error]) if options[:error]
+
+    "Options: #{options.inspect}"
+  end
+end
+
+class LoggingMiddleware < Cuprum::Command
+  include Cuprum::Middleware
+
+  # The middleware injects a logging step before the wrapped command is
+  # called. Notice that this middleware is generic, and can be used with
+  # virtually any other command.
+  private def process(next_command, *args, **kwargs)
+    Logger.info("Calling command #{next_command.class}")
+
+    super
+  end
+end
+
+command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+middleware = LoggingMiddleware.new
+result     = middleware.call(command, { id: 0 })
+#=> logs "Calling command ExampleCommand"
+result.value
+#=> "Options: { id: 0 }"
+```
+
+When defining #process, make sure to either call super or call the wrapped command directly, unless the middleware is specifically intended not to call the wrapped command under those circumstances.
+
+Middleware is powerful because it allows the developer to manipulate the parameters passed to a command, add handling to a result, or even intercept or override the command execution. These are some of the possible use cases for middleware:
+
+- Injecting code before or after a command.
+- Changing the parameters passed to a command.
+- Adding behavior based on the command result.
+- Overriding the command behavior based on the parameters.
+
+```ruby
+class AuthenticationMiddleware < Cuprum::Command
+  include Cuprum::Middleware
+
+  # The middleware finds the current user based on the given keywords. If
+  # a valid user is found, the user is then passed on to the command.
+  # If a user is not found, then the middleware will immediately halt (due
+  # to #step) and return the failing result from the authentication
+  # command.
+  private def process(next_command, *args, **kwargs)
+    current_user = step { AuthenticateUser.new.call(**kwargs) }
+
+    super(next_command, *args, current_user: current_user, **kwargs)
+  end
+end
+```
+
+Middleware is loosely coupled, meaning that one middleware command can wrap any number of other commands. One example would be logging middleware, which could record when a command is called and with what parameters. For a more involved example, consider authorization in a web application. If individual actions are defined as commands, then a single authorization middleware class could wrap each individual action, reducing both the testing burden and the amount of code that must be maintained.
+
+<a id="Operations"></a>
+
+## Operations
+
+    require 'cuprum'
 
 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.
 
@@ -703,15 +955,239 @@ Like a Command, an Operation can be defined directly by passing an implementatio
 
 An operation inherits the `#call` method from Cuprum::Command (see above), and delegates the `#value`, `#error`, `#success?`, and `#failure` methods to the most recent result. If the operation has not been called, these methods will return default values.
 
-#### The Operation Mixin
-
-[Module Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation%2FMixin)
+### The Operation Mixin
 
 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.
 
-### Command Factories
+<a id="Matchers"></a>
+
+## Matchers
+
+    require 'cuprum/matcher'
+
+A Matcher provides a simple DSL for defining behavior based on a Cuprum result object.
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:failure) { 'Something went wrong' }
+
+  match(:success) { 'Ok' }
+end
+
+matcher.call(Cuprum::Result.new(status: :failure))
+#=> 'Something went wrong'
+
+matcher.call(Cuprum::Result.new(status: :success))
+#=> 'Ok'
+```
+
+First, the matcher defines possible matches using the `.match` method. This can either be called on a subclass of `Cuprum::Matcher` or by passing a block to the constructor, as above. Each match clause must have the matching status, and a block that is executed when a result matches that clause. The clause can also filter by the result value or error (see Matching Values And Errors, below).
+
+Once the matcher has found a matching clause, it then calls the block in the clause definition. If the block accepts an argument, the result is passed to the block; otherwise, the block is called with no arguments. This allows the match clause to use the error or value of the result.
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:failure) { |result| result.error.message }
+end
+
+error = Cuprum::Error.new(message: 'An error has occurred.')
+matcher.call(Cuprum::Result.new(error: error))
+#=> 'An error has occurred.'
+```
+
+If the result does not match any of the clauses, a `Cuprum::Matching::NoMatchError` is raised.
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:success) { :ok }
+end
+
+matcher.call(Cuprum::Result.new(status: :failure))
+#=> raises Cuprum::Matching::NoMatchError
+```
+
+### Matching Values And Errors
+
+In addition to a status, match clauses can specify the type of the value or error of a matching result. The error or value must be a Class or Module, and the clause will then match only results whose error or value is an instance of the specified Class or Module (or a subclass of the Class).
+
+```ruby
+class MagicSmokeError < Cuprum::Error; end
+
+matcher = Cuprum::Matcher.new do
+  match(:failure) { 'Something went wrong.' }
+
+  match(:failure, error: Cuprum::Error) do |result|
+    "ERROR: #{result.error.message}"
+  end
+
+  match(:failure, error: MagicSmokeError) do
+    "PANIC: #{result.error.message}"
+  end
+end
+
+matcher.call(Cuprum::Result.new(status: :failure))
+#=> 'Something went wrong.'
+
+error = Cuprum::Error.new(message: 'An error has occurred.')
+matcher.call(Cuprum::Result.new(error: error)
+#=> 'ERROR: An error has occurred.'
+
+error = MagicSmokeError.new(message: 'The magic smoke is escaping.')
+matcher.call(Cuprum::Result.new(error: error))
+#=> 'PANIC: The magic smoke is escaping.'
+```
+
+The matcher will always apply the most specific match clause. In the example above, the result with a `MagicSmokeError` matches all three clauses, but only the final clause is executed.
+
+You can also specify the value of a matching result:
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:success, value: String) { 'a String' }
+
+  match(:success, value: Symbol) { 'a Symbol' }
+end
+
+matcher.call(Cuprum::Result.new(value: 'Greetings, programs!'))
+#=> 'a String'
+
+matcher.call(Cuprum::Result.new(value: :greetings_starfighter))
+#=> 'a Symbol'
+```
+
+### Using Matcher Classes
+
+Matcher classes allow you to define custom behavior that can be called as part of the defined match clauses.
+
+```ruby
+class LogMatcher < Cuprum::Matcher
+  match(:failure) { |result| log(:error, result.error.message) }
+
+  match(:success) { log(:info, 'Ok') }
+
+  def log(level, message)
+    puts "#{level.upcase}: #{message}"
+  end
+end
+
+matcher = LogMatcher.new
+matcher.call(Cuprum::Result.new(status: :success))
+#=> prints "INFO: Ok" to STDOUT
+```
+
+Match clauses are also inherited by matcher subclasses. Inherited clauses are sorted the same as clauses defined on the matcher directly - the most specific clause is matched first, followed by less specific clauses and finally the generic clause (if any) for that result status.
+
+```ruby
+class CustomLogMatcher < Cuprum::Matcher
+  match(:failure, error: ReallyBadError) do |result|
+    log(:fatal, result.error.message)
+  end
+end
+
+matcher = CustomLogMatcher.new
+result  = Cuprum::Result.new(error: Cuprum::Error.new('Something went wrong.'))
+matcher.call(result)
+#=> prints "ERROR: Something went wrong." to STDOUT
+
+result  = Cuprum::Result.new(error: ReallyBadError.new('Computer on fire.'))
+matcher.call(result)
+#=> prints "FATAL: Computer on fire." to STDOUT
+```
+
+### Match Contexts
+
+Match contexts provide an alternative to defining custom matcher classes - instead of defining custom behavior in the matcher itself, the match clauses can be executed in the context of another object.
+
+```ruby
+class Inflector
+  def capitalize(message)
+    message.split(' ').map(&:capitalize).join(' ')
+  end
+end
+
+matcher = Cuprum::Matcher.new(inflector) do
+  match(:success) { |result| capitalize(result.value) }
+end
+matcher.call(Cuprum::Result.new(value: 'greetings starfighter'))
+#=> 'Greetings Starfighter'
+```
+
+For example, a controller in a web framework might need to define behavior for handling different success and error cases for business logic that is defined as Commands. The controller itself defines methods such as `#render` and `#redirect` - by creating a matcher using the controller as the match context, the matcher can call upon those methods to generate a response.
+
+You can also call an existing matcher with a new context. The `#with_context` method returns a copy of the matcher with the given object set as the match context.
+
+```ruby
+matcher = Cuprum::Matcher.new do
+  match(:success) { |result| capitalize(result.value) }
+end
+matcher
+  .with_context(inflector)
+  .call(Cuprum::Result.new(value: 'greetings starfighter'))
+#=> 'Greetings Starfighter'
+```
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommandFactory)
+### Matcher Lists
+
+Matcher lists handle matching a result against an ordered group of matchers.
+
+When given a result, a matcher list will check for the most specific matching clause in each of the matchers. A clause matching both the value and error will match first, followed by a clause matching only the result value or error, and finally a clause matching only the result status will match.
+
+If none of the matchers have a clause that matches the result, a `Cuprum::Matching::NoMatchError` will be raised.
+
+```ruby
+generic_matcher = Cuprum::Matcher.new do
+  match(:failure) { 'generic failure' }
+  #
+  match(:failure, error: CustomError) { 'custom failure' }
+end
+specific_matcher = Cuprum::Matcher.new do
+  match(:failure, error: Cuprum::Error) { 'specific failure' }
+end
+matcher_list = Cuprum::MatcherList.new(
+  [
+    specific_matcher,
+    generic_matcher
+  ]
+)
+
+generic_matcher = Cuprum::Matcher.new do
+  match(:failure) { 'generic failure' }
+
+  match(:failure, error: CustomError) { 'custom failure' }
+end
+specific_matcher = Cuprum::Matcher.new do
+  match(:failure, error: Cuprum::Error) { 'specific failure' }
+end
+matcher_list = Cuprum::MatcherList.new(
+  [
+    specific_matcher,
+    generic_matcher
+  ]
+)
+
+# A failure without an error does not match the first matcher, so the
+# matcher list continues on to the next matcher in the list.
+result = Cuprum::Result.new(status: :failure)
+matcher_list.call(result)
+#=> 'generic failure'
+
+# A failure with an error matches the first matcher.
+error  = Cuprum::Error.new(message: 'Something went wrong.')
+result = Cuprum::Result.new(error: error)
+matcher_list.call(result)
+#=> 'specific failure'
+
+# A failure with an error subclass still matches the first matcher, even
+# though the second matcher has a more exact match.
+error  = CustomError.new(message: 'The magic smoke is escaping.')
+result = Cuprum::Result.new(error: error)
+matcher_list.call(result)
+#=> 'specific failure'
+```
+
+One use case for matcher lists would be in defining hierarchies of classes or objects that have matching functionality. For example, a generic controller class might define default success and failure behavior, an included mixin might provide handling for a particular scope of errors, and a specific controller might override the default behavior for a given action. Using a matcher list allows each class or module to define its own behavior as independent matchers, which the matcher list then composes together.
+
+## Command Factories
 
 Commands are powerful and flexible objects, but they do have a few disadvantages compared to traditional service objects which allow the developer to group together related functionality and shared implementation details. To bridge this gap, Cuprum implements the CommandFactory class. Command factories provide a DSL to quickly group together related commands and create context-specific command classes or instances.
 
@@ -764,7 +1240,7 @@ book.author    #=> 'Ursula K. Le Guin'
 book.publisher #=> nil
 ```
 
-#### The ::command Method And A Command Class
+### The ::command Method And A Command Class
 
 The first way to define a command for a factory is by calling the `::command` method and passing it the name of the command and a command class:
 
@@ -776,7 +1252,7 @@ end
 
 This makes the command class available on a factory instance as `::Build`, and generates the `#build` method which returns an instance of `BuildBookCommand`.
 
-#### The ::command Method And A Block
+### The ::command Method And A Block
 
 By calling the `::command` method with a block, you can define a command with additional control over how the generated command. The block must return an instance of a subclass of Cuprum::Command.
 
@@ -885,7 +1361,7 @@ ary     = result.value              #=> an array with the selected books
 ary.count #=> 1
 ```
 
-#### The ::command_class Method
+### The ::command_class Method
 
 The final way to define a command for a factory is calling the `::command_class` method with the command name and a block. The block must return a subclass (not an instance) of Cuprum::Command. This offers a balance between flexibility and power.
 
@@ -1009,16 +1485,14 @@ books.count          #=> 4
 books.include?(book) #=> true
 ```
 
-### Built In Commands
+## Built In Commands
 
 Cuprum includes a small number of predefined commands and their equivalent operations.
 
-#### IdentityCommand
+### IdentityCommand
 
     require 'cuprum/built_in/identity_command'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityCommand)
-
 A pregenerated command that returns the value or result with which it was called.
 
 ```ruby
@@ -1028,12 +1502,10 @@ result.value    #=> 'expected value'
 result.success? #=> true
 ```
 
-#### IdentityOperation
+### 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.
 
 ```ruby
@@ -1042,12 +1514,10 @@ operation.value    #=> 'expected value'
 operation.success? #=> true
 ```
 
-#### NullCommand
+### NullCommand
 
     require 'cuprum/built_in/null_command'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullCommand)
-
 A pregenerated command that does nothing when called. Accepts any arguments.
 
 ```ruby
@@ -1057,12 +1527,10 @@ result.value    #=> nil
 result.success? #=> true
 ```
 
-#### NullOperation
+### NullOperation
 
     require 'cuprum/built_in/null_operation'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullOperation)
-
 A pregenerated operation that does nothing when called. Accepts any arguments.
 
 ```ruby
@@ -1070,279 +1538,3 @@ operation = Cuprum::BuiltIn::NullOperation.new.call
 operation.value    #=> nil
 operation.success? #=> true
 ```
-
-## Reference
-
-### Cuprum::BuiltIn::IdentityCommand
-
-    require 'cuprum/built_in/identity_command'
-
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityCommand)
-
-Cuprum::BuiltIn::IdentityCommand defines the following methods:
-
-#### `#call`
-
-    call(value) #=> Cuprum::Result
-
-Returns a result, whose `#value` is equal to the given value.
-
-### Cuprum::BuiltIn::IdentityOperation
-
-    require 'cuprum/built_in/identity_operation'
-
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityOperation)
-
-Cuprum::BuiltIn::IdentityOperation defines the following methods:
-
-#### `#call`
-
-    call(value) #=> Cuprum::BuiltIn::IdentityOperation
-
-Sets the last result to a new result, whose `#value` is equal to the given value.
-
-### Cuprum::BuiltIn::NullCommand
-
-    require 'cuprum/built_in/null_command'
-
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullCommand)
-
-Cuprum::BuiltIn::NullCommand defines the following methods:
-
-#### `#call`
-
-    call(*args, **keywords) { ... } #=> Cuprum::Result
-
-Returns a result with nil value. Any arguments or keywords are ignored.
-
-### Cuprum::BuiltIn::NullOperation
-
-    require 'cuprum/built_in/null_operation'
-
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullOperation)
-
-Cuprum::BuiltIn::NullOperation defines the following methods:
-
-#### `#call`
-
-    call(*args, **keywords) { ... } #=> Cuprum::BuiltIn::NullOperation
-
-Sets the last result to a result with nil value. Any arguments or keywords are ignored.
-
-### Cuprum::Command
-
-    require 'cuprum'
-
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommand)
-
-A Cuprum::Command defines the following methods:
-
-#### `#initialize`
-
-    initialize { |*arguments, **keywords, &block| ... } #=> Cuprum::Command
-
-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.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#initialize-instance_method)
-
-#### `#call`
-
-    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 the block returns a Cuprum::Result (or an object responding to `#to_cuprum_result`), 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)
-
-#### `#chain!`
-
-*(Protected Method)*
-
-    chain!(on: nil) { |result| ... } #=> Cuprum::Command
-
-    chain!(command, on: nil) #=> Cuprum::Command
-
-As `#chain`, but modifies the current command instead of creating a clone.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#chain!-instance_method)
-
-#### `#tap_result`
-
-    tap_result(on: nil) { |previous_result| } #=> Cuprum::Result
-
-Creates a copy of the command, and then chains the block to execute after the command implementation. When #call is executed, each chained block will be yielded the previous result, and the previous result returned or yielded to the next block. The return value of the block is discarded.
-
-If the `on` parameter is set to `:success`, the block will be called if the last result is successful. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing. Finally, if the `on` parameter is set to `:always` or to `nil`, the block will always be called.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#tap_result-instance_method)
-
-#### `#tap_result!`
-
-*(Protected Method)*
-
-    tap_result!(on: nil) { |previous_result| } #=> Cuprum::Result
-
-As `#tap_result`, but modifies the current command instead of creating a clone.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#tap_result!-instance_method)
-
-#### `#yield_result`
-
-    yield_result(on: nil) { |previous_result| } #=> Cuprum::Result
-
-Creates a copy of the command, and then chains the block to execute after the command implementation. When #call is executed, each chained block will be yielded the previous result, and the return value wrapped in a result and returned or yielded to the next block.
-
-If the `on` parameter is set to `:success`, the block will be called if the last result is successful. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing. Finally, if the `on` parameter is set to `:always` or to `nil`, the block will always be called.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#yield_result-instance_method)
-
-#### `#yield_result!`
-
-*(Protected Method)*
-
-    yield_result!(on: nil) { |previous_result| } #=> Cuprum::Result
-
-As `#yield_result`, but modifies the current command instead of creating a clone.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#yield_result!-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:
-
-#### `#==`
-
-    ==(other) #=> true, false
-
-Performs a fuzzy comparison with the other object. At a minimum, the other object must respond to `#value`, `#success?`, `#error` and the values of `other.value`, `other.success?`, and `other.error` must be equal to the corresponding value on the result. Returns true if all values match, otherwise returns false.
-
-#### `#error`
-
-    error() #=> nil
-
-The error generated by the command, or `nil` if no error was generated.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#error-instance_method)
-
-#### `#failure?`
-
-    failure?() #=> true, false
-
-True if the command generated an error or was marked as failing. Otherwise false.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure%3F-instance_method)
-
-#### `#success?`
-
-    success?() #=> true, false
-
-True if the command did not generate an error, or the result has an error but was marked as passing. Otherwise false.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#success%3F-instance_method)
-
-#### `#value`
-
-    value() #=> Object
-
-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.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#value-instance_method)
-
-### Cuprum::Utilities::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 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.
-
-#### `::clear_spies`
-
-    clear_spies() #=> nil
-
-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.
-
-    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)
-
-#### `::spy_on`
-
-    spy_on(command_class) #=> InstanceSpy
-    spy_on(command_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 command.
-    spy = Cuprum::Utils::InstanceSpy.spy_on(CustomCommand)
-
-    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
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#spy_on%3F-instance_method)