enumerate_it 1.2.0 → 1.2.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZGI4ZDc1NjJkOTdiODA5Zjg4Y2ExMmMzNGY2OWUzODkxZWVlNmY4Ng==
+  data.tar.gz: !binary |-
+    M2YxZjM3NjhkYzg5NTVhM2ViODQ1YjU4NzNkNjYxMzYzN2U2YjZkNA==
+SHA512:
+  metadata.gz: !binary |-
+    ZmM2MDI1OWRmNzlmNjgwMWI1YzZlMzdhNjg3NzFlOWFmODgxNTQzYzMzOGQz
+    NWQ0YWUzYTQyYzc1MDk2OGE4NDYyMWU5OTA0OTliYzUzNTY0MjFjNmFlMGZk
+    ZjMzODE0Y2VjZjYyM2NhMTM5M2ZiNjdlOTVmODM1MTAwNzUzYTM=
+  data.tar.gz: !binary |-
+    OWNkZmY1ZTc5YTU4OTdkZmM2YzViMTgxYTI5NWJjNzlkZDQ2ZDMwYmEzZDYx
+    ZTk4YzRmNjg3MTI3MjE0ZjgwNGZjMjVlZTgxNjA0OGQ0NmNjZjM2OWE4OThh
+    Mzk3ZmFhMTc3Zjk0M2EzYjBkMDVlMGUzYTU5ZDQwNGFlMzE0YzA=

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    enumerate_it (1.2.0)
+    enumerate_it (1.2.1)
       activesupport (>= 3.0.0)
 
 GEM

data/README.markdown

