### Home Classes Methods

### In Files

- lib/state_machine/transition.rb

### Parent

Object

### Methods

- ::pause_supported?
- #==
- #action
- #attribute
- #attributes
- #event
- #from_name
- #human_event
- #human_from_name
- #human_to_name
- #inspect
- #loopback?
- #perform
- #persist
- #qualified_event
- #qualified_from_name
- #qualified_to_name
- #reset
- #rollback
- #run_callbacks
- #to_name
- #transient?
- #within_transaction

### Files

- LICENSE

### Class/Module Index

Quicksearch

- StateMachine
- StateMachine::AllMatcher
- StateMachine::Assertions
- StateMachine::AttributeTransitionCollection
- StateMachine::BlacklistMatcher
- StateMachine::Branch
- StateMachine::Callback
- StateMachine::ClassMethods
- StateMachine::Error
- StateMachine::EvalHelpers
- StateMachine::Event
- StateMachine::EventCollection
- StateMachine::Graph
- StateMachine::InstanceMethods
- StateMachine::IntegrationNotFound
- StateMachine::Integrations
- StateMachine::Integrations::ActiveModel
- StateMachine::Integrations::ActiveModel::Observer
- StateMachine::Integrations::ActiveModel::ObserverUpdate
- StateMachine::Integrations::ActiveRecord
- StateMachine::Integrations::Base
- StateMachine::Integrations::Base::ClassMethods
- StateMachine::Integrations::DataMapper
- StateMachine::Integrations::DataMapper::Observer
- StateMachine::Integrations::MongoMapper
- StateMachine::Integrations::Mongoid
- StateMachine::Integrations::Sequel
- StateMachine::InvalidEvent
- StateMachine::InvalidParallelTransition
- StateMachine::InvalidTransition
- StateMachine::LoopbackMatcher
- StateMachine::Machine
- StateMachine::MachineCollection
- StateMachine::MacroMethods
- StateMachine::Matcher
- StateMachine::MatcherHelpers
- StateMachine::NodeCollection
- StateMachine::Path
- StateMachine::PathCollection
- StateMachine::RailsEngine
- StateMachine::State
- StateMachine::StateCollection
- StateMachine::StateContext
- StateMachine::Transition
- StateMachine::TransitionCollection
- StateMachine::WhitelistMatcher
- StateMachine::YARD
- StateMachine::YARD::Handlers
- StateMachine::YARD::Handlers::Base
- StateMachine::YARD::Handlers::Event
- StateMachine::YARD::Handlers::Machine
- StateMachine::YARD::Handlers::State
- StateMachine::YARD::Handlers::Transition
- Object

No matching classes.

# StateMachine::Transition

A transition represents a state change for a specific attribute.

Transitions consist of:

- An event

- A starting state

- An ending state

### 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 Class Methods

pause_supported?() click to toggle source

Determines whether the curreny ruby implementation supports pausing and resuming transitions

    # File lib/state_machine/transition.rb, line 89
    def self.pause_supported?
      !defined?(RUBY_ENGINE) || %(ruby maglev).include?(RUBY_ENGINE)
    end

### Public Instance Methods

==(other) click to toggle source

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

    # File lib/state_machine/transition.rb, line 320
    def ==(other)
      other.instance_of?(self.class) &&
      other.object == object &&
      other.machine == machine &&
      other.from_name == from_name &&
      other.to_name == to_name &&
      other.event == event
    end

action() click to toggle source

The action that will be run when this transition is performed

    # File lib/state_machine/transition.rb, line 116
    def action
      machine.action
    end

attribute() click to toggle source

The attribute which this transition's machine is defined for

    # File lib/state_machine/transition.rb, line 111
    def attribute
      machine.attribute
    end

attributes() click to toggle source

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

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

event() click to toggle source

The event that triggered the transition

    # File lib/state_machine/transition.rb, line 121
    def event
      @event.name
    end

from_name() click to toggle source

The state name before the transition

    # File lib/state_machine/transition.rb, line 136
    def from_name
      @from_state.name
    end

human_event() click to toggle source

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

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

human_from_name() click to toggle source

The human-readable state name before the transition

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

human_to_name() click to toggle source

The new human-readable state name after the transition

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

inspect() click to toggle source

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>

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

loopback?() click to toggle source

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

    # File lib/state_machine/transition.rb, line 173
    def loopback?
      from_name == to_name
    end

perform(*args) click to toggle source

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

    # File lib/state_machine/transition.rb, line 214
    def perform(*args)
      run_action = [true, false].include?(args.last) ? args.pop : true
      self.args = args

      # Run the transition
      !!TransitionCollection.new([self], :actions => run_action).perform
    end

persist() click to toggle source

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'

    # File lib/state_machine/transition.rb, line 275
    def persist
      unless @persisted
        machine.write(object, :state, to)
        @persisted = true
      end
    end

qualified_event() click to toggle source

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

    # File lib/state_machine/transition.rb, line 126
    def qualified_event
      @event.qualified_name
    end

qualified_from_name() click to toggle source

The fully-qualified state name before the transition

    # File lib/state_machine/transition.rb, line 141
    def qualified_from_name
      @from_state.qualified_name
    end

qualified_to_name() click to toggle source

The new fully-qualified state name after the transition

    # File lib/state_machine/transition.rb, line 156
    def qualified_to_name
      @to_state.qualified_name
    end

reset() click to toggle source

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

    # File lib/state_machine/transition.rb, line 313
    def reset
      @before_run = @persisted = @after_run = false
      @paused_block = nil
    end

rollback() click to toggle source

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"

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

run_callbacks(options = {}, &block) click to toggle source

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.

    # File lib/state_machine/transition.rb, line 242
    def run_callbacks(options = {}, &block)
      options = {:before => true, :after => true}.merge(options)
      @success = false

      halted = pausable { before(options[:after], &block) } if options[:before]

      # After callbacks are only run if:
      # * An around callback didn't halt after yielding
      # * They're enabled or the run didn't succeed
      after if !(@before_run && halted) && (options[:after] || !@success)

      @before_run
    end

to_name() click to toggle source

The new state name after the transition

    # File lib/state_machine/transition.rb, line 151
    def to_name
      @to_state.name
    end

transient?() click to toggle source

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.

    # File lib/state_machine/transition.rb, line 180
    def transient?
      @transient
    end

within_transaction() click to toggle source

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.

    # File lib/state_machine/transition.rb, line 225
    def within_transaction
      machine.within_transaction(object) do
        yield
      end
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.