power_enum 0.2.5 → 0.3.0

data/README.md

@@ -4,17 +4,19 @@ Enumerations for Rails 3.X Done Right.
 
 ## What is this?:
 
-Power Enum allows you to treat instances of your
-ActiveRecord models as though they were an enumeration of values.
+Power Enum allows you to treat instances of your ActiveRecord models as though they were an enumeration of values.
+It allows you to cleanly solve many of the problems that the traditional Rails alternatives handler poorly if at all.
+It is particularly suitable for scenarios where your Rails application is not the only user of the database, such as
+when it's used for analytics or reporting.
 
 Power Enum is built on top of the Rails 3 modernization made by the fine folks at Protocool https://github.com/protocool/enumerations_mixin
-to the original plugin by Trevor Squires located at https://github.com/protocool/enumerations_mixin.  While mot the core ideas remain,
+to the original plugin by Trevor Squires located at https://github.com/protocool/enumerations_mixin.  While many of the core ideas remain,
 it has been reworked and a full test suite written to facilitate further development.
 
 At it's most basic level, it allows you to say things along the lines of:
 
     booking = Booking.new(:status => BookingStatus[:provisional])
-    booking.update_attribute(:status, BookingStatus[:confirmed])
+    booking.status = :confirmed
 
     Booking.find :first,
                  :conditions => ['status_id = ?', BookingStatus[:provisional].id]
@@ -25,19 +27,29 @@ See "How to use it" below for more information.
 
 ## Installation
 
-To use this version, add the gem to your Gemfile
+Add the gem to your Gemfile
 
     gem 'power_enum'
 
+then run
+
+    bundle install
+
 ## Gem Contents
 
-This package adds two mixins and a helper to Rails' ActiveRecord:
+This package adds two mixins and a helper to Rails' ActiveRecord, as well as methods to migrations to simplify the creation of backing tables.
 
-<code>acts_as_enumerated</code> provides capabilities to treat your model and its records as an enumeration. At a minimum, the database table for  an acts_as_enumerated must contain an 'id' column and a 'name' column. All instances for the acts_as_enumerated model are cached in memory.
+<code>acts_as_enumerated</code> provides capabilities to treat your model and its records as an enumeration.
+At a minimum, the database table for  an acts_as_enumerated must contain an 'id' column and a 'name' column.
+It is strongly recommended that there be a NOT NULL constraint on the 'name' column.
+All instances for the acts_as_enumerated model are cached in memory.  If the table has an 'active' column, the
+value of that attribute will be used to determine which enum instances are active.  Otherwise, all values are considered
+active.
 
 <code>has_enumerated</code> adds methods to your ActiveRecord model for setting and retrieving enumerated values using an associated acts_as_enumerated model.
 
-There is also an <code>ActiveRecord::VirtualEnumerations</code> helper module to create 'virtual' acts_as_enumerated models which helps to avoid cluttering up your models directory with acts_as_enumerated classes.
+There is also an <code>ActiveRecord::VirtualEnumerations</code> helper module to create 'virtual' acts_as_enumerated models which helps to avoid
+cluttering up your models directory with acts_as_enumerated classes.
 
 ## How to use it
 
@@ -45,11 +57,13 @@ In the following example, we'll look at a Booking that can have several types of
 
 ### migration
 
-    create_table :booking_statuses do |t|
-      t.string :name
+    create_enum :booking_status, :name_limit => 50
+    # The above is equivalent to saying
+    # create_table :booking_statuses do |t|
+    #   t.string :name, :limit => 50, :null => false
 
-      t.timestamps
-    end
+    #   t.timestamps
+    # end
 
     create_table :bookings do |t|
       t.integer :status_id
@@ -59,6 +73,47 @@ In the following example, we'll look at a Booking that can have several types of
 
     # Ideally, you would use a gem of some sort to handle foreign keys.
     execute "ALTER TABLE bookings ADD 'bookings_bookings_status_id_fk' FOREIGN KEY (status_id) REFERENCES booking_statuses (id);"
+    
+There are two methods added to Rails migrations:
+
+##### create_enum(enum_name, options = {})
+
+Creates a new enum table.  <code>enum_name</code> will be automatically pluralized.  The following options are supported:
+
+- [:name_column]  Specify the column name for name of the enum.  By default it's :name.  This can be a String or a Symbol
+- [:description]  Set this to <code>true</code> to have a 'description' column generated.
+- [:name_limit]  Set this define the limit of the name column.
+- [:desc_limit]  Set this to define the limit of the description column
+- [:active]  Set this to <code>true</code> to have a boolean 'active' column generated.  The 'active' column will have the options of NOT NULL and DEFAULT TRUE.
+
+Example:
+
+    create_enum :booking_status, :name_column => :booking_name,
+                                 :name_limit  => 50,
+                                 :description => true,
+                                 :desc_limit  => 100,
+                                 :active      => true
+
+is the equivalent of
+    
+    create_table :booking_statuses do |t|
+      t.string :booking_name, :limit => 50, :null => false
+      t.string :description, :limit => 100
+      t.boolean :active, :null => false, :default => true
+      t.timestamps
+    end
+
+##### remove_enum(enum_name)
+
+Drops the enum table.  <code>enum_name</code> will be automatically pluralized.
+
+Example:
+
+    remove_enum :booking_status
+    
+is the equivalent of
+    
+    drop_table :booking_statuses
 
 ### acts_as_enumerated
 
