Class: StateMachine::Transition

Attributes

args	[RW]	The arguments passed in to the event that triggered the transition (does not include the `run_action` boolean argument if specified)
from	[R]	The original state value before the transition
machine	[R]	The state machine for which this transition is defined
object	[R]	The object being transitioned
result	[R]	The result of invoking the action associated with the machine
to	[R]	The new state value after the transition
transient	[W]	Whether the transition is only existing temporarily for the object

Public Instance methods

==(other)

Determines equality of transitions by testing whether the object, states, and event involved in the transition are equal

[Source]

     # File lib/state_machine/transition.rb, line 313
313:     def ==(other)
314:       other.instance_of?(self.class) &&
315:       other.object == object &&
316:       other.machine == machine &&
317:       other.from_name == from_name &&
318:       other.to_name == to_name &&
319:       other.event == event
320:     end

action()

The action that will be run when this transition is performed

[Source]

     # File lib/state_machine/transition.rb, line 109
109:     def action
110:       machine.action
111:     end

attribute()

The attribute which this transition‘s machine is defined for

[Source]

     # File lib/state_machine/transition.rb, line 104
104:     def attribute
105:       machine.attribute
106:     end

attributes()

A hash of all the core attributes defined for this transition with their names as keys and values of the attributes as values.

Example

  machine = StateMachine.new(Vehicle)
  transition = StateMachine::Transition.new(Vehicle.new, machine, :ignite, :parked, :idling)
  transition.attributes   # => {:object => #<Vehicle:0xb7d60ea4>, :attribute => :state, :event => :ignite, :from => 'parked', :to => 'idling'}

[Source]

     # File lib/state_machine/transition.rb, line 185
185:     def attributes
186:       @attributes ||= {:object => object, :attribute => attribute, :event => event, :from => from, :to => to}
187:     end

event()

The event that triggered the transition

[Source]

     # File lib/state_machine/transition.rb, line 114
114:     def event
115:       @event.name
116:     end

from_name()

The state name before the transition

[Source]

     # File lib/state_machine/transition.rb, line 129
129:     def from_name
130:       @from_state.name
131:     end

human_event()

The human-readable name of the event that triggered the transition

[Source]

     # File lib/state_machine/transition.rb, line 124
124:     def human_event
125:       @event.human_name(@object.class)
126:     end

human_from_name()

The human-readable state name before the transition

[Source]

     # File lib/state_machine/transition.rb, line 139
139:     def human_from_name
140:       @from_state.human_name(@object.class)
141:     end

human_to_name()

The new human-readable state name after the transition

[Source]

     # File lib/state_machine/transition.rb, line 154
154:     def human_to_name
155:       @to_state.human_name(@object.class)
156:     end

inspect()

Generates a nicely formatted description of this transitions‘s contents.

For example,

  transition = StateMachine::Transition.new(object, machine, :ignite, :parked, :idling)
  transition   # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>

[Source]

     # File lib/state_machine/transition.rb, line 328
328:     def inspect
329:       "#<#{self.class} #{%w(attribute event from from_name to to_name).map {|attr| "#{attr}=#{send(attr).inspect}"} * ' '}>"
330:     end

loopback?()

Does this transition represent a loopback (i.e. the from and to state are the same)

Example

  machine = StateMachine.new(Vehicle)
  StateMachine::Transition.new(Vehicle.new, machine, :park, :parked, :parked).loopback?   # => true
  StateMachine::Transition.new(Vehicle.new, machine, :park, :idling, :parked).loopback?   # => false

[Source]

     # File lib/state_machine/transition.rb, line 166
166:     def loopback?
167:       from_name == to_name
168:     end

perform(*args)

Runs the actual transition and any before/after callbacks associated with the transition. The action associated with the transition/machine can be skipped by passing in false.

Examples

  class Vehicle
    state_machine :action => :save do
      ...
    end
  end

  vehicle = Vehicle.new
  transition = StateMachine::Transition.new(vehicle, machine, :ignite, :parked, :idling)
  transition.perform                  # => Runs the +save+ action after setting the state attribute
  transition.perform(false)           # => Only sets the state attribute
  transition.perform(Time.now)        # => Passes in additional arguments and runs the +save+ action
  transition.perform(Time.now, false) # => Passes in additional arguments and only sets the state attribute

