power_enum 0.3.0 → 0.3.1

data/LICENSE

@@ -1,4 +1,7 @@
-Copyright (c) 2005 Trevor Squires
+Initial Version Copyright (c) 2005 Trevor Squires
+Rails 3 Updates Copyright (c) 2010 Pivotal Labs
+Initial Test Suite Copyright (c) 2011 Sergey Potapov
+Subsequent Updates Copyright (c) 2011 Arthur Shagall
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -9,8 +9,8 @@ It allows you to cleanly solve many of the problems that the traditional Rails a
 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 many of the core ideas remain,
+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 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:
@@ -39,17 +39,18 @@ then run
 
 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.
-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.
+`acts_as_enumerated` 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 column
+to hold the value of the enum ('name' by default).  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.
+`has_enumerated` 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 `ActiveRecord::VirtualEnumerations` 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
 
@@ -61,8 +62,6 @@ In the following example, we'll look at a Booking that can have several types of
     # The above is equivalent to saying
     # create_table :booking_statuses do |t|
     #   t.string :name, :limit => 50, :null => false
-
-    #   t.timestamps
     # end
 
     create_table :bookings do |t|
@@ -76,23 +75,35 @@ In the following example, we'll look at a Booking that can have several types of
     
 There are two methods added to Rails migrations:
 
-##### create_enum(enum_name, options = {})
+##### `create_enum(enum_name, options = {})`
 
-Creates a new enum table.  <code>enum_name</code> will be automatically pluralized.  The following options are supported:
+Creates a new enum table.  `enum_name` 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.
+- [:description]  Set this to `true` 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.
+- [:active]  Set this to `true` to have a boolean 'active' column generated.  The 'active' column will have the options of NOT NULL and DEFAULT TRUE.
+- [:timestamps]  Set this to `true` to have the timestamp columns (created\_at and updated\_at) generated
 
 Example:
 
+    create_enum :booking_status
+
+is the equivalent of
+
+    create_table :booking_statuses do |t|
+      t.string :name, :null => false
+    end
+
+In a more complex case:
+
     create_enum :booking_status, :name_column => :booking_name,
                                  :name_limit  => 50,
                                  :description => true,
                                  :desc_limit  => 100,
-                                 :active      => true
+                                 :active      => true,
+                                 :timestamps  => true
 
 is the equivalent of
     
@@ -103,9 +114,9 @@ is the equivalent of
       t.timestamps
     end
 
-##### remove_enum(enum_name)
+##### `remove_enum(enum_name)`
 
-Drops the enum table.  <code>enum_name</code> will be automatically pluralized.
+Drops the enum table.  `enum_name` will be automatically pluralized.
 
 Example:
 
@@ -115,77 +126,85 @@ is the equivalent of
     
     drop_table :booking_statuses
 
-### acts_as_enumerated
+### acts\_as\_enumerated
 
     class BookingStatus < ActiveRecord::Base
-      acts_as_enumerated  :conditions => 'optional_sql_conditions',
-        :order => 'optional_sql_orderby',
-        :on_lookup_failure => :optional_class_method,
-        :name_column => 'optional_name_column'  #If required, may override the default name column
+      acts_as_enumerated  :conditions        => 'optional_sql_conditions',
+                          :order             => 'optional_sql_orderby',
+                          :on_lookup_failure => :optional_class_method,
+                          :name_column       => 'optional_name_column'  #If required, may override the default name column
     end
 
 With that, your BookingStatus class will have the following methods defined:
 
 #### Class Methods
 
-##### [](arg)
+##### `[](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.
+`BookingStatus[arg]` performs a lookup for the BookingStatus instance for the given 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.
 
-The <code>:on_lookup_failure</code> option 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 `:on_lookup_failure` option 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.
+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.
 
-##### all
+##### `all`
 
-<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.
+`BookingStatus.all` returns an array of all BookingStatus records that match the `:conditions` specified in `acts_as_enumerated`, in the order specified by `:order`.
 
-##### active
+##### `active`
 
-<code>BookingStatus.active</code> returns an array of all BookingStatus records that are marked active.  See the <code>active?</code> instance method.
+`BookingStatus.active` returns an array of all BookingStatus records that are marked active.  See the `active?` instance method.
 
-##### inactive
+##### `inactive`
 
-<code>BookingStatus.inactive</code> returns an array of all BookingStatus records that are inactive.  See the <code>inactive?</code> instance method.
+`BookingStatus.inactive` returns an array of all BookingStatus records that are inactive.  See the `inactive?` instance method.
 
 #### Instance Methods
 
 Each enumeration model gets the following instance methods.
 
