cuprum 0.7.0 → 0.10.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8d393a222eda76e4b943c721df4a4d54c89966e9
-  data.tar.gz: d0e9efa6075c9346114ecb02883b380621873510
+SHA256:
+  metadata.gz: 8ca65deb82f58ec6a0b9706a7eb81f6edc191ecf54d22a9e3155a82370aec83e
+  data.tar.gz: e259228f7b6128c24a0974666165a0655c4188f1011519c8d9dea498c5d59008
 SHA512:
-  metadata.gz: 196f5f4472c76d664f4d6b8764503a7fee5fabae50061edc877d1cc060421b05067861c96fc654a8a2586911c318b6ff9d65e515c299ffaed647f9742021dd88
-  data.tar.gz: c1cd4f744cdfb37493f100de095ef89d1e3c080ae59f99af76ca43c69f8aaeaf14cfddc9068a824956da2e19aed4017bb70e6bb6d608969ea6e4acc5f096f875
+  metadata.gz: eafd3d6b85ca035cec50fdbbaacf3f3238cfa1a624de85f0663fdfcef4aeb91298f08ee11915631d3f82069222ca641279c243a6d2087a8b29cc0cf1bd01bd01
+  data.tar.gz: '080089f9d312a1019e934e7ed84e6df92b566c2bff83c9472671c0bed9f3738762345082d99f298af70eab33f1ec8af6809310ee2a3f90cd65544a618e812fb8'

data/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 0.10
+
+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 1.0.
+
+#### 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
+
+Delegate Operation#status to the most recent result.
+
+### RSpec
+
+The #be_a_passing_result macro now automatically adds a `with_error(nil)` expectation.
+
+- This causes the error (if any) to be displayed when matching a failing result.
+- This may break some cases when expecting a passing result that still has an error; in these cases, add an error expectation to the call, e.g. `expect().to be_a_passing_result.with_error(some_error)`.
+
+Improve failure message of BeAResultMatcher under some circumstances.
+
+## 0.9.0
+
+The "'Tis Not Too Late To Seek A Newer World" Update
+
+Major refactoring of Command processing and the Result object. This update is **not** backwards compatible.
+
+### Commands
+
+Removed the `#success` and `#failure` chaining helpers.
+
+Permanently removed the deprecated ResultHelpers mixin.
+
+### Errors
+
+Added `Cuprum::Error`, which encapsulates the failure state of a result. It is *recommended*, but not required, that when creating a failing Result, the `:error` property be set to an instance of `Cuprum::Error`.
+
+### Results
+
+Results are now nominally immutable objects. All mutator methods have been removed, including `#failure!`, `#success!`, and `#update`. The `#empty?` predicate has also been removed.
+
+Updated the constructor to take the following keyword arguments: `:value`, `:error`, and `:status`.
+
+- The status can now be overridden on a new Result by passing in the `:status`.
+- Resolves an issue when attempting to instantiate a result with a Hash value.
+- *Note:* The value must now be passed in as a keyword.
+- *Note:* The `:errors` keyword has been renamed to `:error`.
+
+Removed the `:halted` status.
+
+### Other Changes
+
+Removed the `Cuprum#warn` functionality.
+
+### Upgrade Notes
+
+Anywhere a new `Cuprum::Result` is created directly, update the arguments to match the new `value:` and `error:` keywords.
+
+Anywhere the `#result` is referenced inside a command, instead return the desired value directly, or return a result with the desired error.
+
+Anywhere a command is chained with the `#success` or `#failure` shorthand, use the full `chain(on: :success)` or `chain(on: :failure)` format.
+
+## 0.8.0
+
+The "We Have The Technology" Update.
+
+### Commands
+
+Added protected chaining methods `#chain!`, `#tap_result!` and `#yield_result!`. These methods function as their non-imperative counterparts, but add the chained command or block to the current command instead of a clone.
+
+Removed the ResultHelpers mixin from the default Command class. To use the result helper methods, include Cuprum::ResultHelpers in your command class.
+
+Removed the #build_errors helper - each Result is now responsible for building its own errors object. To use a custom errors object, define a subclass of Cuprum::Result and override its #build_errors method, then update your Command's #build_result method to use your custom result class.
+
+### Command Factory
+
+Implemented the CommandFactory class, which provides a builder interface and DSL for grouping and creating commands with a common purpose or with shared configuration.
+
 ## 0.7.0
 
 The "To Strive, To Seek, To Find, And Not To Yield" Update.
@@ -44,21 +136,21 @@ The "Name Not Found For NullFunction" Update.
 
 Added the `Cuprum::warn` helper, which prints a warning message. By default, `::warn` delegates to `Kernel#warn`, but can be configured (e.g. to call a Logger) by setting `Cuprum::warning_proc=` with a Proc that accepts one argument (the message to display).
 
-## Operations
+### Operations
 
 The implementation of `Cuprum::Operation` has been extracted to a module at `Cuprum::Operation::Mixin`, allowing users to easily convert an existing function class or instance to an operation.
 
-## Results
+### Results
 
 Implemented `Cuprum::Result#==` as a fuzzy comparison, allowing a result to be equal to any object with the same value and status.
 
 Implemented `Cuprum::Result#empty?`, which returns true for a new result and false for a result with a value, with non-empty errors, a result with set status, or a halted result.
 
-## Utilities
+### Utilities
 
 Added the `Cuprum::Utils::InstanceSpy` module to empower testing of code that calls a function without providing a reference, such as some chained functions.
 
-## Built In Functions
+### Built In Functions
 
 Added the `NullFunction` and `NullOperation` predefined classes, which do nothing when called and return a result with no errors and a value of nil.
 
@@ -68,7 +160,7 @@ Added the `IdentityFunction` and `IdentityOperation` predefined classes, which r
 
 The "Halt And Catch Fire" Update.
 
-## Functions
+### Functions
 
 Can now call `#success!` or `#failure!` in a function block or `#process` method to override the default, error-based status for the result. This allows for a passing result that still has errors, or a failing result that does not have explicit errors.
 
@@ -78,11 +170,11 @@ Can now generate results with custom error objects by overriding the `#build_err
 
 Fixed an inconsistency issue when a function block or `#process` method returned an instance of `Cuprum::Result`.
 
-## Operations
+### Operations
 
 Calling `#call` on an operation now returns the operation instance.
 
-## Results
+### Results
 
 Can now call `#success!` or `#failure!` to override the default, error-based status.
 
@@ -92,11 +184,11 @@ Can now call `#halt!` and check the `#halted?` status. A halted result will prev
 
 The "Nothing To Lose But Your Chains" Update.
 
-## Functions
+### Functions
 
 Now support chaining via the `#chain`, `#then`, and `#else` methods.
 
-## Results
+### Results
 
 Can pass a value and/or an errors object to the constructor.
 

