Module: Cuprum::Processing

Included in:
Command
Defined in:
lib/cuprum/processing.rb

Overview

Functional implementation for creating a command object. Cuprum::Processing defines a #call method, which performs the implementation defined by #process and returns an instance of Cuprum::Result.

Examples:

Defining a command with Cuprum::Processing.

class AdderCommand
  include Cuprum::Processing

  def initialize addend
    @addend = addend
  end # constructor

  private

  def process int
    int + addend
  end # method process
end # class AdderCommand

adder  = AdderCommand.new(2)
result = adder.call(3)
#=> an instance of Cuprum::Result
result.value    #=> 5
result.success? #=> true

Defining a command with error handling.

class SquareRootCommand
  include Cuprum::Processing

  private

  def process value
    if value.negative?
      result.errors << 'value cannot be negative'

      return nil
    end # if

    Math.sqrt(value)
  end # method process
end # class

result = SquareRootCommand.new.call(2)
result.value    #=> 1.414
result.success? #=> true
result.failure? #=> false
result.errors   #=> []

result = SquareRootCommand.new.call(-1)
result.value    #=> nil
result.success? #=> false
result.failure? #=> true
result.errors   #=> ['value cannot be negative']

See Also:

Instance Method Summary collapse

Instance Method Details

#arity ⇒ Integer

Returns a nonnegative integer for commands that take a fixed number of arguments. For commands that take a variable number of arguments, returns -n-1, where n is the number of required arguments.

Returns:

  • (Integer) —

    The number of arguments.



69
70
71
 
# File 'lib/cuprum/processing.rb', line 69

def arity
  method(:process).arity
end

#build_errors ⇒ Array

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.

Returns:

  • (Array) —

    An empty errors object.



119
120
121
 
# File 'lib/cuprum/processing.rb', line 119

def build_errors
  []
end

#call(*arguments, **keywords) { ... } ⇒ Cuprum::Result

Executes the command implementation and returns a Cuprum::Result or compatible object.

Each time #call is invoked, the object performs the following steps:

  1. Creates a result object, typically an instance of Cuprum::Result. The result is assigned to the command as the private #result reader.

  2. The #process method is called, passing the arguments, keywords, and block that were passed to #call. The #process method can set errors, set the status, or halt the result via the #result reader method.

  3. If #process returns a result, that result is returned by #call. Otherwise, the return value of #process is assigned to the #value property of the result, and the result is returned by #call.

Parameters:

  • arguments (Array) —

    Arguments to be passed to the implementation.

  • keywords (Hash) —

    Keywords to be passed to the implementation.

Yields:

  • If a block argument is given, it will be passed to the implementation.

Returns:

Raises:



99
100
101
102
103
 
# File 'lib/cuprum/processing.rb', line 99

def call *args, &block
  result = build_result(nil, :errors => build_errors)

  process_with_result(result, *args, &block)
end

#process(*arguments, **keywords) { ... } ⇒ Object

Note:

This is a private method.

The implementation of the command, to be executed when the #call method is called. Can add errors to or set the status of the result, and the value of the result will be set to the value returned by #process. Do not call this method directly.

Parameters:

  • arguments (Array) —

    The arguments, if any, passed from #call.

  • keywords (Hash) —

    The keywords, if any, passed from #call.

Yields:

  • The block, if any, passed from #call.

Returns:

  • (Object) —

    the value of the result object to be returned by #call.

Raises:

  • (Cuprum::NotImplementedError) —

    Unless a block was passed to the constructor or the #process method was overriden by a Command subclass.

Raises:



161
162
163
 
# File 'lib/cuprum/processing.rb', line 161

def process *_args
  raise Cuprum::NotImplementedError, nil, caller(1..-1)
end