state_machine 0.6.3 → 0.7.0

data/lib/state_machine/integrations/sequel.rb

@@ -28,10 +28,41 @@ module StateMachine
     # 
     # For example,
     # 
-    #   vehicle = Vehicle.create          # => #<Vehicle id=1 name=nil state="parked">
+    #   vehicle = Vehicle.create          # => #<Vehicle @values={:state=>"parked", :name=>nil, :id=>1}>
     #   vehicle.name = 'Ford Explorer'
     #   vehicle.ignite                    # => true
-    #   vehicle.refresh                   # => #<Vehicle id=1 name="Ford Explorer" state="idling">
+    #   vehicle.refresh                   # => #<Vehicle @values={:state=>"idling", :name=>"Ford Explorer", :id=>1}>
+    # 
+    # == Events
+    # 
+    # As described in StateMachine::InstanceMethods#state_machine, event
+    # attributes are created for every machine that allow transitions to be
+    # performed automatically when the object's action (in this case, :save)
+    # is called.
+    # 
+    # In Sequel, these automated events are run in the following order:
+    # * before validation - Run before callbacks and persist new states, then validate
+    # * before save - If validation was skipped, run before callbacks and persist new states, then save
+    # * after save - Run after callbacks
+    # 
+    # For example,
+    # 
+    #   vehicle = Vehicle.create          # => #<Vehicle @values={:state=>"parked", :name=>nil, :id=>1}>
+    #   vehicle.state_event               # => nil
+    #   vehicle.state_event = 'invalid'
+    #   vehicle.valid?                    # => false
+    #   vehicle.errors.full_messages      # => ["state_event is invalid"]
+    #   
+    #   vehicle.state_event = 'ignite'
+    #   vehicle.valid?                    # => true
+    #   vehicle.save                      # => #<Vehicle @values={:state=>"idling", :name=>nil, :id=>1}>
+    #   vehicle.state                     # => "idling"
+    #   vehicle.state_event               # => nil
+    # 
+    # Note that this can also be done on a mass-assignment basis:
+    # 
+    #   vehicle = Vehicle.create(:state_event => 'ignite')  # => #<Vehicle @values={:state=>"idling", :name=>nil, :id=>1}>
+    #   vehicle.state                                       # => "idling"
     # 
     # == Transactions
     # 
@@ -51,7 +82,7 @@ module StateMachine
     #     end
     #   end
     #   
-    #   vehicle = Vehicle.create      # => #<Vehicle id=1 name=nil state="parked">
+    #   vehicle = Vehicle.create      # => #<Vehicle @values={:state=>"parked", :name=>nil, :id=>1}>
     #   vehicle.ignite                # => false
     #   Message.count                 # => 0
     # 
@@ -60,6 +91,14 @@ module StateMachine
     # rolled back.  If an after callback halts the chain, the previous result
     # still applies and the transaction is *not* rolled back.
     # 
+    # To turn off transactions:
+    # 
+    #   class Vehicle < Sequel::Model
+    #     state_machine :initial => :parked, :use_transactions => false do
+    #       ...
+    #     end
+    #   end
+    # 
     # == Validation errors
     # 
     # If an event fails to successfully fire because there are no matching
@@ -69,9 +108,9 @@ module StateMachine
     # 
     # For example,
     # 
-    #   vehicle = Vehicle.create(:state => 'idling')  # => #<Vehicle id=1 name=nil state="idling">
+    #   vehicle = Vehicle.create(:state => 'idling')  # => #<Vehicle @values={:state=>"parked", :name=>nil, :id=>1}>
     #   vehicle.ignite                                # => false
-    #   vehicle.errors.full_messages                  # => ["state cannot be transitioned via :ignite from :idling"]
+    #   vehicle.errors.full_messages                  # => ["state cannot transition via \"ignite\""]
     # 
     # If an event fails to fire because of a validation error on the record and
     # *not* because a matching transition was not available, no error messages
