enumerations 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a75cec2684b73e9e83a7b60ddd48b95ac01fd991
-  data.tar.gz: 822d8484b921612c31deadd8491994ad1e22a66d
+  metadata.gz: e9193bf66247b09a32a3a72da1257fe97890da52
+  data.tar.gz: b005aaba38109c814c7020e7053d31a56a6f98a3
 SHA512:
-  metadata.gz: 3df5039cf8d021b312058982c26edee6d8e24c56bd05a4f9cba6db2f55adef3f311d3181a544e774cd3607750d0c813e4935fcbf3079608eec3a7a142a546d4d
-  data.tar.gz: 04c31625eecf7f4276bf11d673aa66d2290ca086d49d728502cde004166a32c7a2ff051367356299feeee8399afc0b486551b00694b51fe47b69d1e72aaf05d1
+  metadata.gz: 2003c66e3f930f5b3fafd9eea13036159a0583694384a1c644566ca49150485516186dffa0a2191feac09064602f3a89af31607d7b3c7dab6adea3a589b71d02
+  data.tar.gz: de534b1cab979f08d362ce42ab61fbe2bf4851fb32da2adc4e1e1abd31a7274dd92b261488cb38402eee36ab4220fde052a357ba289fba2491be50879fa3627c

data/Readme.md

@@ -47,7 +47,8 @@ Include enumerations for integer fields in other models:
 ```ruby
 class Post < ActiveRecord::Base
   enumeration :status
-  validates :status_id, presence: true
+
+  validates :status, presence: true           # You can validate either :status or :status_id
 end
 ```
 
@@ -58,7 +59,8 @@ class Post < ActiveRecord::Base
   enumeration :status,
               foreign_key: :post_status_id,   # specifies which column to use
               class_name: Post::Status        # specifies the class of the enumerator
-  validates :post_status_id, presence: true
+
+  validates :post_status, presence: true
 end
 ```
 Attribute `foreign_key` you can pass as a `String` or a `Symbol`. Attribute `class_name` can be set as a `String`, a `Symbol` or a `String`.
@@ -120,17 +122,30 @@ end
 Find enumerations by `id`:
 
 ```ruby
-@post.status = Status.find(2)                  # => Review pending
+@post.status = Status.find(2)                 # => Review pending
 @post.save
 ```
 
+Other finding methods:
+
+```ruby
+# Find by id as a String
+Status.find('2')                              # => Review pending
+
+# Find by symbol as a String
+Status.find('draft')                          # => Draft
+
+# Find by multiple attributes
+Status.find_by(name: 'None', visible: true)   # => None
+```
+
 Compare enumerations:
 
 ```ruby
-@post.status == :published                     # => true
-@post.status == 3                              # => true
-@post.status == Status.find(:published)        # => true
-@post.status.published?                        # => true
+@post.status == :published                    # => true
+@post.status == 3                             # => true
+@post.status == Status.find(:published)       # => true
+@post.status.published?                       # => true
 ```
 
 Get all enumerations:
@@ -141,6 +156,17 @@ Status.all
 
 
 
+## Filtering methods
+
+Enumerations can be filtered with `where` method, similar to `ActiveRecord::QueryMethods#where`.
+
+```ruby
+Role.where(admin: true)                       # => [Role.admin, Role.editor]
+Role.where(admin: true, active: true)         # => [Role.admin]
+```
+
+
+
 ## Scopes on model
 
 With enumerations, you'll get scope for each enumeration value in the
