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 operation that returns the value or result it was called with.
With a value.
operation = IdentityOperation.new.call('custom value')
operation.value
#=> 'custom value'
operation.success?
#=> trueWith a result.
error = 'errors.messages.unknown'
value = Cuprum::Result.new(value: 'result value', error: error)
operation = IdentityOperation.new.call(value)
operation.value
#=> 'result value'
operation.success?
#=> false
operation.error
#=> 'errors.messages.unknown'.subclass(*class_arguments, **class_keywords, &block) => Class
Creates a subclass with partially applied constructor parameters.
#initialize => IdentityCommand
#result => Cuprum::Result (readonly)
#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::Operation
Calls the command implementation and stores the result.
#called? => Boolean
#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.
#error => Object
#failure? => Boolean
#reset! => Object
Clears the reference to the most recent call of the operation, if any. This allows the result and any referenced data to be garbage collected. Use this method to clear any instance variables or state internal to the operation (an operation should never have external state apart from the last result).
If the operation cannot be run more than once, this method should raise an error.
#status => Symbol, nil
#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'#success? => Boolean
#to_cuprum_result => Cuprum::Result
#to_proc => Proc
Wraps the command in a proc.
Calling the proc will call the command with the given arguments, keywords, and block.
#value => Object
Back to Documentation | Reference | Cuprum | Cuprum::BuiltIn