state_machine 0.7.5 → 0.7.6

data/lib/state_machine/integrations/data_mapper/observer.rb

@@ -109,19 +109,19 @@ module StateMachine
           # state machines for each observed class.
           def add_transition_callback(type, *args, &block)
             if args.any? && !args.first.is_a?(Hash)
-              # Specific attribute(s) being targeted
-              attributes = args
+              # Specific machine(s) being targeted
+              names = args
               args = args.last.is_a?(Hash) ? [args.pop] : []
             else
               # Target all state machines
-              attributes = nil
+              names = nil
             end
             
             # Add the transition callback to each class being observed
             observing.each do |klass|
               state_machines =
-                if attributes
-                  attributes.map {|attribute| klass.state_machines.fetch(attribute)}
+                if names
+                  names.map {|name| klass.state_machines.fetch(name)}
                 else
                   klass.state_machines.values
                 end

data/lib/state_machine/integrations/sequel.rb

@@ -84,17 +84,14 @@ module StateMachine
     # you can build two state machines (one public and one protected) like so:
     # 
     #   class Vehicle < Sequel::Model
-    #     # Allow both machines to share the same state
-    #     alias_method :public_state, :state
-    #     alias_method :public_state=, :state=
-    #     
     #     set_restricted_columns :state_event # Prevent access to events in the first machine
     #     
     #     state_machine do
     #       # Define private events here
     #     end
     #     
-    #     state_machine :public_state do
+    #     # Allow both machines to share the same state
+    #     state_machine :public_state, :attribute => :state do
     #       # Define public events here
     #     end
     #   end
@@ -231,7 +228,7 @@ module StateMachine
       
       # Adds a validation error to the given object
       def invalidate(object, attribute, message, values = [])
-        object.errors.add(attribute, generate_message(message, values))
+        object.errors.add(self.attribute(attribute), generate_message(message, values))
       end
       
       # Resets any errors previously added when invalidating the given object
@@ -242,8 +239,9 @@ module StateMachine
       protected
         # Skips defining reader/writer methods since this is done automatically
         def define_state_accessor
+          name = self.name
           owner_class.validates_each(attribute) do |record, attr, value|
-            machine = record.class.state_machine(attr)
+            machine = record.class.state_machine(name)
             machine.invalidate(record, attr, :invalid) unless machine.states.match(record)
           end
         end

data/lib/state_machine/machine.rb

@@ -113,14 +113,14 @@ module StateMachine
   # 
   # Callbacks are supported for hooking before and after every possible
   # transition in the machine.  Each callback is invoked in the order in which
-  # it was defined.  See StateMachine::Machine#before_transition
-  # and StateMachine::Machine#after_transition for documentation
-  # on how to define new callbacks.
+  # it was defined.  See StateMachine::Machine#before_transition 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.
+  # *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,
   # 
@@ -229,7 +229,7 @@ module StateMachine
   #   
   #   [Vehicle, Switch, Project].each do |klass|
   #     klass.state_machines.each do |attribute, machine|
-  #       machine.before_transition klass.method(:before_transition)
+  #       machine.before_transition StateMachineObserver.method(:before_transition)
   #     end
   #   end
   # 
@@ -300,10 +300,10 @@ module StateMachine
       # in the new owner class (the original will remain unchanged).
       def find_or_create(owner_class, *args, &block)
         options = args.last.is_a?(Hash) ? args.pop : {}
-        attribute = args.first || :state
+        name = args.first || :state
         
         # Find an existing machine
-        if owner_class.respond_to?(:state_machines) && machine = owner_class.state_machines[attribute]
+        if owner_class.respond_to?(:state_machines) && machine = owner_class.state_machines[name]
           # 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?)
@@ -316,7 +316,7 @@ module StateMachine
           machine.instance_eval(&block) if block_given?
         else
           # No existing machine: create a new one
-          machine = new(owner_class, attribute, options, &block)
+          machine = new(owner_class, name, options, &block)
         end
         
         machine
@@ -347,7 +347,7 @@ module StateMachine
           end
           
           # Draw each of the class's state machines
-          klass.state_machines.each do |name, machine|
+          klass.state_machines.each_value do |machine|
             machine.draw(options)
           end
         end
@@ -365,8 +365,9 @@ module StateMachine
     # The class that the machine is defined in
     attr_accessor :owner_class
     