@@ -139,6 +178,10 @@ module StateMachine
     # Note, also, that the transition can be accessed by simply defining
     # additional arguments in the callback block.
     module Sequel
+      # The default options to use for state machines using this integration
+      class << self; attr_reader :defaults; end
+      @defaults = {:action => :save}
+      
       # Should this integration be used for state machines in the given class?
       # Classes that include Sequel::Model will automatically use the Sequel
       # integration.
@@ -146,31 +189,30 @@ module StateMachine
         defined?(::Sequel::Model) && klass <= ::Sequel::Model
       end
       
-      # Adds a validation error to the given object after failing to fire a
-      # specific event
-      def invalidate(object, event)
-        object.errors.add(attribute, invalid_message(object, event))
+      # Adds a validation error to the given object
+      def invalidate(object, attribute, message, values = [])
+        object.errors.add(attribute, generate_message(message, values))
       end
       
-      # Resets an errors previously added when invalidating the given object
+      # Resets any errors previously added when invalidating the given object
       def reset(object)
         object.errors.clear
       end
       
-      # Runs a new database transaction, rolling back any changes if the
-      # yielded block fails (i.e. returns false).
-      def within_transaction(object)
-        object.db.transaction {raise ::Sequel::Error::Rollback unless yield}
-      end
-      
       protected
-        # Sets the default action for all Sequel state machines to +save+
-        def default_action
-          :save
+        # Skips defining reader/writer methods since this is done automatically
+        def define_state_accessor
         end
         
-        # Skips defining reader/writer methods since this is done automatically
-        def define_attribute_accessor
+        # Adds hooks into validation for automatically firing events
+        def define_action_helpers
+          if super && action == :save
+            @instance_helper_module.class_eval do
+              define_method(:valid?) do |*args|
+                self.class.state_machines.fire_attribute_events(self, :save, false) { super(*args) }
+              end
+            end
+          end
         end
         
         # Creates a scope for finding records *with* a particular state or
@@ -187,6 +229,12 @@ module StateMachine
           lambda {|model, values| model.filter(~{attribute.to_sym => values})}
         end
         
+        # Runs a new database transaction, rolling back any changes if the
+        # yielded block fails (i.e. returns false).
+        def transaction(object)
+          object.db.transaction {raise ::Sequel::Error::Rollback unless yield}
+        end
+        
         # Creates a new callback in the callback chain, always ensuring that
         # it's configured to bind to the object as this is the convention for
         # Sequel callbacks

data/lib/state_machine/machine.rb

@@ -7,16 +7,67 @@ require 'state_machine/event'
 require 'state_machine/callback'
 require 'state_machine/node_collection'
 require 'state_machine/state_collection'
+require 'state_machine/event_collection'
 require 'state_machine/matcher_helpers'
 
 module StateMachine
   # Represents a state machine for a particular attribute.  State machines
-  # consist of states, events and a set of transitions that define how the state
-  # changes after a particular event is fired.
+  # consist of states, events and a set of transitions that define how the
+  # state changes after a particular event is fired.
   # 