[Source]

     # File lib/state_machine/transition.rb, line 207
207:     def perform(*args)
208:       run_action = [true, false].include?(args.last) ? args.pop : true
209:       self.args = args
210:       
211:       # Run the transition
212:       !!TransitionCollection.new([self], :actions => run_action).perform
213:     end

persist()

Transitions the current value of the state to that specified by the transition. Once the state is persisted, it cannot be persisted again until this transition is reset.

Example

  class Vehicle
    state_machine do
      event :ignite do
        transition :parked => :idling
      end
    end
  end

  vehicle = Vehicle.new
  transition = StateMachine::Transition.new(vehicle, Vehicle.state_machine, :ignite, :parked, :idling)
  transition.persist

  vehicle.state   # => 'idling'

[Source]

     # File lib/state_machine/transition.rb, line 268
268:     def persist
269:       unless @persisted
270:         machine.write(object, :state, to)
271:         @persisted = true
272:       end
273:     end

qualified_event()

The fully-qualified name of the event that triggered the transition

[Source]

     # File lib/state_machine/transition.rb, line 119
119:     def qualified_event
120:       @event.qualified_name
121:     end

qualified_from_name()

The fully-qualified state name before the transition

[Source]

     # File lib/state_machine/transition.rb, line 134
134:     def qualified_from_name
135:       @from_state.qualified_name
136:     end

qualified_to_name()

The new fully-qualified state name after the transition

[Source]

     # File lib/state_machine/transition.rb, line 149
149:     def qualified_to_name
150:       @to_state.qualified_name
151:     end

reset()

Resets any tracking of which callbacks have already been run and whether the state has already been persisted

[Source]

     # File lib/state_machine/transition.rb, line 306
306:     def reset
307:       @before_run = @persisted = @after_run = false
308:       @paused_block = nil
309:     end

rollback()

Rolls back changes made to the object‘s state via this transition. This will revert the state back to the from value.

Example

  class Vehicle
    state_machine :initial => :parked do
      event :ignite do
        transition :parked => :idling
      end
    end
  end

  vehicle = Vehicle.new     # => #<Vehicle:0xb7b7f568 @state="parked">
  transition = StateMachine::Transition.new(vehicle, Vehicle.state_machine, :ignite, :parked, :idling)

  # Persist the new state
  vehicle.state             # => "parked"
  transition.persist
  vehicle.state             # => "idling"

  # Roll back to the original state
  transition.rollback
  vehicle.state             # => "parked"

[Source]

     # File lib/state_machine/transition.rb, line 299
299:     def rollback
300:       reset
301:       machine.write(object, :state, from)
302:     end

run_callbacks(options = {}, &block)

Runs the before / after callbacks for this transition. If a block is provided, then it will be executed between the before and after callbacks.

Configuration options:

before - Whether to run before callbacks.
after - Whether to run after callbacks. If false, then any around callbacks will be paused until called again with after enabled. Default is true.

This will return true if all before callbacks gets executed. After callbacks will not have an effect on the result.

[Source]

     # File lib/state_machine/transition.rb, line 235
235:     def run_callbacks(options = {}, &block)
236:       options = {:before => true, :after => true}.merge(options)
237:       @success = false
238:       
239:       halted = pausable { before(options[:after], &block) } if options[:before]
240:       
241:       # After callbacks are only run if:
242:       # * An around callback didn't halt after yielding
243:       # * They're enabled or the run didn't succeed
244:       after if !(@before_run && halted) && (options[:after] || !@success)
245:       
246:       @before_run
247:     end

to_name()

The new state name after the transition

[Source]

     # File lib/state_machine/transition.rb, line 144
144:     def to_name
145:       @to_state.name
146:     end

transient?()

Is this transition existing for a short period only? If this is set, it indicates that the transition (or the event backing it) should not be written to the object if it fails.

[Source]

     # File lib/state_machine/transition.rb, line 173
173:     def transient?
174:       @transient
175:     end

within_transaction() {|| ...}

Runs a block within a transaction for the object being transitioned. By default, transactions are a no-op unless otherwise defined by the machine‘s integration.

[Source]

     # File lib/state_machine/transition.rb, line 218
218:     def within_transaction
219:       machine.within_transaction(object) do
220:         yield
221:       end
222:     end

Methods

Attributes

Public Instance methods

Example

Example

Examples

Example

Example