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) —

    Optional Metadata for this object.

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

    Tags for this event.



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
# 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

  meta.each do |meta_name, value|
    class_eval do
      attr_accessor meta_name
    end
    instance_variable_set("@#{meta_name}", value)
  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.



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

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

#evaluate!(target) ⇒ Object 



60
61
62
63
64
65
66
67
 
# File 'lib/workflow/event.rb', line 60

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 



45
46
47
 
# File 'lib/workflow/event.rb', line 45

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.



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

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) 


82
83
84
 
# File 'lib/workflow/event.rb', line 82

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

#valid? ⇒ Boolean

Returns:

  • (Boolean) 


41
42
43
 
# File 'lib/workflow/event.rb', line 41

def valid?
  transitions.any?
end