power_enum 0.8.6 → 0.9.1

data/{README.md → README.markdown}

@@ -1,6 +1,6 @@
 # Power Enum
 
-https://github.com/albertosaurus/power\_enum
+https://github.com/albertosaurus/power_enum
 
 Enumerations for Rails 3.X Done Right.
 
@@ -12,23 +12,36 @@ It is particularly suitable for scenarios where your Rails application is not th
 when it's used for analytics or reporting.
 
 Power Enum is a fork 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.  While many of the core ideas
+https://github.com/protocool/enumerations_mixin to the original plugin by Trevor Squires.  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.status = :confirmed
-    booking = Booking.create( :status => :rejected )
+```ruby
+# Create a provisional booking
+booking = Booking.new( :status => BookingStatus[:provisional] )
+# Set the booking status to 'confirmed'
+booking.status = :confirmed
+booking = Booking.create( :status => :rejected )
+# And now...
+booking.status == BookingStatus[:rejected]               # evaluates to true
+booking.status === :rejected                             # also evaluates to true
+booking.status === [:rejected, :confirmed, :provisional] # and so does this
 
-    Booking.where(:status_id => BookingStatus[:provisional])
+Booking.where( :status_id => BookingStatus[:provisional] )
 
-    BookingStatus.all.collect {|status|, [status.name, status.id]}
-
-    Booking.with_status :provisional, :confirmed
+BookingStatus.all.collect { |status|, [status.name, status.id] }
 
+# built in scopes make life easier
+Booking.with_status( :provisional, :confirmed )
+```
 See "How to use it" below for more information.
 
+## Requirements
+
+* Ruby 1.8.7, 1.9.2, 1.9.3, JRuby 1.6+
+* Rails 3.0, 3.1, 3.2
+
 ## Installation
 
 Add the gem to your Gemfile
@@ -87,55 +100,67 @@ from a pre-test Rake task.
 
 If you're using Rails 3.0, your migration file will look something like this:
 
-    class CreateEnumBookingStatus < ActiveRecord::Migration
-    
-      def self.up
-        create_enum :booking_status
-      end
-      
-      def self.down
-        remove_enum :booking_status
-      end
-    
-    end
+```ruby
+class CreateEnumBookingStatus < ActiveRecord::Migration
+
+  def self.up
+    create_enum :booking_status
+  end
+
+  def self.down
+    remove_enum :booking_status
+  end
+
+end
+```
     
 If you're using Rails 3.1 or later, it will look something like this:
 
-    class CreateEnumBookingStatus < ActiveRecord::Migration
-    
-      def change
-        create_enum :booking_status
-      end
-    
-    end
+```ruby
+class CreateEnumBookingStatus < ActiveRecord::Migration
+
+  def change
+    create_enum :booking_status
+  end
+
+end
+```
 
 You can now customize it.
-    
-    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
-    # end
+
+```ruby
+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
+# end
+```
 
 Now, when you create your Booking model, your migration should create a reference column for status id's and a foreign
 key relationship to the booking\_statuses table.
-    
-    create_table :bookings do |t|
-      t.integer :status_id
 
-      t.timestamps
-    end
+```ruby
+create_table :bookings do |t|
+  t.integer :status_id
 
-    # 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);"
+  t.timestamps
+end
+
+# It's highly recommended to add a foreign key constraint here.
+# Ideally, you would use a gem of some sort to handle this.
+execute "ALTER TABLE bookings ADD 'bookings_bookings_status_id_fk'"\
+    " FOREIGN KEY (status_id) REFERENCES booking_statuses (id);"
+```
 
 It's easier to use the `references` method if you intend to stick to the default naming convention for reference columns.
 
-    create_table :bookings do |t|
-      t.references :booking_status # Same as t.integer booking_status_id
+```ruby
+create_table :bookings do |t|
+  t.references :booking_status # Same as t.integer booking_status_id
 
-      t.timestamps
-    end
+  t.timestamps
+end
+```
     
 There are two methods added to Rails migrations:
 