data/DEVELOPMENT.md

@@ -1,30 +1,44 @@
 # Development
 
-## Version 1.0.0+
+## Version 1.0.0
 
-'The "Look On My Works, Ye Mighty, and Despair" Update'
+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
+- Status Badges!
+
+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 }
 
 ### Commands
 
-- Protected Chaining Methods:
-  - #chain!, #success!, #failure!, #tap_chain!, #yield_result!
-  - adds chained command to current command instead of a clone.
 - Command#to_proc
-- :clear_errors => true option on #chain
-- #context object
-- command currying
 
-#### Cuprum::DSL
+## Future Versions
+
+### Commands
+
+- Implement #<<, #>> composition methods.
+  - Calls commands in order passing values.
+  - Return Result early on Failure (or not Success), otherwise final Result.
+
+#### DSL
 
 - ::process - shortcut for defining #process
 - ::rescue - `rescue StandardError do ... end`, rescues matched errors in #process
-- chaining 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.
 - constructor methods:
   - Programmatically generate a constructor method. Raises an error if
     #initialize is defined. Automatically sets instance variables on initialize,
@@ -35,41 +49,49 @@
     optional arguments and their default values.
   - ::keywords - sets keyword arguments; same arguments as ::arguments.
 
-#### Hooks
+#### Dependency Injection
 
-- :before, :around, :after hooks
+- 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
-
-### CommandFactory
-
-- builder/aggregator for command objects, esp. with shared
-  initializers/parameters, e.g. actions for a resource
-- Syntax: |
-
-  actions = ResourceCommandFactory.new(Book)
-  command = actions::Build.new        #=> returns a book builder command
-  result  = command.call(attributes)  #=> returns a result with value => a Book
-  # OR
-  result  = actions.build(attributes) #=> returns a result with value => a Book
-  book    = result.value
-
-### Documentation
-
-Chaining 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 }
+- RetryCommand - takes command, retry count
+  - optional only:, except: - restrict what errors are retried
+
+### Matcher
+
+- Handle success(), failure(), failure(SomeError) cases.
+  - Custom matcher to handle additional cases - halted, pending, etc?
+
+### Middleware
+
+- Implement Command.subclass
+  - Curries constructor arguments
+- Implement Cuprum::Middleware
+  - #process takes next command, \*args, \*\*kwargs
+    - calls next command with \*args, \*\*kwargs
+  - .apply takes middleware: array, root: command
+- 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
+
+- 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
+
+### Steps::Strict
+
+- #step raises exception unless block or method returns a result

data/README.md

@@ -6,7 +6,8 @@ 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) - A data object with a `#value`, an `#errors` object, and `#success?` and `#failure?` status methods.
+- [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.
 
 ## About
 
@@ -22,16 +23,16 @@ Traditional frameworks such as Rails focus on the objects of your application -
 
 ### 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.4.
+Cuprum is tested against Ruby (MRI) 2.3 through 2.5.
 
 ### Documentation
 
@@ -41,7 +42,7 @@ Documentation is generated using [YARD](https://yardoc.org/), and can be generat
 
 ### License
 
-Copyright (c) 2017 Rob Smith
+Copyright (c) 2019 Rob Smith
 
 Cuprum is released under the [MIT License](https://opensource.org/licenses/MIT).
 
@@ -63,9 +64,9 @@ Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use thes
 
     require 'cuprum'
 
-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.
+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.
 
-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).
+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)
 
@@ -77,12 +78,13 @@ The recommended way to define commands is to create a subclass of `Cuprum::Comma
 class BuildBookCommand < Cuprum::Command
   def process attributes
     Book.new(attributes)
-  end # method process
-end # class
+  end
+end
 
 command = BuildPostCommand.new
-result  = command.call(:title => 'The Hobbit')
-result.class #=> Cuprum::Result
+result  = command.call(title: 'The Hobbit')
+result.class    #=> Cuprum::Result
+result.success? #=> true
 
 book = result.value
 book.class #=> Book
@@ -97,23 +99,30 @@ Because a command is just a Ruby object, we can also pass values to the construc
 class SaveBookCommand < Cuprum::Command
   def initialize repository
     @repository = repository
-  end # constructor
+  end
 
   def process book
-    @repository.persist(book)
-  end # method process
-end # class
+    if @repository.persist(book)
+      success(book)
+    else
+      failure('unable to save book')
+    end
+  end
+end
 
 books = [
-  Book.new(:title => 'The Fellowship of the Ring'),
-  Book.new(:title => 'The Two Towers'),
-  Book.new(:title => 'The Return of the King')
+  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) }
 ```
 
-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`.
+Here, we are defining a command that might fail - maybe the database is unavailable, or there's a constraint that is violated by the inserted attributes. If the call to `#persist` succeeds, we're returning a Result with a status of `:success` and the value set to the persisted book.
+Conversely, if the call to `#persist` fails, we're returning a Result with a status of `:failure` and a custom error message. Since the `#process` method returns a Result, it is returned directly by `#call`.
+
+Note also that 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`.
 
 A command can also be defined by passing block to `Cuprum::Command.new`.
 
@@ -136,9 +145,9 @@ Commands defined using `Cuprum::Command.new` are quick to use, but more difficul
 
 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`).
 
-The `#value` depends on whether or not the returned object is a result or is compatible with the result interface. Specifically, any object that responds to the methods `#to_result`, `#value`, and `#success?` is considered to be a result.
+The `#value` depends on whether or not the returned object is a result or is compatible with the result interface. Specifically, any object that responds to the method `#to_cuprum_result` is considered to be a result.
 
-If the object returned is **not** a result, then the `#value` of the returned result is set to the object.
+If the object returned by `#process` is **not** a result, then the `#value` of the returned result is set to the object.
 
 ```ruby
 command = Cuprum::Command.new { 'Greetings, programs!' }
@@ -147,46 +156,18 @@ result.class #=> Cuprum::Result
 result.value #=> 'Greetings, programs!'
 ```
 
-If the object returned is the command's own result object, then the `#value` of the returned result is unchanged. For convenience, methods to set the result status or mark the result as halted will return the result.
+If the object returned by `#process` is a result object, then result is returned directly.
 
 ```ruby
-command = Cuprum::Command.new { result.failure! }
+command = Cuprum::Command.new { Cuprum::Result.new(value: 'Greetings, programs!') }
 result  = command.call
-result.class    #=> Cuprum::Result
-result.value    #=> nil
-result.success? #=> false
-```
-
-If the object returned is another result or compatible object, then `#call` will call the `#to_result` method on the result and return the resulting object.
-
-```ruby
-command = Cuprum::Command.new { |value| Cuprum::Result.new(value) }
-result  = command.call('Greetings, starfighter!')
 result.class #=> Cuprum::Result
-result.value #=> 'Greetings, starfighter!'
-```
-
-In some cases, returning a result directly will discard information on the command's own result object. When this occurs, Cuprum will display a warning.
-
-```ruby
-command =
-  Cuprum::Command.new do
-    result.errors << 'Oops! We are throwing away this result.'
-
-    Cuprum::Result.new
-  end
-
-#=> This calls Kernel#warn with a warning message.
-result = command.call
-result.class    #=> Cuprum::Result
-result.value    #=> nil
-result.success? #=> true
-result.errors   #=> []
+result.value #=> 'Greetings, programs!'
 ```
 
 #### Success, Failure, and Errors
 
