state_machine 0.3.1 → 0.4.0

data/lib/state_machine.rb

@@ -1,123 +1,168 @@
 require 'state_machine/machine'
 
-module PluginAWeek #:nodoc:
-  # A state machine is a model of behavior composed of states, events, and
-  # transitions.  This helper adds support for defining this type of
-  # functionality within ActiveRecord models.
-  module StateMachine
-    module MacroMethods
-      # Creates a state machine for the given attribute.  The default attribute
-      # is "state".
-      # 
-      # Configuration options:
-      # * +initial+ - The initial value of the attribute.  This can either be the actual value or a Proc for dynamic initial states.
-      # 
-      # 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 on the model 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.
-      # 
-      # == Examples
-      # 
-      # With the default attribute and no initial state:
-      # 
-      #   class Switch < ActiveRecord::Base
-      #     state_machine do
-      #       event :park do
-      #         ...
-      #       end
-      #     end
-      #   end
-      # 
-      # The above example will define a state machine for the attribute "state"
-      # on the model.  Every switch will start with no initial state.
-      # 
-      # With a custom attribute:
-      # 
-      #   class Switch < ActiveRecord::Base
-      #     state_machine :status do
-      #       ...
-      #     end
-      #   end
-      # 
-      # With a static initial state:
-      # 
-      #   class Switch < ActiveRecord::Base
-      #     state_machine :status, :initial => 'off' do
-      #       ...
-      #     end
-      #   end
-      # 
-      # With a dynamic initial state:
-      # 
-      #   class Switch < ActiveRecord::Base
-      #     state_machine :status, :initial => lambda {|switch| (8..22).include?(Time.now.hour) ? 'on' : 'off'} do
-      #       ...
-      #     end
-      #   end
-      # 
-      # == Events and Transitions
-      # 
-      # For more information about how to configure an event and its associated
-      # transitions, see PluginAWeek::StateMachine::Machine#event
-      # 
-      # == Defining callbacks
-      # 
-      # Within the +state_machine+ block, you can also define callbacks for
-      # particular states.  For more information about defining these callbacks,
-      # see PluginAWeek::StateMachine::Machine#before_transition and
-      # PluginAWeek::StateMachine::Machine#after_transition.
-      def state_machine(*args, &block)
-        unless included_modules.include?(PluginAWeek::StateMachine::InstanceMethods)
-          write_inheritable_attribute :state_machines, {}
-          class_inheritable_reader :state_machines
-          
-          include PluginAWeek::StateMachine::InstanceMethods
-        end
-        
-        options = args.extract_options!
-        attribute = args.any? ? args.first.to_s : 'state'
-        
-        # Creates the state machine for this class.  If a superclass has already
-        # defined the machine, then a copy of it will be used with its context
-        # changed to this class.  If no machine has been defined before for the
-        # attribute, a new one will be created.
-        original = state_machines[attribute]
-        machine = state_machines[attribute] = original ? original.within_context(self, options) : PluginAWeek::StateMachine::Machine.new(self, attribute, options)
-        machine.instance_eval(&block) if block
-        
-        machine
-      end
-    end
-    
-    module InstanceMethods
-      def self.included(base) #:nodoc:
-        base.class_eval do
-          alias_method_chain :initialize, :state_machine
-        end
-      end
-      
-      # Defines the initial values for state machine attributes
-      def initialize_with_state_machine(attributes = nil)
-        initialize_without_state_machine(attributes)
-        
-        # Set the initial value of each state machine as long as the value wasn't
-        # included in the initial attributes
-        attributes = remove_attributes_protected_from_mass_assignment((attributes || {}).stringify_keys)
-        self.class.state_machines.each do |attribute, machine|
-          send("#{attribute}=", machine.initial_state(self)) unless attributes.include?(attribute)
-        end
-        
-        yield self if block_given?
-      end
+# A state machine is a model of behavior composed of states, events, and
+# transitions.  This helper adds support for defining this type of
+# functionality on any Ruby class.
+module StateMachine
+  module MacroMethods
+    # Creates a new state machine for the given attribute.  The default
+    # 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.
+    # * +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.
+    # 
+    # 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).
+    # 
+    # For examples on the types of configured state machines and blocks, see
+    # the section below.
+    # 
+    # == Examples
+    # 
+    # With the default attribute and no configuration:
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       event :park do
+    #         ...
+    #       end
+    #     end
+    #   end
+    # 
+    # The above example will define a state machine for the attribute "state"
+    # on the class.  Every vehicle will start without an initial state.
+    # 
+    # With a custom attribute:
+    # 
+    #   class Vehicle
+    #     state_machine :status do
+    #       ...
+    #     end
+    #   end
+    # 
+    # With a static initial state:
+    # 
+    #   class Vehicle
+    #     state_machine :status, :initial => 'Vehicle' 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
+    #       ...
+    #     end
+    #   end
+    # 
+    # == Attribute accessor
+    # 
+    # The attribute for each machine stores the value for the current state
+    # 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"):
+    # * <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.
+    # 
+    # For example, the following machine definition will not generate any
+    # accessor methods since the class has already defined an attribute
+    # accessor:
+    # 
+    #   class Vehicle
+    #     attr_accessor :state
+    #     
+    #     state_machine do
+    #       ...
+    #     end
+    #   end
+    # 
+    # On the other hand, the following state machine will define both a
+    # reader and writer method, which is functionally equivalent to the
+    # example above:
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       ...
+    #     end
+    #   end
+    # 
+    # == 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.
+    # 
+    # For each state tracked, a predicate method for that state is generated
+    # on the class.  For example,
+    # 
+    #   class Vehicle
+    #     state_machine :initial => 'parked' do
+    #       event :ignite do
+    #         transition :to => 'idling'
+    #       end
+    #     end
+    #   end
+    # 
+    # ...will generate the following instance methods (assuming they're not
+    # already defined in the class):
+    # * <tt>parked?</tt>
+    # * <tt>idling?</tt>
+    # 
+    # Each predicate method will return true if it matches the object's
+    # current state.  Otherwise, it will return false.
+    # 
+    # == Events and Transitions
+    # 
+    # For more information about how to configure an event and its associated
+    # transitions, see StateMachine::Machine#event.
+    # 
+    # == Defining callbacks
+    # 
+    # Within the +state_machine+ block, you can also define callbacks for
+    # particular states.  For more information about defining these callbacks,
+    # see StateMachine::Machine#before_transition and
+    # StateMachine::Machine#after_transition.
+    # 
+    # == Scopes
+    # 
+    # 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.
+    # 
+    # 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.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.
+    # 
+    # See StateMachine::Machine for more information about using
+    # integrations and the individual integration docs for information about
+    # the actual scopes that are generated.
+    def state_machine(*args, &block)
+      machine = StateMachine::Machine.find_or_create(self, *args)
+      machine.instance_eval(&block) if block
+      machine
     end
   end
 end
 