@@ -154,47 +179,60 @@ You can also pass in a block that takes a table object as an argument, like `cre
 
 Example:
 
-    create_enum :booking_status
+```ruby
+create_enum :booking_status
+```
 
 is the equivalent of
 
-    create_table :booking_statuses do |t|
-      t.string :name, :null => false
-    end
-    add_index :booking_statuses, [:name], :unique => true
+```ruby
+create_table :booking_statuses do |t|
+  t.string :name, :null => false
+end
+add_index :booking_statuses, [:name], :unique => true
+```
 
 In a more complex case:
 
-    create_enum :booking_status, :name_column => :booking_name,
-                                 :name_limit  => 50,
-                                 :description => true,
-                                 :desc_limit  => 100,
-                                 :active      => true,
-                                 :timestamps  => true
+```ruby
+create_enum :booking_status,
+            :name_column => :booking_name,
+            :name_limit  => 50,
+            :description => true,
+            :desc_limit  => 100,
+            :active      => true,
+            :timestamps  => 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
-    add_index :booking_statuses, [:booking_name], :unique => true
+
+```ruby
+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
+add_index :booking_statuses, [:booking_name], :unique => true
+```
 
 You can also customize the creation process by using a block:
 
-    create_enum :booking_status do |t|
-      t.boolean :first_booking, :null => false
-    end
+```ruby
+create_enum :booking_status do |t|
+  t.boolean :first_booking, :null => false
+end
+```
 
 is the equivalent of
 
-    create_table :booking_statuses do |t|
-      t.string :name, :null => false
-      t.boolean :first_booking, :null => false
-    end
-    add_index :booking_statuses, [:name], :unique => true
+```ruby
+create_table :booking_statuses do |t|
+  t.string :name, :null => false
+  t.boolean :first_booking, :null => false
+end
+add_index :booking_statuses, [:name], :unique => true
+```
 
 Notice that a unique index is automatically created on the specified name column.
 
@@ -204,20 +242,29 @@ Drops the enum table.  `enum_name` will be automatically pluralized.
 
 Example:
 
-    remove_enum :booking_status
+```ruby
+remove_enum :booking_status
+```
     
 is the equivalent of
-    
-    drop_table :booking_statuses
+
+```ruby
+drop_table :booking_statuses
+```
 
 ### acts\_as\_enumerated
 
-    class BookingStatus < ActiveRecord::Base
-      acts_as_enumerated  :conditions        => 'optional_sql_conditions',
-                          :order             => 'optional_sql_order_by',
-                          :on_lookup_failure => :optional_class_method, #This also works: lambda{ |arg| some_custom_action }
-                          :name_column       => 'optional_name_column'  #If required, may override the default name column
-    end
+```ruby
+class BookingStatus < ActiveRecord::Base
+  acts_as_enumerated  :conditions        => 'optional_sql_conditions',
+                      :order             => 'optional_sql_order_by',
+                      :on_lookup_failure => :optional_class_method, #This also works: lambda{ |arg| some_custom_action }
+                      :name_column       => 'optional_name_column'  #If required, may override the default name column
+                      :alias_name        => false                   #If set to false and have name_column set, will not
+                                                                    #  alias :name to the name column attribute
+                                                                    #  (version 0.9.0).
+end
+```
 
 With that, your BookingStatus class will have the following methods defined:
 
@@ -270,11 +317,13 @@ to perform any updates.
 
 Example:
 
-    BookingStatus.update_enumerations_model do
-      BookingStatus.create :name        => 'Foo',
-                           :description => 'Bar',
-                           :active      => false
-    end
+```ruby
+BookingStatus.update_enumerations_model do
+  BookingStatus.create :name        => 'Foo',
+                       :description => 'Bar',
+                       :active      => false
+end
+```
 
 ##### acts\_as\_enumerated? (since version 0.8.6)
 
@@ -296,16 +345,20 @@ Behavior depends on the type of `arg`.
 
 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
+```ruby
+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]`.
 
-`like?` is aliased to `===`
+##### like?(arg)
+
+Aliased to `===`
 
 ##### in?(*list)
 
@@ -313,16 +366,27 @@ Returns true if any element in the list returns true for `===(arg)`, false other
 
 Example:
 
-    BookingStatus[:foo].in? :foo, :bar, :baz #Returns true
+```ruby
+BookingStatus[:foo].in? :foo, :bar, :baz #Returns true
+```
+
+##### to_s
+
+Returns the string representation of the enum, i.e. the value in the `:name_column` attribute of the enumeration model.
 
 ##### name
 
-Returns the 'name' of the enum, i.e. the value in the `:name_column` attribute of the enumeration model.
+By default, aliased to the string representation of the `:name_column` attribute.  To avoid this, set the `alias_name`
+option to `false`.
 
 ##### name\_sym
 
 Returns the symbol representation of the name of the enum.  `BookingStatus[:foo].name_sym` returns :foo.
 
