Class StateMachine::StateCollection
In: lib/state_machine/state_collection.rb
Parent: NodeCollection

Represents a collection of states in a state machine

Methods

by_priority   match   match!   matches?  

Public Instance methods

Gets the order in which states should be displayed based on where they were first referenced. This will order states in the following priority:

  1. Initial state
  2. Event transitions (:from, :except_from, :to, :except_to options)
  3. States with behaviors
  4. States referenced via state or other_states
  5. States referenced in callbacks

This order will determine how the GraphViz visualizations are rendered.

[Source]

     # File lib/state_machine/state_collection.rb, line 93
 93:     def by_priority
 94:       order = select {|state| state.initial}.map {|state| state.name}
 95:       
 96:       machine.events.each {|event| order += event.known_states}
 97:       order += select {|state| state.methods.any?}.map {|state| state.name}
 98:       order += keys(:name) - machine.callbacks.values.flatten.map {|callback| callback.known_states}.flatten
 99:       order += keys(:name)
100:       
101:       order.uniq!
102:       order.map! {|name| self[name]}
103:       order
104:     end

Determines the current state of the given object as configured by this state machine. This will attempt to find a known state that matches the value of the attribute on the object.

Examples

  class Vehicle
    state_machine :initial => :parked do
      other_states :idling
    end
  end

  states = Vehicle.state_machine.states

  vehicle = Vehicle.new         # => #<Vehicle:0xb7c464b0 @state="parked">
  states.match(vehicle)         # => #<StateMachine::State name=:parked value="parked" initial=true>

  vehicle.state = 'idling'
  states.match(vehicle)         # => #<StateMachine::State name=:idling value="idling" initial=true>

  vehicle.state = 'invalid'
  states.match(vehicle)         # => nil

[Source]

    # File lib/state_machine/state_collection.rb, line 55
55:     def match(object)
56:       value = machine.read(object, :state)
57:       self[value, :value] || detect {|state| state.matches?(value)}
58:     end

Determines the current state of the given object as configured by this state machine. If no state is found, then an ArgumentError will be raised.

Examples

  class Vehicle
    state_machine :initial => :parked do
      other_states :idling
    end
  end

  states = Vehicle.state_machine.states

  vehicle = Vehicle.new         # => #<Vehicle:0xb7c464b0 @state="parked">
  states.match!(vehicle)        # => #<StateMachine::State name=:parked value="parked" initial=true>

  vehicle.state = 'invalid'
  states.match!(vehicle)        # => ArgumentError: "invalid" is not a known state value

[Source]

    # File lib/state_machine/state_collection.rb, line 79
79:     def match!(object)
80:       match(object) || raise(ArgumentError, "#{machine.read(object, :state).inspect} is not a known #{machine.name} value")
81:     end

Determines whether the given object is in a specific state. If the object‘s current value doesn‘t match the state, then this will return false, otherwise true. If the given state is unknown, then an IndexError will be raised.

Examples

  class Vehicle
    state_machine :initial => :parked do
      other_states :idling
    end
  end

  states = Vehicle.state_machine.states
  vehicle = Vehicle.new               # => #<Vehicle:0xb7c464b0 @state="parked">

  states.matches?(vehicle, :parked)   # => true
  states.matches?(vehicle, :idling)   # => false
  states.matches?(vehicle, :invalid)  # => IndexError: :invalid is an invalid key for :name index

[Source]

    # File lib/state_machine/state_collection.rb, line 29
29:     def matches?(object, name)
30:       fetch(name).matches?(machine.read(object, :state))
31:     end

[Validate]