-ActiveRecord::Base.class_eval do
-  extend PluginAWeek::StateMachine::MacroMethods
+Class.class_eval do
+  include StateMachine::MacroMethods
 end

data/lib/state_machine/assertions.rb

@@ -0,0 +1,21 @@
+module StateMachine
+  # Provides a set of helper methods for making assertions about content of
+  # various objects
+  module Assertions
+    # Validates that all keys in the given hash *only* includes the specified
+    # valid keys.  If any invalid keys are found, an ArgumentError will be
+    # raised.
+    #
+    # == Examples
+    # 
+    #   options = {:name => 'John Smith', :age => 30}
+    #   
+    #   assert_valid_keys(options, :name)           # => ArgumentError: Invalid key(s): age
+    #   assert_valid_keys(options, 'name', 'age')   # => ArgumentError: Invalid key(s): age, name
+    #   assert_valid_keys(options, :name, :age)     # => nil
+    def assert_valid_keys(hash, *valid_keys)
+      invalid_keys = hash.keys - valid_keys
+      raise ArgumentError, "Invalid key(s): #{invalid_keys.join(", ")}" unless invalid_keys.empty?
+    end
+  end
+end

data/lib/state_machine/callback.rb

@@ -0,0 +1,168 @@
+require 'state_machine/guard'
+require 'state_machine/eval_helpers'
+
+module StateMachine
+  # Callbacks represent hooks into objects that allow you to trigger logic
+  # before or after a specific transition occurs.
+  class Callback
+    include EvalHelpers
+    
+    class << self
+      # Whether to automatically bind the callback to the object being
+      # transitioned.  This only applies to callbacks that are defined as
+      # lambda blocks (or Procs).  Some libraries, such as Extlib, handle
+      # callbacks by executing them bound to the object involved, while other
+      # libraries, such as ActiveSupport, pass the object as an argument to
+      # the callback.  This can be configured on an application-wide basis by
+      # setting this configuration to +true+ or +false+.  The default value
+      # is +false+.
+      # 
+      # *Note* that the DataMapper and Sequel integrations automatically
+      # configure this value on a per-callback basis, so it does not have to
+      # be enabled application-wide.
+      # 
+      # == Examples
+      # 
+      # When not bound to the object:
+      # 
+      #   class Vehicle
+      #     state_machine do
+      #       before_transition do |vehicle|
+      #         vehicle.set_alarm
+      #       end
+      #     end
+      #     
+      #     def set_alarm
+      #       ...
+      #     end
+      #   end
+      # 
+      # When bound to the object application-wide:
+      # 
+      #   StateMachine::Callback.bind_to_object = true
+      #   
+      #   class Vehicle
+      #     state_machine do
+      #       before_transition do
+      #         self.set_alarm
+      #       end
+      #     end
+      #     
+      #     def set_alarm
+      #       ...
+      #     end
+      #   end
+      attr_accessor :bind_to_object
+    end
+    
+    # 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.
+    # 
+    # == Examples
+    # 
+    # Canceling the callback chain without a terminator:
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       before_transition do |vehicle|
+    #         throw :halt
+    #       end
+    #     end
+    #   end
+    # 
+    # Canceling the callback chain with a terminator value of +false+:
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       before_transition do |vehicle|
+    #         false
+    #       end
+    #     end
+    #   end
+    attr_reader :terminator
+    
+    # The guard that determines whether or not this callback can be invoked
+    # based on the context of the transition.  The event, from state, and
+    # to state must all match in order for the guard to pass.
+    # 
+    # See StateMachine::Guard for more information.
+    attr_reader :guard
+    
+    # Creates a new callback that can get called based on the configured
+    # options.
+    # 
+    # In addition to the possible configuration options for guards, the
+    # following options can be configured:
+    # * +bind_to_object+ - Whether to bind the callback to the object involved.  If set to false, the object will be passed as a parameter instead.  Default is integration-specific or set to the application default.
+    # * +terminator+ - A block/proc that determines what callback results should cause the callback chain to halt (if not using the default <tt>throw :halt</tt> technique).
+    # 
+    # More information about how those options affect the behavior of the
+    # callback can be found in their attr_accessor definitions.
+    def initialize(options = {}, &block) #:nodoc:
+      if options.is_a?(Hash)
+        @method = options.delete(:do) || block
+      else
+        # Only the callback was configured
+        @method = options
+        options = {}
+      end
+      
+      # The actual method to invoke must be defined
+      raise ArgumentError, ':do callback must be specified' unless @method
+      
+      # Proxy the method so that it's bound to the object
+      @method = bound_method(@method) if @method.is_a?(Proc) && (!options.include?(:bind_to_object) && self.class.bind_to_object || options.delete(:bind_to_object))
+      @terminator = options.delete(:terminator)
+      
+      @guard = Guard.new(options)
+    end
+    
+    # Gets a list of the states known to this callback by looking at the
+    # guard's requirements
+    def known_states
+      guard.known_states
+    end
+    
+    # Runs the callback as long as the transition context matches the guard
+    # requirements configured for this callback.
+    def call(object, context = {}, *args)
+      # Only evaluate the method if the guard passes
+      if @guard.matches?(object, context)
+        result = evaluate_method(object, @method, *args)
+        
+        # If a terminator has been configured and it matches the result from
+        # the evaluated method, then the callback chain should be halted
+        if @terminator && @terminator.call(result)
+          throw :halt
+        else
+          result
+        end
+      end
+    end
+    
+    private
+      # Generates an method that can be bound to the object being transitioned
+      # when the callback is invoked
+      def bound_method(block)
+        # Generate a thread-safe unbound method that can be used on any object
+        unbound_method = Object.class_eval do
+          time = Time.now
+          method_name = "__bind_#{time.to_i}_#{time.usec}"
+          define_method(method_name, &block)
+          method = instance_method(method_name)
+          remove_method(method_name)
+          method
+        end
+        arity = unbound_method.arity
+        
+        # Proxy calls to the method so that the method can be bound *and*
+        # the arguments are adjusted
+        lambda do |object, *args|
+          unbound_method.bind(object).call(*(arity == 0 ? [] : args))
+        end
+      end
+  end
+end