-  # A state machine will not know all of the possible states for an object unless
-  # they are referenced *somewhere* in the state machine definition.  As a result,
-  # any unused states should be defined with the +other_states+ or +state+ helper.
+  # A state machine will not know all of the possible states for an object
+  # unless they are referenced *somewhere* in the state machine definition.
+  # As a result, any unused states should be defined with the +other_states+
+  # or +state+ helper.
+  # 
+  # == Actions
+  # 
+  # When an action is configured for a state machine, it is invoked when an
+  # object transitions via an event.  The success of the event becomes
+  # dependent on the success of the action.  If the action is successful, then
+  # the transitioned state remains persisted.  However, if the action fails
+  # (by returning false), the transitioned state will be rolled back.
+  # 
+  # For example,
+  # 
+  #   class Vehicle
+  #     attr_accessor :fail, :saving_state
+  #     
+  #     state_machine :initial => :parked, :action => :save do
+  #       event :ignite do
+  #         transition :parked => :idling
+  #       end
+  #       
+  #       event :park do
+  #         transition :idling => :parked
+  #       end
+  #     end
+  #     
+  #     def save
+  #       @saving_state = state
+  #       fail != true
+  #     end
+  #   end
+  #   
+  #   vehicle = Vehicle.new     # => #<Vehicle:0xb7c27024 @state="parked">
+  #   vehicle.save              # => true
+  #   vehicle.saving_state      # => "parked" # The state was "parked" was save was called
+  #   
+  #   # Successful event
+  #   vehicle.ignite            # => true
+  #   vehicle.saving_state      # => "idling" # The state was "idling" when save was called
+  #   vehicle.state             # => "idling"
+  #   
+  #   # Failed event
+  #   vehicle.fail = true
+  #   vehicle.park              # => false
+  #   vehicle.saving_state      # => "parked"
+  #   vehicle.state             # => "idling"
+  # 
+  # As shown, even though the state is set prior to calling the +save+ action
+  # on the object, it will be rolled back to the original state if the action
+  # fails.  *Note* that this will also be the case if an exception is raised
+  # while calling the action.
   # 
   # == Callbacks
   # 
@@ -26,6 +77,32 @@ module StateMachine
   # and StateMachine::Machine#after_transition for documentation
   # on how to define new callbacks.
   # 
+  # *Note* that callbacks only get executed within the context of an event.
+  # As a result, if a class has an initial state when it's created, any
+  # callbacks that would normally get executed when the object enters that
+  # state will *not* get triggered.
+  # 
+  # For example,
+  # 
+  #   class Vehicle
+  #     state_machine :initial => :parked do
+  #       after_transition all => :parked do
+  #         raise ArgumentError
+  #       end
+  #       ...
+  #     end
+  #   end
+  #   
+  #   vehicle = Vehicle.new   # => #<Vehicle id: 1, state: "parked">
+  #   vehicle.save            # => true (no exception raised)
+  # 
+  # If you need callbacks to get triggered when an object is created, this
+  # should be done by either:
+  # * Use a <tt>before :save</tt> or equivalent hook, or
+  # * Set an initial state of nil and use the correct event to create the
+  #   object with the proper state, resulting in callbacks being triggered and
+  #   the object getting persisted
+  # 
   # === Canceling callbacks
   # 
   # Callbacks can be canceled by throwing :halt at any point during the
@@ -87,7 +164,7 @@ module StateMachine
   #       logger.info "#{vehicle} instructed to #{transition.event}... #{transition.attribute} is: #{transition.from}, #{transition.attribute} will be: #{transition.to}"
   #     end
   #     
-  #     def self.after_transition(vehicle, transition, result)
+  #     def self.after_transition(vehicle, transition)
   #       logger.info "#{vehicle} instructed to #{transition.event}... #{transition.attribute} was: #{transition.from}, #{transition.attribute} is: #{transition.to}"
   #     end
   #   end
@@ -111,13 +188,13 @@ module StateMachine
   #   end
   #   
   #   [Vehicle, Switch, Project].each do |klass|
-  #     klass.state_machines.each do |machine|
+  #     klass.state_machines.each do |attribute, machine|
   #       machine.before_transition klass.method(:before_transition)
   #     end
   #   end
   # 
   # Additional observer-like behavior may be exposed by the various integrations
-  # available.  See below for more information.
+  # available.  See below for more information on integrations.
   # 
   # == Overriding instance / class methods
   # 
@@ -129,25 +206,20 @@ module StateMachine
   #   class Vehicle
   #     state_machine do
   #       event :park do
-  #         transition :idling => :parked
+  #         ...
   #       end
   #     end
   #     
