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.
A predefined command that does nothing when called.
result = NullCommand.new.call
result.value
#=> nil
result.success?
#=> trueCuprum::BuiltIn::NullOperation
.subclass(*class_arguments, **class_keywords, &block) => Class
Creates a subclass with partially applied constructor parameters.
#initialize => NullCommand
#arity => Integer
Returns an indication of the number of arguments accepted by #call.
If the method takes a fixed number N of arguments, returns N. If the method takes a variable number of arguments, returns -N-1, where N is the number of required arguments. Keyword arguments will be considered as a single additional argument, that argument being mandatory if any keyword argument is mandatory.
#call(*arguments, **keywords, &block) => Cuprum::Result
Executes the command and returns a Cuprum::Result or compatible object.
Each time #call is invoked, the object performs the following steps:
#curry(*arguments, **keywords, &block) => Cuprum::Currying::CurriedCommand
Returns a CurriedCommand that wraps this command with pre-set arguments.
When the curried command is called, the predefined arguments and/or keywords will be combined with the arguments passed to #call.
The original command is unchanged.
#step => Object
Executes the block and returns the value, or halts on a failure.
The #step method is used to evaluate a sequence of processes, and to fail fast and halt processing if any of the steps returns a failing result. Each invocation of #step should be wrapped in a #steps block, or used inside the #process method of a Command.
If the object returned by the block is a Cuprum result or compatible object (such as a called operation), the value is converted to a Cuprum result via the #to_cuprum_result method. Otherwise, the object is returned directly from #step.
If the returned object is a passing result, the #value of the result is returned by #step.
If the returned object is a failing result, then #step will throw :cuprum_failed_result and the failing result. This is caught by the #steps block, and halts execution of any subsequent steps.
Calling a Step
# The #do_something method returns the string 'some value'.
step { do_something() } #=> 'some value'
value = step { do_something() }
value #=> 'some value'Calling a Step with a Passing Result
# The #do_something_else method returns a Cuprum result with a value
# of 'another value'.
step { do_something_else() } #=> 'another value'
# The result is passing, so the value is extracted and returned.
value = step { do_something_else() }
value #=> 'another value'Calling a Step with a Failing Result
# The #do_something_wrong method returns a failing Cuprum result.
step { do_something_wrong() } # Throws the :cuprum_failed_step symbol.#steps(&block) => Cuprum::Result
Returns the first failing #step result, or the final result if none fail.
The #steps method is used to wrap a series of #step calls. Each step is executed in sequence. If any of the steps returns a failing result, that result is immediately returned from #steps. Otherwise, #steps wraps the value returned by a block in a Cuprum result.
With A Passing Step
result = steps do
step { success('some value') }
end
result.class #=> Cuprum::Result
result.success? #=> true
result.value #=> 'some value'With A Failing Step
result = steps do
step { failure('something went wrong') }
end
result.class #=> Cuprum::Result
result.success? #=> false
result.error #=> 'something went wrong'With Multiple Steps
result = steps do
# This step is passing, so execution continues on to the next step.
step { success('first step') }
# This step is failing, so execution halts and returns this result.
step { failure('second step') }
# This step will never be called.
step { success('third step') }
end
result.class #=> Cuprum::Result
result.success? #=> false
result.error #=> 'second step'#to_proc => Proc
Wraps the command in a proc.
Calling the proc will call the command with the given arguments, keywords, and block.
Back to Documentation | Reference | Cuprum | Cuprum::BuiltIn