power_enum 0.8.6 → 0.9.1

data/lib/active_record/virtual_enumerations.rb

@@ -1,68 +1,152 @@
 # Copyright (c) 2005 Trevor Squires
+# Copyright (c) 2012 Arthur Shagall
 # Released under the MIT License.  See the LICENSE file for more details.
 
-module ActiveRecord
+module ActiveRecord # :nodoc:
+
+  # Implements a mechanism to synthesize enum classes for simple enums.  This is for situations where you wish to avoid
+  # cluttering the models directory with your enums.
+  #
+  # Create a custom Rails initializer: Rails.root/config/initializers/virtual_enumerations.rb
+  #
+  #     ActiveRecord::VirtualEnumerations.define do |config|
+  #       config.define 'ClassName',
+  #                     :table_name        => 'table',
+  #                     :extends           => 'SuperclassName',
+  #                     :conditions        => ['something = ?', "value"],
+  #                     :order             => 'column ASC',
+  #                     :on_lookup_failure => :enforce_strict,
+  #                     :name_column       => 'name_column',
+  #                     :alias_name        => false {
+  #         # class_evaled_functions
+  #       }
+  #     end
+  #
+  # Only the 'ClassName' argument is required.  :table_name is used to define a custom table name while the :extends
+  # option is used to set a custom superclass.  Class names can be either camel-cased like ClassName or with
+  # underscores, like class_name.  Strings and symbols are both fine.
+  #
+  # If you need to fine-tune the definition of the enum class, you can optionally pass in a block, which will be
+  # evaluated in the context of the enum class.
+  #
+  # Example:
+  #
+  #     config.define :color, :on_lookup_failure => :enforce_strict, do
+  #       def to_argb(alpha)
+  #         case self.to_sym
+  #         when :white
+  #           [alpha, 255, 255, 255]
+  #         when :red
+  #           [alpha, 255, 0, 0]
+  #         when :blue
+  #           [alpha, 0, 0, 255]
+  #         when :yellow
+  #           [alpha, 255, 255, 0]
+  #         when :black
+  #           [alpha, 0, 0, 0]
+  #         end
+  #       end
+  #     end
+  #
+  # As a convenience, if multiple enums share the same configuration, you can pass all of them to config.define.
+  #
+  # Example:
+  #
+  #     config.define :booking_status, :connector_type, :color, :order => :name
+  #
+  # STI is also supported:
+  #
+  # Example:
+  #
+  #     config.define :base_enum, :name_column => ;foo
+  #     config.define :booking_status, :connector_type, :color, :extends => :base_enum
   module VirtualEnumerations # :nodoc:
-    class << self       
-      def define
-        raise ArgumentError, "#{self.name}: must pass a block to define()" unless block_given?
-        config = ActiveRecord::VirtualEnumerations::Config.new
-        yield config
-        @config = config # we only overwrite config if no exceptions were thrown
+
+    # Defines enumeration classes.  Passes a config object to the given block
+    # which is used to define the virtual enumerations.  Call config.define for
+    # each enum or enums with a given set of options.
+    def self.define
+      raise ArgumentError, "#{self.name}: must pass a block to define()" unless block_given?
+      config = ActiveRecord::VirtualEnumerations::Config.new
+      yield config
+      @config = config # we only overwrite config if no exceptions were thrown
+    end
+
+    # Creates a constant for a virtual enum if a config is defined for it.
+    def self.synthesize_if_defined(const)
+      if @config && options = @config[const]
+        class_declaration = "class #{const} < #{options[:extends]}; end"
+
+        eval( class_declaration, TOPLEVEL_BINDING, __FILE__, __LINE__ )
+
+        virtual_enum_class = const_get( const )
+
+        inject_class_options( virtual_enum_class, options )
+
+        virtual_enum_class
+      else
+        nil
       end