-  #     def park(kind = :parallel, *args)
-  #       take_deep_breath if kind == :parallel
-  #       super(*args)
-  #     end
-  #     
-  #     def take_deep_breath
-  #       sleep 3
+  #     def park(*args)
+  #       logger.info "..."
+  #       super
   #     end
   #   end
   # 
   # In the above example, the +park+ instance method that's generated on the
-  # Vehicle class (by the associated event) is overriden with custom behavior
-  # that takes an additional argument.  Once this behavior is complete, the
-  # original method from the state machine is invoked by simply calling
-  # <tt>super(*args)</tt>.
+  # Vehicle class (by the associated event) is overridden with custom behavior.
+  # Once this behavior is complete, the original method from the state machine
+  # is invoked by simply calling +super+.
   # 
   # The same technique can be used for +state+, +state_name+, and all other
   # instance *and* class methods on the Vehicle class.
@@ -175,10 +247,6 @@ module StateMachine
     include MatcherHelpers
     
     class << self
-      # The default message to use when invalidating objects that fail to
-      # transition when triggering an event
-      attr_accessor :default_invalid_message
-      
       # Attempts to find or create a state machine for the given class.  For
       # example,
       # 
@@ -194,16 +262,17 @@ module StateMachine
         options = args.last.is_a?(Hash) ? args.pop : {}
         attribute = args.first || :state
         
-        # Attempts to find an existing machine
+        # Find an existing machine
         if owner_class.respond_to?(:state_machines) && machine = owner_class.state_machines[attribute]
-          # Create a copy of the state machine if it's being created by a subclass
-          unless machine.owner_class == owner_class
+          # Only create a new copy if changes are being made to the machine in
+          # a subclass
+          if machine.owner_class != owner_class && (options.any? || block_given?)
             machine = machine.clone
             machine.initial_state = options[:initial] if options.include?(:initial)
             machine.owner_class = owner_class
           end
           
-          # Evaluate DSL caller block
+          # Evaluate DSL
           machine.instance_eval(&block) if block_given?
         else
           # No existing machine: create a new one
@@ -245,8 +314,13 @@ module StateMachine
       end
     end
     
-    # Set defaults
-    self.default_invalid_message = 'cannot be transitioned via :%s from :%s'
+    # Default messages to use for validation errors in ORM integrations
+    class << self; attr_accessor :default_messages; end
+    @default_messages = {
+      :invalid => 'is invalid',
+      :invalid_event => 'cannot transition when %s',
+      :invalid_transition => 'cannot transition via "%s"'
+    }
     
     # The class that the machine is defined in
     attr_accessor :owner_class
@@ -254,8 +328,8 @@ module StateMachine
     # The attribute for which the machine is being defined
     attr_reader :attribute
     
-    # The events that trigger transitions.  These are sorted, by default, in the
-    # order in which they were defined.
+    # The events that trigger transitions.  These are sorted, by default, in
+    # the order in which they were defined.
     attr_reader :events
     
     # A list of all of the states known to this state machine.  This will pull
@@ -282,36 +356,41 @@ module StateMachine
     # depending on the context.
     attr_reader :namespace
     
+    # Whether the machine will use transactions when firing events
+    attr_reader :use_transactions
+    
     # Creates a new state machine for the given attribute
     def initialize(owner_class, *args, &block)
       options = args.last.is_a?(Hash) ? args.pop : {}
-      assert_valid_keys(options, :initial, :action, :plural, :namespace, :integration, :invalid_message)
+      assert_valid_keys(options, :initial, :action, :plural, :namespace, :integration, :messages, :use_transactions)
+      
+      # Find an integration that matches this machine's owner class
+      if integration = options[:integration] ? StateMachine::Integrations.find(options[:integration]) : StateMachine::Integrations.match(owner_class)
+        extend integration
+        options = integration.defaults.merge(options) if integration.respond_to?(:defaults)
+      end
+      
+      # Add machine-wide defaults
+      options = {:use_transactions => true}.merge(options)
       
       # Set machine configuration
       @attribute = args.first || :state