-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.
+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.
 
 ```ruby
 class PublishBookCommand < Cuprum::Command
@@ -194,47 +175,99 @@ class PublishBookCommand < Cuprum::Command
 
   def process book
     if book.cover.nil?
-      errors << 'This book does not have a cover.'
-
-      return
-    end # if
+      return Cuprum::Result.new(error: 'This book does not have a cover.')
+    end
 
     book.published = true
 
     book
-  end # method process
-end # class
+  end
+end
 ```
 
-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.
+In addition, the result object defines `#success?` and `#failure?` predicates.
 
 ```ruby
-book = Book.new(:title => 'The Silmarillion', :cover => Cover.new)
+book = Book.new(title: 'The Silmarillion', cover: Cover.new)
 book.published? #=> false
 
 result = PublishBookCommand.new.call(book)
-result.errors   #=> []
+result.error    #=> nil
 result.success? #=> true
 result.failure? #=> false
 result.value    #=> book
 book.published? #=> true
 ```
 
-If the result does have errors, `#success?` will return false and `#failure?` will return true.
+If the result does have an error, `#success?` will return false and `#failure?` will return true.
 
 ```ruby
-book = Book.new(:title => 'The Silmarillion', :cover => nil)
+book = Book.new(title: 'The Silmarillion', cover: nil)
 book.published? #=> false
 
 result = PublishBookCommand.new.call(book)
-result.errors   #=> ['This book does not have a cover.']
+result.error    #=> 'This book does not have a cover.'
 result.success? #=> false
 result.failure? #=> true
 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:
 
@@ -245,10 +278,12 @@ 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
-end # command
+end
 
 add_command.call(1, 1).value #=> 2
 add_command.call(1, 2).value #=> 3
@@ -274,8 +309,12 @@ class AddCommand < Cuprum::Command
 
   private
 
+  def increment_command
+    @increment_command ||= IncrementCommand.new
+  end
+
   def process i
-    addend.times { i = IncrementCommand.new.call(i).value }
+    addend.times { i = increment_command.call(i).value }
 
     i
   end
@@ -287,886 +326,823 @@ 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.
 
-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.
-
-```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 }
+#### Commands As Arguments
 
-table_name_command =
-  name_command
-    .chain(pluralize_command)
-    .chain(underscore_command)
-
-result = table_name_command.call(LibraryCard)
-result.class #=> Cuprum::Result
-result.value #=> 'library_cards'
-```
-
-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.
-
-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:
+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
-table_name_command =
-  Cuprum::Command.new { |klass| klass.name }
-    .chain { |str| str.pluralize }
-    .chain { |str| str.underscore }
-
-table_name_command =
-  Cuprum::Command.new(&:name).chain(&:pluralize).chain(&:underscore)
-```
-
-#### Chaining Details
-
-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:
+class RepeatCommand
+  def initialize(count)
+    @count = count
+  end
 
-```ruby
-first_command = Cuprum::Command.new { puts 'First command!' }
-first_command.call #=> Outputs 'First command!' to STDOUT.
+  private
 
-second_command = first_command.chain { puts 'Second command!' }
-second_command.call #=> Outputs 'First command!' then 'Second command!'.
+  def process(command)
+    @count.times { command.call }
+  end
+end
 
-# The original command is unchanged.
-first_command.call #=> Outputs 'First command!' to STDOUT.
+greet_command  = Cuprum::Command.new { puts 'Greetings, programs!' }
+repeat_command = RepeatCommand.new(3)
+repeat_command.call(greet_command) #=> prints 'Greetings, programs!' 3 times
 ```
 
-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, generating a `Cuprum::Result` and assigning it a value and optionally errors or a status. Rather than returning this result, however, it is passed on to the next command in the chain. In the context of a chained command, this means two things.
+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.
 
-First, the next command 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.
+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
-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)
-
-# 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
-```
+class DeliverEbook < Cuprum::Command; end
 
-Second, the previous result is set as the result of the next command (before it is evaluated). This makes it available to the next command during execution as the `#result` method, and makes available the value, errors, and status of the previous command (and avoids unnecessary object allocation). The value of the result will be updated to reflect the return value of the next command execution.
+class ShipDomestic < Cuprum::Command; end
 
-```ruby
-validate_command =
-  Cuprum::Command.new do |object|
-    result.errors << 'Object is invalid!' unless object.valid?
+class ShipInternational < Cuprum::Command; end
 
-    object
+class FulfillOrder < Cuprum::Command
+  def initialize(delivery_command)
+    @delivery_command = delivery_command
   end
-persist_command =
-  Cuprum::Command.new do |object|
-    object.save if result.success?
 
-    object
+  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
-chained_command = validate_command.chain(persist_command)
-
-# First, validate_command is called with a valid object. This creates a result
-# with no errors and whose value is the valid object.
-#
-# Then, persist_command is called with the object, and its result is assigned to
-# the previous result. Since there are no errors on the result, the object is
-# saved. Finally, the value of the result is set to the object, and the result
-# is returned.
-result = chained_command.call(a_valid_object) #=> Saves the object.
-result.value              #=> a_valid_object
-result.errors             #=> []
-a_valid_object.persisted? #=> true
-
-# First, validate_command is called with an invalid object. This creates a
-# result whose value is the invalid object, and with errors 'Object is
-# invalid!'.
-#
-# Then, persist_command is called with the object, and its result is assigned to
-# the previous result. Since the result has an error, the object is not saved.
-# Finally, the value of the result is set to the object, and the result
-# is returned.
-result = chained_command.call(an_invalid_object) #=> Does not save the object.
-result.value                 #=> an_invalid_object
-result.errors                #=> ['Object is invalid!']
-an_invalid_object.persisted? #=> false
+end
 ```
 
-#### Conditional Chaining
+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).
 
