diff --git a/README.markdown b/README.markdown index baa89c4..20e8a6e 100644 --- a/README.markdown +++ b/README.markdown @@ -56,13 +56,13 @@ you would use `include`. Enumerations are created as models, but you can put then anywhere in your application. In Rails applications, you can put them inside models/. -``` ruby +```ruby class RelationshipStatus < EnumerateIt::Base associate_values( - :single => [1, 'Single'], - :married => [2, 'Married'], - :widow => [3, 'Widow'], - :divorced => [4, 'Divorced'] + single: [1, 'Single'], + married: [2, 'Married'], + widow: [3, 'Widow'], + divorced: [4, 'Divorced'] ) end ``` @@ -71,7 +71,7 @@ This will create some nice stuff: * Each enumeration's value will turn into a constant: - ``` ruby + ```ruby RelationshipStatus::SINGLE #=> 1 @@ -81,7 +81,7 @@ This will create some nice stuff: * You can retrieve a list with all the enumeration codes: - ``` ruby + ```ruby RelationshipStatus.list #=> [1, 2, 3, 4] ``` @@ -89,60 +89,60 @@ This will create some nice stuff: * You can get an array of options, ready to use with the 'select', 'select_tag', etc family of Rails helpers. - ``` ruby + ```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 + ```ruby RelationshipStatus.values_for %w(MARRIED SINGLE) #=> [2, 1] ``` * You can retrieve the value for a specific enumeration constant: - ``` ruby + ```ruby RelationshipStatus.value_for("MARRIED") #=> 2 ``` * You can retrieve the symbol used to declare a specific enumeration value: - ``` ruby + ```ruby RelationshipStatus.key_for(RelationshipStatus::MARRIED) #=> :married ``` * You can iterate over the list of the enumeration's values: - ``` ruby + ```ruby RelationshipStatus.each_value { |value| ... } ``` * You can iterate over the list of the enumeration's translations: - ``` ruby + ```ruby RelationshipStatus.each_translation { |translation| ... } ``` * You can also retrieve all the translations of the enumeration: - ``` ruby + ```ruby RelationshipStatus.translations ``` * You can ask for the enumeration's length: - ``` ruby + ```ruby RelationshipStatus.length #=> 4 ``` * You can manipulate the hash used to create the enumeration: - ``` ruby + ```ruby RelationshipStatus.enumeration #=> returns the exact hash used to define the enumeration ``` @@ -153,7 +153,7 @@ 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 + ```ruby class RelationshipStatus < EnumerateIt::Base associate_values :married, :single end @@ -166,9 +166,9 @@ You can also create enumerations in the following ways: translation. In this case, the I18n feature will be used (more on this below): - ``` ruby + ```ruby class RelationshipStatus < EnumerateIt::Base - associate_values :married => 1, :single => 2 + associate_values married: 1, single: 2 end ``` @@ -180,9 +180,9 @@ 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 +```ruby class RelationshipStatus < EnumerateIt::Base - associate_values :married => 1, :single => 2 + associate_values married: 1, single: 2 sort_by :value end @@ -204,23 +204,23 @@ The `sort_by` methods accept one of the following values: The cool part is that you can use these enumerations with any class, be it an ActiveRecord instance or not. -``` ruby +```ruby class Person extend EnumerateIt attr_accessor :relationship_status - has_enumeration_for :relationship_status, :with => RelationshipStatus + has_enumeration_for :relationship_status, with: RelationshipStatus end ``` -The :with option is not required. If you ommit it, EnumerateIt will try to +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 + ```ruby p = Person.new p.relationship_status = RelationshipStatus::DIVORCED p.relationship_status_humanize @@ -231,11 +231,11 @@ This will create: will use a 'humanized' version of the hash's key to humanize the attribute's value: - ``` ruby + ```ruby class RelationshipStatus < EnumerateIt::Base associate_values( - :married => 1, - :single => 2 + married: 1, + single: 2 ) end @@ -248,17 +248,17 @@ This will create: * The associated enumerations can be retrieved with the 'enumerations' class method. - ``` ruby + ```ruby Person.enumerations[:relationship_status] #=> RelationshipStatus ``` -* If you pass the :create_helpers option as 'true', it will create a helper +* 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 + ```ruby class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => true + has_enumeration_for :relationship_status, with: RelationshipStatus, create_helpers: true end p = Person.new @@ -272,12 +272,13 @@ This will create: ``` * 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 + hash to the `:create_helpers` option. This can be useful when two or more of the enumerations used share the same constants. - ``` ruby + ```ruby class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :prefix => true } + has_enumeration_for :relationship_status, with: RelationshipStatus, + create_helpers: { prefix: true } end p = Person.new @@ -293,7 +294,7 @@ This will create: * You can define polymorphic behavior for the enum values, so you can define a class for each of them: - ``` ruby + ```ruby class RelationshipStatus < EnumerateIt::Base associate_values :married, :single @@ -311,7 +312,8 @@ This will create: end class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :polymorphic => true } + has_enumeration_for :relationship_status, with: RelationshipStatus, + create_helpers: { polymorphic: true } end p = Person.new @@ -324,22 +326,23 @@ This will create: #=> "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 + ```ruby class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => { :polymorphic => { :suffix => "_mode" } } + 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 +* The `:create_helpers` also creates some mutator helper methods, that can be used to change the attribute's value. - ``` ruby + ```ruby class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_helpers => true + has_enumeration_for :relationship_status, with: RelationshipStatus, create_helpers: true end p = Person.new @@ -352,39 +355,40 @@ This will create: #=> false ``` -* If you pass the :create_scopes option as 'true', it will create a scope +* 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 + ```ruby class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_scopes => true + has_enumeration_for :relationship_status, with: RelationshipStatus, create_scopes: true end Person.married.to_sql #=> SELECT "people".* FROM "people" WHERE "people"."relationship_status" = 1 ``` - The :create_scopes also accepts :prefix option. + The `:create_scopes` also accepts :prefix option. - ``` ruby + ```ruby class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :with => RelationshipStatus, :create_scopes => { :prefix => true } + has_enumeration_for :relationship_status, with: RelationshipStatus, + create_scopes: { prefix: true } end Person.relationship_status_married.to_sql ``` -NOTE: The :create_scopes option can only be used for Rails.version >= 3.0.0. +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 + ```ruby class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :with => RelationshipStatus + has_enumeration_for :relationship_status, with: RelationshipStatus end - p = Person.new(:relationship_status => 6) # there is no '6' value in the enumeration + p = Person.new(relationship_status: 6) # there is no '6' value in the enumeration p.valid? #=> false p.errors[:relationship_status] @@ -392,15 +396,15 @@ 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_presence_of, you can pass the :required options as true and + `: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 + ```ruby class Person < ActiveRecord::Base - has_enumeration_for :relationship_status, :required => true + has_enumeration_for :relationship_status, required: true end - p = Person.new :relationship_status => nil + p = Person.new relationship_status: nil p.valid? #=> false p.errors[:relationship_status] @@ -417,7 +421,7 @@ 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 +```yaml # your locale file pt: enumerations: @@ -425,12 +429,12 @@ pt: married: Casado ``` -``` ruby +```ruby class RelationshipStatus < EnumerateIt::Base associate_values( - :married => 1, - :single => 2, - :divorced => [3, "He's divorced"] + married: 1, + single: 2, + divorced: [3, "He's divorced"] ) end @@ -450,14 +454,14 @@ p.relationship_status_humanize # uses the provided string You can also translate specific values: -``` ruby +```ruby RelationshipStatus.t(1) #=> 'Casado' ``` ## Installation -``` bash +```bash gem install enumerate_it ``` @@ -465,13 +469,13 @@ gem install enumerate_it * Add the gem to your Gemfile: - ``` ruby + ```ruby gem "enumerate_it" ``` * Run the install generator: - ``` bash + ```bash rails generate enumerate_it:install ``` @@ -480,7 +484,7 @@ 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 +```ruby module YourApp class Application < Rails::Application config.autoload_paths << "#{Rails.root}/app/enumerations" @@ -491,7 +495,7 @@ 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 +```bash rails generate enumerate_it:enum --help ```