state_machine 0.4.3 → 0.5.0

data/CHANGELOG.rdoc

@@ -1,5 +1,22 @@
 == master
 
+== 0.5.0 / 2008-01-11
+
+* Add to_name and from_name to transition objects
+* Add nicely formatted #inspect for transitions
+* Fix ActiveRecord integrations failing when the database doesn't exist yet
+* Fix states not being drawn in GraphViz graphs in the correct order
+* Add nicely formatted #inspect for states and events
+* Simplify machine context-switching
+* Store events/states in enumerable node collections
+* No longer allow subclasses to change the integration
+* Move fire! action logic into the Event class (no longer calls fire action on the object)
+* Allow states in subclasses to have different values
+* Recommend that all states be referenced as symbols instead of strings
+* All states must now be named (and can be associated with other value types)
+* Add support for customizing the actual stored value for a state
+* Add compatibility with Ruby 1.9+
+
 == 0.4.3 / 2008-12-28
 
 * Allow dm-observer integration to be optional

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2008 Aaron Pfefier
+Copyright (c) 2006-2009 Aaron Pfefier
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -24,7 +24,7 @@ Source
 == Description
 
 State machines make it dead-simple to manage the behavior of a class.  Too often,
-the status of an object is kept by creating multiple boolean attributes and
+the state of an object is kept by creating multiple boolean attributes and
 deciding how to behave based on the values.  This can become cumbersome and
 difficult to maintain when the complexity of your class starts to increase.
 
@@ -41,13 +41,15 @@ Some brief, high-level features include:
 * ActiveRecord integration
 * DataMapper integration
 * Sequel integration
-* States of any data type
 * State predicates
 * State-driven behavior
+* State values of any data type
+* Dynamically-generated state values
+* Inheritance
 * GraphViz visualization creator
 
 Examples of the usage patterns for some of the above features are shown below.
-You can find more detailed documentation in the actual API.
+You can find much more detailed documentation in the actual API.
 
 == Usage
 
@@ -59,79 +61,83 @@ Below is an example of many of the features offered by this plugin, including:
 * Transition callbacks
 * Conditional transitions
 * State-driven behavior
+* Customized state values
 
 Class definition:
 
   class Vehicle
     attr_accessor :seatbelt_on
     
-    state_machine :state, :initial => 'parked' do
-      before_transition :from => %w(parked idling), :do => :put_on_seatbelt
-      after_transition :on => 'crash', :do => :tow
-      after_transition :on => 'repair', :do => :fix
-      after_transition :to => 'parked' do |vehicle, transition|
+    state_machine :state, :initial => :parked do
+      before_transition :from => [:parked, :idling], :do => :put_on_seatbelt
+      after_transition :on => :crash, :do => :tow
+      after_transition :on => :repair, :do => :fix
+      after_transition :to => :parked do |vehicle, transition|
         vehicle.seatbelt_on = false
       end
       
       event :park do
-        transition :to => 'parked', :from => %w(idling first_gear)
+        transition :to => :parked, :from => [:idling, :first_gear]
       end
       
       event :ignite do
-        transition :to => 'stalled', :from => 'stalled'
-        transition :to => 'idling', :from => 'parked'
+        transition :to => :stalled, :from => :stalled
+        transition :to => :idling, :from => :parked
       end
       
       event :idle do
-        transition :to => 'idling', :from => 'first_gear'
+        transition :to => :idling, :from => :first_gear
       end
       
       event :shift_up do
-        transition :to => 'first_gear', :from => 'idling'
-        transition :to => 'second_gear', :from => 'first_gear'
-        transition :to => 'third_gear', :from => 'second_gear'
+        transition :to => :first_gear, :from => :idling
+        transition :to => :second_gear, :from => :first_gear
+        transition :to => :third_gear, :from => :second_gear
       end
       
       event :shift_down do
-        transition :to => 'second_gear', :from => 'third_gear'
-        transition :to => 'first_gear', :from => 'second_gear'
+        transition :to => :second_gear, :from => :third_gear
+        transition :to => :first_gear, :from => :second_gear
       end
       
       event :crash do