@@ -0,0 +1,508 @@
+# EnumerateIt - Ruby Enumerations
+
+[![Build Status](https://travis-ci.org/cassiomarques/enumerate_it.png?branch=master)](https://travis-ci.org/cassiomarques/enumerate_it)
+[![Gem Version](https://badge.fury.io/rb/enumerate_it.png)](http://badge.fury.io/rb/enumerate_it)
+
+Author: Cássio Marques - cassiommc at gmail
+
+## Description
+
+Ok, I know there are a lot of different solutions to this problem. But none of
+them solved my problem, so here's EnumerateIt. I needed to build a Rails
+application around a legacy database and this database was filled with those
+small, unchangeable tables used to create foreign key constraints everywhere.
+
+### For example:
+
+    Table "public.relationshipstatus"
+
+      Column     |     Type      | Modifiers
+    -------------+---------------+-----------
+     code        | character(1)  | not null
+     description | character(11) |
+
+    Indexes:
+      "relationshipstatus_pkey" PRIMARY KEY, btree (code)
+
+    SELECT * FROM relationshipstatus;
+
+    code   |  description
+    -------+--------------
+    1      | Single
+    2      | Married
+    3      | Widow
+    4      | Divorced
+
+And then I had things like a people table with a 'relationship_status' column
+with a foreign key pointing to the relationshipstatus table.
+
+While this is a good thing from the database normalization perspective,
+managing this values in my tests was very hard. Doing database joins just to
+get the description of some value was absurd. And, more than this, referencing
+them in my code using magic numbers was terrible and meaningless: What does it
+mean when we say that someone or something is '2'?
+
+Enter EnumerateIt.
+
+## About versions compatibility
+
+Versions 1.x.x are NOT backwards compatible with 0.x.x versions. The biggest
+difference is that on 1.0.0 you need to `extend` the EnumerateIt module inside
+classes that are going to have enumerated attributes, while in past versions
+you would use `include`.
+
+## Creating enumerations
+
+Enumerations are created as models, but you can put then anywhere in your
+application. In Rails applications, you can put them inside models/.
+
+``` ruby
+class RelationshipStatus < EnumerateIt::Base
+  associate_values(
+    :single   => [1, 'Single'],
+    :married  => [2, 'Married'],
+    :widow    => [3, 'Widow'],
+    :divorced => [4, 'Divorced']
+  )
+end
+```
+
+This will create some nice stuff:
+
+*   Each enumeration's value will turn into a constant:
+
+    ``` ruby
+    RelationshipStatus::SINGLE
+    #=> 1
+
+    RelationshipStatus::MARRIED
+    #=> 2
+    ```
+
+*   You can retrieve a list with all the enumeration codes:
+
+    ``` ruby
+    RelationshipStatus.list
+    #=> [1, 2, 3, 4]
+    ```
+
+*   You can get an array of options, ready to use with the 'select',
+    'select_tag', etc family of Rails helpers.
+
+    ``` ruby
+    RelationshipStatus.to_a
+    #=> [["Divorced", 4], ["Married", 2], ["Single", 1], ["Widow", 3]]
+    ```
+
+*   You can retrieve a list with values for a group of enumeration constants.
+
+    ``` ruby
+    RelationshipStatus.values_for %w(MARRIED SINGLE)
+    #=> [2, 1]
+    ```
+
+*   You can retrieve the value for a specific enumeration constant:
+
+    ``` ruby
+    RelationshipStatus.value_for("MARRIED")
+    #=> 2
+    ```
+
+*   You can retrieve the symbol used to declare a specific enumeration value:
+
+    ``` ruby
+    RelationshipStatus.key_for(RelationshipStatus::MARRIED)
+    #=> :married
+    ```
+
+*   You can iterate over the list of the enumeration's values:
+
+    ``` ruby
+    RelationshipStatus.each_value { |value| ... }
+    ```
+
+*   You can iterate over the list of the enumeration's translations:
+
+    ``` ruby
+    RelationshipStatus.each_translation { |translation| ... }
+    ```
+
+*   You can ask for the enumeration's length:
+
+    ``` ruby
+    RelationshipStatus.length
+    #=> 4
+    ```
+
+*   You can manipulate the hash used to create the enumeration:
+
+    ``` ruby
+    RelationshipStatus.enumeration
+    #=> returns the exact hash used to define the enumeration
+    ```
+
+
+You can also create enumerations in the following ways:
+
+*   Passing an array of symbols, so that the respective value for each symbol
+    will be the stringified version of the symbol itself:
+
+    ``` ruby
+    class RelationshipStatus < EnumerateIt::Base
+      associate_values :married, :single
+    end
+
+    RelationshipStatus::MARRIED
+    #=> "married"
+    ```
+
+*   Passing hashes where the value for each key/pair does not include a
+    translation. In this case, the I18n feature will be used (more on this
+    below):
+
+    ``` ruby
+    class RelationshipStatus < EnumerateIt::Base
+      associate_values :married => 1, :single => 2
+    end
+    ```
+
+
+### Defining a default sort mode
+
+When calling methods like `to_a` and `to_json`, the returned values will be
+sorted using the translation for each one of the enumeration values. If you
+want to overwrite the default sort mode, you can use the `sort_by` class
+method.
+
+``` ruby
+class RelationshipStatus < EnumerateIt::Base
+  associate_values :married => 1, :single => 2
+
+  sort_by :value
+end
+```
+
+The `sort_by` methods accept one of the following values:
+
+*   `:translation`: The default behavior, will sort the returned values based
+    on translations.
+*   `:value`: Will sort the returned values based on values.
+*   `:name`: Will sort the returned values based on the name of each
+    enumeration option.
+*   `:none`: Will return values in order that was passed to associate_values
+    call.
+
+
+## Using enumerations
+
+The cool part is that you can use these enumerations with any class, be it an
+ActiveRecord instance or not.
+
+``` ruby
+class Person
+  extend EnumerateIt
+  attr_accessor :relationship_status
+
+  has_enumeration_for :relationship_status, :with => RelationshipStatus
+end
+```
+
+The :with option is not required. If you ommit it, EnumerateIt will try to
+load an enumeration class based on the camelized attribute name.
+
+This will create:
+
+*   A humanized description for the values of the enumerated attribute:
+
+    ``` ruby
+    p = Person.new
+    p.relationship_status = RelationshipStatus::DIVORCED
+    p.relationship_status_humanize
+    #=> 'Divorced'
+    ```
+
+*   If you don't supply a humanized string to represent an option, EnumerateIt
+    will use a 'humanized' version of the hash's key to humanize the
+    attribute's value:
+
+    ``` ruby
+    class RelationshipStatus < EnumerateIt::Base
+      associate_values(
+        :married => 1,
+        :single => 2
+      )
+    end
+
+    p = Person.new
+    p.relationship_status = RelationshipStatus::MARRIED
+    p.relationship_status_humanize
+    #=> 'Married'
+    ```
+
+*   The associated enumerations can be retrieved with the 'enumerations' class
+    method.
+
+    ``` ruby
+    Person.enumerations[:relationship_status]
+    #=> RelationshipStatus
+    ```
+
+*   If you pass the :create_helpers option as 'true', it will create a helper
+    method for each enumeration option (this option defaults to false):
+
+    ``` ruby
+    class Person < ActiveRecord::Base
+      has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => true
+    end
+
+    p = Person.new
+    p.relationship_status = RelationshipStatus::MARRIED
+
+    p.married?
+    #=> true
+
+    p.divorced?
+    #=> false
+    ```
+
+*   It's also possible to "namespace" the created helper methods, passing a
+    hash to the :create_helpers option. This can be useful when two or more of
+    the enumerations used share the same constants.
+
+    ``` ruby
+    class Person < ActiveRecord::Base
+      has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :prefix => true }
+    end
+
+    p = Person.new
+    p.relationship_status = RelationshipStatus::MARRIED
+
+    p.relationship_status_married?
+    #=> true
+
+    p.relationship_status_divoced?
+    #=> false
+    ```
+
+*   You can define polymorphic behavior for the enum values, so you can define
+    a class for each of them:
+
+    ``` ruby
+    class RelationshipStatus < EnumerateIt::Base
+      associate_values :married, :single
+
+      class Married
+        def saturday_night
+          "At home with the kids"
+        end
+      end
+
+      class Single
+        def saturday_night
+          "Party Hard!"
+        end
+      end
+    end
+
+    class Person < ActiveRecord::Base
+      has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :polymorphic => true }
+    end
+
+    p = Person.new
+    p.relationship_status = RelationshipStatus::MARRIED
+    p.relationship_status_object.saturday_night
+    #=> "At home with the kids"
+
+    p.relationship_status = RelationshipStatus::SINGLE
+    p.relationship_status_object.saturday_night
+    #=> "Party Hard!"
+    ```
+
+    You can also change the suffix '_object', using the :suffix option:
+
+    ``` ruby
+    class Person < ActiveRecord::Base
+      has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :polymorphic => { :suffix => "_mode" } }
+    end
+
+    p.relationship_status_mode.saturday_night
+    ```
+
+*   The :create_helpers also creates some mutator helper methods, that can be
+    used to change the attribute's value.
+
+    ``` ruby
+    class Person < ActiveRecord::Base
+      has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => true
+    end
+
+    p = Person.new
+    p.married!
+
+    p.married?
+    #=> true
+
+    p.divorced?
+    #=> false
+    ```
+
+*   If you pass the :create_scopes option as 'true', it will create a scope
+    method for each enumeration option (this option defaults to false):
+
+    ``` ruby
+    class Person < ActiveRecord::Base
+      has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_scopes => true
+    end
+
+    Person.married.to_sql
+    #=> SELECT "people".* FROM "people" WHERE "people"."relationship_status" = 1
+    ```
+
+
+NOTE: The :create_scopes option can only be used for Rails.version >= 3.0.0.
+
+*   If your class can manage validations and responds to
+    :validates_inclusion_of, it will create this validation:
+
+    ``` ruby
+    class Person < ActiveRecord::Base
+      has_enumeration_for :relationship_status, :with => RelationshipStatus
+    end
+
+    p = Person.new(:relationship_status => 6) # there is no '6' value in the enumeration
+    p.valid?
+    #=> false
+    p.errors[:relationship_status]
+    #=> "is not included in the list"
+    ```
+
+*   If your class can manage validations and responds to
+    :validates_presence_of, you can pass the :required options as true and
+    this validation will be created for you (this option defaults to false):
+
+    ``` ruby
+    class Person < ActiveRecord::Base
+      has_enumeration_for :relationship_status, :required => true
+    end
+
+    p = Person.new :relationship_status => nil
+    p.valid?
+    #=> false
+    p.errors[:relationship_status]
+    #=> "can't be blank"
+    ```
+
+
+Remember that in Rails 3 you can add validations to any kind of class and not
+only to those derived from ActiveRecord::Base.
+
+## I18n
+
+I18n lookup is provided on both '_humanized' and 'Enumeration#to_a' methods,
+given the hash key is a Symbol. The I18n strings are located on
+enumerations.'enumeration_name'.'key' :
+
+``` yaml
+# your locale file
+pt:
+  enumerations:
+    relationship_status:
+      married: Casado
+```
+
+``` ruby
+class RelationshipStatus < EnumerateIt::Base
+  associate_values(
+    :married => 1,
+    :single => 2,
+    :divorced => [3, "He's divorced"]
+  )
+end
+
+p = Person.new
+p.relationship_status = RelationshipStatus::MARRIED
+p.relationship_status_humanize
+#=> 'Casado'
+
+p.relationship_status = RelationshipStatus::SINGLE
+p.relationship_status_humanize # nonexistent key
+#=> 'Single'
+
+p.relationship_status = RelationshipStatus::DIVORCED
+p.relationship_status_humanize # uses the provided string
+#=> 'He's divorced'
+```
+
+You can also translate specific values:
+
+``` ruby
+RelationshipStatus.t(1)
+#=> 'Casado'
+```
+
+## Installation
+
+``` bash
+gem install enumerate_it
+```
+
+## Using with Rails
+
+*   Add the gem to your Gemfile:
+
+    ``` ruby
+    gem "enumerate_it"
+    ```
+
+*   Run the install generator:
+
+    ``` bash
+    rails generate enumerate_it:install
+    ```
+
+
+An interesting approach to use it in Rails apps is to create an
+app/enumerations folder and add it to your autoload path in
+config/application.rb:
+
+``` ruby
+module YourApp
+  class Application < Rails::Application
+    config.autoload_paths << "#{Rails.root}/app/enumerations"
+  end
+end
+```
+
+There is also a Rails Generator that you can use to generate enumerations and
+their locale files. Take a look at how to use it running
+
+``` bash
+rails generate enumerate_it:enum --help
+```
+
+## Why did you reinvent the wheel?
+
+There are other similar solutions to the problem out there, but I could not
+find one that worked both with strings and integers as the enumerations'
+codes. I had both situations in my legacy database.
+
+## Why defining enumerations outside the class that use it?
+
+*   I think it's cleaner.
+*   You can add behaviour to the enumeration class.
+*   You can reuse the enumeration inside other classes.
+
+## Note on Patches/Pull Requests
+
+*   Fork the project.
+*   Make your feature addition or bug fix.
+*   Add tests for it. This is important so I don't break it in a future
+    version unintentionally.
+*   Commit, do not mess with rakefile, version, or history. (if you want to
+    have your own version, that is fine but bump version in a commit by itself
+    I can ignore when I pull)
+*   Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Cássio Marques. See LICENSE for details.

data/lib/enumerate_it/version.rb

@@ -1,3 +1,3 @@
 module EnumerateIt
-  VERSION = "1.2.0"
+  VERSION = "1.2.1"
 end

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: enumerate_it
 version: !ruby/object:Gem::Version
-  version: 1.2.0
-  prerelease: 
+  version: 1.2.1
 platform: ruby
 authors:
 - Cássio Marques
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-16 00:00:00.000000000 Z
+date: 2014-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -30,7 +27,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -38,7 +34,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -46,7 +41,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -54,7 +48,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -62,7 +55,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -70,7 +62,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -78,7 +69,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -86,7 +76,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -94,7 +83,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: pry-nav
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -102,15 +90,11 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Have a legacy database and need some enumerations in your models to match
-  those stupid '4 rows/2 columns' tables with foreign keys and stop doing joins just
-  to fetch a simple description? Or maybe use some integers instead of strings as
-  the code for each value of your enumerations? Here's EnumerateIt.
+description: Enumerations for Ruby with some magic powers!
 email:
 - cassiommc@gmail.com
 executables: []
@@ -123,7 +107,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README.rdoc
+- README.markdown
 - Rakefile
 - enumerate_it.gemspec
 - lib/enumerate_it.rb
@@ -146,33 +130,26 @@ files:
 - spec/support/test_classes.rb
 homepage: http://github.com/cassiomarques/enumerate_it
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 1153526174871300187
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 1153526174871300187
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.1.4
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Ruby Enumerations
 test_files:
 - spec/enumerate_it/base_spec.rb

data/README.rdoc

@@ -1,366 +0,0 @@
-= EnumerateIt - Ruby Enumerations
-
-{<img src="https://secure.travis-ci.org/cassiomarques/enumerate_it.png?branch=master" alt="Build Status" />}[http://travis-ci.org/cassiomarques/enumerate_it]
-
-Author: Cássio Marques - cassiommc at gmail
-
-== Description
-
-Ok, I know there are a lot of different solutions to this problem. But none of them solved my problem,
-so here's EnumerateIt. I needed to build a Rails application around a legacy database and this database was
-filled with those small, unchangeable tables used to create foreign key constraints everywhere.
-
-=== For example:
-
-   Table "public.relationshipstatus"
-  Column     |     Type      | Modifiers
-  -------------+---------------+-----------
-   code        | character(1)  | not null
-   description | character(11) |
-  Indexes:
-    "relationshipstatus_pkey" PRIMARY KEY, btree (code)
-
-  select * from relationshipstatus;
-  code   |  description
-  -------+--------------
-  1      | Single
-  2      | Married
-  3      | Widow
-  4      | Divorced
-
-
-And then I had things like a people table with a 'relationship_status' column with a foreign key
-pointing to the relationshipstatus table.
-
-While this is a good thing from the database normalization perspective, managing this values in
-my tests was very hard. Doing database joins just to get the description of some value was absurd.
-And, more than this, referencing them in my code using magic numbers was terrible and meaningless:
-What does it mean when we say that someone or something is '2'?
-
-Enter EnumerateIt.
-
-== About versions compatibility
-
-Versions 1.x.x are NOT backwards compatible with 0.x.x versions. The biggest difference is that on 1.0.0 you need to `extend` the EnumerateIt
-module inside classes that are going to have enumerated attributes, while in past versions you would use `include`.
-
-== Creating enumerations
-
-Enumerations are created as models, but you can put then anywhere in your application. In Rails
-applications, you can put them inside models/.
-
-   class RelationshipStatus < EnumerateIt::Base
-     associate_values(
-       :single   => [1, 'Single'],
-       :married  => [2, 'Married'],
-       :widow    => [3, 'Widow'],
-       :divorced => [4, 'Divorced']
-     )
-   end
-
-This will create some nice stuff:
-
-* Each enumeration's value will turn into a constant:
-
-   RelationshipStatus::SINGLE # returns 1
-   RelationshipStatus::MARRIED # returns 2 and so on...
-
-* You can retrieve a list with all the enumeration codes:
-
-   RelationshipStatus.list # [1,2,3,4]
-
-* You can get an array of options, ready to use with the 'select', 'select_tag', etc family of Rails helpers.
-
-   RelationshipStatus.to_a # [["Divorced", 4],["Married", 2],["Single", 1],["Widow", 3]]
-
-* You can retrieve a list with values for a group of enumeration constants.
-
-   RelationshipStatus.values_for %w(MARRIED SINGLE) # [2, 1]
-
-* You can retrieve the value for a specific enumeration constant:
-
-   RelationshipStatus.value_for("MARRIED") # 2
-
-* You can retrieve the symbol used to declare a specific enumeration value:
-
-   RelationshipStatus.key_for(RelationshipStatus::MARRIED) # :married
-
-* You can iterate over the list of the enumeration's values:
-
-   RelationshipStatus.each_value { |value| # ... }
-
-* You can iterate over the list of the enumeration's translations:
-
-   RelationshipStatus.each_translation { |translation| # ... }
-
-* You can ask for the enumeration's length:
-
-   RelationshipStatus.length # 4
-
-* You can manipulate the hash used to create the enumeration:
-
-   RelationshipStatus.enumeration # returns the exact hash used to define the enumeration
-
-You can also create enumerations in the following ways:
-
-* Passing an array of symbols, so that the respective value for each symbol will be the stringified version of the symbol itself:
-
-   class RelationshipStatus < EnumerateIt::Base
-     associate_values :married, :single
-   end
-
-   RelationshipStatus::MARRIED # returns "married" and so on
-
-* Passing hashes where the value for each key/pair does not include a translation. In this case, the I18n feature will be used (more on this below):
-
-   class RelationshipStatus < EnumerateIt::Base
-     associate_values :married => 1, :single => 2
-   end
-
-=== Defining a default sort mode
-
-When calling methods like `to_a` and `to_json`, the returned values will be sorted using the translation for each one of the enumeration values. If you want
-to overwrite the default sort mode, you can use the `sort_mode` class method.
-
-    class RelationshipStatus < EnumerateIt::Base
-      associate_values :married => 1, :single => 2
-
-      sort_by :value
-    end
-
-The `sort_by` methods accept one of the following values:
-
-* `:translation`: The default behavior, will sort the returned values based on translations.
-* `:value`: Will sort the returned values based on values.
-* `:name`: Will sort the returned values based on the name of each enumeration option.
-* `:none`: Will return values in order that was passed to associate_values call.
-
-== Using enumerations
-
-The cool part is that you can use these enumerations with any class, be it an ActiveRecord instance
-or not.
-
-   class Person
-     extend EnumerateIt
-     attr_accessor :relationship_status
-
-     has_enumeration_for :relationship_status, :with => RelationshipStatus
-   end
-
-The :with option is not required. If you ommit it, EnumerateIt will try to load an enumeration class based on the camelized attribute name.
-
-This will create:
-
-* A humanized description for the values of the enumerated attribute:
-
-   p = Person.new
-   p.relationship_status = RelationshipStatus::DIVORCED
-   p.relationship_status_humanize # => 'Divorced'
-
-* If you don't supply a humanized string to represent an option, EnumerateIt will use a 'humanized' version of the hash's key to humanize the attribute's value:
-
-   class RelationshipStatus < EnumerateIt::Base
-     associate_values(
-       :married => 1,
-       :single => 2
-     )
-   end
-
-   p = Person.new
-   p.relationship_status = RelationshipStatus::MARRIED
-   p.relationship_status_humanize # => 'Married'
-
-* The associated enumerations can be retrieved with the 'enumerations' class method.
-
-   Person.enumerations[:relationship_status] # => RelationshipStatus
-
-* If you pass the :create_helpers option as 'true', it will create a helper method for each enumeration option (this option defaults to false):
-
-   class Person < ActiveRecord::Base
-     has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => true
-   end
-
-   p = Person.new
-   p.relationship_status = RelationshipStatus::MARRIED
-   p.married? #=> true
-   p.divorced? #=> false
-
-* It's also possible to "namespace" the created helper methods, passing a hash to the :create_helpers option.
-  This can be useful when two or more of the enumerations used share the same constants.
-
-  class Person < ActiveRecord::Base
-    has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :prefix => true }
-  end
-
-  p = Person.new
-  p.relationship_status = RelationshipStatus::MARRIED
-  p.relationship_status_married? #=> true
-  p.relationship_status_divoced? #=> false
-
-* You can define polymorphic behavior for the enum values, so you can define a class for each of
- them:
-
-  class RelationshipStatus < EnumerateIt::Base
-    associate_values :married, :single
-
-    class Married
-      def saturday_night
-        "At home with the kids"
-      end
-    end
-
-    class Single
-      def saturday_night
-        "Party Hard!"
-      end
-    end
-  end
-
-  class Person < ActiveRecord::Base
-    has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :polymorphic => true }
-  end
-
-  p = Person.new
-  p.relationship_status = RelationshipStatus::MARRIED
-  p.relationship_status_object.saturday_night # => "At home with the kids"
-
-  p.relationship_status = RelationshipStatus::SINGLE
-  p.relationship_status_object.saturday_night # => "Party Hard!"
-
-  You can also change the suffix '_object', using the :suffix option:
-
-  class Person < ActiveRecord::Base
-    has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :polymorphic => { :suffix => "_mode" } }
-  end
-
-  p.relationship_status_mode.saturday_night
-
-* The :create_helpers also creates some mutator helper methods, that can be used to change the attribute's value.
-
-   class Person < ActiveRecord::Base
-     has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => true
-   end
-
-   p = Person.new
-   p.married!
-   p.married? #=> true
-   p.divorced? #=> false
-
-* If you pass the :create_scopes option as 'true', it will create a scope method for each enumeration option (this option defaults to false):
-
-   class Person < ActiveRecord::Base
-     has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_scopes => true
-   end
-
-   Person.married.to_sql # => SELECT "people".* FROM "people" WHERE "people"."relationship_status" = 1
-
-NOTE: The :create_scopes option can only be used for Rails.version >= 3.0.0.
-
-* If your class can manage validations and responds to :validates_inclusion_of, it will create this validation:
-
-   class Person < ActiveRecord::Base
-     has_enumeration_for :relationship_status, :with => RelationshipStatus
-   end
-
-   p = Person.new :relationship_status => 6 # => there is no '6' value in the enumeration
-   p.valid? # => false
-   p.errors[:relationship_status] # => "is not included in the list"
-
-* If your class can manage validations and responds to :validates_presence_of, you can pass the :required options as true and this validation will be created for you (this option defaults to false):
-
-   class Person < ActiveRecord::Base
-     has_enumeration_for :relationship_status, :required => true
-   end
-
-   p = Person.new :relationship_status => nil
-   p.valid? # => false
-   p.errors[:relationship_status] # => "can't be blank"
-
-
-Remember that in Rails 3 you can add validations to any kind of class and not only to those derived from
-ActiveRecord::Base.
-
-== I18n
-
-I18n lookup is provided on both '_humanized' and 'Enumeration#to_a' methods, given the hash key is a Symbol. The I18n strings are
-located on enumerations.'enumeration_name'.'key' :
-
-  class RelationshipStatus < EnumerateIt::Base
-   associate_values(
-     :married => 1,
-     :single => 2,
-     :divorced => [3, 'He's divorced']
-   )
-  end
-
-  # your locale file
-  pt:
-    enumerations:
-      relationship_status:
-        married: Casado
-
-  p = Person.new
-  p.relationship_status = RelationshipStatus::MARRIED
-  p.relationship_status_humanize # => 'Casado'
-
-  p.relationship_status = RelationshipStatus::SINGLE
-  p.relationship_status_humanize # => 'Single' => nonexistent key
-
-  p.relationship_status = RelationshipStatus::DIVORCED
-  p.relationship_status_humanize # => 'He's divorced' => uses the provided string
-
-You can also translate specific values:
-
-  RelationshipStatus.t(1) # => 'Casado'
-
-== Installation
-
-  gem install enumerate_it
-
-== Using with Rails
-
-* Add the gem to your Gemfile:
-
-  gem "enumerate_it"
-
-* Run the install generator:
-
-  rails g enumerate_it:install
-
-An interesting approach to use it in Rails apps is to create an app/enumerations folder and add it to your autoload path in config/application.rb:
-
-  module YourApp
-    class Application < Rails::Application
-      config.autoload_paths << "#{Rails.root}/app/enumerations"
-    end
-  end
-
-There is also a Rails Generator that you can use to generate enumerations and their locale files. Take a look at how to use it running
-
-  rails generate enumerate_it:enum --help
-
-== Why did you reinvent the wheel?
-
-There are other similar solutions to the problem out there, but I could not find one that
-worked both with strings and integers as the enumerations' codes. I had both situations in
-my legacy database.
-
-== Why defining enumerations outside the class that use it?
-
-* I think it's cleaner.
-* You can add behaviour to the enumeration class.
-* You can reuse the enumeration inside other classes.
-
-== Note on Patches/Pull Requests
-
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2010 Cássio Marques. See LICENSE for details.