-    # The attribute for which the machine is being defined
-    attr_reader :attribute
+    # The name of the machine, used for scoping methods generated for the
+    # machine as a whole (not states or events)
+    attr_reader :name
     
     # The events that trigger transitions.  These are sorted, by default, in
     # the order in which they were defined.
@@ -402,7 +403,7 @@ module StateMachine
     # 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, :messages, :use_transactions)
+      assert_valid_keys(options, :attribute, :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)
@@ -414,7 +415,8 @@ module StateMachine
       options = {:use_transactions => true}.merge(options)
       
       # Set machine configuration
-      @attribute = args.first || :state
+      @name = args.first || :state
+      @attribute = options[:attribute] || @name
       @events = EventCollection.new(self)
       @states = StateCollection.new(self)
       @callbacks = {:before => [], :after => []}
@@ -467,10 +469,9 @@ module StateMachine
         include instance_helper_module
       end
       
-      # Record this machine as matched to the attribute in the current owner
-      # class.  This will override any machines mapped to the same attribute
-      # in any superclasses.
-      owner_class.state_machines[attribute] = self
+      # Record this machine as matched to the name in the current owner class.
+      # This will override any machines mapped to the same name in any superclasses.
+      owner_class.state_machines[name] = self
     end
     
     # Sets the initial state of the machine.  This can be either the static name
@@ -484,22 +485,27 @@ module StateMachine
       states.each {|state| state.initial = (state.name == @initial_state)}
     end
     
+    # Gets the actual name of the attribute on the machine's owner class that
+    # stores data with the given name.
+    def attribute(name = :state)
+      name == :state ? @attribute : :"#{self.name}_#{name}"
+    end
+    
     # Defines a new instance method with the given name on the machine's owner
     # class.  If the method is already defined in the class, then this will not
     # override it.
     # 
     # Example:
     # 
-    #   attribute = machine.attribute
     #   machine.define_instance_method(:state_name) do |machine, object|
     #     machine.states.match(object)
     #   end
     def define_instance_method(method, &block)
-      attribute = self.attribute
+      name = self.name
       
       @instance_helper_module.class_eval do
         define_method(method) do |*args|
-          block.call(self.class.state_machine(attribute), self, *args)
+          block.call(self.class.state_machine(name), self, *args)
         end
       end
     end
@@ -515,11 +521,11 @@ module StateMachine
     #     machine.states.keys
     #   end
     def define_class_method(method, &block)
-      attribute = self.attribute
+      name = self.name
       
       @class_helper_module.class_eval do
         define_method(method) do |*args|
-          block.call(self.state_machine(attribute), self, *args)
+          block.call(self.state_machine(name), self, *args)
         end
       end
     end
@@ -616,7 +622,7 @@ module StateMachine
     #   end
     #   
     #   class Vehicle < ActiveRecord::Base
-    #     state_machine :state_id, :initial => :parked do
+    #     state_machine :attribute => :state_id, :initial => :parked do
     #       event :ignite do
     #         transition :parked => :idling
     #       end
@@ -824,7 +830,7 @@ module StateMachine
     end
     alias_method :other_states, :state
     
-    # Gets the current value stored in the given object's state.
+    # Gets the current value stored in the given object's attribute.
     # 
     # For example,
     # 
@@ -834,13 +840,15 @@ module StateMachine
     #     end
     #   end
     #   
-    #   vehicle = Vehicle.new                 # => #<Vehicle:0xb7d94ab0 @state="parked">
-    #   Vehicle.state_machine.read(vehicle)   # => "parked"
-    def read(object)
-      object.send(attribute)
+    #   vehicle = Vehicle.new                           # => #<Vehicle:0xb7d94ab0 @state="parked">
+    #   Vehicle.state_machine.read(vehicle, :state)     # => "parked" # Equivalent to vehicle.state
+    #   Vehicle.state_machine.read(vehicle, :event)     # => nil      # Equivalent to vehicle.state_event
+    def read(object, attribute, ivar = false)
+      attribute = self.attribute(attribute)
+      ivar ? object.instance_variable_get("@#{attribute}") : object.send(attribute)
     end
     
-    # Sets a new value in the given object's state.
+    # Sets a new value in the given object's attribute.
     # 
     # For example,
     # 
