Class: StateMachine::Event

Inherits:

Object

• Object
• StateMachine::Event

show all

Includes:

Assertions, MatcherHelpers

Defined in:

lib/state_machine/event.rb

Overview

Instance Attribute Summary (collapse)

• - (Object) branches readonly

  The list of branches that determine what state this event transitions objects to when fired.

• - (Object) human_name(klass = @machine.owner_class)

  Transforms the event name into a more human-readable format, such as “turn on” instead of “turn_on”.

• - (Object) known_states readonly

  A list of all of the states known to this event using the configured branches/transitions as the source.

• - (Object) machine

  The state machine for which this event is defined.

• - (Object) name readonly

  The name of the event.

• - (Object) qualified_name readonly

  The fully-qualified name of the event, scoped by the machine's namespace.

Instance Method Summary (collapse)

• - (Boolean) can_fire?(object, requirements = {})

  Determines whether any transitions can be performed for this event based on the current state of the given object.

• - (Object) context(&block)

  Evaluates the given block within the context of this event.

• - (Object) draw(graph, options = {})

  Draws a representation of this event on the given graph.

• - (Object) fire(object, *args)

  Attempts to perform the next available transition on the given object.

• - (Event) initialize(machine, name, options = {}) constructor

  Creates a new event within the context of the given machine.

• - (Object) initialize_copy(orig)

  Creates a copy of this event in addition to the list of associated branches to prevent conflicts across events within a class hierarchy.

• - (Object) inspect

  Generates a nicely formatted description of this event's contents.

• - (Object) on_failure(object)

  Marks the object as invalid and runs any failure callbacks associated with this event.

• - (Object) reset

  Resets back to the initial state of the event, with no branches / known states associated.

• - (Object) transition(options)

  Creates a new transition that determines what to change the current state to when this event fires.

• - (Object) transition_for(object, requirements = {})

  Finds and builds the next transition that can be performed on the given object.

Methods included from MatcherHelpers

#all, #same

Methods included from Assertions

#assert_exclusive_keys, #assert_valid_keys

51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# File 'lib/state_machine/event.rb', line 51

def initialize(machine, name, options = {}) #:nodoc:
  assert_valid_keys(options, :human_name)
  
  @machine = machine
  @name = name
  @qualified_name = machine.namespace ? :#{name}_#{machine.namespace}" : name
  @human_name = options[:human_name] || @name.to_s.tr('_', ' ')
  reset
  
  # Output a warning if another event has a conflicting qualified name
  if conflict = machine.owner_class.state_machines.detect {|other_name, other_machine| other_machine != @machine && other_machine.events[qualified_name, :qualified_name]}
    name, other_machine = conflict
    warn "Event #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
  else
    add_actions
  end
end

41
42
43

# File 'lib/state_machine/event.rb', line 41

def branches
  @branches
end

79
80
81

# File 'lib/state_machine/event.rb', line 79

def human_name(klass = @machine.owner_class)
  @human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name
end

45
46
47

# File 'lib/state_machine/event.rb', line 45

def known_states
  @known_states
end

28
29
30

# File 'lib/state_machine/event.rb', line 28

def machine
  @machine
end

31
32
33

# File 'lib/state_machine/event.rb', line 31

def name
  @name
end

34
35
36

# File 'lib/state_machine/event.rb', line 34

def qualified_name
  @qualified_name
end

125
126
127

# File 'lib/state_machine/event.rb', line 125

def can_fire?(object, requirements = {})
  !transition_for(object, requirements).nil?
end

85
86
87

# File 'lib/state_machine/event.rb', line 85

def context(&block)
  instance_eval(&block)
end

205
206
207
208
209
210
211
212

# File 'lib/state_machine/event.rb', line 205

def draw(graph, options = {})
  valid_states = machine.states.by_priority.map {|state| state.name}
  branches.each do |branch|
    branch.draw(graph, options[:human_name] ? human_name : name, valid_states)
  end
  
  true
end

169
170
171
172
173
174
175
176
177
178

# File 'lib/state_machine/event.rb', line 169

def fire(object, *args)
  machine.reset(object)
  
  if transition = transition_for(object)
    transition.perform(*args)
  else
    on_failure(object)
    false
  end
end

71
72
73
74
75

# File 'lib/state_machine/event.rb', line 71

def initialize_copy(orig) #:nodoc:
  super
  @branches = @branches.dup
  @known_states = @known_states.dup
end

event = StateMachine::Event.new(machine, :park)
event.transition all - :idling => :parked, :idling => same
event   # => #<StateMachine::Event name=:park transitions=[all - :idling => :parked, :idling => same]>

221
222
223
224
225
226
227
228
229

# File 'lib/state_machine/event.rb', line 221

def inspect
  transitions = branches.map do |branch|
    branch.state_requirements.map do |state_requirement|
      "#{state_requirement[:from].description} => #{state_requirement[:to].description}"
    end * ', '
  end
  
  "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
end

182
183
184
185
186
187

# File 'lib/state_machine/event.rb', line 182

def on_failure(object)
  state = machine.states.match!(object)
  machine.invalidate(object, :state, :invalid_transition, [[:event, human_name(object.class)], [:state, state.human_name(object.class)]])
  
  Transition.new(object, machine, name, state.name, state.name).run_callbacks(:before => false)
end

193
194
195
196

# File 'lib/state_machine/event.rb', line 193

def reset
  @branches = []
  @known_states = []
end

state_machine do
  event :ignite do
    transition :parked => :idling, :idling => same, :if => :seatbelt_on? # Transitions to :idling if seatbelt is on
    transition all => :parked, :unless => :seatbelt_on?                  # Transitions to :parked if seatbelt is off
  end
end

105
106
107
108
109
110
111
112
113
114
115

# File 'lib/state_machine/event.rb', line 105

def transition(options)
  raise ArgumentError, 'Must specify as least one transition requirement' if options.empty?
  
  # Only a certain subset of explicit options are allowed for transition
  # requirements
  assert_valid_keys(options, :from, :to, :except_from, :except_to, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
  
  branches << branch = Branch.new(options.merge(:on => name))
  @known_states |= branch.known_states
  branch
end

139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

# File 'lib/state_machine/event.rb', line 139

def transition_for(object, requirements = {})
  assert_valid_keys(requirements, :from, :to, :guard)
  requirements[:from] = machine.states.match!(object).name unless custom_from_state = requirements.include?(:from)
  
  branches.each do |branch|
    if match = branch.match(object, requirements)
      # Branch allows for the transition to occur
      from = requirements[:from]
      to = if match[:to].is_a?(LoopbackMatcher)
        from
      else
        values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map {|state| state.name}
        
        match[:to].filter(values).first
      end
      
      return Transition.new(object, machine, name, from, to, !custom_from_state)
    end
  end
  
  # No transition matched
  nil
end