enumerate_it 1.3.1 → 1.4.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f38356eaa7e97dd863aebe8a0a5b05043176bbd7
-  data.tar.gz: e409af191da4875f1649eea4dabc0f1f25e360cd
+  metadata.gz: 75cf6c3f112a2575798bcf189871687e81a46e19
+  data.tar.gz: 31c1f6b460883f3b152c73730e0fed10c9c037e3
 SHA512:
-  metadata.gz: 17644e925e069bf0488a0bb2d146eb104eca4aa7fa7a57e2c6d7f5131dee68ab4b80095cad6e45ce58a8ea7f77b02c4613c3ecb2e3ec8c5b3ce7e20a81be89fe
-  data.tar.gz: 5abb6fb31ad4360d37e3545029c2b2e889c5d97fa0f2a35625b29e9595be0b0b91cfa2e27dcd69709ab91b9577a4661348dd97ea589cab3e337b0508b3924adb
+  metadata.gz: b6c4da4b694618f9eedc01f3234469df4d8192beaa431adac5f7e0f0168858e3a6f311f470b10e0b45cc6dcbdbb9662f164cb4193277e9856c9115d2c1dacb75
+  data.tar.gz: 5bfe4f685fc279a834b23946aa25f1aff2435f0dfe3357bf3b4af213c87a02e31de98e81dcd1a362ca21c5cf0f22a88309338a98a00848166844657a81265e66

data/.rubocop.yml

@@ -38,3 +38,15 @@ Style/MultilineMethodCallIndentation:
 Style/PredicateName:
   Exclude:
     - 'lib/enumerate_it/class_methods.rb'
+
+Style/GuardClause:
+  MinBodyLength: 3
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/MessageExpectation:
+  Enabled: false

data/.travis.yml

@@ -33,3 +33,7 @@ matrix:
     gemfile: gemfiles/rails_5.0.gemfile
   - rvm: 2.1.10
     gemfile: gemfiles/rails_5.0.gemfile
+
+addons:
+  code_climate:
+    repo_token: 60e4a18e2a4bc86a98f92847f16756876c13d1e772058a9b3296643b04a697d7

data/Gemfile

@@ -1,4 +1,4 @@
-source 'http://rubygems.org'
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in enumerate_it.gemspec
 gemspec

data/Gemfile.lock

@@ -1,11 +1,11 @@
 PATH
   remote: .
   specs:
-    enumerate_it (1.3.1)
+    enumerate_it (1.4.0.rc1)
       activesupport (>= 3.0.0)
 
 GEM