-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`.
+#### Commands As Returned Values
 
-If the `:on` keyword is omitted, the chained command will always be executed after the previous command unless the result is halted (see [Halting A Command Chain](#label-Commands))
+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.
 
-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 and the command is not halted. A result is passing if there are no errors, or if the status is set to `:success`.
+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.
 
-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 and the command is not halted. A result is failing if the errors object is not empty, or if the status is set to `:failure`.
-
-If the command is chained with `:on => always`, then the chained command will always be executed, even if the previous result is halted.
+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
-find_command =
-  Cuprum::Command.new do |attributes|
-    book = Book.where(:id => attributes[:id]).first
+class ShippingMethod < Cuprum::Command
+  private
 
-    result.errors << 'Book not found' unless book
+  def process(book:, user:)
+    return DeliverEbook.new(user.email) if book.ebook?
 
-    book
-  end
-create_command =
-  Cuprum::Command.new do |attributes|
-    book = Book.new(attributes)
+    return ShipDomestic.new(user.address) if user.address&.domestic?
 
-    if book.save
-      result.success!
-    else
-      book.errors.full_messages.each { |message| result.errors << message }
-    end
+    return ShipInternational.new(user.address) if user.address&.international?
 
-    book
-  end
+    err = Cuprum::Error.new(message: 'user does not have a valid address')
 
-find_or_create_command = find_command.chain(create_command, :on => :failure)
-
-# With a book that exists in the database, the find_command is called and
-# returns a result with no errors 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.errors   #=> []
-
-# 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 but
-# preserving the errors.
-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.errors   #=> ['Book not found']
-
-# 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.errors   #=> ['Book not found', "Title can't be blank"]
+    failure(err)
+  end
+end
 ```
 
-The `#success` method can be used as shorthand for `chain(command, :on => :success)`. Likewise, the `#failure` method can be used in place of `chain(command, :on => :failure)`.
+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.
 
-#### Halting A Command Chain
+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 `#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.
+### Command Steps
 
-```ruby
-double_command  = Cuprum::Command.new { |i| 2 * i }
-halt_command    = Cuprum::Command.new { |value| value.tap { result.halt! } }
-add_one_command = Cuprum::Command.new { |i| i + 1 }
-
-chained_command =
-  double_command
-    .chain(halt_command)
-    .chain(add_one_command)
-    .chain(:on => :always) { |count| "There are #{count} lights!" }
-
-# First, double_command is called with 2, returning a result with no errors and
-# a value of 4. Then, halt_command is called, which marks the result as halted.
-# Because the result is now halted, the add_one_command is not called. Finally,
-# the last command is called (even though the result is halted, the command is
-# chained :on => :always), which returns a result with the string value. The
-# result is passing, but is still halted.
-result = chained_command.call(2)
-result.value    #=> 'There are 4 lights!'
-result.success? #=> true
-result.halted?  #=> true
-```
-
-### Advanced Chaining
-
-The `#tap_result` and `#yield_result` methods provide advanced control over the flow of chained commands.
+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.
 
-#### Tap Result
-
-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.
+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
-command =
-  Cuprum::Command.new do
-    result.errors << 'Example error'
-
-    'Example value'
-  end
-chained_command =
-  command
-    .tap_result do |result|
-      puts "The result value was #{result.inspect}"
-    end
+triple_command = Cuprum::Command.new { |i| success(3 * i) }
 
-# Prints 'The result value was "Example value"' to STDOUT.
-result = chained_command.call
-result.class    #=> Cuprum::Result
-result.value    #=> 'Example value'
-result.success? #=> false
-result.errors   #=> ['Example error']
+int = 2
+int = step { triple_command.call(int) } #=> returns 6
+int = step { triple_command.call(int) } #=> returns 18
 ```
 
-Like `#chain`, `#tap_result` can be given an `:on => value` keyword.
+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.
 
-```ruby
-find_book_command =
-  Cuprum::Command.new do |book_id|
-    book = Book.where(:id => book_id).first
+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`.
 
-    result.errors << "Unable to find book with id #{book_id}" unless book
-
-    book
-  end
+```ruby
+divide_command = Cuprum::Command.new do |dividend, divisor|
+  return failure('divide by zero') if divisor.zero?
 
-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
+  success(dividend / divisor)
+end
 
-# Calls find_book_command with the id, which queries for the book and returns a
-# result with a value of the book and no errors. 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)
-result.class    #=> Cuprum::Result
-result.value    #=> an instance of Book
-result.success? #=> true
-result.errors   #=> []
-
-# 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.errors   #=> ['Unable to find book with id invalid_id']
+value = step { divide_command.call(10, 5) } #=> returns 2
+value = step { divide_command.call(2, 0) }  #=> throws :cuprum_failed_result
 ```
 
-#### Yield Result
+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.
+
+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:
 
-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.
+- 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.
 
-Unlike `#chain`, the block in `#yield_result` yields the previous result, not the previous value. In addition, `#yield_result` does not automatically carry over any errors from the previous result, the result status, or whether the result was marked as halted.
+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
-chained_command =
-  Cuprum::Command.new do
-    'Example value'
-  end
-  .yield_result do |result|
-    result.errors << 'Example error'
+class CheckUserStatus < Cuprum::Command; end
 
-    result
-  end
-  .yield_result do |result|
-    "The last result was a #{result.success? ? 'success' : 'failure'}."
-  end
+class CreateBookReservation < Cuprum::Command; end
 
-# The first command creates a passing result with a value of 'Example value'.
-#
-# This is passed to the first yield_result block, which adds the 'Example error'
-# string to the result errors, and then returns the result. Because the
-# yield_result block returns the previous result, it is then passed to the next
-# item in the chain.
-#
-# Finally, the second yield_result block is called, which checks the status of
-# the passed result. Since the second 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.errors   #=> []
-```
-
-Like `#chain`, `#yield_result` can be given an `:on => value` keyword.
+class FindBookByTitle < Cuprum::Command; end
 
-```ruby
-# The Collatz conjecture in mathematics concerns a sequence of numbers defined
-# as follows. Start with any positive integer. If the number is even, then
-# divide the number by two. If the number is odd, multiply by three and add one.
-# These steps are repeated until the value is one or the numbers loop.
-step_command =
-  Cuprum::Command.new do |i|
-    result.failure! unless i.even?
+class ReserveBookByTitle < Cuprum::Command
+  private
 
-    i
+  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
-    .yield_result(:on => :success) { |result| result.value / 2 }
-    .yield_result(:on => :failure) { |result| 1 + 3 * result.value }
-
-# Because the value is even, the first command returns a passing result with a
-# value of 8. The first yield_result block is then called with that result,
-# returning a new result with a value of 4. The result is passing, so the second
-# yield_result block is skipped and the result is returned.
-result = collatz_command.call(8)
-result.value    #=> 4
-result.success? #=> true
-
-# Because the value is odd, the first command returns a failing result with a
-# value of 5. Because the result is failing, the first yield_result block is
-# skipped. The second yield_result block is then called with the result,
-# returning a new (passing) result with a value of 16.
-result = collatz_command.call(5)
-result.value    #=> 16
-result.success? #=> true
+end
 ```
 