@@ -850,11 +858,13 @@ module StateMachine
     #     end
     #   end
     #   
-    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7d94ab0 @state="parked">
-    #   Vehicle.state_machine.write(vehicle, 'idling')
-    #   vehicle.state           # => "idling"
-    def write(object, value)
-      object.send("#{attribute}=", value)
+    #   vehicle = Vehicle.new                                   # => #<Vehicle:0xb7d94ab0 @state="parked">
+    #   Vehicle.state_machine.write(vehicle, :state, 'idling')  # => Equivalent to vehicle.state = 'idling'
+    #   Vehicle.state_machine.write(vehicle, :event, 'park')    # => Equivalent to vehicle.state_event = 'park'
+    #   vehicle.state                                           # => "idling"
+    #   vehicle.event                                           # => "park"
+    def write(object, attribute, value)
+      object.send("#{self.attribute(attribute)}=", value)
     end
     
     # Defines one or more events for the machine and the transitions that can
@@ -1112,12 +1122,12 @@ module StateMachine
     # 
     #   class Vehicle
     #     # Only specifies one parameter (the object being transitioned)
-    #     before_transition :to => :parked do |vehicle|
+    #     before_transition all => :parked do |vehicle|
     #       vehicle.set_alarm
     #     end
     #     
     #     # Specifies 2 parameters (object being transitioned and actual transition)
-    #     before_transition :to => :parked do |vehicle, transition|
+    #     before_transition all => :parked do |vehicle, transition|
     #       vehicle.set_alarm(transition)
     #     end
     #   end
@@ -1143,7 +1153,7 @@ module StateMachine
     #       before_transition [:first_gear, :idling] => :parked, :on => :park, :do => :take_off_seatbelt
     #       
     #       # With conditional callback:
-    #       before_transition :to => :parked, :do => :take_off_seatbelt, :if => :seatbelt_on?
+    #       before_transition all => :parked, :do => :take_off_seatbelt, :if => :seatbelt_on?
     #       
     #       # Using helpers:
     #       before_transition all - :stalled => same, :on => any - :crash, :do => :update_dashboard
@@ -1205,7 +1215,7 @@ module StateMachine
     # 
     # Configuration options:
     # * <tt>:name</tt> - The name of the file to write to (without the file extension).
-    #   Default is "#{owner_class.name}_#{attribute}"
+    #   Default is "#{owner_class.name}_#{name}"
     # * <tt>:path</tt> - The path to write the graph file to.  Default is the
     #   current directory (".").
     # * <tt>:format</tt> - The image format to generate the graph in.