-  remote: http://rubygems.org/
+  remote: https://rubygems.org/
   specs:
     activesupport (5.0.0.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
@@ -22,8 +22,8 @@ GEM
     diff-lcs (1.2.5)
     i18n (0.7.0)
     method_source (0.8.2)
-    minitest (5.9.0)
-    parser (2.3.1.2)
+    minitest (5.9.1)
+    parser (2.3.1.4)
       ast (~> 2.2)
     powerpack (0.1.1)
     pry (0.10.4)
@@ -31,12 +31,12 @@ GEM
       method_source (~> 0.8.1)
       slop (~> 3.4)
     rainbow (2.1.0)
-    rake (11.2.2)
+    rake (11.3.0)
     rspec (3.5.0)
       rspec-core (~> 3.5.0)
       rspec-expectations (~> 3.5.0)
       rspec-mocks (~> 3.5.0)
-    rspec-core (3.5.2)
+    rspec-core (3.5.4)
       rspec-support (~> 3.5.0)
     rspec-expectations (3.5.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -45,13 +45,13 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.5.0)
     rspec-support (3.5.0)
-    rubocop (0.42.0)
+    rubocop (0.44.1)
       parser (>= 2.3.1.1, < 3.0)
       powerpack (~> 0.1)
       rainbow (>= 1.99.1, < 3.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
-    rubocop-rspec (1.6.0)
+    rubocop-rspec (1.7.0)
       rubocop (>= 0.42.0)
     ruby-progressbar (1.8.1)
     slop (3.6.0)
@@ -59,7 +59,7 @@ GEM
     thread_safe (0.3.5)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
-    unicode-display_width (1.1.0)
+    unicode-display_width (1.1.1)
 
 PLATFORMS
   ruby
@@ -75,4 +75,4 @@ DEPENDENCIES
   rubocop-rspec
 
 BUNDLED WITH
-   1.12.5
+   1.13.2

data/README.md

@@ -1,429 +1,401 @@
-# EnumerateIt - Ruby Enumerations
+![EnumerateIt Logo](https://raw.github.com/lucascaton/enumerate_it/master/enumerate_it.png)
+
+Ruby Enumerations
 
 [![Build Status](https://travis-ci.org/lucascaton/enumerate_it.svg?branch=master)](https://travis-ci.org/lucascaton/enumerate_it)
 [![Gem Version](https://badge.fury.io/rb/enumerate_it.svg)](https://rubygems.org/gems/enumerate_it)
+[![Code Climate](https://codeclimate.com/github/lucascaton/enumerate_it/badges/gpa.svg)](https://codeclimate.com/github/lucascaton/enumerate_it)
+[![Changelog](https://img.shields.io/badge/changelog--brightgreen.svg?style=flat)](https://github.com/lucascaton/enumerate_it/releases)
 
-* **Author:** Cássio Marques
-* **Maintainer:** Lucas Caton
+**EnumerateIt** helps you to declare and use enumerations in a very simple and flexible way.
 
-## Description
+### Why would I want a gem if Rails already has native enumerations support?
 
-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.
+Firstly, **EnumerateIt** works amazingly well along with **Rails** but it is not required!
+It means you can add it to any **Ruby** project! 😀
 
-### For example:
+Secondly, Rails' enumerations has a problem:
+[`ActiveRecord::Enum`](http://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html) uses
+`integers` instead of `strings`, which means that if you change your enumeration list oder in your
+model, your database will no longer be consistent.
+Database storage pricing is not a problem nowadays, so it's recommended to use `strings` columns.
 
-    Table "public.relationshipstatus"
+- [Installation](#installation)
+- [Using with Rails](#using-with-rails)
+- [Creating enumerations](#creating-enumerations)
+  - [Sorting enumerations](#sorting-enumerations)
+- [Using enumerations](#using-enumerations)
+- [I18n](#i18n)
+- [Using enumerations to handle a legacy database](#using-enumerations-to-handle-a-legacy-database)
+- [FAQ](#faq)
+- [Changelog](#changelog)
 
-      Column     |     Type      | Modifiers
-    -------------+---------------+-----------
-     code        | character(1)  | not null
-     description | character(11) |
+## Installation
 
-    Indexes:
-      "relationshipstatus_pkey" PRIMARY KEY, btree (code)
+```bash
+gem install enumerate_it
+```
 
-    SELECT * FROM relationshipstatus;
+## Using with Rails
 
-    code   |  description
-    -------+--------------
-    1      | Single
-    2      | Married
-    3      | Widow
-    4      | Divorced
+Add the gem to your Gemfile:
 
-And then I had things like a people table with a 'relationship_status' column
-with a foreign key pointing to the relationshipstatus table.
+```ruby
+gem 'enumerate_it'
+```
 
-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'?
+Run the install generator:
 
-Enter EnumerateIt.
+```bash
+rails generate enumerate_it:install
+```
 
-## Changelog
+There is also a Rails Generator which generates enumerations and their locale files:
 
-Changes are maintained under [Releases](https://github.com/lucascaton/enumerate_it/releases).
+```bash
+rails generate enumerate_it:enum --help
+```
 
 ## Creating enumerations
 
 Enumerations are created as classes and you should put them inside `app/enumerations` folder.
 
+You can pass 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(
-    single:   [1, 'Single'],
-    married:  [2, 'Married'],
-    widow:    [3, 'Widow'],
-    divorced: [4, 'Divorced']
+    :single,
+    :married,
+    :divorced
   )
 end
 ```
 
 This will create some nice stuff:
 
-*   Each enumeration's value will turn into a constant:
+* Each enumeration's value will turn into a constant:
 
-    ```ruby
-    RelationshipStatus::SINGLE
-    #=> 1
+  ```ruby
+  RelationshipStatus::SINGLE
+  # => 'single'
 
-    RelationshipStatus::MARRIED
-    #=> 2
-    ```
+  RelationshipStatus::MARRIED
+  #=> 'married'
+  ```
 
-*   You can retrieve a list with all the enumeration codes:
+* You can retrieve a list with all the enumeration codes:
 
-    ```ruby
-    RelationshipStatus.list
-    #=> [1, 2, 3, 4]
-    ```
+  ```ruby
+  RelationshipStatus.list
+  #=> ['divorced', 'married', 'single']
+  ```
 
-*   You can get an array of options, ready to use with the 'select',
-    'select_tag', etc family of Rails helpers.
+* You can retrieve a JSON with all the enumeration codes:
 
-    ```ruby
-    RelationshipStatus.to_a
-    #=> [["Divorced", 4], ["Married", 2], ["Single", 1], ["Widow", 3]]
-    ```
+  ```ruby
+  RelationshipStatus.to_json
+  #=> "[{\"value\":\"divorced\",\"label\":\"Divorced\"},{\"value\":\"married\", ...
+  ```
 
-*   You can retrieve a list with values for a group of enumeration constants.
+* You can get an array of options, ready to use with the 'select',
+  'select_tag', etc family of Rails helpers.
 
-    ```ruby
-    RelationshipStatus.values_for %w(MARRIED SINGLE)
-    #=> [2, 1]
-    ```
+  ```ruby
+  RelationshipStatus.to_a
+  #=> [['Divorced', 'divorced'], ['Married', 'married'], ['Single', 'single']]
+  ```
 
-*   You can retrieve the value for a specific enumeration constant:
+* You can retrieve a list with values for a group of enumeration constants.
 
-    ```ruby
-    RelationshipStatus.value_for("MARRIED")
-    #=> 2
-    ```
+  ```ruby
+  RelationshipStatus.values_for %w(MARRIED SINGLE)
+  #=> ['married', 'single']
+  ```
 
-*   You can retrieve the symbol used to declare a specific enumeration value:
+* You can retrieve the value for a specific enumeration constant:
 
-    ```ruby
-    RelationshipStatus.key_for(RelationshipStatus::MARRIED)
-    #=> :married
-    ```
+  ```ruby
+  RelationshipStatus.value_for('MARRIED')
+  #=> 'married'
+  ```
 
-*   You can iterate over the list of the enumeration's values:
+* You can retrieve the symbol used to declare a specific enumeration value:
 
-    ```ruby
-    RelationshipStatus.each_value { |value| ... }
-    ```
+  ```ruby
+  RelationshipStatus.key_for(RelationshipStatus::MARRIED)
+  #=> :married
+  ```
 
-*   You can iterate over the list of the enumeration's translations:
+* You can iterate over the list of the enumeration's values:
 
-    ```ruby
-    RelationshipStatus.each_translation { |translation| ... }
-    ```
+  ```ruby
+  RelationshipStatus.each_value { |value| ... }
+  ```
 
-*   You can also retrieve all the translations of the enumeration:
+* You can iterate over the list of the enumeration's translations:
 
-    ```ruby
-    RelationshipStatus.translations
-    ```
+  ```ruby
+  RelationshipStatus.each_translation { |translation| ... }
+  ```
 
-*   You can ask for the enumeration's length:
+* You can also retrieve all the translations of the enumeration:
 
-    ```ruby
-    RelationshipStatus.length
-    #=> 4
-    ```
+  ```ruby
+  RelationshipStatus.translations
+  ```
 
-*   You can manipulate the hash used to create the enumeration:
+* You can ask for the enumeration's length:
 
-    ```ruby
-    RelationshipStatus.enumeration
-    #=> returns the exact hash used to define the enumeration
-    ```
+  ```ruby
+  RelationshipStatus.length
+  #=> 3
+  ```
 
-You can also create enumerations in the following ways:
+### Sorting enumerations
 
-*   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`, `to_json` and `list`, 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.
+When calling methods like `to_a`, `to_json` and `list`, 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
+  sort_by :translation
 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.
+| Value          | Behavior                                                                                     |
+| :------------- | :------------------------------------------------------------------------------------------- |
+| `:none`        | The default behavior, will return values in order that was passed to `associate_values` call |
+| `:translation` | will sort the returned values based on translations                                          |
+| `:name`        | Will sort the returned values based on the name of each enumeration option                   |
 
 ## Using enumerations
 
-The cool part is that you can use these enumerations with any class, be it an
-ActiveRecord instance or not.
+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
+  has_enumeration_for :relationship_status
 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.
+> **Note:** **EnumerateIt** will try to load an enumeration class based on the camelized attribute
+> name. If you have a different name, you can specify it by using the `with` option:
+>
+> `has_enumeration_for :relationship_status, with: RelationshipStatus`
 
 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
+* A "humanized" version of the hash's key to humanize the attribute's value:
 
-    p = Person.new
-    p.relationship_status = RelationshipStatus::MARRIED
-    p.relationship_status_humanize
-    #=> 'Married'
-    ```
+  ```ruby
+  p = Person.new
+  p.relationship_status = RelationshipStatus::DIVORCED
+  p.relationship_status_humanize
+  #=> 'Divorced'
+  ```
 
-*   The associated enumerations can be retrieved with the 'enumerations' class
-    method.
+* A translation for your options, if you include a locale to represent it
+  (see more in the [#i18n](I18n section):
 
-    ```ruby
-    Person.enumerations[:relationship_status]
-    #=> RelationshipStatus
-    ```
+  ```ruby
+  p = Person.new
+  p.relationship_status = RelationshipStatus::DIVORCED
+  p.relationship_status_humanize
+  #=> 'Divorciado'
+  ```
 
-*   If you pass the `:create_helpers` option as `true`, it will create a helper
-    method for each enumeration option (this option defaults to false):
+* The associated enumerations, which can be retrieved with the `enumerations` class method:
 
-    ```ruby
-    class Person < ActiveRecord::Base
-      has_enumeration_for :relationship_status, with: RelationshipStatus, create_helpers: true
-    end
+  ```ruby
+  Person.enumerations
+  #=> { relationship_status: RelationshipStatus }
+  ```
 
-    p = Person.new
-    p.relationship_status = RelationshipStatus::MARRIED
+* A helper method for each enumeration option, if you pass the `create_helpers` option as `true`:
 
-    p.married?
-    #=> true
+  ```ruby
+  class Person < ActiveRecord::Base
+    has_enumeration_for :relationship_status, with: RelationshipStatus, create_helpers: true
+  end
 
-    p.divorced?
-    #=> false
-    ```
+  p = Person.new
+  p.relationship_status = RelationshipStatus::MARRIED
 
-*   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.
+  p.married?
+  #=> true
 
-    ```ruby
-    class Person < ActiveRecord::Base
-      has_enumeration_for :relationship_status, with: RelationshipStatus,
-                                                create_helpers: { prefix: true }
-    end
+  p.divorced?
+  #=> false
+  ```
 
-    p = Person.new
-    p.relationship_status = RelationshipStatus::MARRIED
+  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:
 
-    p.relationship_status_married?
-    #=> true
+  ```ruby
+  class Person < ActiveRecord::Base
+    has_enumeration_for :relationship_status,
+      with: RelationshipStatus, create_helpers: { prefix: true }
+  end
 
-    p.relationship_status_divoced?
-    #=> false
-    ```
+  p = Person.new
+  p.relationship_status = RelationshipStatus::MARRIED
 
-*   You can define polymorphic behavior for the enum values, so you can define
-    a class for each of them:
+  p.relationship_status_married?
+  #=> true
 
-    ```ruby
-    class RelationshipStatus < EnumerateIt::Base
-      associate_values :married, :single
+  p.relationship_status_divoced?
+  #=> false
+  ```
 
-      class Married
-        def saturday_night
-          "At home with the kids"
-        end
-      end
+  You can define polymorphic behavior for the enumeration values, so you can define a class for each
+  of them:
 
-      class Single
-        def saturday_night
-          "Party Hard!"
-        end
+  ```ruby
+  class RelationshipStatus < EnumerateIt::Base
+    associate_values :married, :single
+
+    class Married
+      def saturday_night
+        'At home with the kids'
       end
     end
 
-    class Person < ActiveRecord::Base
-      has_enumeration_for :relationship_status, with: RelationshipStatus,
-                                                create_helpers: { polymorphic: true }
+    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 = 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!"
-    ```
+  p.relationship_status = RelationshipStatus::SINGLE
+  p.relationship_status_object.saturday_night
+  #=> 'Party Hard!'
+  ```
 
-    You can also change the suffix '_object', using the `:suffix` option:
+  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
+  ```ruby
+  class Person < ActiveRecord::Base
+    has_enumeration_for :relationship_status,
+      with: RelationshipStatus, create_helpers: { polymorphic: { suffix: '_mode' } }
+  end
 
-    p.relationship_status_mode.saturday_night
-    ```
+  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.
+  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
+  ```ruby
+  p = Person.new
+  p.married!
 
-    p = Person.new
-    p.married!
+  p.married?
+  #=> true
+  ```
 
-    p.married?
-    #=> true
+* A scope method for each enumeration option if you pass the `create_scopes` option as `true`:
 
-    p.divorced?
-    #=> false
-    ```
+  ```ruby
+  class Person < ActiveRecord::Base
+    has_enumeration_for :relationship_status, with: RelationshipStatus, create_scopes: true
+  end
 
-*   If you pass the `:create_scopes` option as `true`, it will create a scope
-    method for each enumeration option (this option defaults to false):
+  Person.married.to_sql
+  #=> SELECT "users".* FROM "users" WHERE "users"."relationship_status" = "married"
+  ```
 
-    ```ruby
-    class Person < ActiveRecord::Base
-      has_enumeration_for :relationship_status, with: RelationshipStatus, create_scopes: true
-    end
+  The `:create_scopes` also accepts :prefix option.
 
-    Person.married.to_sql
-    #=> SELECT "people".* FROM "people" WHERE "people"."relationship_status" = 1
-    ```
+  ```ruby
+  class Person < ActiveRecord::Base
+    has_enumeration_for :relationship_status,
+      with: RelationshipStatus, create_scopes: { prefix: true }
+  end
 
-    The `:create_scopes` also accepts :prefix option.
+  Person.relationship_status_married.to_sql
+  ```
 
-    ```ruby
-    class Person < ActiveRecord::Base
-      has_enumeration_for :relationship_status, with: RelationshipStatus,
-                                                create_scopes: { prefix: true }
-    end
+* An inclustion validation (if your class can manage validations and responds to
+  `validates_inclusion_of`):
 
-    Person.relationship_status_married.to_sql
-    ```
+  ```ruby
+  class Person < ActiveRecord::Base
+    has_enumeration_for :relationship_status, with: RelationshipStatus
+  end
 
-*   If your class can manage validations and responds to
-    :validates_inclusion_of, it will create this validation:
+  p = Person.new(relationship_status: 'invalid')
+  p.valid?
+  #=> false
+  p.errors[:relationship_status]
+  #=> 'is not included in the list'
+  ```
 
-    ```ruby
-    class Person < ActiveRecord::Base
-      has_enumeration_for :relationship_status, with: RelationshipStatus
-    end
+* An presence validation (if your class can manage validations and responds to
+  `validates_presence_of` and you pass the `required` options as `true`):
 
-    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"
-    ```
+  ```ruby
+  class Person < ActiveRecord::Base
+    has_enumeration_for :relationship_status, required: true
+  end
 
-*   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):
+  p = Person.new relationship_status: nil
+  p.valid?
+  #=> false
+  p.errors[:relationship_status]
+  #=> "can't be blank"
+  ```
 
-    ```ruby
-    class Person < ActiveRecord::Base
-      has_enumeration_for :relationship_status, required: true
-    end
+  If you pass the `skip_validation` option as `true`, it will not create any validations:
 
-    p = Person.new relationship_status: nil
-    p.valid?
-    #=> false
-    p.errors[:relationship_status]
-    #=> "can't be blank"
-    ```
+  ```ruby
+  class Person < ActiveRecord::Base
+    has_enumeration_for :relationship_status, with: RelationshipStatus, skip_validation: true
+  end
 
-* If you pass the `:skip_validation` option as `true`, it will not create any validations:
+  p = Person.new(relationship_status: 'invalid')
+  p.valid?
+  #=> true
+  ```
 
-    ```ruby
-    class Person < ActiveRecord::Base
-      has_enumeration_for :relationship_status, with: RelationshipStatus, skip_validation: true
-    end
+Remember that you can add validations to any kind of class and not only to those derived from
+`ActiveRecord::Base`.
 
-    p = Person.new(relationship_status: 1_000_000)
-    p.valid?
-    #=> true
-    ```
+### Why to define enumerations outside the class that uses them?
 
-Remember that you can add validations to any kind of class and not only to
-those derived from ActiveRecord::Base.
+* It's clearer.
+* You can add behaviour to the enumeration class.
+* You can reuse the enumeration inside other classes.
 
 ## 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>`:
+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:
+pt-BR:
   enumerations:
     relationship_status:
       married: Casado
@@ -432,9 +404,8 @@ pt:
 ```ruby
 class RelationshipStatus < EnumerateIt::Base
   associate_values(
-    married: 1,
-    single: 2,
-    divorced: [3, "He's divorced"]
+    :married,
+    :single
   )
 end
 
@@ -444,79 +415,95 @@ p.relationship_status_humanize
 #=> 'Casado'
 
 p.relationship_status = RelationshipStatus::SINGLE
-p.relationship_status_humanize # nonexistent key
+p.relationship_status_humanize # Non-existent 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)
+status = RelationshipStatus::MARRIED
+RelationshipStatus.t(status)
 #=> 'Casado'
 ```
 
-## Installation
+## Using enumerations to handle a legacy database
 
-```bash
-gem install enumerate_it
-```
+**EnumerateIt** can help you to build a Rails application around a legacy database which was filled
+with those small and unchangeable tables used to create foreign key constraints everywhere, like the
+following example:
 
-## Using with Rails
+```sql
+Table "public.relationship_status"
 
-*   Add the gem to your Gemfile:
+  Column     |     Type      | Modifiers
+-------------+---------------+-----------
+ code        | character(1)  | not null
+ description | character(11) |
 
-    ```ruby
-    gem 'enumerate_it'
-    ```
+Indexes:
+  "relationship_status_pkey" PRIMARY KEY, btree (code)
 
-*   Run the install generator:
+SELECT * FROM relationship_status;
 
-    ```bash
-    rails generate enumerate_it:install
-    ```
+code |  description
+---- +--------------
+1    | Single
+2    | Married
+3    | Divorced
+```
 
-An interesting approach to use it in Rails apps is to create an
-`app/enumerations` folder.
+You might also have something like a `users` table with a `relationship_status` column and a foreign
+key pointing to the `relationship_status` table.
 
-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:
+While this is a good thing from the database normalization perspective, managing these values in
+tests is very hard. Doing database joins just to get the description of some value is absurd.
+And, more than this, referencing them in the code using magic numbers was terrible and meaningless:
+What does it mean when we say that someone or something is `2`?
 
-```bash
-rails generate enumerate_it:enum --help
+In this case, you can pass a hash:
+
+```ruby
+class RelationshipStatus < EnumerateIt::Base
+  associate_values(
+    single:   1,
+    married:  2,
+    divorced: 3
+  )
+end
 ```
 
-## Supported Ruby and Rails versions
+```ruby
+RelationshipStatus::MARRIED
+#=> 2
+```
 
-Check [travis config file](https://github.com/lucascaton/enumerate_it/blob/master/.travis.yml).
+You can also sort it by its value: `sort_by :value`.
 
-## Why did you reinvent the wheel?
+## FAQ
 
-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.
+#### What versions of Ruby and Rails are supported?
 
-## Why defining enumerations outside the class that use it?
+Please check out [travis config file](https://github.com/lucascaton/enumerate_it/blob/master/.travis.yml).
 
-* I think it's cleaner.
-* You can add behaviour to the enumeration class.
-* You can reuse the enumeration inside other classes.
+#### Can I set a value to always be at the end of a sorted list?
+
+Yes, please see [issue #60](https://github.com/lucascaton/enumerate_it/issues/60).
+
+## Changelog
+
+Changes are maintained under [Releases](https://github.com/lucascaton/enumerate_it/releases).
 
 ## 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.
-*   Run the tests agaist all supported versions: `$ rake`.
-*   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.
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so we don't break it in a future version unintentionally.
+* [Optional] Run the tests agaist a specific Gemfile: `$ appraisal rails_5.0 rake spec`.
+* Run the tests agaist all supported versions: `$ rake`.
+* Commit, but please do not mess with `Rakefile`, version, or history.
+* Send a Pull Request. Bonus points for topic branches.
 
 ## Copyright
 
-Copyright (c) 2010-2016 Cássio Marques and Lucas Caton. See LICENSE for details.
+Copyright (c) 2010-2016 Cássio Marques and Lucas Caton. See `LICENSE` file for details.

data/gemfiles/rails_3.0.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 3.0.9"
 gem "activerecord", "~> 3.0.9"

data/gemfiles/rails_3.1.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 3.1.9"
 gem "activerecord", "~> 3.1.9"

data/gemfiles/rails_3.2.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 3.2.9"
 gem "activerecord", "~> 3.2.9"

data/gemfiles/rails_4.0.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 4.0.9"
 gem "activerecord", "~> 4.0.9"

data/gemfiles/rails_4.1.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 4.1.9"
 gem "activerecord", "~> 4.1.9"

data/gemfiles/rails_4.2.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 4.2.7.1"
 gem "activerecord", "~> 4.2.7.1"

data/gemfiles/rails_5.0.gemfile

@@ -1,6 +1,6 @@
 # This file was generated by Appraisal
 
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem "activesupport", "~> 5.0.0.1"
 gem "activerecord", "~> 5.0.0.1"

data/lib/enumerate_it/base.rb

@@ -93,7 +93,7 @@ module EnumerateIt
       private
 
       def sorted_map
-        return enumeration if sort_mode == :none
+        return enumeration if sort_mode.nil? || sort_mode == :none
 
         enumeration.sort_by { |k, v| sort_lambda.call(k, v) }
       end
@@ -103,7 +103,7 @@ module EnumerateIt
           value:       ->(_k, v) { v[0] },
           name:        ->(k, _v) { k },
           translation: ->(_k, v) { translate(v[1]) }
-        }[sort_mode || :translation]
+        }[sort_mode]
       end
 
       def normalize_enumeration(values_hash)

data/lib/enumerate_it/version.rb

@@ -1,3 +1,3 @@
 module EnumerateIt
-  VERSION = '1.3.1'.freeze
+  VERSION = '1.4.0.rc1'.freeze
 end

data/lib/generators/enumerate_it/enum/enum_generator.rb

@@ -7,7 +7,7 @@ module EnumerateIt
 
       class_option :singular, type: 'string', desc: 'Singular name for i18n'
 
-      class_option :lang, type: 'string', desc: 'Lang to use in i18n', default: 'en'
+      class_option :lang, type: 'string', desc: 'Language to use in i18n', default: 'en'
 
       desc 'Creates a locale file on config/locales'
       def create_locale

data/spec/enumerate_it/base_spec.rb

@@ -198,7 +198,7 @@ describe EnumerateIt::Base do
 
   context 'associate values with a list' do
     it 'creates constants for each enumeration value' do
-      expect(TestEnumerationWithList::FIRST).to eq('first')
+      expect(TestEnumerationWithList::FIRST).to  eq('first')
       expect(TestEnumerationWithList::SECOND).to eq('second')
     end
 
@@ -207,7 +207,15 @@ describe EnumerateIt::Base do
     end
   end
 
-  context 'specifying a default sort mode' do
+  context 'not specifying a sort mode' do
+    subject { create_enumeration_class_with_sort_mode(nil).to_a }
+
+    it 'does not sort' do
+      is_expected.to eq([%w(xyz 1), %w(fgh 2), %w(abc 3), %w(jkl 0)])
+    end
+  end
+
+  context 'specifying a sort mode' do
     subject { create_enumeration_class_with_sort_mode(sort_mode).to_a }
 
     context 'by value' do

data/spec/support/test_classes.rb

@@ -7,17 +7,12 @@ class TestEnumeration < EnumerateIt::Base
 end
 
 class TestEnumerationWithoutArray < EnumerateIt::Base
-  associate_values(
-    value_one: '1',
-    value_two: '2'
-  )
+  associate_values value_one: '1', value_two: '2'
 end
 
 class TestEnumerationWithExtendedBehaviour < EnumerateIt::Base
-  associate_values(
-    first:  '1',
-    second: '2'
-  )
+  associate_values first: '1', second: '2'
+
   def self.to_a
     super.reverse
   end
@@ -32,21 +27,15 @@ class TestEnumerationWithReservedWords < EnumerateIt::Base
 end
 
 class TestEnumerationWithDash < EnumerateIt::Base
-  associate_values(
-    'pt-BR'
-  )
+  associate_values 'pt-BR'
 end
 
 class TestEnumerationWithCamelCase < EnumerateIt::Base
-  associate_values(
-    'iPhone'
-  )
+  associate_values 'iPhone'
 end
 
 class Foobar < EnumerateIt::Base
-  associate_values(
-    bar: 'foo'
-  )
+  associate_values bar: 'foo'
 end
 
 class PolymorphicEnum < EnumerateIt::Base
@@ -67,12 +56,13 @@ end
 
 class BaseClass
   extend EnumerateIt
+
   has_enumeration_for :foobar, with: TestEnumeration
 end
 
 def create_enumeration_class_with_sort_mode(sort_mode)
   Class.new(EnumerateIt::Base) do
-    sort_by sort_mode
+    sort_by(sort_mode)
 
     associate_values(
       foo:  %w(1 xyz),

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enumerate_it
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0.rc1
 platform: ruby
 authors:
 - Cássio Marques
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-28 00:00:00.000000000 Z
+date: 2016-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -142,6 +142,7 @@ files:
 - README.md
 - Rakefile
 - enumerate_it.gemspec
+- enumerate_it.png
 - gemfiles/rails_3.0.gemfile
 - gemfiles/rails_3.1.gemfile
 - gemfiles/rails_3.2.gemfile
@@ -180,12 +181,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.6
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby Enumerations