-        transition :to => 'stalled', :from => %w(first_gear second_gear third_gear), :unless => :auto_shop_busy?
+        transition :to => :stalled, :from => [:first_gear, :second_gear, :third_gear], :unless => :auto_shop_busy?
       end
       
       event :repair do
-        transition :to => 'parked', :from => 'stalled', :if => :auto_shop_busy?
+        transition :to => :parked, :from => :stalled, :if => :auto_shop_busy?
       end
       
-      state 'parked' do
+      state :parked do
         def speed
           0
         end
       end
       
-      state 'idling', 'first_gear' do
+      state :idling, :first_gear do
         def speed
           10
         end
       end
       
-      state 'second_gear' do
+      state :second_gear do
         def speed
           20
         end
       end
     end
     
-    state_machine :hood_state, :initial => 'closed', :namespace => 'hood' do
+    state_machine :hood_state, :initial => :closed, :namespace => 'hood' do
       event :open do
-        transition :to => 'opened', :from => 'closed'
+        transition :to => :opened
       end
       
       event :close do
-        transition :to => 'closed', :from => 'opened'
+        transition :to => :closed
       end
+      
+      state :opened, :value => 1
+      state :closed, :value => 0
     end
     
     def initialize
@@ -160,9 +166,11 @@ Using the above class as an example, you can interact with the state machine
 like so:
 
   vehicle = Vehicle.new           # => #<Vehicle:0xb7cf4eac @state="parked", @seatbelt_on=false>
+  vehicle.state                   # => "parked"
+  vehicle.state_name              # => :parked
   vehicle.parked?                 # => true
   vehicle.can_ignite?             # => true
-  vehicle.next_ignite_transition  # => #<StateMachine::Transition:0xb7c34cec ...>
+  vehicle.next_ignite_transition  # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
   vehicle.speed                   # => 0
   
   vehicle.ignite                  # => true
@@ -180,15 +188,20 @@ like so:
   vehicle                         # => #<Vehicle:0xb7cf4eac @state="second_gear", @seatbelt_on=true>
   
   # The bang (!) operator can raise exceptions if the event fails
-  vehicle.park!                   # => StateMachine::InvalidTransition: Cannot transition via :park from "second_gear"
+  vehicle.park!                   # => StateMachine::InvalidTransition: Cannot transition state via :park from :second_gear
   
   # Generic state predicates can raise exceptions if the value does not exist
-  vehicle.state?('parked')        # => true
-  vehicle.state?('invalid')       # => ArgumentError: "parked" is not a known state value
+  vehicle.state?(:parked)         # => true
+  vehicle.state?(:invalid)        # => ArgumentError: :invalid is an invalid name
   
   # Namespaced machines have uniquely-generated methods
+  vehicle.hood_state              # => 0
+  vehicle.hood_state_name         # => :closed
+  
   vehicle.can_open_hood?          # => true
   vehicle.open_hood               # => true
+  vehicle.hood_state              # => 1
+  vehicle.hood_state_name         # => :opened
   vehicle.can_close_hood?         # => true
   
   vehicle.hood_opened?            # => true
@@ -218,14 +231,14 @@ The ActiveRecord integration adds support for database transactions, automatical
 saving the record, named scopes, and observers.  For example,
 
   class Vehicle < ActiveRecord::Base
-    state_machine :initial => 'parked' do
-      before_transition :to => 'idling', :do => :put_on_seatbelt
-      after_transition :to => 'parked' do |vehicle, transition|
+    state_machine :initial => :parked do
+      before_transition :to => :idling, :do => :put_on_seatbelt
+      after_transition :to => :parked do |vehicle, transition|
         vehicle.seatbelt = 'off'
       end
       
       event :ignite do
-        transition :to => 'idling', :from => 'parked'
+        transition :to => :idling, :from => :parked
       end
     end
     