-      @events = NodeCollection.new
-      @states = StateCollection.new
+      @events = EventCollection.new(self)
+      @states = StateCollection.new(self)
       @callbacks = {:before => [], :after => []}
       @namespace = options[:namespace]
-      @invalid_message = options[:invalid_message]
-      
+      @messages = options[:messages] || {}
+      @action = options[:action]
+      @use_transactions = options[:use_transactions]
       self.owner_class = owner_class
       self.initial_state = options[:initial]
       
-      # Find an integration that matches this machine's owner class
-      if integration = options[:integration] ? StateMachine::Integrations.find(options[:integration]) : StateMachine::Integrations.match(owner_class)
-        extend integration
-      end
-      
-      # Set integration-specific configurations
-      @action = options.include?(:action) ? options[:action] : default_action
-      define_attribute_helpers
+      # Define class integration
+      define_helpers
       define_scopes(options[:plural])
-      
-      # Call after hook for integration-specific extensions
       after_initialize
       
-      # Evaluate DSL caller block
+      # Evaluate DSL
       instance_eval(&block) if block_given?
     end
     
@@ -369,22 +448,18 @@ module StateMachine
     # class.  If the method is already defined in the class, then this will not
     # override it.
     # 
-    # Not that in order for inheritance to work properly within state machines,
-    # any states/events/etc. must be referred to from the current state machine
-    # associated with the executing class.
-    # 
     # Example:
     # 
     #   attribute = machine.attribute
-    #   machine.define_instance_method(:parked?) do |machine, object|
-    #     machine.state?(object, :parked)
+    #   machine.define_instance_method(:state_name) do |machine, object|
+    #     machine.states.match(object)
     #   end
     def define_instance_method(method, &block)
       attribute = self.attribute
       
       @instance_helper_module.class_eval do
         define_method(method) do |*args|
-          block.call(self.class.state_machines[attribute], self, *args)
+          block.call(self.class.state_machine(attribute), self, *args)
         end
       end
     end
@@ -394,10 +469,6 @@ module StateMachine
     # class.  If the method is already defined in the class, then this will not
     # override it.
     # 
-    # Not that in order for inheritance to work properly within state machines,
-    # any states/events/etc. must be referred to from the current state machine
-    # associated with the executing class.
-    # 
     # Example:
     # 
     #   machine.define_class_method(:states) do |machine, klass|
@@ -408,7 +479,7 @@ module StateMachine
       
       @class_helper_module.class_eval do
         define_method(method) do |*args|
-          block.call(self.state_machines[attribute], self, *args)
+          block.call(self.state_machine(attribute), self, *args)
         end
       end
     end
@@ -428,7 +499,7 @@ module StateMachine
     #   end
     #   
     #   vehicle = Vehicle.new
-    #   Vehicle.state_machines[:state].initial_state(vehicle)   # => #<StateMachine::State name=:parked value="parked" initial=true>
+    #   Vehicle.state_machine.initial_state(vehicle)  # => #<StateMachine::State name=:parked value="parked" initial=true>
     # 
     # With a dynamic initial state:
     # 
@@ -443,10 +514,10 @@ module StateMachine
     #   vehicle = Vehicle.new
     #   
     #   vehicle.force_idle = true
-    #   Vehicle.state_machines[:state].initial_state(vehicle)   # => #<StateMachine::State name=:idling value="idling" initial=false>
+    #   Vehicle.state_machine.initial_state(vehicle)  # => #<StateMachine::State name=:idling value="idling" initial=false>
     #   
     #   vehicle.force_idle = false
