enum_state_machine 0.0.1 → 0.0.2

data/lib/enum_state_machine/event_collection.rb

@@ -1,141 +0,0 @@
-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

@@ -1,149 +0,0 @@
-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

@@ -1,92 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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.rb

@@ -1,4 +0,0 @@
-# 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/initializers/rails.rb

@@ -1,22 +0,0 @@
-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/integrations.rb

@@ -1,97 +0,0 @@
-# Load each available integration
-require 'enum_state_machine/integrations/base'
-Dir["#{File.dirname(__FILE__)}/integrations/*.rb"].sort.each do |path|
-  require "enum_state_machine/integrations/#{File.basename(path)}"
-end
-
-require 'enum_state_machine/error'
-
-module EnumStateMachine
-  # An invalid integration was specified
-  class IntegrationNotFound < Error
-    def initialize(name)
-      super(nil, "#{name.inspect} is an invalid integration")
-    end
-  end
-  
-  # Integrations allow state machines to take advantage of features within the
-  # context of a particular library.  This is currently most useful with
-  # database libraries.  For example, the various database integrations allow
-  # state machines to hook into features like:
-  # * Saving
-  # * Transactions
-  # * Observers
-  # * Scopes
-  # * Callbacks
-  # * Validation errors
-  # 
-  # This type of integration allows the user to work with state machines in a
-  # fashion similar to other object models in their application.
-  # 
-  # The integration interface is loosely defined by various unimplemented
-  # methods in the EnumStateMachine::Machine class.  See that class or the various
-  # built-in integrations for more information about how to define additional
-  # integrations.
-  module Integrations
-    # Attempts to find an integration that matches the given class.  This will
-    # look through all of the built-in integrations under the EnumStateMachine::Integrations
-    # namespace and find one that successfully matches the class.
-    # 
-    # == Examples
-    # 
-    #   class Vehicle
-    #   end
-    #   
-    #   class ActiveModelVehicle
-    #     include ActiveModel::Observing
-    #     include ActiveModel::Validations
-    #   end
-    #   
-    #   class ActiveRecordVehicle < ActiveRecord::Base
-    #   end
-    #
-    #
-    #   EnumStateMachine::Integrations.match(Vehicle)             # => nil
-    #   EnumStateMachine::Integrations.match(ActiveModelVehicle)  # => EnumStateMachine::Integrations::ActiveModel
-    #   EnumStateMachine::Integrations.match(ActiveRecordVehicle) # => EnumStateMachine::Integrations::ActiveRecord
-    def self.match(klass)
-      all.detect {|integration| integration.matches?(klass)}
-    end
-    
-    # Attempts to find an integration that matches the given list of ancestors.
-    # This will look through all of the built-in integrations under the EnumStateMachine::Integrations
-    # namespace and find one that successfully matches one of the ancestors.
-    # 
-    # == Examples
-    # 
-    #   EnumStateMachine::Integrations.match([])                    # => nil
-    #   EnumStateMachine::Integrations.match(['ActiveRecord::Base') # => EnumStateMachine::Integrations::ActiveModel
-    def self.match_ancestors(ancestors)
-      all.detect {|integration| integration.matches_ancestors?(ancestors)}
-    end
-    
-    # Finds an integration with the given name.  If the integration cannot be
-    # found, then a NameError exception will be raised.
-    # 
-    # == Examples
-    # 
-    #   EnumStateMachine::Integrations.find_by_name(:active_record) # => EnumStateMachine::Integrations::ActiveRecord
-    #   EnumStateMachine::Integrations.find_by_name(:active_model)  # => EnumStateMachine::Integrations::ActiveModel
-    #   EnumStateMachine::Integrations.find_by_name(:invalid)       # => EnumStateMachine::IntegrationNotFound: :invalid is an invalid integration
-    def self.find_by_name(name)
-      all.detect {|integration| integration.integration_name == name} || raise(IntegrationNotFound.new(name))
-    end
-    
-    # Gets a list of all of the available integrations for use.  This will
-    # always list the ActiveModel integration last.
-    # 
-    # == Example
-    # 
-    #   EnumStateMachine::Integrations.all
-    #   # => [EnumStateMachine::Integrations::ActiveRecord, EnumStateMachine::Integrations::ActiveModel]
-    def self.all
-      constants = self.constants.map {|c| c.to_s}.select {|c| c != 'ActiveModel'}.sort << 'ActiveModel'
-      constants.map {|c| const_get(c)}
-    end
-  end
-end