Class StateMachine::Transition
In: lib/state_machine/transition.rb
Parent: Object

A transition represents a state change for a specific attribute.

Transitions consist of:

  • An event
  • A starting state
  • An ending state

Methods

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

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

The action that will be run when this transition is performed

The attribute which this transition‘s machine is defined for

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'}

The event that triggered the transition

The state name before the transition

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

The human-readable state name before the transition

The new human-readable state name after the transition

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>

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

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

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'

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

The fully-qualified state name before the transition

The new fully-qualified state name after the transition

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

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"

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.

The new state name after the transition

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.

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.

[Validate]