-    #   Vehicle.state_machines[:state].initial_state(vehicle)   # => #<StateMachine::State name=:parked value="parked" initial=false>
+    #   Vehicle.state_machine.initial_state(vehicle)  # => #<StateMachine::State name=:parked value="parked" initial=false>
     def initial_state(object)
       states.fetch(@initial_state.is_a?(Proc) ? @initial_state.call(object) : @initial_state)
     end
@@ -623,7 +694,6 @@ module StateMachine
     #   vehicle.rotate_driver     # => true
     #   vehicle.driver            # => "John"
     #   vehicle.passenger         # => "Jane"
-    #   vehicle.state             # => "parked"
     # 
     # As can be seen, both the +speed+ and +rotate_driver+ instance method
     # implementations changed how they behave based on what the current state
@@ -692,58 +762,37 @@ module StateMachine
     end
     alias_method :other_states, :state
     
-    # 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 ArgumentError
-    # will be raised.
+    # Gets the current value stored in the given object's state.
     # 
-    # == Examples
+    # For example,
     # 
     #   class Vehicle
     #     state_machine :initial => :parked do
-    #       other_states :idling
+    #       ...
     #     end
     #   end
     #   
-    #   machine = Vehicle.state_machines[:state]
-    #   vehicle = Vehicle.new               # => #<Vehicle:0xb7c464b0 @state="parked">
-    #   
-    #   machine.state?(vehicle, :parked)    # => true
-    #   machine.state?(vehicle, :idling)    # => false
-    #   machine.state?(vehicle, :invalid)   # => ArgumentError: :invalid is an invalid key for :name index
-    def state?(object, name)
-      states.fetch(name).matches?(object.send(attribute))
+    #   vehicle = Vehicle.new                 # => #<Vehicle:0xb7d94ab0 @state="parked">
+    #   Vehicle.state_machine.read(vehicle)   # => "parked"
+    def read(object)
+      object.send(attribute)
     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.  If no state is found, then
-    # an ArgumentError will be raised.
+    # Sets a new value in the given object's state.
     # 
-    # == Examples
+    # For example,
     # 
     #   class Vehicle
     #     state_machine :initial => :parked do
-    #       other_states :idling
+    #       ...
     #     end
     #   end
     #   
-    #   machine = Vehicle.state_machines[:state]
-    #   
-    #   vehicle = Vehicle.new         # => #<Vehicle:0xb7c464b0 @state="parked">
-    #   machine.state_for(vehicle)    # => #<StateMachine::State name=:parked value="parked" initial=true>
-    #   
-    #   vehicle.state = 'idling'
-    #   machine.state_for(vehicle)    # => #<StateMachine::State name=:idling value="idling" initial=true>
-    #   
-    #   vehicle.state = 'invalid'
-    #   machine.state_for(vehicle)    # => ArgumentError: "invalid" is not a known state value
-    def state_for(object)
-      value = object.send(attribute)
-      state = states[value, :value] || states.detect {|state| state.matches?(value)}
-      raise ArgumentError, "#{value.inspect} is not a known #{attribute} value" unless state
-      
-      state
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7d94ab0 @state="parked">
+    #   Vehicle.state_machine.write(vehicle, 'idling')
+    #   vehicle.state           # => "idling"
+    def write(object, value)
+      object.send("#{attribute}=", value)
     end
     
     # Defines one or more events for the machine and the transitions that can
@@ -758,7 +807,7 @@ module StateMachine
     # (the "park" event is used as an example):
     # * <tt>can_park?</tt> - Checks whether the "park" event can be fired given
     #   the current state of the object.
-    # * <tt>next_park_transition</tt> -  Gets the next transition that would be
+    # * <tt>park_transition</tt> -  Gets the next transition that would be
     #   performed if the "park" event were to be fired now on the object or nil
     #   if no transitions can be performed.
     # * <tt>park(run_action = true)</tt> - Fires the "park" event, transitioning
@@ -769,7 +818,7 @@ module StateMachine
     # 
     # With a namespace of "car", the above names map to the following methods:
     # * <tt>can_park_car?</tt>
