state_machine 0.4.1 → 0.4.2

data/CHANGELOG.rdoc

@@ -1,5 +1,13 @@
 == master
 
+== 0.4.2 / 2008-12-28
+
+* Fix graphs not being drawn the same way consistently
+* Add support for sharing transitions across multiple events
+* Add support for state-driven behavior
+* Simplify initialize hooks, requiring super to be called instead
+* Add :namespace option for generated state predicates / event methods
+
 == 0.4.1 / 2008-12-16
 
 * Fix nil states not being handled properly in guards, known states, or visualizations

data/README.rdoc

@@ -36,12 +36,14 @@ state machine is :)
 Some brief, high-level features include:
 * Defining state machines on any Ruby class
 * Multiple state machines on a single class
+* Namespaced state machines
 * before/after transition hooks with explicit transition requirements
 * ActiveRecord integration
 * DataMapper integration
 * Sequel integration
 * States of any data type
 * State predicates
+* State-driven behavior
 * GraphViz visualization creator
 
 Examples of the usage patterns for some of the above features are shown below.
@@ -51,10 +53,14 @@ You can find more detailed documentation in the actual API.
 
 === Example
 
-Below is an example of many of the features offered by this plugin, including
+Below is an example of many of the features offered by this plugin, including:
 * Initial states
+* Namespaced states
 * Transition callbacks
 * Conditional transitions
+* State-driven behavior
+
+Class definition:
 
   class Vehicle
     attr_accessor :seatbelt_on
@@ -98,10 +104,39 @@ Below is an example of many of the features offered by this plugin, including
       event :repair do
         transition :to => 'parked', :from => 'stalled', :if => :auto_shop_busy?
       end
+      
+      state 'parked' do
+        def speed
+          0
+        end
+      end
+      
+      state 'idling', 'first_gear' do
+        def speed
+          10
+        end
+      end
+      
+      state 'second_gear' do
+        def speed
+          20
+        end
+      end
+    end
+    
+    state_machine :hood_state, :initial => 'closed', :namespace => 'hood' do
+      event :open do
+        transition :to => 'opened', :from => 'closed'
+      end
+      
+      event :close do
+        transition :to => 'closed', :from => 'opened'
+      end
     end
     
     def initialize
       @seatbelt_on = false
+      super() # NOTE: This *must* be called, otherwise states won't get initialized
     end
     
     def put_on_seatbelt
@@ -128,13 +163,20 @@ like so:
   vehicle.parked?                 # => true
   vehicle.can_ignite?             # => true
   vehicle.next_ignite_transition  # => #<StateMachine::Transition:0xb7c34cec ...>
+  vehicle.speed                   # => 0
+  
   vehicle.ignite                  # => true
   vehicle.parked?                 # => false
   vehicle.idling?                 # => true
+  vehicle.speed                   # => 10
   vehicle                         # => #<Vehicle:0xb7cf4eac @state="idling", @seatbelt_on=true>
+  
   vehicle.shift_up                # => true
+  vehicle.speed                   # => 10
   vehicle                         # => #<Vehicle:0xb7cf4eac @state="first_gear", @seatbelt_on=true>
+  
   vehicle.shift_up                # => true
+  vehicle.speed                   # => 20
   vehicle                         # => #<Vehicle:0xb7cf4eac @state="second_gear", @seatbelt_on=true>
   
   # The bang (!) operator can raise exceptions if the event fails
@@ -143,6 +185,18 @@ like so:
   # 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
+  
+  # Namespaced machines have uniquely-generated methods
+  vehicle.can_open_hood?          # => true
+  vehicle.open_hood               # => true
+  vehicle.can_close_hood?         # => true
+  
+  vehicle.hood_opened?            # => true
+  vehicle.hood_closed?            # => false
+
+*Note* the comment made on the +initialize+ method in the class.  In order for
+state machine attributes to be properly initialized, <tt>super()</tt> must be called.
+See StateMachine::MacroMethods for more information about this.
 
 == Integrations
 

data/Rakefile

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

data/lib/state_machine.rb

@@ -9,16 +9,17 @@ module StateMachine
     # attribute, if not specified, is "state".
     # 
     # Configuration options:
-    # * +initial+ - The initial value to set the attribute to. This can be a static value or a dynamic proc which will be evaluated at runtime.  Default is nil.
+    # * +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.
-    # * +integration+ - The name of the integration to use for adding library-specific behavior to the machine.  Built-in integrations include :data_mapper and :active_record.  By default, this is determined automatically.
+    # * +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
-    # 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 to
-    # them directly (i.e. specifying the class name).
+    # 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
+    # to them directly (i.e. specifying the class name).
     # 
     # For examples on the types of configured state machines and blocks, see
     # the section below.
@@ -95,6 +96,82 @@ module StateMachine
     #     end
     #   end
     # 
+    # == Attribute initialization
+    # 
+    # For most classes, the initial values for state machine attributes are
+    # automatically assigned when a new object is created.  However, this
+    # behavior will *not* work if the class defines an +initialize+ method
+    # without properly calling +super+.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => 'parked' do
+    #       ...
+    #     end
+    #   end
+    #   
+    #   v = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
+    #   v.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.
+    # 
+    # In the following example, a custom +initialize+ method is defined:
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => 'parked' do
+    #       ...
+    #     end
+    #     
+    #     def initialize
+    #     end
+    #   end
+    #   
+    #   v = Vehicle.new   # => #<Vehicle:0xb7c77678>
+    #   v.state           # => nil
+    # 
+    # Since the +initialize+ method is defined, the state machine attributes
+    # never get initialized.  In order to ensure that all initialization hooks
+    # are called, the custom method *must* call +super+ without any arguments
+    # like so:
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => 'parked' do
+    #       ...
+    #     end
+    #     
+    #     def initialize(attributes = {})
+    #       ...
+    #       super()
+    #     end
+    #   end
+    #   
+    #   v = Vehicle.new   # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   v.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.
+    # 
+    # 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
+    #       ...
+    #     end
+    #     
+    #     def initialize(attributes = {})
+    #       ...
+    #       initialize_state_machines
+    #     end
+    #   end
+    #   
+    #   v = Vehicle.new   # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   v.state           # => "parked"
+    # 
     # == States
     # 
     # All of the valid states for the machine are automatically tracked based
@@ -103,8 +180,8 @@ module StateMachine
     # explicitly added using the StateMachine::Machine#other_states
     # helper.
     # 
-    # For each state tracked, a predicate method for that state is generated
-    # on the class.  For example,
+    # When using String or Symbol-based states, a predicate method for that
+    # state is generated on the class.  For example,
     # 
     #   class Vehicle
     #     state_machine :initial => 'parked' do
@@ -122,6 +199,11 @@ module StateMachine
     # Each predicate method will return true if it matches the object's
     # current state.  Otherwise, it will return false.
     # 
+    # When a namespace is configured for a state machine, the name will be
+    # prepended to each state predicate like so:
+    # * <tt>car_parked?</tt>
+    # * <tt>car_idling?</tt>
+    # 
     # == Events and Transitions
     # 
     # For more information about how to configure an event and its associated
@@ -130,10 +212,65 @@ module StateMachine
     # == Defining callbacks
     # 
     # Within the +state_machine+ block, you can also define callbacks for
-    # particular states.  For more information about defining these callbacks,
+    # transitions.  For more information about defining these callbacks,
     # see StateMachine::Machine#before_transition and
     # StateMachine::Machine#after_transition.
     # 