-Under the hood, both `#chain` and `#tap_result` are implemented on top of `#yield_result`.
-
-### 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 `#errors` object (defaults to an Array), and status methods `#success?`, `#failure?`, and `#halted?`.
+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
-value  = 'A result value'.freeze
-result = Cuprum::Result.new(value)
-
-result.value    #=> 'A result value'
-result.errors   #=> []
-result.success? #=> true
-result.failure? #=> false
-result.halted?  #=> false
+result = ReserveBookByTitle.new.call(
+  title: 'The C Programming Language',
+  user:  'Ed Dillinger'
+)
+result.class    #=> Cuprum::Result
+result.success? #=> false
+result.error    #=> 'not authorized to reserve book'
 ```
 
-Adding errors to the `#errors` object will change the status of the result.
+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
-result.errors << "I'm sorry, something went wrong."
+result = ReserveBookByTitle.new.call(
+  title: 'Using GOTO For Fun And Profit',
+  user:  'Alan Bradley'
+)
+result.class    #=> Cuprum::Result
 result.success? #=> false
-result.failure? #=> true
+result.error    #=> 'title not found'
 ```
 
-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.
+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`.
 
 ```ruby
-result.success!
-result.errors   #=> ["I'm sorry, something went wrong."]
-result.success? #=> true
-result.failure? #=> false
+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'
 ```
 
-### Operations
-
-    require 'cuprum'
-
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
-
-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.
-
-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).
+Finally, if each of the steps succeeds, the `#call` method will return the result of the final step.
 
 ```ruby
-class CreateBookOperation < Cuprum::Operation
-  def process
-    # Implementation here.
-  end # method process
-end # class
-
-# Defining a controller action using an operation.
-def create
-  operation = CreateBookOperation.new.call(book_params)
-
-  if operation.success?
-    redirect_to(operation.value)
-  else
-    @book = operation.value
-
-    render :new
-  end # if-else
-end # create
+result = ReserveBookByTitle.new.call(
+  title: 'The C Programming Language',
+  user:  'Alan Bradley'
+)
+result.class    #=> Cuprum::Result
+result.success? #=> true
+result.value    #=> an instance of BookReservation
 ```
 
-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.
+#### Using Methods As Steps
 
-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.
+Steps can also be defined as method calls. Instead of providing a block to `#step`, provide the name of the method as the first argument, either as a symbol or as a string. Any subsequent arguments, keywords, or a block is passed to the method when it is called.
 
-#### The Operation Mixin
+A step defined with a method behaves the same as a step defined with a block. If the method returns a successful result, then `#step` will return the value of the result. If the method returns a failing result, then `#step` will throw `:cuprum_failed_result` and the result, to be caught by the `#process` method or the containing `#steps` block.
 
-[Module Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation%2FMixin)
-
-The implementation of `Cuprum::Operation` is defined by the `Cuprum::Operation::Mixin` module, which provides the methods defined above. Any command class or instance can be converted to an operation by including (for a class) or extending (for an instance) the operation mixin.
-
-Finally, the result can be halted using the `#halt` method, which indicates that further chained commands should not be executed.
+We can use this to rewrite our `ReserveBookByTitle` command to use methods:
 
 ```ruby
-result.halt!
-result.halted? #=> true
-```
-
-### Built In Commands
+class ReserveBookByTitle < Cuprum::Result
+  private
 
-Cuprum includes a small number of predefined commands and their equivalent operations.
+  def check_user_status(user)
+    CheckUserStatus.new(user)
+  end
 
-#### IdentityCommand
+  def create_book_reservation(book:, user:)
+    CreateBookReservation.new(book: book, user: user)
+  end
 
-    require 'cuprum/built_in/identity_command'
+  def find_book_by_title(title)
+    FindBookByTitle.new.call(title)
+  end
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityCommand)
+  def process(title:, user:)
+    step :check_user_status, user
 
-A pregenerated command that returns the value or result with which it was called.
+    book = step :find_book_by_title, title
 
-```ruby
-command = Cuprum::BuiltIn::IdentityCommand.new
-result  = command.call('expected value')
-result.value    #=> 'expected value'
-result.success? #=> true
+    create_book_reservation, book: book, user: user
+  end
+end
 ```
 
-#### IdentityOperation
+In this case, our methods simply delegate to our previously defined commands. However, a more complex example could include other logic in each method, or even a sequence of steps defining subtasks for the method. The only requirement is that the method returns a result. You can use the `#success` helpers to wrap a non-result value, or the `#failure` helper to generate a failing result.
 
-    require 'cuprum/built_in/identity_operation'
+#### Using Steps Outside Of Commands
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityOperation)
+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.
 
-A pregenerated operation that sets its result to the value or result with which it was 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
-operation = Cuprum::BuiltIn::IdentityOperation.new.call('expected value')
-operation.value    #=> 'expected value'
-operation.success? #=> true
-```
-
-#### NullCommand
-
-    require 'cuprum/built_in/null_command'
-
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullCommand)
+steps do
+  step { check_something }
 
-A pregenerated command that does nothing when called. Accepts any arguments.
+  obj = step { find_something }
 
-```ruby
-command = Cuprum::BuiltIn::NullCommand.new
-result  = command.call
-result.value    #=> nil
-result.success? #=> true
+  step :do_something, with: obj
+end
 ```
 
-#### NullOperation
-
-    require 'cuprum/built_in/null_operation'
+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`.
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullOperation)
+Let's consider the example of a controller action for creating a new resource. This would have several steps, each of which can fail:
 
-A pregenerated operation that does nothing when called. Accepts any arguments.
+- 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
-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.
+class BooksController
+  include Cuprum::Steps
 
-### Cuprum::BuiltIn::NullCommand
+  def create
+    attributes = params[:books]
+    result     = steps do
+      @book = step :build_book, attributes
 
-    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:
+      step :run_validations, @book
 
-#### `#call`
-
-    call(*args, **keywords) { ... } #=> Cuprum::Result
-
-Returns a result with nil value. Any arguments or keywords are ignored.
+      step :persist_book, book
+    end
 
-### Cuprum::BuiltIn::NullOperation
+    result.success ? redirect_to(@book) : render(:edit)
+  end
 
-    require 'cuprum/built_in/null_operation'
+  private
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullOperation)
+  def build_book(attributes)
+    success(Book.new(attributes))
+  rescue InvalidAttributes
+    failure('attributes are invalid')
+  end
 
-Cuprum::BuiltIn::NullOperation defines the following methods:
+  def persist_book(book)
+    book.save ? success(book) : failure('unable to persist book')
+  end
 