-    # * <tt>next_park_car_transition</tt>
+    # * <tt>park_car_transition</tt>
     # * <tt>park_car</tt>
     # * <tt>park_car!</tt>
     # 
@@ -805,6 +854,36 @@ module StateMachine
     #     end
     #   end 
     # 
+    # == Defining additional arguments
+    # 
+    # Additional arguments on event actions can be defined like so:
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       event :park do
+    #         ...
+    #       end
+    #     end
+    #     
+    #     def park(kind = :parallel, *args)
+    #       take_deep_breath if kind == :parallel
+    #       super
+    #     end
+    #     
+    #     def take_deep_breath
+    #       sleep 3
+    #     end
+    #   end
+    # 
+    # Note that +super+ is called instead of <tt>super(*args)</tt>.  This
+    # allows the entire arguments list to be accessed by transition callbacks
+    # through StateMachine::Transition#args like so:
+    # 
+    #   after_transition :on => :park do |vehicle, transition|
+    #     kind = *transition.args
+    #     ...
+    #   end
+    # 
     # == Example
     # 
     #   class Vehicle
@@ -1002,11 +1081,10 @@ module StateMachine
       add_callback(:after, options.is_a?(Hash) ? options : {:do => options}, &block)
     end
     
-    # Marks the given object as invalid after failing to transition via the
-    # given event.
+    # Marks the given object as invalid with the given message.
     # 
     # By default, this is a no-op.
-    def invalidate(object, event)
+    def invalidate(object, attribute, message, values = [])
     end
     
     # Resets an errors previously added when invalidating the given object
@@ -1021,7 +1099,11 @@ module StateMachine
     # default, this will not run any transactions, since the changes aren't
     # taking place within the context of a database.
     def within_transaction(object)
-      yield
+      if use_transactions
+        transaction(object) { yield }
+      else
+        yield
+      end
     end
     
     # Draws a directed graph of the machine for visualizing the various events,
@@ -1090,44 +1172,89 @@ module StateMachine
       def after_initialize
       end
       
-      # Gets the default action that should be invoked when performing a
-      # transition on the attribute for this machine.  This may change
-      # depending on the configured integration for the owner class.
-      def default_action
-      end
-      
-      # Adds helper methods for interacting with this state machine's attribute,
-      # including reader, writer, and predicate methods
-      def define_attribute_helpers
-        define_attribute_accessor
-        define_attribute_predicate
-        
-        attribute = self.attribute
+      # Adds helper methods for interacting with the state machine, including
+      # for states, events, and transitions
+      def define_helpers
+        define_state_accessor
+        define_state_predicate
+        define_event_helpers
+        define_action_helpers if action
         
         # Gets the state name for the current value
         define_instance_method("#{attribute}_name") do |machine, object|
-          machine.state_for(object).name
+          machine.states.match(object).name
         end
       end
       
-      # Adds reader/writer methods for accessing the attribute
-      def define_attribute_accessor
+      # Adds reader/writer methods for accessing the state attribute
+      def define_state_accessor
         attribute = self.attribute
         
         @instance_helper_module.class_eval do
-          attr_reader attribute
-          attr_writer attribute
+          attr_accessor attribute
         end
       end
       
       # Adds predicate method to the owner class for determining the name of the
       # current state
-      def define_attribute_predicate
-        attribute = self.attribute
-        
-        # Checks whether the current state is a given value
+      def define_state_predicate
         define_instance_method("#{attribute}?") do |machine, object, state|