@@ -205,6 +231,36 @@ Status.review_pending.description              # => 'Some description...'
 Status.draft.description                       # => nil
 ```
 
+Translations
+=====
+
+**Enumerations** uses power of I18n API to enable you to create a locale file
+for enumerations like this:
+
+```yaml
+---
+en:
+  enumerations:
+    status:
+      draft:
+        name: Draft
+        description: Article draft...
+        ...
+    role:
+      admin:
+        name: Administrator
+```
+
+> You can separate enumerations locales into a separate `*.yml` files.
+> Then you should add locale file paths to I18n load path:
+
+```ruby
+# config/initializers/locale.rb
+
+# Where the I18n library should search for translation files (e.g.):
+I18n.load_path += Dir[Rails.root.join('config', 'locales', 'enumerations', '*.yml')]
+```
+
 Author
 ======
 

data/enumerations.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency 'activerecord'
   s.add_dependency 'activesupport'
+  s.add_dependency 'i18n'
   s.add_development_dependency 'pry-byebug'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'codeclimate-test-reporter'

data/lib/enumerations/base.rb

@@ -82,7 +82,7 @@ module Enumerations
       _values.values
     end
 
-    attr_reader :symbol
+    attr_reader :symbol, :attributes
 
     def initialize(symbol, attributes)
       @symbol = symbol

data/lib/enumerations/finder_methods.rb

@@ -17,6 +17,17 @@ module Enumerations
       end
     end
 
+    # Finds all enumerations which meets given attributes.
+    # Similar to ActiveRecord::QueryMethods#where.
+    #
+    # Example:
+    #
+    #   Role.find_by(name: 'Admin') => #<Enumerations::Value: @base=Role, @symbol=:admin...>
+    #
+    def where(**args)
+      _values.values.select { |value| args.map { |k, v| value.attributes[k] == v }.all? }
+    end
+
     # Finds an enumeration by defined attribute. Similar to ActiveRecord::FinderMethods#find_by
     #
     # Example:
@@ -24,7 +35,7 @@ module Enumerations
     #   Role.find_by(name: 'Admin') => #<Enumerations::Value: @base=Role, @symbol=:admin...>
     #
     def find_by(**args)
-      _values.values.find { |value| args.map { |k, v| value.send(k) == v }.all? }
+      where(args).first
     end
 
     def find_by_key(key)

data/lib/enumerations/value.rb

@@ -57,12 +57,21 @@ module Enumerations
       @attributes.each do |key, _|
         next if respond_to?(key)
 
-        self.class.send :define_method, key do
-          @attributes[key]
+        self.class.send :define_method, key do |locale: I18n.locale|
+          case @attributes[key]
+          when String, Symbol then translate_attribute(key, locale)
+          else @attributes[key]
+          end
         end
       end
     end
 
+    def translate_attribute(key, locale)
+      I18n.t(key, scope: [:enumerations, self.class.name.underscore, symbol],
+                  default: @attributes[key],
+                  locale: locale)
+    end
+
     # Predicate methods for values
     #
     # Example:

data/lib/enumerations/version.rb

@@ -1,3 +1,3 @@
 module Enumerations
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/test/base_test.rb

@@ -1,42 +1,6 @@
 require_relative 'test_helper'
 
 class BaseTest < Minitest::Test
-  def test_lookup_by_symbol
-    status = Status.find(:draft)
-
-    assert_equal :draft, status.symbol
-  end
-
-  def test_lookup_fail_by_symbol
-    status = Status.find(:draft)
-
-    refute_same :published, status.symbol
-  end
-
-  def test_lookup_by_string_id
-    status = Status.find('1')
-
-    assert_equal :draft, status.symbol
-  end
-
-  def test_lookup_by_string_key
-    status = Status.find('draft')
-
-    assert_equal :draft, status.symbol
-  end
-
-  def test_find_by
-    status = Status.find_by(name: 'Draft')
-
-    assert_equal :draft, status.symbol
-  end
-
-  def test_fail_find_by
-    status = Status.find_by(name: 'Draft1')
-
-    assert_equal nil, status
-  end
-
   def test_all
     statuses = Status.all
 

data/test/enumerations_test.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+require_relative 'test_helper'
 
 class EnumerationsTest < Minitest::Test
   def test_reflect_on_all_enumerations

data/test/finder_test.rb

@@ -0,0 +1,71 @@
+require_relative 'test_helper'
+
+class FinderTest < Minitest::Test
+  def test_lookup_by_symbol
+    status = Status.find(:draft)
+
+    assert_equal :draft, status.symbol
+  end
+
+  def test_lookup_fail_by_symbol
+    status = Status.find(:draft)
+
+    refute_same :published, status.symbol
+  end
+
+  def test_lookup_by_string_id
+    status = Status.find('1')
+
+    assert_equal :draft, status.symbol
+  end
+
+  def test_lookup_by_string_key
+    status = Status.find('draft')
+
+    assert_equal :draft, status.symbol
+  end
+
+  def test_find_by
+    status = Status.find_by(name: 'Draft')
+
+    assert_equal :draft, status.symbol
+  end
+
+  def test_fail_find_by
+    status = Status.find_by(name: 'Draft1')
+
+    assert_equal nil, status
+  end
+
+  def test_where_by_name
+    statuses = Status.where(name: 'Draft')
+
+    assert_equal [Status.find(:draft)], statuses
+  end
+
+  def test_where_by_name_with_no_results
+    statuses = Status.where(name: 'Draft1')
+
+    assert_equal [], statuses
+  end
+
+  def test_where_by_custom_attributes
+    roles = Role.where(admin: true)
+
+    assert_equal 2, roles.count
+    assert_equal [:admin, :editor], roles.map(&:symbol)
+  end
+
+  def test_where_by_multiple_custom_attributes
+    roles = Role.where(admin: true, active: true)
+
+    assert_equal 1, roles.count
+    assert_equal [:admin], roles.map(&:symbol)
+  end
+
+  def test_where_by_undefined_custom_attributes
+    roles = Role.where(description1: false)
+
+    assert_equal [], roles
+  end
+end

data/test/helpers/locale_helper.rb

@@ -0,0 +1,4 @@
+require 'i18n'
+
+I18n.available_locales = [:en, :hr, :fr]
+I18n.load_path = Dir[File.join('test', 'locales', '*.yml')]

data/test/locales/hr.yml

@@ -0,0 +1,20 @@
+---
+hr:
+  enumerations:
+    status:
+      draft:
+        name: Nacrt
+      review_pending:
+        name: Čeka pregled
+      published:
+        name: Published
+
+    role:
+      admin:
+        name: Admin
+      editor:
+        name: Urednik
+        description: Uređuje novine
+      author:
+        name: Autor
+        description: Autor novina

data/test/test_helper.rb

@@ -6,20 +6,21 @@ require 'enumerations'
 require 'active_record'
 require 'pry'
 
-require_relative 'database_helper'
+require_relative 'helpers/database_helper'
+require_relative 'helpers/locale_helper'
 
 class Status < Enumerations::Base
   values draft:           { id: 1, name: 'Draft' },
          review_pending:  { id: 2, name: 'Review pending' },
          published:       { id: 3, name: 'Published' }
 
-  value :none,    id: 4, name: 'None', visible: true
+  value :none,    id: 4, name: 'None', visible: true, deleted: false
   value :deleted, id: 5, deleted: true
 end
 
 class Role < Enumerations::Base
-  value :admin,   id: 1, name: 'Admin', admin: true
-  value :editor,  id: 2, name: 'Editor'
+  value :admin,   id: 1, name: 'Admin',  admin: true, active: true
+  value :editor,  id: 2, name: 'Editor', admin: true, active: false, description: 'Edits newspapers'
   value :author,  id: 3, name: 'Author'
 
   def my_custom_name

data/test/translation_test.rb

@@ -0,0 +1,94 @@
+require_relative 'test_helper'
+
+class TranslationTest < Minitest::Test
+  def test_translated_value_with_default_locale
+    status = Status.find(:draft)
+
+    assert_equal 'Draft', status.name
+  end
+
+  def test_translated_value_with_i18n_locale
+    status = Status.find(:draft)
+
+    I18n.locale = :hr
+    translated_name = status.name
+    I18n.locale = :en
+
+    assert_equal 'Nacrt', translated_name
+  end
+
+  def test_translated_value_with_i18n_locales
+    status = Status.find(:draft)
+
+    I18n.locale = :hr
+    assert_equal 'Nacrt', status.name
+    I18n.locale = :en
+    assert_equal 'Draft', status.name
+  end
+
+  def test_translated_value_with_custom_locale
+    status = Status.find(:draft)
+
+    assert_equal 'Nacrt', status.name(locale: :hr)
+  end
+
+  def test_boolean_value_true_not_changed_by_translations
+    status = Status.find(:none)
+
+    assert_equal true, status.visible
+  end
+
+  def test_boolean_value_false_not_changed_by_translations
+    status = Status.find(:none)
+
+    assert_equal false, status.deleted
+  end
+
+  def test_boolean_value_false_not_changed_by_translations_with_custom_locale
+    status = Status.find(:none)
+
+    assert_equal false, status.deleted(locale: :hr)
+  end
+
+  def test_translated_custom_attribute_with_i18n_locale
+    role = Role.find(:editor)
+
+    I18n.locale = :hr
+    translated_value = role.description
+    I18n.locale = :en
+
+    assert_equal 'Uređuje novine', translated_value
+  end
+
+  def test_translated_custom_attribute_with_custom_locale
+    role = Role.find(:editor)
+
+    assert_equal 'Uređuje novine', role.description(locale: :hr)
+  end
+
+  def test_empty_custom_attribute_with_custom_locale
+    role = Role.find(:admin)
+
+    assert_equal nil, role.description(locale: :hr)
+  end
+
+  def test_empty_custom_attribute_with_custom_locale_and_defined_translation
+    role = Role.find(:author)
+
+    assert_equal nil, role.description(locale: :hr)
+  end
+
+  def test_find_by_localized_name
+    status = Status.find_by(name: 'Draft')
+
+    assert_equal :draft, status.symbol
+  end
+
+  def test_find_by_localized_name_with_i18n_locale
+    I18n.locale = :hr
+    status = Status.find_by(name: 'Nacrt')
+    I18n.locale = :en
+
+    assert_equal nil, status
+  end
+end

data/test/version_test.rb

@@ -2,6 +2,6 @@ require_relative 'test_helper'
 
 class VersionTest < Minitest::Test
   def test_version
-    assert_equal '2.0.0', Enumerations::VERSION
+    assert_equal '2.1.0', Enumerations::VERSION
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enumerations
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Tomislav Car
@@ -40,6 +40,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -117,10 +131,14 @@ files:
 - lib/enumerations/value.rb
 - lib/enumerations/version.rb
 - test/base_test.rb
-- test/database_helper.rb
 - test/enumerations_test.rb
+- test/finder_test.rb
+- test/helpers/database_helper.rb
+- test/helpers/locale_helper.rb
+- test/locales/hr.yml
 - test/reflection_test.rb
 - test/test_helper.rb
+- test/translation_test.rb
 - test/value_test.rb
 - test/version_test.rb
 homepage: https://github.com/infinum/enumerations
@@ -148,9 +166,13 @@ specification_version: 4
 summary: Enumerations for ActiveRecord!
 test_files:
 - test/base_test.rb
-- test/database_helper.rb
 - test/enumerations_test.rb
+- test/finder_test.rb
+- test/helpers/database_helper.rb
+- test/helpers/locale_helper.rb
+- test/locales/hr.yml
 - test/reflection_test.rb
 - test/test_helper.rb
+- test/translation_test.rb
 - test/value_test.rb
 - test/version_test.rb