-#### `#call`
+  def run_validations(book)
+    book.valid? ? success : failure('book is invalid')
+  end
+end
+```
 
-    call(*args, **keywords) { ... } #=> Cuprum::BuiltIn::NullOperation
+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.
 
-Sets the last result to a result with nil value. Any arguments or keywords are ignored.
+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.
 
-### Cuprum::Command
+### Results
 
     require 'cuprum'
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommand)
-
-A Cuprum::Command defines the following methods:
-
-#### `#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 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).
 
-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.
+```ruby
+result = Cuprum::Result.new
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#initialize-instance_method)
+result.value    #=> nil
+result.error    #=> nil
+result.status   #=> :success
+result.success? #=> true
+result.failure? #=> true
+```
 
-#### `#build_errors`
+Creating a result with a value stores the value.
 
-*(Private Method)*
+```ruby
+value  = 'A result value'.freeze
+result = Cuprum::Result.new(value: value)
 
-    build_errors() #=> Array
+result.value    #=> 'A result value'
+result.error    #=> nil
+result.status   #=> :success
+result.success? #=> true
+result.failure? #=> false
+```
 
-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.
+Creating a Result with an error stores the error and sets the status to `:failure`.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#build_errors-instance_method)
+```ruby
+error  = Cuprum::Error.new(message: "I'm sorry, something went wrong.")
+result = Cuprum::Result.new(error: error)
+result.value    #=> nil
+result.error    #=> Error with message "I'm sorry, something went wrong."
+result.status   #=> :failure
+result.success? #=> false
+result.failure? #=> true
+```
 
-#### #call
+Although using a `Cuprum::Error` instance as the `:error` is recommended, it is not required. You can use a custom error object, or just a string message.
 
-    call(*arguments, **keywords) { ... } #=> Cuprum::Result
+```ruby
+result = Cuprum::Result.new(error: "I'm sorry, something went wrong.")
+result.value    #=> nil
+result.error    #=> "I'm sorry, something went wrong."
+result.status   #=> :failure
+result.success? #=> false
+result.failure? #=> true
+```
 
-Executes the logic encoded in the constructor block, or the #process method if no block was passed to the constructor.
+Finally, the status can be overridden via the `:status` keyword.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#call-instance_method)
+```ruby
+result = Cuprum::Result.new(status: :failure)
+result.error    #=> nil
+result.status   #=> :failure
+result.success? #=> false
+result.failure? #=> true
 
-#### #chain
+error  = Cuprum::Error.new(message: "I'm sorry, something went wrong.")
+result = Cuprum::Result.new(error: error, status: :success)
+result.error    #=> Error with message "I'm sorry, something went wrong."
+result.status   #=> :success
+result.success? #=> true
+result.failure? #=> false
+```
 
-    chain(on: nil) { |result| ... } #=> Cuprum::Command
+### Errors
 
-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.
+    require 'cuprum/error'
 
-    chain(command, on: nil) #=> Cuprum::Command
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FError)
 
-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).
+A `Cuprum::Error` encapsulates a specific failure state of a Command. Each Error has a `#message` property, which defaults to nil.
 
-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.
+```ruby
+error = Cuprum::Error.new
+error.message => # nil
 
-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.
+error = Cuprum::Error.new(message: 'Something went wrong.')
+error.message => # 'Something went wrong.'
+```
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#chain-instance_method)
+Each application should define its own failure states as errors. For example, a typical web application might define the following errors:
 
-#### `#else`
+```ruby
+class NotFoundError < Cuprum::Error
+  def initialize(resource:, resource_id:)
+    @resource    = resource
+    @resource_id = resource_id
 
-    else(command) #=> Cuprum::Command
+    super(message: "#{resource} not found with id #{resource_id}")
+  end
 
-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.
+  attr_reader :resource, :resource_id
+end
 
-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).
+class ValidationError < Cuprum::Error
+  def initialize(resource:, errors:)
+    @resource = resource
+    @errors   = errors
 
-    else() { |result| ... } #=> Cuprum::Command
+    super(message: "#{resource} was invalid")
+  end
 
-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.
+  attr_reader :resource, :errors
+end
+```
 
-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.
+It is optional but recommended to use a `Cuprum::Error` when returning a failed result from a command.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#else-instance_method)
+### Operations
 
-#### `#errors`
+    require 'cuprum'
 
-*(Private Method)*
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
 
-    errors() #=> Array
+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.
 
-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.
+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).
 
-Inside of the Command block or the `#process` method, you can add errors to the result.
+```ruby
+class CreateBookOperation < Cuprum::Operation
+  def process
+    # Implementation here.
+  end
+end
 
-    command =
-      Cuprum::Command.new do
-        errors << "I'm sorry, something went wrong."
+# Defining a controller action using an operation.
+def create
+  operation = CreateBookOperation.new.call(book_params)
 
-        nil
-      end # command
+  if operation.success?
+    redirect_to(operation.value)
+  else
+    @book = operation.value
 
-    result = command.call
-    result.failure?
-    #=> true
-    result.errors
-    #=> ["I'm sorry, something went wrong."]
+    render :new
+  end
+end
+```
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#errors-instance_method)
+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.
 
-#### `#failure!`
+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.
 
-    failure!() #=> NilClass
+#### The Operation Mixin
 
-*(Private Method)*
+[Module Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation%2FMixin)
 
-Only available while the Command is being called. If called, marks the result object as failing, even if the result does not have errors.
+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.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#failure!-instance_method)
+### Command Factories
 
-#### `#halt!`
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommandFactory)
 
-    halt!() #=> NilClass
+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.
 
-*(Private Method)*
+For example, consider a basic entity command:
 
-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.
+```ruby
+class Book
+  def initialize(attributes = {})
+    @title  = attributes[:title]
+    @author = attributes[:author]
+  end
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#halt!-instance_method)
+  attr_accessor :author, :publisher, :title
+end
 
-#### `#success!`
+class BuildBookCommand < Cuprum::Command
+  private
 
-    success!() #=> NilClass
+  def process(attributes = {})
+    Book.new(attributes)
+  end
+end
 
-*(Private Method)*
+class BookFactory < Cuprum::CommandFactory
+  command :build, BuildBookCommand
+end
+```
 
-Only available while the Command is being called. If called, marks the result object as passing, even if the result has errors.
+Our factory is defined by subclassing `Cuprum::CommandFactory`, and then we map the individual commands with the `::command` or `::command_class` class methods. In this case, we've defined a Book factory with the build command. The build command can be accessed on a factory instance in one of two ways.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#success!-instance_method)
+First, the command class can be accessed directly as a constant on the factory instance.
 
-#### `#tap_result`
+```ruby
+factory = BookFactory.new
+factory::Build #=> BuildBookCommand
+```
 
-    tap_result(on: nil) { |previous_result| } #=> Cuprum::Result
+Second, the factory instance now defines a `#build` method, which returns an instance of our defined command class. This command instance can be called like any command, or returned or passed around like any other object.
 