+##### to\_sym
+
+Aliased to `name_sym` (Since version 0.9.0).
+
 ##### active?
 
 Returns true if the instance is active, false otherwise.  If it has an attribute 'active',
@@ -346,10 +410,12 @@ into the database.
 
 Using the above example you would do the following:
 
-    BookingStatus.enumeration_model_updates_permitted = true
-    ['pending', 'confirmed', 'canceled'].each do | status_name |
-        BookingStatus.create( :name => status_name )
-    end
+```ruby
+BookingStatus.enumeration_model_updates_permitted = true
+['pending', 'confirmed', 'canceled'].each do | status_name |
+    BookingStatus.create( :name => status_name )
+end
+```
 
 Note that a `:presence` and `:uniqueness` validation is automatically defined on each model for the name column.
 
@@ -359,14 +425,17 @@ First of all, note that you *could* specify the relationship to an `acts_as_enum
 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,
-                               :permit_empty_name => true,  #Setting this to true disables automatic conversion of empty strings to nil.  Default is false.
-                               :default           => :unconfirmed,  #Default value of the attribute.
-                               :create_scope      => false  #Setting this to false disables the automatic creation of the 'with_status' scope.
-    end
+```ruby
+class Booking < ActiveRecord::Base
+  has_enumerated  :status,
+                  :class_name        => 'BookingStatus',
+                  :foreign_key       => 'status_id',
+                  :on_lookup_failure => :optional_instance_method,
+                  :permit_empty_name => true,  #Setting this to true disables automatic conversion of empty strings to nil.  Default is false.
+                  :default           => :unconfirmed,  #Default value of the attribute.
+                  :create_scope      => false  #Setting this to false disables the automatic creation of the 'with_status' scope.
+end
+```
 
 By default, the foreign key is interpreted to be the name of your has\_enumerated field (in this case 'booking\_status')
 plus '\_id'.  Since we chose to make the column name 'status\_id' for the sake of brevity, we must explicitly designate
@@ -391,15 +460,21 @@ id directly.
 
 example:
 
-    mybooking.status = :confirmed
-    
+```ruby
+mybooking.status = :confirmed
+```
+
 this is equivalent to:
 
-    mybooking.status = 'confirmed'
+```ruby
+mybooking.status = 'confirmed'
+```
 
 or:
 
-    mybooking.status = BookingStatus[:confirmed]
+```ruby
+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
@@ -412,7 +487,9 @@ subsequent lookups, but the model will fail validation.
 
 2) 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)
+```ruby
+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.
@@ -424,9 +501,11 @@ failures for all has\_enumerated fields if you happen to have more than one defi
 its first argument, with the rest of the arguments being identical to the signature of the lookup handler instance
 method.
 
-    :on_lookup_failure => lambda{ |record, op, attr, fk, cl_name, value|
-       # handle lookup failure
-    }
+```ruby
+:on_lookup_failure => lambda{ |record, op, attr, fk, cl_name, value|
+   # handle lookup failure
+}
+```
 
 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.
@@ -436,12 +515,16 @@ the foreign key.  The `:on_lookup_failure` will be bypassed.
 Unless the `:create_scope` option is set to `false`, a scope is automatically created that takes a list of enums as
 arguments.  This allows us to say things like:
 
-    Booking.with_status :confirmed, :received
+```ruby
+Booking.with_status :confirmed, :received
+```
 
 Strings, symbols, ids, or enum instances are all valid arguments.  For example, the following would be valid, though not
 recommended for obvious reasons.
 
-    Booking.with_status 1, 'confirmed', BookingStatus[:rejected]
+```ruby
+Booking.with_status 1, 'confirmed', BookingStatus[:rejected]
+```
 
 As of version 0.5.5, it also aliases a pluralized version of the scope, i.e. `:with_statuses`
 
@@ -450,7 +533,9 @@ As of version 0.5.5, it also aliases a pluralized version of the scope, i.e. `:w
 As of version 0.8.0, a scope for the inverse of `with_enumerated_attribute` is created, unless the `:create_scope`
 option is set to `false`.  As a result, this allows us to do things like
 
-    Booking.exclude_status :received
+```ruby
+Booking.exclude_status :received
+```
 
 This will give us all the Bookings where the status is a value other than `BookingStatus[:received]`.
 
@@ -473,15 +558,72 @@ Returns an array of attributes which are enumerated.
 
 ### ActiveRecord::VirtualEnumerations
 