@@ -249,45 +262,6 @@ saving the record, named scopes, and observers.  For example,
 For more information about the various behaviors added for ActiveRecord state
 machines, see StateMachine::Integrations::ActiveRecord.
 
-==== With enumerations
-
-Using the acts_as_enumeration[http://github.com/pluginaweek/acts_as_enumeration] plugin
-with an ActiveRecord integration, states can be transparently stored using
-record ids in the database like so:
-
-  class VehicleState < ActiveRecord::Base
-    acts_as_enumeration
-    
-    create :id => 1, :name => 'parked'
-    create :id => 2, :name => 'idling'
-    ...
-  end
-  
-  class Vehicle < ActiveRecord::Base
-    belongs_to :state, :class_name => 'VehicleState'
-    
-    state_machine :state, :initial => 'parked' do
-      ...
-      
-      event :park do
-        transition :to => 'parked', :from => %w(idling first_gear)
-      end
-    end
-    
-    ...
-  end
-
-Notice that the state machine definition remains *exactly* the same.  However,
-when interacting with the records, the actual state will be stored using the
-identifiers defined for the enumeration:
-
-  vehicle = Vehicle.create  # => #<Vehicle id: 1, seatbelt_on: false, state_id: 1>
-  vehicle.ignite            # => true
-  vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state_id: 2>
-
-This allows states to take on more complex functionality other than just being
-a string value.
-
 === DataMapper
 
 Like the ActiveRecord integration, the DataMapper integration adds support for
@@ -300,14 +274,14 @@ callbacks, and observers.  For example,
     property :id, Serial
     property :state, String
     
-    state_machine :initial => 'parked' do
-      before_transition :to => 'idling', :do => :put_on_seatbelt
-      after_transition :to => 'parked' do |transition|
+    state_machine :initial => :parked do
+      before_transition :to => :idling, :do => :put_on_seatbelt
+      after_transition :to => :parked do |transition|
         self.seatbelt = 'off' # self is the record
       end
       
       event :ignite do
-        transition :to => 'idling', :from => 'parked'
+        transition :to => :idling, :from => :parked
       end
     end
     
@@ -345,14 +319,14 @@ database transactions, automatically saving the record, named scopes, and
 callbacks.  For example,
 
   class Vehicle < Sequel::Model
-    state_machine :initial => 'parked' do
-      before_transition :to => 'idling', :do => :put_on_seatbelt
-      after_transition :to => 'parked' do |transition|
+    state_machine :initial => :parked do
+      before_transition :to => :idling, :do => :put_on_seatbelt
+      after_transition :to => :parked do |transition|
         self.seatbelt = 'off' # self is the record
       end
       
       event :ignite do
-        transition :to => 'idling', :from => 'parked'
+        transition :to => :idling, :from => :parked
       end
     end
     
@@ -441,7 +415,3 @@ dependencies are listed below.
 * ActiveRecord[http://rubyonrails.org] integration: 2.1.0 or later
 * DataMapper[http://datamapper.org] integration: 0.9.0 or later
 * Sequel[http://sequel.rubyforge.org] integration: 2.8.0 or later
-
-== References
-
-* acts_as_enumeration[http://github.com/pluginaweek/acts_as_enumeration]

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.4.3'
+  s.version           = '0.5.0'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   

data/examples/auto_shop.rb

@@ -0,0 +1,11 @@
+class AutoShop
+  state_machine :initial => :available do
+    event :tow_vehicle do
+      transition :to => :busy, :from => :available
+    end
+    
+    event :fix_vehicle do
+      transition :to => :available, :from => :busy
+    end
+  end
+end

data/examples/car.rb

@@ -0,0 +1,19 @@
+class Car < Vehicle
+  state_machine do
+    event :reverse do
+      transition :to => :backing_up, :from => [:parked, :idling, :first_gear]
+    end
+    
+    event :park do
+      transition :to => :parked, :from => :backing_up
+    end
+    
+    event :idle do
+      transition :to => :idling, :from => :backing_up
+    end
+    
+    event :shift_up do
+      transition :to => :first_gear, :from => :backing_up
+    end
+  end
+end

data/examples/traffic_light.rb

@@ -0,0 +1,9 @@
+class TrafficLight
+  state_machine :initial => :stop do
+    event :cycle do
+      transition :to => :proceed, :from => :stop
+      transition :to => :caution, :from => :proceed
+      transition :to => :stop, :from => :caution
+    end
+  end
+end

data/examples/vehicle.rb

@@ -0,0 +1,35 @@
+class Vehicle
+  state_machine :initial => :parked do
+    event :park do
+      transition :to => :parked, :from => [:idling, :first_gear]
+    end
+    
+    event :ignite do
+      transition :to => :stalled, :from => :stalled
+      transition :to => :idling, :from => :parked
+    end
+    
+    event :idle do
+      transition :to => :idling, :from => :first_gear
+    end
+    
+    event :shift_up do
+      transition :to => :first_gear, :from => :idling
+      transition :to => :second_gear, :from => :first_gear
+      transition :to => :third_gear, :from => :second_gear
+    end
+    
+    event :shift_down do
+      transition :to => :second_gear, :from => :third_gear
+      transition :to => :first_gear, :from => :second_gear
+    end
+    
+    event :crash do
+      transition :to => :stalled, :from => [:first_gear, :second_gear, :third_gear]
+    end
+    
+    event :repair do
+      transition :to => :parked, :from => :stalled
+    end
+  end
+end

data/lib/state_machine.rb

@@ -6,16 +6,27 @@ require 'state_machine/machine'
 module StateMachine
   module MacroMethods
     # Creates a new state machine for the given attribute.  The default
-    # attribute, if not specified, is "state".
+    # attribute, if not specified, is <tt>:state</tt>.
     # 
     # Configuration options:
-    # * +initial+ - The initial value to set the attribute to. This can be a static value or a lambda block which will be evaluated at runtime.  Default is nil.
-    # * +action+ - The action to invoke when an object transitions.  Default is nil unless otherwise specified by the configured integration.
-    # * +plural+ - The pluralized name of the attribute.  By default, this will attempt to call +pluralize+ on the attribute, otherwise an "s" is appended.
-    # * +namespace+ - The name to use for namespacing all generated instance methods (e.g. "email" => "activate_email", "deactivate_email", etc.).  Default is no namespace.
-    # * +integration+ - The name of the integration to use for adding library-specific behavior to the machine.  Built-in integrations include :data_mapper, :active_record, and :sequel.  By default, this is determined automatically.
-    # 
-    # This also requires a block which will be used to actually configure the
+    # * <tt>:initial</tt> - The initial state of the attribute. This can be a
+    #   static state or a lambda block which will be evaluated at runtime
+    #   (e.g. lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling}).
+    #   Default is nil.
+    # * <tt>:action</tt> - The action to invoke when an object transitions.
+    #   Default is nil unless otherwise specified by the configured integration.
+    # * <tt>:plural</tt> - The pluralized name of the attribute.  By default,
+    #   this will attempt to call +pluralize+ on the attribute, otherwise
+    #   an "s" is appended.  This is used for generating scopes.
+    # * <tt>:namespace</tt> - The name to use for namespacing all generated
+    #   instance methods (e.g. "heater" would generate :turn_on_heater and
+    #   :turn_off_header for the :turn_on/:turn_off events).  Default is nil.
+    # * <tt>:integration</tt> - The name of the integration to use for adding
+    #   library-specific behavior to the machine.  Built-in integrations include
+    #   :data_mapper, :active_record, and :sequel.  By default, this is
+    #   determined automatically.
+    # 
+    # This also expects a block which will be used to actually configure the
     # states, events and transitions for the state machine.  *Note* that this
     # block will be executed within the context of the state machine.  As a
     # result, you will not be able to access any class methods unless you refer
@@ -36,7 +47,7 @@ module StateMachine
     #     end
     #   end
     # 
-    # The above example will define a state machine for the attribute "state"
+    # The above example will define a state machine for the +state+ attribute
     # on the class.  Every vehicle will start without an initial state.
     # 
     # With a custom attribute:
@@ -50,15 +61,15 @@ module StateMachine
     # With a static initial state:
     # 
     #   class Vehicle
-    #     state_machine :status, :initial => 'Vehicle' do
+    #     state_machine :status, :initial => :parked do
     #       ...
     #     end
     #   end
     # 
     # With a dynamic initial state:
     # 
-    #   class Switch
-    #     state_machine :status, :initial => lambda {|switch| (8..22).include?(Time.now.hour) ? 'on' : 'off'} do
+    #   class Vehicle
+    #     state_machine :status, :initial => lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling} do
     #       ...
     #     end
     #   end
@@ -69,13 +80,15 @@ module StateMachine
     # of the machine.  In order to access this value and modify it during
     # transitions, a reader/writer must be available.  The following methods
     # will be automatically generated if they are not already defined
-    # (assuming the attribute is called "state"):
+    # (assuming the attribute is called +state+):
     # * <tt>state</tt> - Gets the current value for the attribute
     # * <tt>state=(value)</tt> - Sets the current value for the attribute
-    # * <tt>state?(value)</tt> - Checks the given value against the current value.  If the value is not a known state, then an ArgumentError is raised.
+    # * <tt>state?(name)</tt> - Checks the given state name against the current
+    #   state.  If the name is not a known state, then an ArgumentError is raised.
+    # * <tt>state_name</tt> - Gets the name of the state for the current value
     # 
-    # For example, the following machine definition will not generate any
-    # accessor methods since the class has already defined an attribute
+    # For example, the following machine definition will not generate the reader
+    # or writer methods since the class has already defined an attribute
     # accessor:
     # 
     #   class Vehicle
@@ -86,7 +99,7 @@ module StateMachine
     #     end
     #   end
     # 
-    # On the other hand, the following state machine will define both a
+    # On the other hand, the following state machine will define *both* a
     # reader and writer method, which is functionally equivalent to the
     # example above:
     # 
@@ -106,13 +119,13 @@ module StateMachine
     # For example,
     # 
     #   class Vehicle
-    #     state_machine :state, :initial => 'parked' do
+    #     state_machine :state, :initial => :parked do
     #       ...
     #     end
     #   end
     #   
-    #   v = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
-    #   v.state           # => "parked"
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
+    #   vehicle.state           # => "parked"
     # 
     # In the above example, no +initialize+ method is defined.  As a result,
     # the default behavior of initializing the state machine attributes is used.
@@ -120,7 +133,7 @@ module StateMachine
     # In the following example, a custom +initialize+ method is defined:
     # 
     #   class Vehicle
-    #     state_machine :state, :initial => 'parked' do
+    #     state_machine :state, :initial => :parked do
     #       ...
     #     end
     #     
@@ -128,8 +141,8 @@ module StateMachine
     #     end
     #   end
     #   
-    #   v = Vehicle.new   # => #<Vehicle:0xb7c77678>
-    #   v.state           # => nil
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c77678>
+    #   vehicle.state           # => nil
     # 
     # Since the +initialize+ method is defined, the state machine attributes
     # never get initialized.  In order to ensure that all initialization hooks
@@ -137,7 +150,7 @@ module StateMachine
     # like so:
     # 
     #   class Vehicle
-    #     state_machine :state, :initial => 'parked' do
+    #     state_machine :state, :initial => :parked do
     #       ...
     #     end
     #     
@@ -147,19 +160,19 @@ module StateMachine
     #     end
     #   end
     #   
-    #   v = Vehicle.new   # => #<Vehicle:0xb7c464b0 @state="parked">
-    #   v.state           # => "parked"
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
+    #   vehicle.state           # => "parked"
     # 
-    # Because of the way the inclusion of modules works in Ruby, calling <tt>super()</tt>
-    # will not only call the superclass's +initialize+, but also +initialize+ on
-    # all included modules.  This allows the original state machine hook to get
-    # called properly.
+    # Because of the way the inclusion of modules works in Ruby, calling
+    # <tt>super()</tt> will not only call the superclass's +initialize+, but
+    # also +initialize+ on all included modules.  This allows the original state
+    # machine hook to get called properly.
     # 
     # If you want to avoid calling the superclass's constructor, but still want
     # to initialize the state machine attributes:
     # 
     #   class Vehicle
-    #     state_machine :state, :initial => 'parked' do
+    #     state_machine :state, :initial => :parked do
     #       ...
     #     end
     #     
@@ -169,24 +182,24 @@ module StateMachine
     #     end
     #   end
     #   
-    #   v = Vehicle.new   # => #<Vehicle:0xb7c464b0 @state="parked">
-    #   v.state           # => "parked"
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
+    #   vehicle.state           # => "parked"
     # 
     # == States
     # 
     # All of the valid states for the machine are automatically tracked based
     # on the events, transitions, and callbacks defined for the machine.  If
     # there are additional states that are never referenced, these should be
-    # explicitly added using the StateMachine::Machine#other_states
-    # helper.
+    # explicitly added using the StateMachine::Machine#state or
+    # StateMachine::Machine#other_states helpers.
     # 
-    # When using String or Symbol-based states, a predicate method for that
-    # state is generated on the class.  For example,
+    # When a new state is defined, a predicate method for that state is
+    # generated on the class.  For example,
     # 
     #   class Vehicle
-    #     state_machine :initial => 'parked' do
+    #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => 'idling'
+    #         transition :to => :idling
     #       end
     #     end
     #   end
@@ -227,23 +240,23 @@ module StateMachine
     # For example,
     # 
     #   class Vehicle
-    #     state_machine :heater_state, :initial => 'off' :namespace => 'heater' do
+    #     state_machine :heater_state, :initial => :off :namespace => 'heater' do
     #       event :turn_on do
-    #         transition :to => 'on', :from => 'off'
+    #         transition :to => :on
     #       end
     #       
     #       event :turn_off do
-    #         transition :to => 'off', :from => 'on'
+    #         transition :to => :off
     #       end
     #     end
     #     
-    #     state_machine :hood_state, :initial => 'closed', :namespace => 'hood' do
+    #     state_machine :hood_state, :initial => :closed, :namespace => 'hood' do
     #       event :open do
-    #         transition :to => 'opened', :from => 'closed'
+    #         transition :to => :opened
     #       end
     #       
     #       event :close do
-    #         transition :to => 'closed', :from => 'opened'
+    #         transition :to => :closed
     #       end
     #     end
     #   end
@@ -275,19 +288,19 @@ module StateMachine
     # 
     # For integrations that support it, a group of default scope filters will
     # be automatically created for assisting in finding objects that have the
-    # attribute set to a given value.
+    # attribute set to the value for a given set of states.
     # 
     # For example,
     # 
-    #   Vehicle.with_state('parked') # => Finds all vehicles where the state is parked
-    #   Vehicle.with_states('parked', 'idling') # => Finds all vehicles where the state is either parked or idling
+    #   Vehicle.with_state(:parked) # => Finds all vehicles where the state is parked
+    #   Vehicle.with_states(:parked, :idling) # => Finds all vehicles where the state is either parked or idling
     #   
-    #   Vehicle.without_state('parked') # => Finds all vehicles where the state is *not* parked
-    #   Vehicle.without_states('parked', 'idling') # => Finds all vehicles where the state is *not* parked or idling
+    #   Vehicle.without_state(:parked) # => Finds all vehicles where the state is *not* parked
+    #   Vehicle.without_states(:parked, :idling) # => Finds all vehicles where the state is *not* parked or idling
     # 
     # *Note* that if class methods already exist with those names (i.e.
-    # "with_state", "with_states", "without_state", or "without_states"), then
-    # a scope will not be defined for that name.
+    # :with_state, :with_states, :without_state, or :without_states), then a
+    # scope will not be defined for that name.
     # 
     # See StateMachine::Machine for more information about using
     # integrations and the individual integration docs for information about