+    # == Namespaces
+    # 
+    # When a namespace is configured for a state machine, the name provided will
+    # be used in generating the instance methods for interacting with
+    # events/states in the machine.  This is particularly useful when a class
+    # has multiple state machines and it would be difficult to differentiate
+    # between the various states / events.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine :heater_state, :initial => 'off' :namespace => 'heater' do
+    #       event :turn_on do
+    #         transition :to => 'on', :from => 'off'
+    #       end
+    #       
+    #       event :turn_off do
+    #         transition :to => 'off', :from => 'on'
+    #       end
+    #     end
+    #     
+    #     state_machine :hood_state, :initial => 'closed', :namespace => 'hood' do
+    #       event :open do
+    #         transition :to => 'opened', :from => 'closed'
+    #       end
+    #       
+    #       event :close do
+    #         transition :to => 'closed', :from => 'opened'
+    #       end
+    #     end
+    #   end
+    # 
+    # The above class defines two state machines: +heater_state+ and +hood_state+.
+    # For the +heater_state+ machine, the following methods are generated since
+    # it's namespaced by "heater":
+    # * <tt>can_turn_on_heater?</tt>
+    # * <tt>turn_on_heater</tt>
+    # * ...
+    # * <tt>can_turn_off_heater?</tt>
+    # * <tt>turn_off_heater</tt>
+    # * ..
+    # * <tt>heater_off?</tt>
+    # * <tt>heater_on?</tt>
+    # 
+    # As shown, each method is unique to the state machine so that the states
+    # and events don't conflict.  The same goes for the +hood_state+ machine:
+    # * <tt>can_open_hood?</tt>
+    # * <tt>open_hood</tt>
+    # * ...
+    # * <tt>can_close_hood?</tt>
+    # * <tt>close_hood</tt>
+    # * ..
+    # * <tt>hood_open?</tt>
+    # * <tt>hood_closed?</tt>
+    # 
     # == Scopes
     # 
     # For integrations that support it, a group of default scope filters will

data/lib/state_machine/assertions.rb

@@ -1,5 +1,5 @@
 module StateMachine
-  # Provides a set of helper methods for making assertions about content of
+  # Provides a set of helper methods for making assertions about the content of
   # various objects
   module Assertions
     # Validates that all keys in the given hash *only* includes the specified

data/lib/state_machine/callback.rb

@@ -58,8 +58,8 @@ module StateMachine
     # An optional block for determining whether to cancel the callback chain
     # based on the return value of the callback.  By default, the callback
     # chain never cancels based on the return value (i.e. there is no implicit
-    # terminator).  Certain integrations, such as ActiveRecord, change this
-    # default value.
+    # terminator).  Certain integrations, such as ActiveRecord and Sequel,
+    # change this default value.
     # 
     # == Examples
     # 
@@ -148,6 +148,7 @@ module StateMachine
       # when the callback is invoked
       def bound_method(block)
         # Generate a thread-safe unbound method that can be used on any object
+        # This is essentially a workaround for not having Ruby 1.9's instance_exec
         unbound_method = Object.class_eval do
           time = Time.now
           method_name = "__bind_#{time.to_i}_#{time.usec}"

data/lib/state_machine/event.rb

@@ -44,7 +44,7 @@ module StateMachine
     # Creates a new transition that will be evaluated when the event is fired.
     # 
     # Configuration options:
-    # * +to+ - The state that being transitioned to.  If not specified, then the transition will not change the state.
+    # * +to+ - The state that's being transitioned to.  If not specified, then the transition will not change the state.
     # * +from+ - A state or array of states that can be transitioned from. If not specified, then the transition can occur for *any* from state.
     # * +except_from+ - A state or array of states that *cannot* be transitioned from.
     # * +if+ - Specifies a method, proc or string to call to determine if the transition should occur (e.g. :if => :moving?, or :if => Proc.new {|car| car.speed > 60}). The method, proc or string should return or evaluate to a true or false value.
@@ -119,32 +119,43 @@ module StateMachine
       end
     end
     
+    # Draws a representation of this event on the given graph.  This will
+    # create 1 or more edges on the graph for each guard (i.e. transition)
+    # configured.
+    # 
+    # A collection of the generated edges will be returned.
+    def draw(graph)
+      valid_states = machine.states_order
+      guards.collect {|guard| guard.draw(graph, name, valid_states)}.flatten
+    end
+    
     protected
       # Add the various instance methods that can transition the object using
       # the current event
       def add_actions
         attribute = machine.attribute
-        name = self.name
+        qualified_name = name = self.name
+        qualified_name = "#{name}_#{machine.namespace}" if machine.namespace
         
         machine.owner_class.class_eval do
           # Checks whether the event can be fired on the current object
-          define_method("can_#{name}?") do
-            self.class.state_machines[attribute].events[name].can_fire?(self)
+          define_method("can_#{qualified_name}?") do
+            self.class.state_machines[attribute].event(name).can_fire?(self)
           end
           
           # Gets the next transition that would be performed if the event were to be fired now