-In many instances, 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,
+you can use ActiveRecord::VirtualEnumerations to reduce that clutter.
+
+Create a custom Rails initializer: Rails.root/config/initializers/virtual\_enumerations.rb
+
+```ruby
+ActiveRecord::VirtualEnumerations.define do |config|
+
+  # Define the enum class
+  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 {
+    # This gets evaluated within the class scope of the enum class.
+    def to_s
+      "#{id} - #{name}"
+    end
+  }
+
+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:
+
+```ruby
+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.
 
-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.
+```ruby
+config.define :booking_status, :connector_type, :color, :order => :name
+```
 
-Copy virtual\_enumerations\_sample.rb to Rails.root/config/initializers/virtual\_enumerations.rb and configure it
-accordingly.
+STI is also supported:
 
-See virtual\_enumerations\_sample.rb in the examples directory of this gem for a full description.
+```ruby
+config.define :base_enum, :name_column => ;foo
+config.define :booking_status, :connector_type, :color, :extends => :base_enum
+```
 
 ### Testing (Since version 0.6.0)
 
@@ -491,62 +633,78 @@ A pair of custom RSpec matchers are included to streamline testing of enums and
 
 This is used to test that a model acts as enumerated.  Example:
 
-    describe BookingStatus do
-      it { should act_as_enumerated }
-    end
+```ruby
+describe BookingStatus do
+  it { should act_as_enumerated }
+end
+```
 
 This also works:
 
-    describe BookingStatus do
-      it "should act as enumerated" do
-        BookingStatus.should act_as_enumerated
-      end
-    end
+```ruby
+describe BookingStatus do
+  it "should act as enumerated" do
+    BookingStatus.should act_as_enumerated
+  end
+end
+```
 
 You can use the `with_items` chained matcher to test that each enum is properly seeded:
 
-    describe BookingStatus do
-      it {
-        should act_as_enumerated.with_items(:confirmed, :received, :rejected)
-      }
-    end
+```ruby
+describe BookingStatus do
+  it {
+    should act_as_enumerated.with_items(:confirmed, :received, :rejected)
+  }
+end
+```
 
 You can also pass in hashes if you want to be thorough and test out all the attributes of each enum.  If
 you do this, you must pass in the `:name` attribute in each hash
 
-    describe BookingStatus do
-      it {
-        should act_as_enumerated.with_items({ :name => 'confirmed', :description => "Processed and confirmed" },
-                                            { :name => 'received', :description => "Pending confirmation" },
-                                            { :name => 'rejected', :description => "Rejected due to internal rules" })
-      }
-    end
+```ruby
+describe BookingStatus do
+  it {
+    should act_as_enumerated.with_items(
+      { :name => 'confirmed', :description => "Processed and confirmed" },
+      { :name => 'received',  :description => "Pending confirmation" },
+      { :name => 'rejected',  :description => "Rejected due to internal rules" }
+    )
+  }
+end
+```
 
 #### have\_enumerated
 
 This is used to test that a model has enumerated the given attribute:
 
-    describe Booking do
-      it { should have_enumerated(:status) }
-    end
+```ruby
+describe Booking do
+  it { should have_enumerated(:status) }
+end
+```
 
 This is also valid:
 
-    describe Booking do
-      it "Should have enumerated the status attribute" do
-        Booking.should have_enumerated(:status)
-      end
-    end
+```ruby
+describe Booking do
+  it "Should have enumerated the status attribute" do
+    Booking.should have_enumerated(:status)
+  end
+end
+```
 
 #### match\_enum (Since version 0.8.6)
 
 Tests if an enum instance matches the given value, which may be a symbol, id, string, or enum instance:
 
-    describe Booking do
-      it "status should be 'received' for a new booking" do
-        Booking.new.status.should match_enum(:received)
-      end
-    end
+```ruby
+describe Booking do
+  it "status should be 'received' for a new booking" do
+    Booking.new.status.should match_enum(:received)
+  end
+end
+```
 
 Of course `Booking.new.status.should === :received` still works, but is liable to produce false positives.
 
@@ -577,13 +735,13 @@ 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
-* Subsequent Updates Copyright (c) 2011 Arthur Shagall
+* Subsequent Updates Copyright (c) 2011-2012 Arthur Shagall
 
 Released under the MIT License.  See the LICENSE file for more details.
 
 ## Contributing
 
-Contributions are welcome.  However, before issuing a pull request, please make sure of the following:
+Contributions are welcome.  However, please make sure of the following before issuing a pull request:
 
 * All specs are passing.
 * Any new features have test coverage.