-##### ===(arg)
+##### `===(arg)`
 
-<code>BookingStatus[:foo] === arg</code> returns true if <code>BookingStatus[:foo] === BookingStatus[arg]</code> returns true if arg is Fixnum, String, or Symbol.  If arg is an Array, will compare every element of the array and return true if any element return true for ===.
+`BookingStatus[:foo] === arg` returns true if `BookingStatus[:foo] === BookingStatus[arg]` returns true if arg is Fixnum, String,
+or Symbol.  If arg is an Array, will compare every element of the array and return true if any element return true for `===`.
 
-You should note that defining an :on_lookup_failure method that raises an exception will cause <code>===</code> to also raise an exception for any lookup failure of <code>BookingStatus</arg>.
+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]`.
 
-<code>like?</code> is aliased to <code>===<code>
+`like?` is aliased to `===`
 
-##### in?(*list)
+##### `in?(*list)`
 
-Returns true if any element in the list returns true for <code>===(arg)</code>, false otherwise.
+Returns true if any element in the list returns true for `===(arg)`, false otherwise.
 
-##### name
+##### `name`
 
-Returns the 'name' of the enum, i.e. the value in the <code>:name_column</code> attribute of the enumeration model.
+Returns the 'name' of the enum, i.e. the value in the `:name_column` attribute of the enumeration model.
 
-##### name_sym
+##### `name_sym`
 
-Returns the symbol representation of the name of the enum.  <code>BookingStatus[:foo].name_sym</code> returns :foo.
+Returns the symbol representation of the name of the enum.  `BookingStatus[:foo].name_sym` returns :foo.
 
-##### active?
+##### `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'
+returns the attribute cast to a boolean, otherwise returns true.  This method is used by the `active`
 class method to select active enums.
 
-##### inactive?
+##### `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.
+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.
+`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.
 
 However, one instance where updating the models *should* be allowed is if you are using seeds.rb to seed initial values into the database.
 
@@ -196,64 +215,76 @@ Using the above example you would do the following:
         BookingStatus.create( :name => status_name )
     end
 
-A <code>:presence</code> and <code>:uniqueness</code> validation is automatically defined on each model.
+Note that a `:presence` and `:uniqueness` validation is automatically defined on each model for the name column.
 
-### has_enumerated
+### has\_enumerated
 
-First of all, note that you *could* specify the relationship to an acts_as_enumerated class using the belongs_to association. However, has_enumerated is preferable because you aren't really associated to the enumerated value, you are *aggregating* it. As such, the has_enumerated macro behaves more like an aggregation than an association.
+First of all, note that you *could* specify the relationship to an `acts_as_enumerated` class using the belongs_to association.
+However, `has_enumerated` is preferable because you aren't really associated to the enumerated value, you are *aggregating* it. As such,
+the `has_enumerated` macro behaves more like an aggregation than an association.
 
     class Booking < ActiveRecord::Base
-      has_enumerated  :status, :class_name => 'BookingStatus',
-        :foreign_key => 'status_id',
-        :on_lookup_failure => :optional_instance_method
+      has_enumerated  :status, :class_name        => 'BookingStatus',
+                               :foreign_key       => 'status_id',
+                               :on_lookup_failure => :optional_instance_method
     end
 
-By default, the foreign key is interpreted to be the name of your has_enumerated field (in this case 'status') plus '_id'.  Additionally, the default value for :class_name is the camel-ized version of the name for your has_enumerated field. :on_lookup_failure is explained below.
+By default, the foreign key is interpreted to be the name of your has\_enumerated field (in this case 'status') plus '\_id'.  Additionally,
+the default value for `:class_name` is the camel-ized version of the name for your has\_enumerated field. `:on_lookup_failure` is explained below.
 
 With that, your Booking class will have the following methods defined:
 
-#### status
+#### `status`
 
 Returns the BookingStatus with an id that matches the value in the Booking.status_id.
 
-#### status=(arg)
+#### `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.
+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:
+this is equivalent to:
 
     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.  
+or:
+
+    mybooking.status = BookingStatus[:confirmed]
+
+The `:on_lookup_failure` option in has_enumerated is there because you may want to create an error handler for situations
+where the argument passed to `status=(arg)` is invalid.  By default, an invalid value will cause an ArgumentError to be raised.  
 
 Of course, this may not be optimal in your situation.  In this case you can specify an *instance* method to be called in the case of a lookup failure. The method signature is as follows:
 
     your_lookup_handler(operation, name, name_foreign_key, acts_enumerated_class_name, lookup_value)
 
