Class: Workflow::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/workflow/event.rb

Defined Under Namespace

Classes: Conditions, Transition

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, tags: [], meta: {}) ⇒ Event

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

See State#on for creating objects of this class.

Parameters:

  • name (Symbol) —

    The name of the event to create.

  • meta (Hash) (defaults to: {}) —

    Optional Metadata for this object.

  • tags (Array) (defaults to: []) —

    Tags for this event.



19
20
21
22
23
24
25
26
27
 
# File 'lib/workflow/event.rb', line 19

def initialize(name, tags: [], meta: {})
  @name = name.to_sym
  @transitions = []
  @meta = meta || {}
  @tags = [tags].flatten.uniq
  unless @tags.reject { |t| t.is_a? Symbol }
    raise WorkflowDefinitionError, "Tags can only include symbols, event: [#{name}]"
  end
end

Instance Attribute Details

#meta ⇒ Hash (readonly)

Returns Extra information defined for this event.

Returns:

  • (Hash) —

    Extra information defined for this event.



12
 
# File 'lib/workflow/event.rb', line 12

attr_reader :name, :transitions, :meta, :tags

#name ⇒ Symbol (readonly)

Returns The name of the event.

Returns:

  • (Symbol) —

    The name of the event.



12
13
14
 
# File 'lib/workflow/event.rb', line 12

def name
  @name
end

#tags ⇒ Object (readonly)

Returns the value of attribute tags.



12
 
# File 'lib/workflow/event.rb', line 12

attr_reader :name, :transitions, :meta, :tags

#transitions ⇒ Array (readonly)

Returns Array of Transitions defined for this event.

Returns:

  • (Array) —

    Array of Transitions defined for this event.



12
 
# File 'lib/workflow/event.rb', line 12

attr_reader :name, :transitions, :meta, :tags

Instance Method Details

#evaluate(target) ⇒ Workflow::State

Returns the State that the target object should enter. This will be the first one in the list of transitions, whose conditions apply to the target object in its present state.

Parameters:

  • target (Object) —

    An object of the class that this event was defined on.

Returns:

  • (Workflow::State) —

    The first applicable destination state, or nil if none.



47
48
49
50
51
 
# File 'lib/workflow/event.rb', line 47

def evaluate(target)
  transitions.find do |transition|
    transition.matches? target
  end&.target_state
end

#evaluate!(target) ⇒ Object 



53
54
55
56
57
58
59
60
 
# File 'lib/workflow/event.rb', line 53

def evaluate!(target)
  state_name = evaluate(target)
  unless state_name
    raise NoMatchingTransitionError, "No matching transition found on #{name}
      for target #{target}.  Consider adding a catchall transition.".squish
  end
  state_name
end

#inspect ⇒ Object 



38
39
40
 
# File 'lib/workflow/event.rb', line 38

def inspect
  "<Event name=#{name.inspect} transitions(#{transitions.length})=#{transitions.inspect}>"
end

#title ⇒ String

Returns Titleized name of this event.

Returns:

  • (String) —

    Titleized name of this event.



30
31
32
 
# File 'lib/workflow/event.rb', line 30

def title
  name.to_s.titleize
end

#to(target_state, **conditions_def) { ... } ⇒ nil

Add a Transition to the possible #transitions for this event.

Parameters:

  • target_state (Symbol) —

    the name of the state target state if this transition matches.

  • conditions_def (Hash) —

    a customizable set of options

Options Hash (**conditions_def):

  • :if (Symbol) —

    Name of instance method to evaluate. e.g. :valid?

  • :if (Array) —

    Mixed array of Symbol, String or Proc conditions. All must match for the transition to apply.

  • :if (String) —

    A string to evaluate on the target. e.g. "self.foo == :bar"

  • :if (Proc) —

    A proc which will be evaluated on the object e.g. ->{self.foo == :bar}

  • :unless (Symbol) —

    Same Like :if but all conditions must not match

Yields:

  • [] Optional block which, if provided, becomes an :if condition for the transition.

Returns:

  • (nil) 


75
76
77
 
# File 'lib/workflow/event.rb', line 75

def to(target_state, **conditions_def, &block)
  transitions << Transition.new(target_state, conditions_def, &block)
end

#valid? ⇒ Boolean

Returns:

  • (Boolean) 


34
35
36
 
# File 'lib/workflow/event.rb', line 34

def valid?
  transitions.any?
end