An opinionated implementation of the Command pattern for Ruby applications. Cuprum wraps your business logic in a consistent, object-oriented interface and features status and error management, composability and control flow management.
Implements result matching based on result status, error, and value.
.match(status, error: nil, value: nil, &block) => Object
Defines a match clause for the matcher.
#match_context => Object, nil (readonly)
#call(result) => Object
Finds the match clause matching the result and calls the stored block.
Match clauses are defined using the .match DSL. When a result is matched, the defined clauses matching the result status are checked in descending order of specificity:
If there are multiple clauses that expect a value or an error, they are sorted by inheritance - a clause with a subclass value or error is checked before the clause with the parent class.
Using that ordering, each potential clause is checked for a match with the result. If the clause defines a value, then the result will match the clause only if the result value is an instance of the expected value (or an instance of a subclass). Likewise, if the clause defines an error, then the result will match the clause only if the result error is an instance of the expected error class (or an instance of a subclass). Clauses that do not define either a value nor an error will match with any result with the same status, but as the least specific are always matched last.
Matchers can also inherit clauses from a parent class or from an included module. Inherited or included clauses are checked after clauses defined on the matcher itself, so the matcher can override generic matches with more specific functionality.
Finally, once the most specific matching clause is found, #call will call the block used to define the clause. If the block takes at least one argument, the result will be passed to the block; otherwise, it will be called with no parameters. If there is no clause matching the result, #call will instead raise a Cuprum::Matching::NoMatchError.
The match clause is executed in the context of the matcher object. This allows instance methods defined for the matcher to be called as part of the match clause block. If the matcher defines a non-nil #matching_context, the block is instead executed in the context of the matching_context using #instance_exec.
#match_context? => Boolean
#matches?(result) => Boolean#matches?(status, error: nil, value: nil) => Boolean#matches?(result) => Boolean
Checks if the matcher has any match clauses that match the given result.
#matches?(status, error: nil, value: nil) => Boolean
Checks if the matcher has any clauses matching the status and details.
Back to Documentation | Reference | Cuprum