-      
-      def synthesize_if_defined(const)
-        options = @config[const]
-        return nil unless options
-        class_def = <<-end_eval
-          class #{const} < #{options[:extends]}
-            acts_as_enumerated  :conditions => #{options[:conditions].inspect},
-                                :order => #{options[:order].inspect},
-                                :on_lookup_failure => #{options[:on_lookup_failure].inspect}
-            set_table_name(#{options[:table_name].inspect}) unless #{options[:table_name].nil?}
-          end          
-        end_eval
-        eval(class_def, TOPLEVEL_BINDING)
-        rval = const_get(const)
-        if options[:post_synth_block]
-          rval.class_eval(&options[:post_synth_block])
+    end
+
+    def self.inject_class_options( virtual_enum_class, options ) # :nodoc:
+      # Declare it acts_as_enumerated
+      virtual_enum_class.class_eval do
+        acts_as_enumerated :conditions        => options[:conditions],
+                           :order             => options[:order],
+                           :on_lookup_failure => options[:on_lookup_failure],
+                           :name_column       => options[:name_column],
+                           :alias_name        => options[:table_name]
+      end
+
+      # If necessary, set the table name
+      unless (table_name = options[:table_name]).blank?
+        virtual_enum_class.class_eval do
+          self.table_name = table_name
         end
-        return rval
-      end      
+      end
+
+      if block = options[:customizations_block]
+        virtual_enum_class.class_eval(&block)
+      end
     end
-    
+    private_class_method :inject_class_options
+
+    # Config class for VirtualEnumerations
     class Config
-      def initialize
+      def initialize # :nodoc:
         @enumeration_defs = {}
       end
-      
-      def define(arg, options = {}, &synth_block)
-        (arg.is_a?(Array) ? arg : [arg]).each do |class_name|
-          camel_name = class_name.to_s.camelize 
-          raise ArgumentError, "ActiveRecord::VirtualEnumerations.define - invalid class_name argument (#{class_name.inspect})" if camel_name.blank?
-          raise ArgumentError, "ActiveRecord::VirtualEnumerations.define - class_name already defined (#{camel_name})" if @enumeration_defs[camel_name.to_sym]
-          options.assert_valid_keys(:table_name, :extends, :conditions, :order, :on_lookup_failure)
+
+      # Creates definition(s) for one or more enums.
+      def define(*args, &block)
+        options = args.extract_options!
+        args.compact!
+        args.flatten!
+        args.each do |class_name|
+          camel_name = class_name.to_s.camelize
+          if camel_name.blank?
+            raise ArgumentError, "ActiveRecord::VirtualEnumerations.define - invalid class_name argument (#{class_name.inspect})"
+          end
+          if @enumeration_defs[camel_name.to_sym]
+            raise ArgumentError, "ActiveRecord::VirtualEnumerations.define - class_name already defined (#{camel_name})"
+          end
+          options.assert_valid_keys(:table_name, :extends, :conditions, :order, :on_lookup_failure, :name_column, :alias_name)
           enum_def = options.clone
-          enum_def[:extends] ||= "ActiveRecord::Base"
-          enum_def[:post_synth_block] = synth_block
+          enum_def[:extends] = if superclass = enum_def[:extends]
+                                 superclass.to_s.camelize
+                               else
+                                 "ActiveRecord::Base"
+                               end
+          enum_def[:customizations_block] = block
           @enumeration_defs[camel_name.to_sym] = enum_def   
         end
       end
-      
+
+      # Proxies lookups to @enumeration_defs
       def [](arg)
         @enumeration_defs[arg]
       end            
     end #class Config
   end #module VirtualEnumerations
 end #module ActiveRecord
-
-class Module # :nodoc:
-  alias_method :enumerations_original_const_missing, :const_missing
-  def const_missing(const_id)
-    # let rails have a go at loading it
-    enumerations_original_const_missing(const_id)
-  rescue NameError
-    # now it's our turn
-    ActiveRecord::VirtualEnumerations.synthesize_if_defined(const_id) or raise
-  end
-end

data/lib/power_enum/enumerated.rb

@@ -0,0 +1,405 @@
+# Copyright (c) 2005 Trevor Squires
+# Copyright (c) 2012 Arthur Shagall
+# Released under the MIT License.  See the LICENSE file for more details.
+
+module PowerEnum::Enumerated
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+
+    # Returns false for ActiveRecord models that do not act as enumerated.
+    def acts_as_enumerated?
+      false
+    end
+
+    # Declares the model as enumerated.  See the README for detailed usage instructions.
+    #
+    # === Supported options
+    # [:conditions]
+    #   SQL search conditions
+    # [:order]
+    #   SQL load order clause
+    # [:on_lookup_failure]
+    #   Specifies the name of a class method to invoke when the +[]+ method is unable to locate a BookingStatus
+    #   record for arg. The default is the built-in :enforce_none which returns nil. There are also built-ins for
+    #   :enforce_strict (raise and exception regardless of the type for arg), :enforce_strict_literals (raises an
+    #   exception if the arg is a Fixnum or Symbol), :enforce_strict_ids (raises and exception if the arg is a
+    #   Fixnum) and :enforce_strict_symbols (raises an exception if the arg is a Symbol).  The purpose of the
+    #   :on_lookup_failure option is that a) under some circumstances a lookup failure is a Bad Thing and action
+    #   should be taken, therefore b) a fallback action should be easily configurable.  You can also give it a
+    #   lambda that takes in a single argument (The arg that was passed to +[]+).
+    # [:name_column]
+    #   Override for the 'name' column.  By default, assumed to be 'name'.
+    # [:alias_name]
+    #   By default, if a name column is not 'name', will create an alias of 'name' to the name_column attribute.  Set
+    #   this to +false+ if you don't want this behavior.
+    #
+    # === Examples
+    #
+    # ====Example 1
+    #  class BookingStatus < ActiveRecord::Base
+    #    acts_as_enumerated
+    #  end
+    #
+    # ====Example 2
+    #  class BookingStatus < ActiveRecord::Base
+    #    acts_as_enumerated :on_lookup_failure => :enforce_strict
+    #  end
+    #
+    # ====Example 3
+    #  class BookingStatus < ActiveRecord::Base
+    #    acts_as_enumerated :conditions        => [:exclude => false],
+    #                       :order             => 'created_at DESC',
+    #                       :on_lookup_failure => :lookup_failed,
+    #                       :name_column       => :status_code
+    #
+    #    def self.lookup_failed(arg)
+    #      logger.error("Invalid status code lookup #{arg.inspect}")
+    #      nil
+    #    end
+    #  end
+    #
+    # ====Example 4
+    #  class BookingStatus < ActiveRecord::Base
+    #    acts_as_enumerated :conditions        => [:exclude => false],
+    #                       :order             => 'created_at DESC',
+    #                       :on_lookup_failure => lambda { |arg| raise CustomError, "BookingStatus lookup failed; #{arg}" },
+    #                       :name_column       => :status_code
+    #  end
+    def acts_as_enumerated(options = {})
+      valid_keys = [:conditions, :order, :on_lookup_failure, :name_column, :alias_name]
+      options.assert_valid_keys(*valid_keys)
+
+      valid_keys.each do |key|
+        class_attribute "acts_enumerated_#{key.to_s}"
+        if options.has_key?( key )
+          self.send "acts_enumerated_#{key.to_s}=", options[key]
+        end
+      end
+
+      name_column = if options.has_key?(:name_column) && !options[:name_column].blank? then
+                      options[:name_column].to_s.to_sym
+                    else
+                      :name
+                    end
+
+      alias_name = if options.has_key?(:alias_name) then
+                     options[:alias_name]
+                   else
+                     true
+                   end
+
+      class_attribute :acts_enumerated_name_column
+      self.acts_enumerated_name_column = name_column
+
+      unless self.is_a? PowerEnum::Enumerated::EnumClassMethods
+        extend PowerEnum::Enumerated::EnumClassMethods
+
+        class_eval do
+          include PowerEnum::Enumerated::EnumInstanceMethods
+
+          before_save :enumeration_model_update
+          before_destroy :enumeration_model_update
+          validates name_column, :presence => true, :uniqueness => true
+
+          define_method :__enum_name__ do
+            read_attribute( name_column ).to_s
+          end
+
+          if alias_name && name_column != :name
+            alias_method :name, :__enum_name__
+          end
+        end # class_eval
+      end
+    end
+  end
+
+  module EnumClassMethods
+    attr_accessor :enumeration_model_updates_permitted
+
+    # Returns true for ActiveRecord models that act as enumerated.
+    def acts_as_enumerated?
+      true
+    end
+
+    # Returns all the enum values.  Caches results after the first time this method is run.
+    def all
+      return @all if @all
+      conditions = self.acts_enumerated_conditions
+      order = self.acts_enumerated_order
+      @all = where(conditions).order(order).collect{|val| val.freeze}.freeze
+    end
+
+    # Returns all the active enum values.  See the 'active?' instance method.
+    def active
+      return @all_active if @all_active
+      @all_active = all.select{ |enum| enum.active? }.freeze
+    end
+
+    # Returns all the inactive enum values.  See the 'inactive?' instance method.
+    def inactive
+      return @all_inactive if @all_inactive
+      @all_inactive = all.select{ |enum| !enum.active? }.freeze
+    end
+
+    # Returns the names of all the enum values as an array of symbols.
+    def names
+      all.map { |item| item.name_sym }
+    end
+
+    # Enum lookup by Symbol, String, or id.  Returns <tt>arg<tt> if arg is
+    # an enum instance.  Passing in a list of arguments returns a list of enums.
+    def [](*args)
+      case args.size
+      when 0
+        nil
+      when 1
+        arg = args.first
+        case arg
+        when Symbol
+          return_val = lookup_name(arg.id2name) and return return_val
+        when String
+          return_val = lookup_name(arg) and return return_val
+        when Fixnum
+          return_val = lookup_id(arg) and return return_val
+        when self
+          return arg
+        when nil
+          nil
+        else
+          raise TypeError, "#{self.name}[]: argument should be a String, Symbol or Fixnum but got a: #{arg.class.name}"
+        end
+
+        handle_lookup_failure(arg)
+      else
+        args.map{ |item| self[item] }.uniq
+      end
+    end
+
+    # Deals with a lookup failure for the given argument.
+    def handle_lookup_failure(arg)
+      if (lookup_failure_handler = self.acts_enumerated_on_lookup_failure)
+        case lookup_failure_handler
+        when Proc
+          lookup_failure_handler.call(arg)
+        else
+          self.send(lookup_failure_handler, arg)
+        end
+      else
+        self.send(:enforce_none, arg)
+      end
+    end
+    private :handle_lookup_failure
+
+    # Enum lookup by id
+    def lookup_id(arg)
+      all_by_id[arg]
+    end
+
+    # Enum lookup by String
+    def lookup_name(arg)
+      all_by_name[arg]
+    end
+
+    # Returns true if the enum lookup by the given Symbol, String or id would have returned a value, false otherwise.
+    def include?(arg)
+      case arg
+      when Symbol
+        !lookup_name(arg.id2name).nil?
+      when String
+        !lookup_name(arg).nil?
+      when Fixnum
+        !lookup_id(arg).nil?
+      when self
+        possible_match = lookup_id(arg.id)
+        !possible_match.nil? && possible_match == arg
+      else
+        false
+      end
+    end
+
+    # NOTE: purging the cache is sort of pointless because
+    # of the per-process rails model.
+    # By default this blows up noisily just in case you try to be more
+    # clever than rails allows.
+    # For those times (like in Migrations) when you really do want to
+    # alter the records you can silence the carping by setting
+    # enumeration_model_updates_permitted to true.
+    def purge_enumerations_cache
+      unless self.enumeration_model_updates_permitted
+        raise "#{self.name}: cache purging disabled for your protection"
+      end
+      @all = @all_by_name = @all_by_id = @all_active = nil
+    end
+
+    # The preferred method to update an enumerations model.  The same
+    # warnings as 'purge_enumerations_cache' and
+    # 'enumerations_model_update_permitted' apply.  Pass a block to this
+    # method (no args) where you perform your updates.  Cache will be
+    # flushed automatically.
+    def update_enumerations_model
+      if block_given?
+        begin
+          self.enumeration_model_updates_permitted = true
+          yield
+        ensure
+          purge_enumerations_cache
+          self.enumeration_model_updates_permitted = false
+        end
+      end
+    end
+
+    # Returns the name of the column this enum uses as the basic underlying value.
+    def name_column
+      @name_column ||= self.acts_enumerated_name_column
+    end
+
+    # ---Private methods---
+
+    # Returns a hash of all enumeration members keyed by their ids.
+    def all_by_id
+      @all_by_id ||= all_by_attribute( :id )
+    end
+    private :all_by_id
+
+    # Returns a hash of all the enumeration members keyed by their names.
+    def all_by_name
+      begin
+        @all_by_name ||= all_by_attribute( :__enum_name__ )
+      rescue NoMethodError => err
+        if err.name == name_column
+          raise TypeError, "#{self.name}: you need to define a '#{name_column}' column in the table '#{table_name}'"
+        end
+        raise
+      end
+    end
+    private :all_by_name
+
+    def all_by_attribute(attr)
+      all.inject({}) { |memo, item|
+        memo[item.send(attr)] = item
+        memo
+      }.freeze
+    end
+    private :all_by_attribute
+
+    def enforce_none(arg)
+      nil
+    end
+    private :enforce_none
+
+    def enforce_strict(arg)
+      raise_record_not_found(arg)
+    end
+    private :enforce_strict
+
+    def enforce_strict_literals(arg)
+      raise_record_not_found(arg) if (Fixnum === arg) || (Symbol === arg)
+      nil
+    end
+    private :enforce_strict_literals
+
+    def enforce_strict_ids(arg)
+      raise_record_not_found(arg) if Fixnum === arg
+      nil
+    end
+    private :enforce_strict_ids
+
+    def enforce_strict_symbols(arg)
+      raise_record_not_found(arg) if Symbol === arg
+      nil
+    end
+    private :enforce_strict_symbols
+
+    def raise_record_not_found(arg)
+      raise ActiveRecord::RecordNotFound, "Couldn't find a #{self.name} identified by (#{arg.inspect})"
+    end
+    private :raise_record_not_found
+
+  end
+
+  module EnumInstanceMethods
+    # Behavior depends on the type of +arg+.
+    #
+    # * If +arg+ is +nil+, returns +false+.
+    # * If +arg+ is an instance of +Symbol+, +Fixnum+ or +String+, returns the result of +BookingStatus[:foo] == BookingStatus[arg]+.
+    # * If +arg+ is an +Array+, returns +true+ if any member of the array returns +true+ for +===(arg)+, +false+ otherwise.
+    # * In all other cases, delegates to +===(arg)+ of the superclass.
+    #
+    # Examples:
+    #
+    #     BookingStatus[:foo] === :foo #Returns true
+    #     BookingStatus[:foo] === 'foo' #Returns true
+    #     BookingStatus[:foo] === :bar #Returns false
+    #     BookingStatus[:foo] === [:foo, :bar, :baz] #Returns true
+    #     BookingStatus[:foo] === nil #Returns false
+    #
+    # You should note that defining an +:on_lookup_failure+ method that raises an exception will cause +===+ to
+    # also raise an exception for any lookup failure of +BookingStatus[arg]+.
+    def ===(arg)
+      case arg
+      when nil
+        false
+      when Symbol, String, Fixnum
+        return self == self.class[arg]
+      when Array
+        return self.in?(*arg)
+      else
+        super
+      end
+    end
+
+    alias_method :like?, :===
+
+    # Returns true if any element in the list returns true for ===(arg), false otherwise.
+    def in?(*list)
+      for item in list
+        self === item and return true
+      end
+      false
+    end
+
+    # Returns the symbol representation of the name of the enum. BookingStatus[:foo].name_sym returns :foo.
+    def name_sym
+      self.__enum_name__.to_sym
+    end
+
+    alias_method :to_sym, :name_sym
+
+    # By default enumeration #to_s should return stringified name of the enum. BookingStatus[:foo].to_s returns "foo"
+    def to_s
+      self.__enum_name__
+    end
+
+    # Returns true if the instance is active, false otherwise.  If it has an attribute 'active',
+    # returns the attribute cast to a boolean, otherwise returns true.  This method is used by the 'active'
+    # class method to select active enums.
+    def active?
+      @_active_status ||= ( attributes.include?('active') ? !!self.active : true )
+    end
+
+    # Returns true if the instance is inactive, false otherwise.  Default implementations returns !active?
+    # This method is used by the 'inactive' class method to select inactive enums.
+    def inactive?
+      !active?
+    end
+
+    # NOTE: updating the models that back an acts_as_enumerated is
+    # rather dangerous because of rails' per-process model.
+    # The cached values could get out of synch between processes
+    # and rather than completely disallow changes I make you jump
+    # through an extra hoop just in case you're defining your enumeration
+    # values in Migrations.  I.e. set enumeration_model_updates_permitted = true
+    def enumeration_model_update
+      if self.class.enumeration_model_updates_permitted
+        self.class.purge_enumerations_cache
+        true
+      else
+        # Ugh.  This just seems hack-ish.  I wonder if there's a better way.
+        self.errors.add(self.class.name_column, "changes to acts_as_enumeration model instances are not permitted")
+        false
+      end
+    end
+    private :enumeration_model_update
+  end # module EnumInstanceMethods
+end # module PowerEnum::Enumerated