-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.
+```ruby
+factory = BookFactory.new
 
-If the `on` parameter is omitted, the block will be called if the last result is not halted. If the `on` parameter is set to `:success`, the block will be called if the last result is successful and not halted. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing and not halted. Finally, if the `on` parameter is set to `:always`, the block will always be called, even if the last result is halted.
+attrs   = { title: 'A Wizard of Earthsea', author: 'Ursula K. Le Guin' }
+command = factory.build()     #=> an instance of BuildBookCommand
+result  = command.call(attrs) #=> an instance of Cuprum::Result
+book    = result.value        #=> an instance of Book
 
-#### `#then`
+book.title     #=> 'A Wizard of Earthsea'
+book.author    #=> 'Ursula K. Le Guin'
+book.publisher #=> nil
+```
 
-    then(command) #=> Cuprum::Command
+#### The ::command Method And A Command Class
 
-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 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:
 
-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).
+```ruby
+class BookFactory < Cuprum::CommandFactory
+  command :build, BuildBookCommand
+end
+```
 
-    then() { |result| ... } #=> Cuprum::Command
+This makes the command class available on a factory instance as `::Build`, and generates the `#build` method which returns an instance of `BuildBookCommand`.
 
-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.
+#### The ::command Method And A Block
 
-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.
+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.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#then-instance_method)
+```ruby
+class PublishBookCommand < Cuprum::Command
+  def initialize(publisher:)
+    @publisher = publisher
+  end
 
-#### `#yield_result`
+  attr_reader :publisher
 
-    yield_result(on: nil) { |previous_result| } #=> Cuprum::Result
+  private
 
-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.
+  def process(book)
+    book.publisher = publisher
 
-If the `on` parameter is omitted, the block will be called if the last result is not halted. If the `on` parameter is set to `:success`, the block will be called if the last result is successful and not halted. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing and not halted. Finally, if the `on` parameter is set to `:always`, the block will always be called, even if the last result is halted.
+    book
+  end
+end
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#yield_result-instance_method)
+class BookFactory < Cuprum::CommandFactory
+  command :publish do |publisher|
+    PublishBookCommand.new(publisher: publisher)
+  end
+end
+```
 
-### Cuprum::Operation
+This defines the `#publish` method on an instance of the factory. The method takes one argument (the publisher), which is then passed on to the constructor for `PublishBookCommand` by our block. Finally, the block returns an instance of the publish command, which is then returned by `#publish`.
 
-    require 'cuprum'
+```ruby
+factory = BookFactory.new
+book    = Book.new(title: 'The Tombs of Atuan', author: 'Ursula K. Le Guin')
+book.publisher #=> nil
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FOperation)
+command = factory.publish('Harper & Row') #=> an instance of PublishBookCommand
+result  = command.call(book)              #=> an instance of Cuprum::Result
+book.publisher #=> 'Harper & Row'
+```
 
-A Cuprum::Operation inherits the methods from Cuprum::Command (see above), and defines the following additional methods:
+Note that unlike when `::command` is called with a command class, calling `::command` with a block will not set a constant on the factory instance. In this case, trying to access the `PublishBookCommand` at `factory::Publish` will raise a `NameError`.
 
-#### `#called?`
+The block is evaluated in the context of the factory instance. This means that instance variables or methods are available to the block, allowing you to create commands with instance-specific configuration.
 
-    called?() #=> true, false
+```ruby
+class PublishedBooksCommand < Cuprum::Command
+  def initialize(collection = [])
+    @collection = collection
+  end
 
-True if the operation has been called and there is a result available by calling `#result` or one of the delegated methods, otherwise false.
+  attr_reader :collection
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#called%3F-instance_method)
+  private
 
-#### `#reset!`
+  def process
+    books.reject { |book| book.publisher.nil? }
+  end
+end
 
-    reset!()
+class BookFactory < Cuprum::CommandFactory
+  def initialize(books)
+    @books_collection = books
+  end
 
-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.
+  attr_reader :books_collection
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#reset!-instance_method)
+  command :published do
+    PublishedBooksCommand.new(books_collection)
+  end
+end
+```
 
-#### `#result`
+This defines the `#published` method on an instance of the factory. The method takes no arguments, but grabs the books collection from the factory instance. The block returns an instance of `PublishedBooksCommand`, which is then returned by `#published`.
 
-    result() #=> Cuprum::Result
+```ruby
+books   = [Book.new, Book.new(publisher: 'Baen'), Book.new(publisher: 'Tor')]
+factory = BookFactory.new(books)
+factory.books_collection #=> the books array
 
-The most recent result, from the previous time `#call` was executed for the operation.
+command = factory.published #=> an instance of PublishedBooksCommand
+result  = command.call      #=> an instance of Cuprum::Result
+ary     = result.value      #=> an array with the published books
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Operation#result-instance_method)
+ary.count                                    #=> 2
+ary.any? { |book| book.publisher == 'Baen' } #=> true
+ary.any? { |book| book.publisher.nil? }      #=> false
+```
 
-### Cuprum::Result
+Simple commands can be defined directly in the block, rather than referencing an existing command class:
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FResult)
+```ruby
+class BookFactory < Cuprum::CommandFactory
+  command :published_by_baen do
+    Cuprum::Command.new do |books|
+      books.select { |book| book.publisher == 'Baen' }
+    end
+  end
+end
 
-A Cuprum::Result defines the following methods:
+books   = [Book.new, Book.new(publisher: 'Baen'), Book.new(publisher: 'Tor')]
+factory = BookFactory.new(books)
 
-#### `#==`
+command = factory.published_by_baen #=> an instance of the anonymous command
+result  = command.call              #=> an instance of Cuprum::Result
+ary     = result.value              #=> an array with the selected books
 
-    ==(other) #=> true, false
+ary.count #=> 1
+```
 
-Performs a fuzzy comparison with the other object. At a minimum, the other object must respond to `#value` and `#success?`, and the values of `other.value` and `other.success?` must be equal to the corresponding value on the result. In addition, if the `#failure?`, `#errors`, or `#halted?` methods are defined on the other object, then the value of each defined method is compared to the value on the result. Returns true if all values match, otherwise returns false.
+#### The ::command_class Method
 
-#### `#empty?`
+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.
 
-    empty?() #=> true, false
+```ruby
+class SelectByAuthorCommand < Cuprum::Command
+  def initialize(author)
+    @author = author
+  end
 
-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.
+  attr_reader :author
 
-#### `#errors`
+  private
 
-    errors() #=> Array
+  def process(books)
+    books.select { |book| book.author == author }
+  end
+end
 
-The errors generated by the command, or an empty array if no errors were generated.
+class BooksFactory < Cuprum::CommandFactory
+  command_class :select_by_author do
+    SelectByAuthorCommand
+  end
+end
+```
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#errors-instance_method)
+The command class can be accessed directly as a constant on the factory instance:
 
-#### `#failure!`
+```ruby
+factory = BookFactory.new
+factory::SelectByAuthor #=> SelectByAuthorCommand
+```
 