@@ -1217,7 +1227,7 @@ module StateMachine
     # * <tt>:output</tt> - Whether to generate the output of the graph
     def draw(options = {})
       options = {
-        :name => "#{owner_class.name}_#{attribute}",
+        :name => "#{owner_class.name}_#{name}",
         :path => '.',
         :format => 'png',
         :font => 'Arial',
@@ -1272,7 +1282,7 @@ module StateMachine
         define_action_helpers if action
         
         # Gets the state name for the current value
-        define_instance_method("#{attribute}_name") do |machine, object|
+        define_instance_method(attribute(:name)) do |machine, object|
           machine.states.match!(object).name
         end
       end
@@ -1289,7 +1299,7 @@ module StateMachine
       # Adds predicate method to the owner class for determining the name of the
       # current state
       def define_state_predicate
-        define_instance_method("#{attribute}?") do |machine, object, state|
+        define_instance_method("#{name}?") do |machine, object, state|
           machine.states.matches?(object, state)
         end
       end
@@ -1298,31 +1308,31 @@ module StateMachine
       # 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|
+        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|
+        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
+          event_attribute = attribute(:event)
+          event_transition_attribute = attribute(:event_transition)
           @instance_helper_module.class_eval do
-            attr_writer "#{attribute}_event"
+            attr_writer event_attribute
             
             protected
-              attr_accessor "#{attribute}_event_transition"
+              attr_accessor event_transition_attribute
           end
           
           # Interpret non-blank events as present
-          define_instance_method("#{attribute}_event") do |machine, object|
-            event = object.instance_variable_get("@#{attribute}_event")
+          define_instance_method(attribute(:event)) do |machine, object|
+            event = machine.read(object, :event, true)
             event && !(event.respond_to?(:empty?) && event.empty?) ? event.to_sym : nil
           end
         end
@@ -1334,7 +1344,7 @@ module StateMachine
         action = self.action
         private_method = owner_class.private_method_defined?(action_hook)
         
-        if (owner_class.method_defined?(action_hook) || private_method) && !owner_class.state_machines.any? {|attribute, machine| machine.action == action && machine != self}
+        if (owner_class.method_defined?(action_hook) || private_method) && !owner_class.state_machines.any? {|name, 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
@@ -1358,9 +1368,9 @@ 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)
-        plural = custom_plural || (attribute.to_s.respond_to?(:pluralize) ? attribute.to_s.pluralize : "#{attribute}s")
+        plural = custom_plural || (name.to_s.respond_to?(:pluralize) ? name.to_s.pluralize : "#{name}s")
         
-        [attribute, plural].uniq.each do |name|
+        [name, plural].uniq.each do |name|
           [:with, :without].each do |kind|
             method = "#{kind}_#{name}"
             

data/lib/state_machine/machine_collection.rb

@@ -5,9 +5,9 @@ module StateMachine
     # values are only set if the machine's attribute doesn't already exist
     # (which must mean the defaults are being skipped)
     def initialize_states(object)
-      each do |attribute, machine|
-        value = machine.read(object)
-        machine.write(object, machine.initial_state(object).value) if value.nil? || value.respond_to?(:empty?) && value.empty?
+      each_value do |machine|
+        value = machine.read(object, :state)
+        machine.write(object, :state, machine.initial_state(object).value) if value.nil? || value.respond_to?(:empty?) && value.empty?
       end
     end
     
@@ -17,19 +17,19 @@ module StateMachine
       run_action = [true, false].include?(events.last) ? events.pop : true
       
       # Generate the transitions to run for each event
-      transitions = events.collect do |name|
+      transitions = events.collect do |event_name|
         # Find the actual event being run
         event = nil
-        detect do |attribute, machine|
-          event = machine.events[name, :qualified_name]
+        detect do |name, machine|
+          event = machine.events[event_name, :qualified_name]
         end
         
-        raise InvalidEvent, "#{name.inspect} is an unknown state machine event" unless event
+        raise InvalidEvent, "#{event_name.inspect} is an unknown state machine event" unless event
         
         # Get the transition that will be performed for the event
         unless transition = event.transition_for(object)
           machine = event.machine
-          machine.invalidate(object, machine.attribute, :invalid_transition, [[:event, name]])
+          machine.invalidate(object, :state, :invalid_transition, [[:event, event_name]])
         end
         
         transition
@@ -107,7 +107,7 @@ module StateMachine
     #   vehicle.state_event_transition                # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
     def fire_event_attributes(object, action, complete = true)
       # Get the transitions to fire for each applicable machine
-      transitions = map {|attribute, machine| machine.action == action ? machine.events.attribute_transition_for(object, true) : nil}.compact
+      transitions = map {|name, machine| machine.action == action ? machine.events.attribute_transition_for(object, true) : nil}.compact
       return yield if transitions.empty?
       
       # The value generated by the yielded block (the actual action)
@@ -118,27 +118,25 @@ module StateMachine
         begin
           result = Transition.perform(transitions, :after => complete) do
             # Prevent events from being evaluated multiple times if actions are nested
-            transitions.each {|transition| object.send("#{transition.attribute}_event=", nil)}
+            transitions.each {|transition| transition.machine.write(object, :event, nil)}
             action_value = yield
           end
         rescue Exception
-          # Revert attribute modifications
+          # Revert object modifications
           transitions.each do |transition|
-            object.send("#{transition.attribute}_event=", transition.event)
-            object.send("#{transition.attribute}_event_transition=", nil) if complete
+            transition.machine.write(object, :event, transition.event)
+            transition.machine.write(object, :event_transition, nil) if complete
           end
           
           raise
         end
         
         transitions.each do |transition|
-          attribute = transition.attribute
-          
           # Revert event unless transition was successful
-          object.send("#{attribute}_event=", transition.event) unless complete && result
+          transition.machine.write(object, :event, transition.event) unless complete && result
           
           # Track transition if partial transition completed successfully
-          object.send("#{attribute}_event_transition=", !complete && result ? transition : nil)
+          transition.machine.write(object, :event_transition, !complete && result ? transition : nil)
         end
       end