-          define_method("next_#{name}_transition") do
-            self.class.state_machines[attribute].events[name].next_transition(self)
+          define_method("next_#{qualified_name}_transition") do
+            self.class.state_machines[attribute].event(name).next_transition(self)
           end
           
           # Fires the event
-          define_method(name) do |*args|
-            self.class.state_machines[attribute].events[name].fire(self, *args)
+          define_method(qualified_name) do |*args|
+            self.class.state_machines[attribute].event(name).fire(self, *args)
           end
           
           # Fires the event, raising an exception if it fails to transition
-          define_method("#{name}!") do |*args|
-            send(name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition via :#{name} from #{send(attribute).inspect}")
+          define_method("#{qualified_name}!") do |*args|
+            send(qualified_name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{attribute} via :#{name} from #{send(attribute).inspect}")
           end
         end
       end

data/lib/state_machine/extensions.rb

@@ -3,46 +3,6 @@ module StateMachine
     def self.extended(base) #:nodoc:
       base.class_eval do
         @state_machines = {}
-        
-        # method_added may get defined by the class, so instead it's chained
-        class << self
-          alias_method :method_added_without_state_machine, :method_added
-          alias_method :method_added, :method_added_with_state_machine
-        end
-      end
-    end
-    
-    # Ensures that the +initialize+ hook defined in StateMachine::InstanceMethods
-    # remains there even if the class defines its own +initialize+ method
-    # *after* the state machine has been defined.  For example,
-    # 
-    #   class Switch
-    #     state_machine do
-    #       ...
-    #     end
-    #     
-    #     def initialize(attributes = {})
-    #       ...
-    #     end
-    #   end
-    def method_added_with_state_machine(method) #:nodoc:
-      method_added_without_state_machine(method)
-      
-      # Aliasing the +initialize+ method also invokes +method_added+, so
-      # alias processing is tracked to prevent an infinite loop
-      if !@skip_initialize_hook && [:initialize, :initialize_with_state_machine].include?(method)
-        @skip_initialize_hook = true
-        
-        # Re-defining +initialize+ instead of alias chaining is done in order to
-        # prevent +initialize+ from showing up in #instance_methods
-        alias_method :initialize_without_state_machine, :initialize
-        class_eval <<-end_eval, __FILE__, __LINE__
-          def initialize(*args, &block)
-            initialize_with_state_machine(*args, &block)
-          end
-        end_eval
-        
-        @skip_initialize_hook = false
       end
     end
     
@@ -51,7 +11,7 @@ module StateMachine
     # is available to each subclass, each subclass having a copy of its
     # superclass's attribute.
     # 
-    # The hash of state machines maps +name+ => +machine+, e.g.
+    # The hash of state machines maps +attribute+ => +machine+, e.g.
     # 
     #   Vehicle.state_machines # => {"state" => #<StateMachine::Machine:0xb6f6e4a4 ...>
     def state_machines
@@ -60,25 +20,23 @@ module StateMachine
   end
   
   module InstanceMethods
-    def self.included(base) #:nodoc:
-      # Methods added from an included module don't invoke +method_added+,
-      # triggering the initialize alias, so it's done explicitly
-      base.method_added(:initialize_with_state_machine)
-    end
-    
     # Defines the initial values for state machine attributes.  The values
     # will be set *after* the original initialize method is invoked.  This is
     # necessary in order to ensure that the object is initialized before
     # dynamic initial attributes are evaluated.
-    def initialize_with_state_machine(*args, &block)
-      initialize_without_state_machine(*args, &block)
-      
-      self.class.state_machines.each do |attribute, machine|
-        # Set the initial value of the machine's attribute unless it already
-        # exists (which must mean the defaults are being skipped)
-        value = send(attribute)
-        send("#{attribute}=", machine.initial_state(self)) if value.nil? || value.respond_to?(:empty?) && value.empty?
-      end
+    def initialize(*args, &block)
+      super
+      initialize_state_machines
     end
+    
+    protected
+      def initialize_state_machines #:nodoc:
+        self.class.state_machines.each do |attribute, machine|
+          # Set the initial value of the machine's attribute unless it already
+          # exists (which must mean the defaults are being skipped)
+          value = send(attribute)
+          send("#{attribute}=", machine.initial_state(self)) if value.nil? || value.respond_to?(:empty?) && value.empty?
+        end
+      end
   end
 end