@@ -73,7 +128,7 @@ With that, your BookingStatus class will have the following methods defined:
 
 #### Class Methods
 
-##### []
+##### [](arg)
 
 <code>BookingStatus[arg]</code> performs a lookup the BookingStatus instance for arg. The arg value can be a 'string' or a :symbol, in which case the lookup will be against the BookingStatus.name field. Alternatively arg can be a Fixnum, in which case the lookup will be against the BookingStatus.id field.
 
@@ -85,6 +140,14 @@ The purpose of the :on_lookup_failure option is that a) under some circumstances
 
 <code>BookingStatus.all</code> returns an array of all BookingStatus records that match the :conditions specified in acts_as_enumerated, in the order specified by :order.
 
+##### active
+
+<code>BookingStatus.active</code> returns an array of all BookingStatus records that are marked active.  See the <code>active?</code> instance method.
+
+##### inactive
+
+<code>BookingStatus.inactive</code> returns an array of all BookingStatus records that are inactive.  See the <code>inactive?</code> instance method.
+
 #### Instance Methods
 
 Each enumeration model gets the following instance methods.
@@ -109,6 +172,17 @@ Returns the 'name' of the enum, i.e. the value in the <code>:name_column</code>
 
 Returns the symbol representation of the name of the enum.  <code>BookingStatus[:foo].name_sym</code> returns :foo.
 
+##### active?
+
+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.
+
+##### inactive?
+
+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.
+
 #### Notes
 
 acts_as_enumerated records are considered immutable. By default you cannot create/alter/destroy instances because they are cached in memory.  Because of Rails' process-based model it is not safe to allow updating acts_as_enumerated records as the caches will get out of sync.
@@ -142,13 +216,17 @@ With that, your Booking class will have the following methods defined:
 
 Returns the BookingStatus with an id that matches the value in the Booking.status_id.
 
-#### status=
+#### status=(arg)
 
 Sets the value for Booking.status_id using the id of the BookingStatus instance passed as an argument.  As a short-hand, you can also pass it the 'name' of a BookingStatus instance, either as a 'string' or :symbol, or pass in the id directly.
 
 example:
 
     mybooking.status = :confirmed
+    
+this also works:
+
+    mybooking.status = 'confirmed'
 
 The <code>:on_lookup_failure</code> option in has_enumerated is there because you may want to create an error handler for situations where the argument passed to status= is invalid.  By default, an invalid value will cause an ArgumentError to be raised.  
 

data/lib/active_record/acts/enumerated.rb

@@ -45,7 +45,8 @@ module ActiveRecord
       
       module ClassMethods  
         attr_accessor :enumeration_model_updates_permitted
-        
+
+        # Returns all the enum values.  Caches results after the first time this method is run.
         def all
           return @all if @all
           @all = find(:all, 
@@ -54,6 +55,18 @@ module ActiveRecord
                       ).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
+
         # Enum lookup by Symbol, String, or id.
         def [](arg)
           case arg
@@ -109,7 +122,7 @@ module ActiveRecord
           unless self.enumeration_model_updates_permitted
             raise "#{self.name}: cache purging disabled for your protection"
           end
-          @all = @all_by_name = @all_by_id = nil
+          @all = @all_by_name = @all_by_id = @all_active = nil
         end
 
         # Returns the name of the column this enum uses as the basic underlying value.
@@ -194,7 +207,18 @@ module ActiveRecord
           self.name.to_sym
         end
 
-        private
+        # 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.
@@ -212,6 +236,7 @@ module ActiveRecord
             false
           end
         end
+        private :enumeration_model_update
       end
     end
   end

data/lib/power_enum/migration/command_recorder.rb

@@ -0,0 +1,18 @@
+module PowerEnum::Migration
+
+  module CommandRecorder
+    def create_enum(*args)
+      record(:create_enum, args)
+    end
+
+    def remove_enum(*args)
+      record(:remove_enum, args)
+    end
+
+    def invert_create_enum(args)
+      enum_name = args[0]
+      [:remove_enum, [enum_name]]
+    end
+  end
+
+end

data/lib/power_enum/schema/schema_statements.rb

