enum_state_machine 0.0.2 → 0.1.0

data/lib/enum_state_machine/integrations/base.rb

@@ -0,0 +1,100 @@
+module EnumStateMachine
+  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 EnumStateMachine
+        #     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.exists?(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

data/lib/enum_state_machine/integrations.rb

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