enum_state_machine 0.0.1

data/lib/enum_state_machine/event_collection.rb

@@ -0,0 +1,141 @@
+require 'enum_state_machine/node_collection'
+
+module EnumStateMachine
+  # 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)           # => [#<EnumStateMachine::Event name=:ignite transitions=[:parked => :idling]>]
+    #   
+    #   vehicle.state = 'idling'
+    #   events.valid_for(vehicle)           # => [#<EnumStateMachine::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)                   # => [#<EnumStateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    #   
+    #   vehicle.state = 'idling'
+    #   events.transitions_for(vehicle)                   # => [#<EnumStateMachine::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) # => [#<EnumStateMachine::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)    # => #<EnumStateMachine::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/enum_state_machine/extensions.rb

@@ -0,0 +1,149 @@
+require 'enum_state_machine/machine_collection'
+
+module EnumStateMachine
+  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 => #<EnumStateMachine::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)          # => EnumStateMachine::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 EnumStateMachine::InvalidTransition exception will be raised.
+    # 
+    # See EnumStateMachine::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) # => EnumStateMachine::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(EnumStateMachine::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/enum_state_machine/graph.rb

@@ -0,0 +1,92 @@
+begin
+  require 'rubygems'
+  gem 'ruby-graphviz', '>=0.9.17'
+  require 'graphviz'
+rescue LoadError => ex
+  $stderr.puts "Cannot draw the machine (#{ex.message}). `gem install ruby-graphviz` >= v0.9.17 and try again."
+  raise
+end
+
+require 'enum_state_machine/assertions'
+
+module EnumStateMachine
+  # Provides a set of higher-order features on top of the raw GraphViz graphs
+  class Graph < GraphViz
+    include Assertions
+    
+    # The name of the font to draw state names in
+    attr_reader :font
+    
+    # The graph's full filename
+    attr_reader :file_path
+    
+    # The image format to generate the graph in
+    attr_reader :file_format
+    
+    # Creates a new graph with the given name.
+    # 
+    # Configuration options:
+    # * <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.
+    #   Default is "png'.
+    # * <tt>:font</tt> - The name of the font to draw state names in.
+    #   Default is "Arial".
+    # * <tt>:orientation</tt> - The direction of the graph ("portrait" or
+    #   "landscape").  Default is "portrait".
+    def initialize(name, options = {})
+      options = {:path => '.', :format => 'png', :font => 'Arial', :orientation => 'portrait'}.merge(options)
+      assert_valid_keys(options, :path, :format, :font, :orientation)
+      
+      @font = options[:font]
+      @file_path = File.join(options[:path], "#{name}.#{options[:format]}")
+      @file_format = options[:format]
+      
+      super('G', :rankdir => options[:orientation] == 'landscape' ? 'LR' : 'TB')
+    end
+    
+    # Generates the actual image file based on the nodes / edges added to the
+    # graph.  The path to the file is based on the configuration options for
+    # this graph.
+    def output
+      super(@file_format => @file_path)
+    end
+    
+    # Adds a new node to the graph.  The font for the node will be automatically
+    # set based on the graph configuration.  The generated node will be returned.
+    # 
+    # For example,
+    # 
+    #   graph = EnumStateMachine::Graph.new('test')
+    #   graph.add_nodes('parked', :label => 'Parked', :width => '1', :height => '1', :shape => 'ellipse')
+    def add_nodes(*args)
+      node = v0_api? ? add_node(*args) : super
+      node.fontname = @font
+      node
+    end
+    
+    # Adds a new edge to the graph.  The font for the edge will be automatically
+    # set based on the graph configuration.  The generated edge will be returned.
+    # 
+    # For example,
+    # 
+    #   graph = EnumStateMachine::Graph.new('test')
+    #   graph.add_edges('parked', 'idling', :label => 'ignite')
+    def add_edges(*args)
+      edge = v0_api? ? add_edge(*args) : super
+      edge.fontname = @font
+      edge
+    end
+    
+    private
+    # Determines whether the old v0 api is in use
+    def v0_api?
+      version[0] == '0' || version[0] == '1' && version[1] == '0' && version[2] <= '2'
+    end
+    
+    # The ruby-graphviz version data
+    def version
+      Constants::RGV_VERSION.split('.')
+    end
+  end
+end

data/lib/enum_state_machine/helper_module.rb

@@ -0,0 +1,17 @@
+module EnumStateMachine
+  # 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/enum_state_machine/initializers/rails.rb