@@ -0,0 +1,84 @@
+module PowerEnum::Schema
+  module SchemaStatements
+
+    def self.included(base)
+      base::AbstractAdapter.class_eval do
+        include PowerEnum::Schema::AbstractAdapter
+      end
+    end
+
+  end
+
+  module AbstractAdapter
+
+    # Creates a new enum table.  +enum_name+ will be automatically pluralized.
+    #
+    # === Supported options
+    # [:name_column]
+    #   Specify the column name for name of the enum.  By default it's :name.
+    #   This can be a String or a Symbol
+    # [:description]
+    #   Set this to <tt>true</tt> to have a 'description' column generated.
+    # [:name_limit]
+    #   Set this define the limit of the name column.
+    # [:desc_limit]
+    #   Set this to define the limit of the description column.
+    # [:active]
+    #   Set this to <tt>true</tt> to have a boolean 'active' column generated.  The 'active' column will have the options of NOT NULL and DEFAULT TRUE.
+    #
+    # ===== Examples
+    # ====== Basic Enum
+    #  create_enum :connector_type
+    # is the equivalent of
+    #  create_table :connector_types do |t|
+    #    t.string :name, :null => false
+    #    t.timestamps
+    #  end
+    #
+    # ====== Advanced Enum
+    #  create_enum :connector_type, :name_column => :connector, :name_limit => 50, :description => true, :desc_limit => 100, :active => true
+    # is the equivalent of
+    #  create_table :connector_types do |t|
+    #    t.string :connector, :limit => 50, :null => false
+    #    t.string :description, :limit => 100
+    #    t.boolean :active, :null => false, :default => true
+    #    t.timestamps
+    #  end
+    #
+    def create_enum(enum_name, options = {})
+      enum_table_name = enum_name.pluralize
+      name_column = options[:name_column] || :name
+      generate_description = !!options[:description]
+      generate_active = !!options[:active]
+      name_limit = options[:name_limit]
+      desc_limit = options[:desc_limit]
+
+      create_table enum_table_name do |t|
+        t.string name_column, :limit => name_limit, :null => false
+        if generate_description
+          t.string :description, :limit => desc_limit
+        end
+        if generate_active
+          t.boolean :active, :null => false, :default => true
+        end
+
+        t.timestamps
+      end
+
+      add_index enum_table_name, [name_column], :unique => true
+
+    end
+
+    # Drops the enum table.  +enum_name+ will be automatically pluralized.
+    #
+    # ===== Example
+    #  remove_enum :connector_type
+    # is the equivalent of
+    #  drop_table :connector_types
+    def remove_enum(enum_name)
+      drop_table enum_name.pluralize
+    end
+
+  end
+
+end

data/lib/power_enum.rb

@@ -7,6 +7,17 @@ class PowerEnum < Rails::Engine
     ActiveSupport.on_load(:active_record) do
       include ActiveRecord::Acts::Enumerated
       include ActiveRecord::Aggregations::HasEnumerated
+
+      ActiveRecord::ConnectionAdapters.module_eval do
+        include PowerEnum::Schema::SchemaStatements
+      end
+
+      if defined?(ActiveRecord::Migration::CommandRecorder)
+        ActiveRecord::Migration::CommandRecorder.class_eval do
+          include PowerEnum::Migration::CommandRecorder
+        end
+      end
     end
+
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: power_enum
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -12,11 +12,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-18 00:00:00.000000000Z
+date: 2011-09-23 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &15753300 !ruby/object:Gem::Requirement
+  requirement: &18214180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -24,10 +24,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *15753300
+  version_requirements: *18214180
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &15752440 !ruby/object:Gem::Requirement
+  requirement: &18213580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -35,10 +35,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *15752440
+  version_requirements: *18213580
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &15751840 !ruby/object:Gem::Requirement
+  requirement: &18189680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -46,10 +46,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *15751840
+  version_requirements: *18189680
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &15751240 !ruby/object:Gem::Requirement
+  requirement: &18188860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -57,9 +57,19 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *15751240
-description: Allows you to treat instances of your ActiveRecord models as though they
-  were an enumeration of values
+  version_requirements: *18188860
+description: ! 'Power Enum allows you to treat instances of your ActiveRecord models
+  as though they were an enumeration of values.
+
+  It allows you to cleanly solve many of the problems that the traditional Rails alternatives
+  handler poorly if at all.
+
+  It is particularly suitable for scenarios where your Rails application is not the
+  only user of the database, such as
+
+  when it''s used for analytics or reporting.
+
+'
 email: arthur.shagall@gmail.com
 executables: []
 extensions: []
@@ -72,6 +82,8 @@ files:
 - lib/active_record/aggregations/has_enumerated.rb
 - lib/active_record/virtual_enumerations.rb
 - lib/power_enum.rb
+- lib/power_enum/migration/command_recorder.rb
+- lib/power_enum/schema/schema_statements.rb
 - LICENSE
 - README.md
 homepage: http://github.com/albertosaurus/enumerations_mixin