-          machine.state?(object, state)
+          machine.states.matches?(object, state)
+        end
+      end
+      
+      # Adds helper methods for getting information about this state machine's
+      # events
+      def define_event_helpers
+        # Gets the events that are allowed to fire on the current object
+        define_instance_method("#{attribute}_events") do |machine, object|
+          machine.events.valid_for(object).map {|event| event.name}
+        end
+        
+        # Gets the next possible transitions that can be run on the current
+        # object
+        define_instance_method("#{attribute}_transitions") do |machine, object, *args|
+          machine.events.transitions_for(object, *args)
+        end
+        
+        # Add helpers for interacting with the action
+        if action
+          attribute = self.attribute
+          
+          # Tracks the event / transition to invoke when the action is called
+          @instance_helper_module.class_eval do
+            attr_writer "#{attribute}_event"
+            attr_accessor "#{attribute}_event_transition"
+          end
+          
+          # Interpret non-blank events as present
+          define_instance_method("#{attribute}_event") do |machine, object|
+            event = object.instance_variable_get("@#{attribute}_event")
+            event && !(event.respond_to?(:empty?) && event.empty?) ? event.to_sym : nil
+          end
+        end
+      end
+      
+      # Adds helper methods for automatically firing events when an action
+      # is invoked
+      def define_action_helpers
+        action = self.action
+        
+        if owner_class.method_defined?(action) && !owner_class.state_machines.any? {|attribute, machine| machine.action == action && machine != self}
+          # Action is defined and hasn't already been overridden by another machine
+          @instance_helper_module.class_eval do
+            # Override the default action to invoke the before / after hooks
+            define_method(action) do |*args|
+              value = nil
+              result = self.class.state_machines.fire_attribute_events(self, action) { value = super(*args) }
+              value.nil? ? result : value
+            end
+          end
+          
+          true
+        else
+          # Action already defined: don't add integration-specific hooks
+          false
         end
       end
       
@@ -1137,7 +1264,6 @@ module StateMachine
       # automatically determined by either calling +pluralize+ on the attribute
       # name or adding an "s" to the end of the name.
       def define_scopes(custom_plural = nil)
-        attribute = self.attribute
         plural = custom_plural || (attribute.to_s.respond_to?(:pluralize) ? attribute.to_s.pluralize : "#{attribute}s")
         
         [attribute, plural].uniq.each do |name|
@@ -1148,10 +1274,7 @@ module StateMachine
               # Converts state names to their corresponding values so that they
               # can be looked up properly
               define_class_method(method) do |machine, klass, *states|
-                machine_states = machine.states
-                values = states.flatten.map {|state| machine_states.fetch(state).value}
-                
-                # Invoke the original scope implementation
+                values = states.flatten.map {|state| machine.states.fetch(state).value}
                 scope.call(klass, values)
               end
             end
@@ -1162,17 +1285,22 @@ module StateMachine
       # Creates a scope for finding objects *with* a particular value or values
       # for the attribute.
       # 
-      # This is only applicable to specific integrations.
+      # By default, this is a no-op.
       def create_with_scope(name)
       end
       
       # Creates a scope for finding objects *without* a particular value or
       # values for the attribute.
       # 
-      # This is only applicable to specific integrations.
+      # By default, this is a no-op.
       def create_without_scope(name)
       end
       
+      # Always yields
+      def transaction(object)
+        yield
+      end
+      
       # Adds a new transition callback of the given type.
       def add_callback(type, options, &block)
         callbacks[type] << callback = Callback.new(options, &block)
@@ -1183,7 +1311,7 @@ module StateMachine
       # Tracks the given set of states in the list of all known states for
       # this machine
       def add_states(new_states)
-        new_states.collect do |new_state|
+        new_states.map do |new_state|
           unless state = states[new_state]
             states << state = State.new(self, new_state)
           end
@@ -1194,8 +1322,8 @@ module StateMachine
       
       # Generates the message to use when invalidating the given object after
       # failing to transition on a specific event
-      def invalid_message(object, event)
-        (@invalid_message || self.class.default_invalid_message) % [event.name, state_for(object).name]
+      def generate_message(name, values)
+        (@messages[name] || self.class.default_messages[name]) % values.map {|value| value.last}
       end
   end
 end