@@ -0,0 +1,22 @@
+if defined?(Rails)
+  # Track all of the applicable locales to load
+  locale_paths = []
+  EnumStateMachine::Integrations.all.each do |integration|
+    locale_paths << integration.locale_path if integration.available? && integration.locale_path
+  end
+  
+  if defined?(Rails::Engine)
+    # Rails 3.x
+    class EnumStateMachine::RailsEngine < Rails::Engine
+      rake_tasks do
+        load 'tasks/enum_state_machine.rb'
+      end
+    end
+    
+    if Rails::VERSION::MAJOR == 3 && Rails::VERSION::MINOR == 0
+      EnumStateMachine::RailsEngine.paths.config.locales = locale_paths
+    else
+      EnumStateMachine::RailsEngine.paths['config/locales'] = locale_paths
+    end
+  end
+end

data/lib/enum_state_machine/initializers.rb

@@ -0,0 +1,4 @@
+# Load each application initializer
+Dir["#{File.dirname(__FILE__)}/initializers/*.rb"].sort.each do |path|
+  require "enum_state_machine/initializers/#{File.basename(path)}"
+end

data/lib/enum_state_machine/integrations/active_model/locale.rb

@@ -0,0 +1,11 @@
+{:en => {
+  :activemodel => {
+    :errors => {
+      :messages => {
+        :invalid => EnumStateMachine::Machine.default_messages[:invalid],
+        :invalid_event => EnumStateMachine::Machine.default_messages[:invalid_event] % ['%{state}'],
+        :invalid_transition => EnumStateMachine::Machine.default_messages[:invalid_transition] % ['%{event}']
+      }
+    }
+  }
+}}

data/lib/enum_state_machine/integrations/active_model/observer.rb

@@ -0,0 +1,33 @@
+module EnumStateMachine
+  module Integrations #:nodoc:
+    module ActiveModel
+      # Adds support for invoking callbacks on ActiveModel observers with more
+      # than one argument (e.g. the record *and* the state transition).  By
+      # default, ActiveModel only supports passing the record into the
+      # callbacks.
+      # 
+      # For example:
+      # 
+      #   class VehicleObserver < ActiveModel::Observer
+      #     # The default behavior: only pass in the record
+      #     def after_save(vehicle)
+      #     end
+      #     
+      #     # Custom behavior: allow the transition to be passed in as well
+      #     def after_transition(vehicle, transition)
+      #       Audit.log(vehicle, transition)
+      #     end
+      #   end
+      module Observer
+        def update_with_transition(observer_update)
+          method = observer_update.method
+          send(method, *observer_update.args) if respond_to?(method)
+        end
+      end
+    end
+  end
+end
+
+ActiveModel::Observer.class_eval do
+  include EnumStateMachine::Integrations::ActiveModel::Observer
+end if defined?(ActiveModel::Observer)

data/lib/enum_state_machine/integrations/active_model/observer_update.rb

@@ -0,0 +1,42 @@
+module EnumStateMachine
+  module Integrations #:nodoc:
+    module ActiveModel
+      # Represents the encapsulation of all of the details to be included in an
+      # update to state machine observers.  This allows multiple arguments to
+      # get passed to an observer method (instead of just a single +object+)
+      # while still respecting the way in which ActiveModel checks for the
+      # object's list of observers.
+      class ObserverUpdate
+        # The method to invoke on the observer
+        attr_reader :method
+        
+        # The object being transitioned
+        attr_reader :object
+        
+        # The transition being run
+        attr_reader :transition
+        
+        def initialize(method, object, transition) #:nodoc:
+          @method, @object, @transition = method, object, transition
+        end
+        
+        # The arguments to pass into the method
+        def args
+          [object, transition]
+        end
+        
+        # The class of the object being transitioned.  Normally the object
+        # getting passed into observer methods is the actual instance of the
+        # ActiveModel class.  ActiveModel uses that instance's class to check
+        # for enabled / disabled observers.
+        # 
+        # Since state_machine is passing an ObserverUpdate instance into observer
+        # methods, +class+ needs to be overridden so that ActiveModel can still
+        # get access to the enabled / disabled observers.
+        def class
+          object.class
+        end
+      end
+    end
+  end
+end

data/lib/enum_state_machine/integrations/active_model/versions.rb

@@ -0,0 +1,31 @@
+module EnumStateMachine
+  module Integrations #:nodoc:
+    module ActiveModel
+      version '2.x' do
+        def self.active?
+          !defined?(::ActiveModel::VERSION) || ::ActiveModel::VERSION::MAJOR == 2
+        end
+        
+        def define_validation_hook
+          define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
+            def valid?(*)
+              self.class.state_machines.transitions(self, #{action.inspect}, :after => false).perform { super }
+            end
+          end_eval
+        end
+      end
+      
+      version '3.0.x' do
+        def self.active?
+          defined?(::ActiveModel::VERSION) && ::ActiveModel::VERSION::MAJOR == 3 && ::ActiveModel::VERSION::MINOR == 0
+        end
+        
+        def define_validation_hook
+          # +around+ callbacks don't have direct access to results until AS 3.1
+          owner_class.set_callback(:validation, :after, 'value', :prepend => true)
+          super
+        end
+      end
+    end
+  end
+end