state_machines 0.0.1

data/lib/state_machines/event.rb

@@ -0,0 +1,246 @@
+require 'state_machines/transition'
+require 'state_machines/branch'
+require 'state_machines/assertions'
+require 'state_machines/matcher_helpers'
+require 'state_machines/error'
+
+module StateMachines
+  # An invalid event was specified
+  class InvalidEvent < Error
+    # The event that was attempted to be run
+    attr_reader :event
+
+    def initialize(object, event_name) #:nodoc:
+      @event = event_name
+
+      super(object, "#{event.inspect} is an unknown state machine event")
+    end
+  end
+
+  # An event defines an action that transitions an attribute from one state to
+  # another.  The state that an attribute is transitioned to depends on the
+  # branches configured for the event.
+  class Event
+
+    include MatcherHelpers
+
+    # The state machine for which this event is defined
+    attr_accessor :machine
+
+    # The name of the event
+    attr_reader :name
+
+    # The fully-qualified name of the event, scoped by the machine's namespace 
+    attr_reader :qualified_name
+
+    # The human-readable name for the event
+    attr_writer :human_name
+
+    # The list of branches that determine what state this event transitions
+    # objects to when fired
+    attr_reader :branches
+
+    # A list of all of the states known to this event using the configured
+    # branches/transitions as the source
+    attr_reader :known_states
+
+    # Creates a new event within the context of the given machine
+    # 
+    # Configuration options:
+    # * <tt>:human_name</tt> - The human-readable version of this event's name
+    def initialize(machine, name, options = {}) #:nodoc:
+      options.assert_valid_keys(:human_name)
+
+      @machine = machine
+      @name = name
+      @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
+      @human_name = options[:human_name] || @name.to_s.tr('_', ' ')
+      reset
+
+      # Output a warning if another event has a conflicting qualified name
+      if conflict = machine.owner_class.state_machines.detect { |other_name, other_machine| other_machine != @machine && other_machine.events[qualified_name, :qualified_name] }
+        name, other_machine = conflict
+        warn "Event #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
+      else
+        add_actions
+      end
+    end
+
+    # Creates a copy of this event in addition to the list of associated
+    # branches to prevent conflicts across events within a class hierarchy.
+    def initialize_copy(orig) #:nodoc:
+      super
+      @branches = @branches.dup
+      @known_states = @known_states.dup
+    end
+
+    # Transforms the event name into a more human-readable format, such as
+    # "turn on" instead of "turn_on"
+    def human_name(klass = @machine.owner_class)
+      @human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name
+    end
+
+    # Evaluates the given block within the context of this event.  This simply
+    # provides a DSL-like syntax for defining transitions.
+    def context(&block)
+      instance_eval(&block)
+    end
+
+    # Creates a new transition that determines what to change the current state
+    # to when this event fires.
+    # 
+    # Since this transition is being defined within an event context, you do
+    # *not* need to specify the <tt>:on</tt> option for the transition.  For
+    # example:
+    # 
+    #  state_machine do
+    #    event :ignite do
+    #      transition :parked => :idling, :idling => same, :if => :seatbelt_on? # Transitions to :idling if seatbelt is on
+    #      transition all => :parked, :unless => :seatbelt_on?                  # Transitions to :parked if seatbelt is off
+    #    end
+    #  end
+    # 
+    # See StateMachines::Machine#transition for a description of the possible
+    # configurations for defining transitions.
+    def transition(options)
+      raise ArgumentError, 'Must specify as least one transition requirement' if options.empty?
+
+      # Only a certain subset of explicit options are allowed for transition
+      # requirements
+      options.assert_valid_keys(:from, :to, :except_from, :except_to, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
+
+      branches << branch = Branch.new(options.merge(:on => name))
+      @known_states |= branch.known_states
+      branch
+    end
+
+    # Determines whether any transitions can be performed for this event based
+    # on the current state of the given object.
+    # 
+    # If the event can't be fired, then this will return false, otherwise true.
+    # 
+    # *Note* that this will not take the object context into account.  Although
+    # a transition may be possible based on the state machine definition,
+    # object-specific behaviors (like validations) may prevent it from firing.
+    def can_fire?(object, requirements = {})
+      !transition_for(object, requirements).nil?
+    end
+
+    # Finds and builds the next transition that can be performed on the given
+    # object.  If no transitions can be made, then this will return nil.
+    # 
+    # Valid requirement options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will be the object's current state.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   specified, then this will match any to state.
+    # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
+    #   conditionals defined for each one.  Default is true.
+    def transition_for(object, requirements = {})
+      requirements.assert_valid_keys(:from, :to, :guard)
+      requirements[:from] = machine.states.match!(object).name unless custom_from_state = requirements.include?(:from)
+
+      branches.each do |branch|
+        if match = branch.match(object, requirements)
+          # Branch allows for the transition to occur
+          from = requirements[:from]
+          to = if match[:to].is_a?(LoopbackMatcher)
+                 from
+               else
+                 values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map { |state| state.name }
+
+                 match[:to].filter(values).first
+               end
+
+          return Transition.new(object, machine, name, from, to, !custom_from_state)
+        end
+      end
+
+      # No transition matched
+      nil
+    end
+
+    # Attempts to perform the next available transition on the given object.
+    # If no transitions can be made, then this will return false, otherwise
+    # true.
+    # 
+    # Any additional arguments are passed to the StateMachines::Transition#perform
+    # instance method.
+    def fire(object, *args)
+      machine.reset(object)
+
+      if transition = transition_for(object)
+        transition.perform(*args)
+      else
+        on_failure(object)
+        false
+      end
+    end
+
+    # Marks the object as invalid and runs any failure callbacks associated with
+    # this event.  This should get called anytime this event fails to transition.
+    def on_failure(object)
+      state = machine.states.match!(object)
+      machine.invalidate(object, :state, :invalid_transition, [[:event, human_name(object.class)], [:state, state.human_name(object.class)]])
+
+      Transition.new(object, machine, name, state.name, state.name).run_callbacks(:before => false)
+    end
+
+    # Resets back to the initial state of the event, with no branches / known
+    # states associated.  This allows you to redefine an event in situations
+    # where you either are re-using an existing state machine implementation
+    # or are subclassing machines.
+    def reset
+      @branches = []
+      @known_states = []
+    end
+
+
+    def draw(graph, options = {})
+      fail NotImplementedError
+    end
+
+    # Generates a nicely formatted description of this event's contents.
+    # 
+    # For example,
+    # 
+    #   event = StateMachines::Event.new(machine, :park)
+    #   event.transition all - :idling => :parked, :idling => same
+    #   event   # => #<StateMachines::Event name=:park transitions=[all - :idling => :parked, :idling => same]>
+    def inspect
+      transitions = branches.map do |branch|
+        branch.state_requirements.map do |state_requirement|
+          "#{state_requirement[:from].description} => #{state_requirement[:to].description}"
+        end * ', '
+      end
+
+      "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
+    end
+
+    protected
+    # Add the various instance methods that can transition the object using
+    # the current event
+    def add_actions
+      # Checks whether the event can be fired on the current object
+      machine.define_helper(:instance, "can_#{qualified_name}?") do |machine, object, *args|
+        machine.event(name).can_fire?(object, *args)
+      end
+
+      # Gets the next transition that would be performed if the event were
+      # fired now
+      machine.define_helper(:instance, "#{qualified_name}_transition") do |machine, object, *args|
+        machine.event(name).transition_for(object, *args)
+      end
+
+      # Fires the event
+      machine.define_helper(:instance, qualified_name) do |machine, object, *args|
+        machine.event(name).fire(object, *args)
+      end
+
+      # Fires the event, raising an exception if it fails
+      machine.define_helper(:instance, "#{qualified_name}!") do |machine, object, *args|
+        object.send(qualified_name, *args) || raise(StateMachines::InvalidTransition.new(object, machine, name))
+      end
+    end
+  end
+end

data/lib/state_machines/event_collection.rb

@@ -0,0 +1,141 @@
+require 'state_machines/node_collection'
+
+module StateMachines
+  # Represents a collection of events in a state machine
+  class EventCollection < NodeCollection
+    def initialize(machine) #:nodoc:
+      super(machine, :index => [:name, :qualified_name])
+    end
+    
+    # Gets the list of events that can be fired on the given object.
+    # 
+    # Valid requirement options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will be the object's current state.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   specified, then this will match any to state.
+    # * <tt>:on</tt> - One or more events that fire the transition.  If none
+    #   are specified, then this will match any event.
+    # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
+    #   conditionals defined for each one.  Default is true.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #       
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #   
+    #   events = Vehicle.state_machine(:state).events
+    #   
+    #   vehicle = Vehicle.new               # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:ignite transitions=[:parked => :idling]>]
+    #   
+    #   vehicle.state = 'idling'
+    #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:park transitions=[:idling => :parked]>]
+    def valid_for(object, requirements = {})
+      match(requirements).select {|event| event.can_fire?(object, requirements)}
+    end
+    
+    # Gets the list of transitions that can be run on the given object.
+    # 
+    # Valid requirement options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will be the object's current state.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   specified, then this will match any to state.
+    # * <tt>:on</tt> - One or more events that fire the transition.  If none
+    #   are specified, then this will match any event.
+    # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
+    #   conditionals defined for each one.  Default is true.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #       
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #   
+    #   events = Vehicle.state_machine.events
+    #   
+    #   vehicle = Vehicle.new                             # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   events.transitions_for(vehicle)                   # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    #   
+    #   vehicle.state = 'idling'
+    #   events.transitions_for(vehicle)                   # => [#<StateMachines::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
+    #   
+    #   # Search for explicit transitions regardless of the current state
+    #   events.transitions_for(vehicle, :from => :parked) # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    def transitions_for(object, requirements = {})
+      match(requirements).map {|event| event.transition_for(object, requirements)}.compact
+    end
+    
+    # Gets the transition that should be performed for the event stored in the
+    # given object's event attribute.  This also takes an additional parameter
+    # for automatically invalidating the object if the event or transition are
+    # invalid.  By default, this is turned off.
+    # 
+    # *Note* that if a transition has already been generated for the event, then
+    # that transition will be used.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new                       # => #<Vehicle id: nil, state: "parked">
+    #   events = Vehicle.state_machine.events
+    #   
+    #   vehicle.state_event = nil
+    #   events.attribute_transition_for(vehicle)    # => nil # Event isn't defined
+    #   
+    #   vehicle.state_event = 'invalid'
+    #   events.attribute_transition_for(vehicle)    # => false # Event is invalid
+    #   
+    #   vehicle.state_event = 'ignite'
+    #   events.attribute_transition_for(vehicle)    # => #<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
+    def attribute_transition_for(object, invalidate = false)
+      return unless machine.action
+      
+      result = machine.read(object, :event_transition) || if event_name = machine.read(object, :event)
+        if event = self[event_name.to_sym, :name]
+          event.transition_for(object) || begin
+            # No valid transition: invalidate
+            machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
+            false
+          end
+        else
+          # Event is unknown: invalidate
+          machine.invalidate(object, :event, :invalid) if invalidate
+          false
+        end
+      end
+      
+      result
+    end
+    
+    private
+      def match(requirements) #:nodoc:
+        requirements && requirements[:on] ? [fetch(requirements.delete(:on))] : self
+      end
+  end
+end

data/lib/state_machines/extensions.rb

@@ -0,0 +1,148 @@
+
+module StateMachines
+  module ClassMethods
+    def self.extended(base) #:nodoc:
+      base.class_eval do
+        @state_machines = MachineCollection.new
+      end
+    end
+    
+    # Gets the current list of state machines defined for this class.  This
+    # class-level attribute acts like an inheritable attribute.  The attribute
+    # is available to each subclass, each having a copy of its superclass's
+    # attribute.
+    # 
+    # The hash of state machines maps <tt>:attribute</tt> => +machine+, e.g.
+    # 
+    #   Vehicle.state_machines # => {:state => #<StateMachines::Machine:0xb6f6e4a4 ...>}
+    def state_machines
+      @state_machines ||= superclass.state_machines.dup
+    end
+  end
+  
+  module InstanceMethods
+    # Runs one or more events in parallel.  All events will run through the
+    # following steps:
+    # * Before callbacks
+    # * Persist state
+    # * Invoke action
+    # * After callbacks
+    # 
+    # For example, if two events (for state machines A and B) are run in
+    # parallel, the order in which steps are run is:
+    # * A - Before transition callbacks
+    # * B - Before transition callbacks
+    # * A - Persist new state
+    # * B - Persist new state
+    # * A - Invoke action
+    # * B - Invoke action (only if different than A's action)
+    # * A - After transition callbacks
+    # * B - After transition callbacks
+    # 
+    # *Note* that multiple events on the same state machine / attribute cannot
+    # be run in parallel.  If this is attempted, an ArgumentError will be
+    # raised.
+    # 
+    # == Halting callbacks
+    # 
+    # When running multiple events in parallel, special consideration should
+    # be taken with regard to how halting within callbacks affects the flow.
+    # 
+    # For *before* callbacks, any <tt>:halt</tt> error that's thrown will
+    # immediately cancel the perform for all transitions.  As a result, it's
+    # possible for one event's transition to affect the continuation of
+    # another.
+    # 
+    # On the other hand, any <tt>:halt</tt> error that's thrown within an
+    # *after* callback with only affect that event's transition.  Other
+    # transitions will continue to run their own callbacks.
+    # 
+    # == Example
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #       
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #     end
+    #     
+    #     state_machine :alarm_state, :namespace => 'alarm', :initial => :on do
+    #       event :enable do
+    #         transition all => :active
+    #       end
+    #       
+    #       event :disable do
+    #         transition all => :off
+    #       end
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new                         # => #<Vehicle:0xb7c02850 @state="parked", @alarm_state="active">
+    #   vehicle.state                                 # => "parked"
+    #   vehicle.alarm_state                           # => "active"
+    #   
+    #   vehicle.fire_events(:ignite, :disable_alarm)  # => true
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    #   
+    #   # If any event fails, the entire event chain fails
+    #   vehicle.fire_events(:ignite, :enable_alarm)   # => false
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    #   
+    #   # Exception raised on invalid event
+    #   vehicle.fire_events(:park, :invalid)          # => StateMachines::InvalidEvent: :invalid is an unknown event
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    def fire_events(*events)
+      self.class.state_machines.fire_events(self, *events)
+    end
+    
+    # Run one or more events in parallel.  If any event fails to run, then
+    # a StateMachines::InvalidTransition exception will be raised.
+    # 
+    # See StateMachines::InstanceMethods#fire_events for more information.
+    # 
+    # == Example
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #       
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #     end
+    #     
+    #     state_machine :alarm_state, :namespace => 'alarm', :initial => :active do
+    #       event :enable do
+    #         transition all => :active
+    #       end
+    #       
+    #       event :disable do
+    #         transition all => :off
+    #       end
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new                         # => #<Vehicle:0xb7c02850 @state="parked", @alarm_state="active">
+    #   vehicle.fire_events(:ignite, :disable_alarm)  # => true
+    #   
+    #   vehicle.fire_events!(:ignite, :disable_alarm) # => StateMachines::InvalidTranstion: Cannot run events in parallel: ignite, disable_alarm
+    def fire_events!(*events)
+      run_action = [true, false].include?(events.last) ? events.pop : true
+      fire_events(*(events + [run_action])) || raise(StateMachines::InvalidParallelTransition.new(self, events))
+    end
+    
+    protected
+      def initialize_state_machines(options = {}, &block) #:nodoc:
+        self.class.state_machines.initialize_states(self, options, &block)
+      end
+  end
+end

data/lib/state_machines/helper_module.rb

@@ -0,0 +1,17 @@
+module StateMachines
+  # Represents a type of module that defines instance / class methods for a
+  # state machine
+  class HelperModule < Module #:nodoc:
+    def initialize(machine, kind)
+      @machine = machine
+      @kind = kind
+    end
+    
+    # Provides a human-readable description of the module
+    def to_s
+      owner_class = @machine.owner_class
+      owner_class_name = owner_class.name && !owner_class.name.empty? ? owner_class.name : owner_class.to_s
+      "#{owner_class_name} #{@machine.name.inspect} #{@kind} helpers"
+    end
+  end
+end

data/lib/state_machines/integrations/base.rb

@@ -0,0 +1,100 @@
+module StateMachines
+  module Integrations
+    # Provides a set of base helpers for managing individual integrations
+    module Base
+      module ClassMethods
+        # The default options to use for state machines using this integration
+        attr_reader :defaults
+        
+        # The name of the integration
+        def integration_name
+          @integration_name ||= begin
+            name = self.name.split('::').last
+            name.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+            name.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+            name.downcase!
+            name.to_sym
+          end
+        end
+        
+        # Whether this integration is available for the current library.  This
+        # is only true if the ORM that the integration is for is currently
+        # defined.
+        def available?
+          matching_ancestors.any? && Object.const_defined?(matching_ancestors[0].split('::')[0])
+        end
+        
+        # The list of ancestor names that cause this integration to matched.
+        def matching_ancestors
+          []
+        end
+        
+        # Whether the integration should be used for the given class.
+        def matches?(klass)
+          matches_ancestors?(klass.ancestors.map {|ancestor| ancestor.name})
+        end
+        
+        # Whether the integration should be used for the given list of ancestors.
+        def matches_ancestors?(ancestors)
+          (ancestors & matching_ancestors).any?
+        end
+        
+        # Tracks the various version overrides for an integration
+        def versions
+          @versions ||= []
+        end
+        
+        # Creates a new version override for an integration.  When this
+        # integration is activated, each version that is marked as active will
+        # also extend the integration.
+        # 
+        # == Example
+        # 
+        #   module StateMachines
+        #     module Integrations
+        #       module ORMLibrary
+        #         version '0.2.x - 0.3.x' do
+        #           def self.active?
+        #             ::ORMLibrary::VERSION >= '0.2.0' && ::ORMLibrary::VERSION < '0.4.0'
+        #           end
+        #           
+        #           def invalidate(object, attribute, message, values = [])
+        #             # Override here...
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        # 
+        # In the above example, a version override is defined for the ORMLibrary
+        # integration when the version is between 0.2.x and 0.3.x.
+        def version(name, &block)
+          versions << mod = Module.new(&block)
+          mod
+        end
+        
+        # The path to the locale file containing translations for this
+        # integration.  This file will only exist for integrations that actually
+        # support i18n.
+        def locale_path
+          path = "#{File.dirname(__FILE__)}/#{integration_name}/locale.rb"
+          path if File.exist?(path)
+        end
+        
+        # Extends the given object with any version overrides that are currently
+        # active
+        def extended(base)
+          versions.each do |version|
+             base.extend(version) if version.active?
+          end
+        end
+      end
+      
+      extend ClassMethods
+      
+      def self.included(base) #:nodoc:
+        base.class_eval { extend ClassMethods }
+      end
+    end
+  end
+end