-    failure!() #=> Cuprum::Result
+The factory instance now defines a `#select_by_author` method, which returns an instance of our defined command class. This command instance can be called like any command, or returned or passed around like any other object.
 
-Marks the result as failing and returns the result. Calling `#failure?` will return true, even if the result has no errors.
+```ruby
+factory = BookFactory.new
+books   = [
+  Book.new,
+  Book.new(author: 'Arthur C. Clarke'),
+  Book.new(author: 'Ursula K. Le Guin')
+]
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure!-instance_method)
+command = factory.select_by_author('Ursula K. Le Guin')
+#=> an instance of SelectByAuthorCommand
+command.author #=> 'Ursula K. Le Guin'
 
-#### `#failure?`
+result = command.call(books)      #=> an instance of Cuprum::Result
+ary    = result.value             #=> an array with the selected books
 
-    failure?() #=> true, false
+ary.count                                              #=> 1
+ary.any? { |book| book.author == 'Ursula K. Le Guin' } #=> true
+ary.any? { |book| book.author == 'Arthur C. Clarke'  } #=> false
+ary.any? { |book| book.author.nil? }                   #=> false
+```
 
-True if the command generated one or more errors or was marked as failing. Otherwise false.
+The block is evaluated in the context of the factory instance. This means that instance variables or methods are available to the block, allowing you to create custom command subclasses with instance-specific configuration.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#failure%3F-instance_method)
+```ruby
+class SaveBookCommand < Cuprum::Command
+  def initialize(collection = [])
+    @collection = collection
+  end
 
-#### `#halt!`
+  attr_reader :collection
 
-    halt!() #=> Cuprum::Result
+  private
 
-Marks the result as halted and returns the result. Calling `#halted?` will return true.
+  def process(book)
+    books << book
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#halt!-instance_method)
+    book
+  end
+end
 
-#### `#halted?`
+class BookFactory < Cuprum::CommandFactory
+  command :save do
+    collection = self.books_collection
 
-    halted?() #=> true, false
+    Class.new(SaveBookCommand) do
+      define_method(:initialize) do
+        @books = collection
+      end
+    end
+  end
 
-True if the result is halted, which prevents chained commands from executing.
+  def initialize(books)
+    @books_collection = books
+  end
 
-#### `#success!`
+  attr_reader :books_collection
+end
+```
 
-    success!() #=> Cuprum::Result
+The custom command subclass can be accessed directly as a constant on the factory instance:
 
-Marks the result as passing and returns the result. Calling `#success?` will return true, even if the result has errors.
+```ruby
+books   = [Book.new, Book.new, Book.new]
+factory = BookFactory.new(books)
+factory::Save #=> a subclass of SaveBookCommand
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#success!-instance_method)
+command = factory::Save.new # an instance of the command subclass
+command.collection          #=> the books array
+command.collection.count    #=> 3
+```
 
-#### `#success?`
+The factory instance now defines a `#save` method, which returns an instance of our custom command subclass. This command instance can be called like any command, or returned or passed around like any other object.
 
-    success?() #=> true, false
+The custom command subclass can be accessed directly as a constant on the factory instance:
 
-True if the command did not generate any errors, or the result has errors but was marked as passing. Otherwise false.
+```ruby
+books   = [Book.new, Book.new, Book.new]
+factory = BookFactory.new(books)
+command = factory.save   # an instance of the command subclass
+command.collection       #=> the books array
+command.collection.count #=> 3
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#success%3F-instance_method)
+book   = Book.new(title: 'The Farthest Shore', author: 'Ursula K. Le Guin')
+result = command.call(book) #=> an instance of Cuprum::Result
 
-#### `#value`
+books.count          #=> 4
+books.include?(book) #=> true
+```
 
-    value() #=> Object
+### Built In Commands
 
-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.
+Cuprum includes a small number of predefined commands and their equivalent operations.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Result#value-instance_method)
+#### IdentityCommand
 
-### Cuprum::Utilities::InstanceSpy
+    require 'cuprum/built_in/identity_command'
 
-    require 'cuprum/utils/instance_spy'
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityCommand)
 
-[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FUtils%2FInstanceSpy)
+A pregenerated command that returns the value or result with which it was called.
 
-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.
+```ruby
+command = Cuprum::BuiltIn::IdentityCommand.new
+result  = command.call('expected value')
+result.value    #=> 'expected value'
+result.success? #=> true
+```
 
-#### `::clear_spies`
+#### IdentityOperation
 
-    clear_spies() #=> nil
+    require 'cuprum/built_in/identity_operation'
 
-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.
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FIdentityOperation)
 
-    after(:example) { Cuprum::Utils::InstanceSpy.clear_spies }
+A pregenerated operation that sets its result to the value or result with which it was called.
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#clear_spies%3F-instance_method)
+```ruby
+operation = Cuprum::BuiltIn::IdentityOperation.new.call('expected value')
+operation.value    #=> 'expected value'
+operation.success? #=> true
+```
 
-#### `::spy_on`
+#### NullCommand
 
-    spy_on(command_class) #=> InstanceSpy
-    spy_on(command_class) { |spy| ... } #=> nil
+    require 'cuprum/built_in/null_command'
 
-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.
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullCommand)
 
-    # Observing calls to instances of a command.
-    spy = Cuprum::Utils::InstanceSpy.spy_on(CustomCommand)
+A pregenerated command that does nothing when called. Accepts any arguments.
 
-    expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
+```ruby
+command = Cuprum::BuiltIn::NullCommand.new
+result  = command.call
+result.value    #=> nil
+result.success? #=> true
+```
 
-    CustomCommand.new.call(1, 2, 3, :four => '4')
+#### NullOperation
 
-    # Observing calls to a chained command.
-    spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedCommand)
+    require 'cuprum/built_in/null_operation'
 
-    expect(spy).to receive(:call)
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FBuiltIn%2FNullOperation)
 
-    Cuprum::Command.new {}.
-      chain { |result| ChainedCommand.new.call(result) }.
-      call
+A pregenerated operation that does nothing when called. Accepts any arguments.
 
-    # Block syntax
-    Cuprum::Utils::InstanceSpy.spy_on(CustomCommand) do |spy|
-      expect(spy).to receive(:call)
+```ruby
+operation = Cuprum::BuiltIn::NullOperation.new.call
+operation.value    #=> nil
+operation.success? #=> true
+```
 
-      CustomCommand.new.call
-    end # spy_on
+## Reference
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Utils/InstanceSpy#spy_on%3F-instance_method)
+Method and class documentation is available courtesy of [RubyDoc](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master).