-The 'operation' arg will be either :read or :write.  In the case of :read you are expected to return something or raise an exception, while in the case of a :write you don't have to return anything.
+The 'operation' arg will be either `:read` or `:write`.  In the case of `:read` you are expected to return something or raise an exception,
+while in the case of a `:write` you don't have to return anything.
 
-Note that there's enough information in the method signature that you can specify one method to handle all lookup failures for all has_enumerated fields if you happen to have more than one defined in your model.
+Note that there's enough information in the method signature that you can specify one method to handle all lookup failures
+for all has\_enumerated fields if you happen to have more than one defined in your model.
 
-NOTE: A nil is always considered to be a valid value for status= since it's assumed you're trying to null out the foreign key, therefore the <code>:on_lookup_failure</code> will be bypassed.
+NOTE: A `nil` is always considered to be a valid value for `status=(arg)` since it's assumed you're trying to null out the foreign key.
+The `:on_lookup_failure` will be bypassed.
 
 ### ActiveRecord::VirtualEnumerations
 
-For the most part, your acts_as_enumerated classes will do nothing more than just act as enumerated.
+In many instances, your `acts_as_enumerated` classes will do nothing more than just act as enumerated.
 
 In that case there isn't much point cluttering up your models directory with those class files. You can use ActiveRecord::VirtualEnumerations to reduce that clutter.
 
-Copy virtual_enumerations_sample.rb to Rails.root/config/initializers/virtual_enumerations.rb and configure it accordingly.
+Copy virtual\_enumerations\_sample.rb to Rails.root/config/initializers/virtual\_enumerations.rb and configure it accordingly.
 
-See virtual_enumerations_sample.rb in the examples directory of this gem for a full description.
+See virtual\_enumerations\_sample.rb in the examples directory of this gem for a full description.
 
 
 ## How to run tests
 
-Go to dummy project:
+Go to the 'dummy' project:
     
     cd ./spec/dummy
 
@@ -277,7 +308,7 @@ And finally run tests:
 
 * Initial Version Copyright (c) 2005 Trevor Squires
 * Rails 3 Updates Copyright (c) 2010 Pivotal Labs
-* Initial test suite Copyright (c) 2011 Sergey Potapov
-* Additional Updates Copyright (c) 2011 Arthur Shagall
+* Initial Test Suite Copyright (c) 2011 Sergey Potapov
+* Subsequent Updates Copyright (c) 2011 Arthur Shagall
 
 Released under the MIT License.  See the LICENSE file for more details.

data/lib/power_enum/schema/schema_statements.rb

@@ -25,6 +25,8 @@ module PowerEnum::Schema
     #   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.
+    # [:timestamps]
+    #   Set this to <tt>true</tt> to have timestamp columns (created_at and updated_at) generated.
     #
     # ===== Examples
     # ====== Basic Enum
@@ -32,11 +34,15 @@ module PowerEnum::Schema
     # 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
+    #  create_enum :connector_type, :name_column => :connector,
+    #                               :name_limit => 50,
+    #                               :description => true,
+    #                               :desc_limit => 100,
+    #                               :active => true,
+    #                               :timestamps => true
     # is the equivalent of
     #  create_table :connector_types do |t|
     #    t.string :connector, :limit => 50, :null => false
@@ -50,6 +56,7 @@ module PowerEnum::Schema
       name_column = options[:name_column] || :name
       generate_description = !!options[:description]
       generate_active = !!options[:active]
+      generate_timestamps = !!options[:timestamps]
       name_limit = options[:name_limit]
       desc_limit = options[:desc_limit]
 
@@ -61,8 +68,9 @@ module PowerEnum::Schema
         if generate_active
           t.boolean :active, :null => false, :default => true
         end
-
-        t.timestamps
+        if generate_timestamps
+          t.timestamps
+        end
       end
 
       add_index enum_table_name, [name_column], :unique => true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: power_enum
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -12,11 +12,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-23 00:00:00.000000000Z
+date: 2011-09-25 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &18214180 !ruby/object:Gem::Requirement
+  requirement: &28153380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -24,10 +24,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *18214180
+  version_requirements: *28153380
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &18213580 !ruby/object:Gem::Requirement
+  requirement: &28152380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -35,10 +35,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18213580
+  version_requirements: *28152380
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &18189680 !ruby/object:Gem::Requirement
+  requirement: &28151860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -46,10 +46,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18189680
+  version_requirements: *28151860
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &18188860 !ruby/object:Gem::Requirement
+  requirement: &28151280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -57,7 +57,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18188860
+  version_requirements: *28151280
 description: ! 'Power Enum allows you to treat instances of your ActiveRecord models
   as though they were an enumeration of values.