enumerations 1.0.0 → 1.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c202450cd19bc9f524f6ef5756c44bd304a4ef6047d274abda8d165601b6e64
+  data.tar.gz: 61977fd20143ade7cb63242cc0b6098a981861783b412b62fa6b36e28b195f35
+SHA512:
+  metadata.gz: 60cb0a9f041e566e090e7b26b5a099f912e6a63a94a652a165b1e83f1d71fd5b7d280c25ebe13e1bca12d16c4dd0407f8db736ad7893ec2ed491a21ef199ffbc
+  data.tar.gz: 04f4aff2e90b826b5e47022083c919d28f561b9370963b9c37251c83eb1101c68b1500624c3ef0e4e039c88465da46a1afe707cd5cda15778dfb47a4bae16ed4

data/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+*.gem
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+ - 2.1.0
+ - 2.3.1
+script: rake

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rake'
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+desc 'Default: run unit tests.'
+task default: :test
+
+desc 'Run unit tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end

data/Readme.md

@@ -0,0 +1,128 @@
+Enumerations
+============
+
+Rails plugin for enumerations in ActiveRecord models.
+
+[![Build Status](https://travis-ci.org/infinum/enumerations.svg?branch=master)](https://travis-ci.org/infinum/enumerations)
+
+Installation
+============
+
+Inside your `Gemfile` add the following:
+
+```ruby
+gem 'enumerations'
+```
+
+Usage
+=====
+
+Create a model for your enumerations:
+
+```ruby
+class Status < Enumeration::Base
+  values draft:           { id: 1, name: 'Draft' },
+         review_pending:  { id: 2, name: 'Review pending' },
+         published:       { id: 3, name: 'Published' }
+end
+```
+
+Or you can use `value` method for defining your enumerations:
+
+```ruby
+class Status < Enumeration::Base
+  value :draft,           id: 1, name: 'Draft'
+  value :review_pending,  id: 2, name: 'Review pending'
+  value :published,       id: 3, name: 'Published'
+end
+```
+
+Include enumerations for integer fields in other models:
+
+```ruby
+class Post < ActiveRecord::Base
+  enumeration :status
+  validates :status_id, presence: true
+end
+```
+
+You can pass attributes to specify which enumeratior and which column to use:
+
+```ruby
+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
+end
+```
+
+Set enumerations, find enumerations by `symbol`:
+
+```ruby
+@post = Post.first
+@post.status = Status.find(:draft)
+@post.save
+```
+
+Or you can set enumerations on this way:
+
+```ruby
+@post.status = Status.draft
+```
+
+Find enumerations by `id`:
+
+```ruby
+@post.status = Status.find(2)               # => Review pending
+@post.save
+```
+
+Compare enumerations:
+
+```ruby
+@post.status == :published                  # => true
+@post.status == 3                           # => true
+@post.status == Status.find(:published)     # => true
+@post.status.published?                     # => true
+```
+
+Get all enumerations:
+
+```ruby
+Status.all
+```
+
+Use in forms:
+
+```ruby
+%p
+  = f.label :status_id
+  %br
+  = f.collection_select :status_id, Status.all, :id, :name
+```
+
+Advance Usage
+=====
+
+Except `id` and `name` you can specify other attributes to your enumerations:
+
+```ruby
+class Status < Enumeration::Base
+  value :draft,           id: 1, name: 'Draft'
+  value :review_pending,  id: 2, name: 'Review pending', description: 'Some description...'
+  value :published,       id: 3, name: 'Published'
+end
+```
+
+Every enumeration has `id`, `name` and `description` methods. If you call method that is not in attribute list for enumeration, it will return `nil`.
+
+```ruby
+Status.review_pending.description             # => 'Some description...'
+Status.draft.description                      # => nil
+```
+
+Author
+======
+
+Copyright © 2010 Tomislav Car, Infinum Ltd.

data/enumerations.gemspec

@@ -0,0 +1,19 @@
+require File.expand_path('../lib/enumerations/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'enumerations'
+  s.version     = Enumeration::VERSION
+  s.date        = '2010-08-20'
+  s.summary     = "Enumerations for ActiveRecord!"
+  s.description = 'Extends ActiveRecord with enumeration capabilites.'
+  s.authors     = ['Tomislav Car', 'Nikica Jokic', 'Nikola Santic']
+  s.email       = ['tomislav@infinum.hr', 'nikica.jokic@infinum.hr', 'nikola.santic@infinum.hr']
+  s.homepage    = 'https://github.com/infinum/enumerations'
+
+  s.add_dependency 'activerecord'
+  s.add_dependency 'activesupport'
+  s.add_development_dependency 'pry-byebug'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+end

data/lib/enumerations.rb

@@ -0,0 +1,96 @@
+require 'active_support'
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/string/inflections'
+
+require 'enumerations/version'
+require 'enumerations/base'
+require 'enumerations/reflection'
+
+# TODO: rename to Enumeration(s) in a major version change
+module Enumeration
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :_enumerations
+    self._enumerations = []
+  end
+
+  module ClassMethods
+    # Create an enumeration for the symbol <tt>name</tt>.
+    # Options include <tt>foreign_key</tt> attribute and <tt>class_name</tt>
+    #
+    # Example:
+    #
+    #   class User < ActiveRecord::Base
+    #     enumeration :role
+    #   end
+    #
+    #  user.role_id = 1
+    #  user.role => #<Enumeration::Value:0x007fff45d7ec30 @base=Role, @symbol=:admin...>
+    #
+    #  user.role = Role.staff
+    #  user.role_id => 2
+    #
+    # TODO: add documentation for foreign_key and class_name
+    def enumeration(name, options = {})
+      options[:foreign_key] ||= "#{name}_id".to_sym
+      options[:class_name] ||= name.to_s.camelize
+
+      add_enumeration(name, options)
+    end
+
+    # Output all the enumerations that this model has defined
+    # Returns an array of Reflection objects for all the
+    # enumerations in the class.
+    #
+    # Example:
+    #
+    #   User.reflect_on_all_enumerations => # [
+    #      #<Enumeration::Reflection:0x007fe894724320 @name=:role...>,
+    #      #<Enumeration::Reflection:0x007fe89471d020 @name=:status...>]
+    #
+    def reflect_on_all_enumerations
+      _enumerations
+    end
+
+    private
+
+    def add_enumeration(name, options)
+      # Getter for belongs_to
+      #
+      # Example:
+      #
+      #   user.role_id = 1
+      #   user.role => #<Enumeration::Value:0x007fff45d7ec30 @base=Role, @symbol=:admin...>
+      #
+      define_method name do
+        enumerator_class = if options[:class_name].is_a?(Class)
+                             options[:class_name]
+                           else
+                             options[:class_name].constantize
+                           end
+
+        enumerator_class.find(send(options[:foreign_key]))
+      end
+
+      # Setter for belongs_to
+      #
+      # Example:
+      #
+      #   user.role = Role.admin
+      #   user.role_id => 1
+      #
+      define_method "#{name}=" do |other|
+        send("#{options[:foreign_key]}=", other.id)
+      end
+
+      self._enumerations += [Reflection.new(name, options)]
+    end
+  end
+end
+
+# Extend ActiveRecord with Enumeration capabilites
+ActiveSupport.on_load(:active_record) do
+  include Enumeration
+end

data/lib/enumerations/base.rb

@@ -0,0 +1,187 @@
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/string/inflections'
+
+module Enumeration
+  class Base
+    class_attribute :_values, :_symbol_index
+    self._values = {}
+    self._symbol_index = {}
+
+    # Adding new value to enumeration
+    #
+    # Example:
+    #
+    #   value :admin, id: 1, name: 'Admin', description: 'Some description...'
+    #
+    #   Role.admin.id => # 1
+    #   Role.find(:admin).name => # "Admin"
+    #   Role.find(1).description => # "Some description..."
+    #
+    def self.value(symbol, attributes)
+      # TODO: make this errors better if needed
+      # TODO: test this errors
+      raise 'Enumeration id is required' if attributes[:id].nil?
+      raise "Duplicate symbol #{symbol}" if find(symbol)
+      raise "Duplicate id #{attributes[:id]}" if find(attributes[:id])
+
+      self._values = _values.merge(symbol => new(symbol, attributes))
+      self._symbol_index = _symbol_index.merge(symbol => attributes[:id])
+
+      # Adds name base finder methods
+      #
+      # Example:
+      #
+      #    Role.admin => #<Enumeration::Value:0x007fff45d7ec30 @base=Role, @symbol=:admin...>
+      #    Role.staff => #<Enumeration::Value:0x007f980e9cb0a0 @base=Role, @symbol=:staff...>
+      #
+      singleton_class.send(:define_method, symbol) do
+        find(symbol)
+      end
+    end
+
+    # Adding multiple values to enumeration
+    #
+    # Example:
+    #
+    #   values admin:           { id: 1, name: 'Admin' },
+    #          manager:         { id: 2, name: 'Manager' },
+    #          staff:           { id: 3, name: 'Staff', description: 'Some description...' }
+    #
+    #   Role.admin.id => # 1
+    #   Role.find(:manager).name => # "Manager"
+    #   Role.find(3).description => # "Some description..."
+    #
+    def self.values(values)
+      values.each do |symbol, attributes|
+        value(symbol, attributes)
+      end
+    end
+
+    # Returns an array of all enumeration symbols
+    #
+    # Example:
+    #
+    #   Role.symbols => # [:admin, :manager, :staff]
+    #
+    def self.symbols
+      _values.keys
+    end
+
+    # Returns an array of all enumeration values
+    #
+    # Example:
+    #
+    #   Role.all => # [#<Enumeration::Value:0x007f8ed7f46100 @base=Role, @symbol=:admin...>,
+    #                  #<Enumeration::Value:0x007f8ed7f45de0 @base=Role, @symbol=:manager...>,
+    #                  #<Enumeration::Value:0x007f8ed7f45ae8 @base=Role, @symbol=:staff...>]
+    #
+    def self.all
+      _values.values
+    end
+
+    # Finds an enumeration by symbol, id or name
+    #
+    # Example:
+    #
+    #   Role.find(:admin)  => #<Enumeration::Value:0x007f8ed7f46100 @base=Role, @symbol=:admin...>
+    #   Role.find(2)       => #<Enumeration::Value:0x007f8ed7f45de0 @base=Role, @symbol=:manager...>
+    #   Role.find('2')     => #<Enumeration::Value:0x007f8ed7f45de0 @base=Role, @symbol=:manager...>
+    #   Role.find('staff') => #<Enumeration::Value:0x007f8ed7f45ae8 @base=Role, @symbol=:staff...>
+    #
+    def self.find(key)
+      case key
+      when Symbol then find_by_key(key)
+      when String then find_by_key(key.to_sym) || find_by_id(key.to_i)
+      when Integer then find_by_id(key)
+      end
+    end
+
+    # Finds an enumeration by defined attribute. Simmilar to AcriveRecord::FinderMethods#find_by
+    #
+    # Example:
+    #
+    #   Role.find_by(name: 'Admin')  => #<Enumeration::Value:0x007f8ed7f46100 @base=Role, @symbol=:admin...>
+    #
+    def self.find_by(**args)
+      _values.values.find { |value| args.map { |k, v| value.send(k) == v }.all? }
+    end
+
+    def self.find_by_key(key)
+      _values[key]
+    end
+
+    def self.find_by_id(id)
+      _values[_symbol_index.key(id)]
+    end
+
+    def initialize(symbol, attributes)
+      @symbol = symbol
+      @attributes = attributes
+      create_instance_methods
+    end
+
+    attr_reader :symbol
+
+    def to_i
+      id
+    end
+
+    def to_s
+      name
+    end
+
+    def to_sym
+      @symbol
+    end
+
+    def to_param
+      id
+    end
+
+    # Comparison by id, symbol or object
+    #
+    # Example:
+    #
+    #   Role.admin == 1           => true
+    #   Role.admin == :admin      => true
+    #   Role.admin == Role.admin  => true
+    #   Role.admin == 2           => false
+    #   Role.admin == :staff      => false
+    #   Role.admin == Role.staff  => false
+    #
+    # TODO: test if case..when is working with this
+    def ==(other)
+      case other
+      when Integer then other == id
+      when Symbol then other == @symbol
+      else super
+      end
+    end
+
+    private
+
+    # Getters for all attributes
+    #
+    # Example:
+    #
+    #   Role.admin => #<Enumeration::Value:0x007fff45d7ec30 @base=Role, @symbol=:admin,
+    #                   @attributes={:id=>1, :name=>"Admin", :description=>"Some description..."}>
+    #   user.role.id => # 1
+    #   user.role.name => # "Admin"
+    #   user.role.description => # "Some description..."
+    #   user.role.admin? => # true
+    #   user.role.staff? => # false
+    #
+    def create_instance_methods
+      @attributes.each do |key, _|
+        self.class.send :define_method, key do
+          @attributes[key]
+        end
+      end
+
+      self.class.send :define_method, "#{@symbol}?" do
+        __callee__[0..-2].to_sym == @symbol
+      end
+    end
+  end
+end

data/lib/enumerations/reflection.rb

@@ -0,0 +1,18 @@
+module Enumeration
+  class Reflection
+    attr_reader :name
+
+    def initialize(name, options)
+      @name = name
+      @options = options
+    end
+
+    def class_name
+      @options[:class_name]
+    end
+
+    def foreign_key
+      @options[:foreign_key]
+    end
+  end
+end

data/lib/enumerations/version.rb

@@ -0,0 +1,3 @@
+module Enumeration
+  VERSION = '1.3.2'
+end

data/test/base_test.rb

@@ -0,0 +1,101 @@
+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_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
+
+    assert_equal 5, statuses.size
+    assert_equal statuses.first, Status.draft
+  end
+
+  def test_duplicated_id
+    assert_raises 'Duplicate id 1' do
+      Class.new.values draft: { id: 1, name: 'Draft' },
+                       test:  { id: 1, name: 'Draft' }
+    end
+  end
+
+  def test_duplicated_symbol
+    assert_raises 'Duplicate symbol draft' do
+      obj = Class.new
+
+      obj.value :draft, id: 1, name: 'Draft'
+      obj.value :draft, id: 2, name: 'Draft Again'
+    end
+  end
+
+  def test_all_has_custom_attributes
+    statuses = Status.all
+
+    assert_silent do
+      statuses.map(&:visible)
+      statuses.map(&:deleted)
+    end
+  end
+
+  def test_with_defined_custom_attributes_visible
+    status = Status.find(:none)
+
+    assert_equal true, status.visible
+  end
+
+  def test_with_defined_custom_attributes_deleted
+    status = Status.find(:deleted)
+
+    assert_equal true, status.deleted
+  end
+
+  def test_without_defined_custom_attributes
+    status = Status.find(:draft)
+
+    assert_equal nil, status.visible
+  end
+
+  def test_equal_by_id
+    status = Status.find(:draft)
+
+    assert_equal true, status == 1
+  end
+
+  def test_equal_by_symbol
+    status = Status.draft
+
+    assert_equal true, status == :draft
+  end
+
+  def test_equal_by_enumeration
+    status = Status.draft
+
+    assert_equal true, status == Status.draft
+  end
+
+  def test_not_equal_by_enumeration
+    status = Status.draft
+
+    assert_equal false, status == Status.published
+  end
+end

data/test/enumerations_test.rb

@@ -0,0 +1,41 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class EnumerationsTest < Minitest::Test
+  def test_reflect_on_all_enumerations
+    enumerations = Post.reflect_on_all_enumerations
+
+    assert_equal 2, enumerations.size
+    assert_equal :status, enumerations.first.name
+    assert_equal 'Status', enumerations.first.class_name
+
+    assert_equal :some_other_status_id, enumerations[1].foreign_key
+  end
+
+  def test_model_enumeration_assignment
+    p = Post.new
+    p.status = Status.draft
+
+    assert_equal 'Draft', p.status.to_s
+  end
+
+  def test_model_via_id_assignment
+    p = Post.new
+    p.some_other_status_id = Status.published.id
+
+    assert_equal 'Published', p.different_status.to_s
+  end
+
+  def test_boolean_lookup
+    p = Post.new
+    p.status = Status.draft
+
+    assert_equal true, p.status.draft?
+  end
+
+  def test_false_boolean_lookup
+    p = Post.new
+    p.status = Status.draft
+
+    assert_equal false, p.status.published?
+  end
+end

data/test/reflection_test.rb

@@ -0,0 +1,11 @@
+require_relative 'test_helper'
+
+class ReflectionTest < Minitest::Test
+  def test_reflections
+    reflection = Enumeration::Reflection.new(:role, class_name: 'Role', foreign_key: :role_id)
+
+    assert_equal :role, reflection.name
+    assert_equal 'Role', reflection.class_name
+    assert_equal :role_id, reflection.foreign_key
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,25 @@
+# TODO: improve tests
+require 'minitest/autorun'
+require 'enumerations'
+require 'pry'
+
+# Faking ActiveRecord
+class MockActiveRecordBase
+  include Enumeration
+end
+
+class Status < Enumeration::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 :deleted, id: 5, deleted: true
+end
+
+class Post < MockActiveRecordBase
+  attr_accessor :status_id, :some_other_status_id
+
+  enumeration :status
+  enumeration :different_status, foreign_key: :some_other_status_id, class_name: 'Status'
+end

data/test/version_test.rb

@@ -0,0 +1,7 @@
+require_relative 'test_helper'
+
+class VersionTest < Minitest::Test
+  def test_version
+    assert_equal '1.3.0', Enumeration::VERSION
+  end
+end

metadata

@@ -1,45 +1,108 @@
 --- !ruby/object:Gem::Specification
 name: enumerations
 version: !ruby/object:Gem::Version
-  version: 1.0.0
-  prerelease: 
+  version: 1.3.2
 platform: ruby
 authors:
 - Tomislav Car
-autorequire: 
+- Nikica Jokic
+- Nikola Santic
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2010-04-28 00:00:00.000000000 Z
-dependencies: []
+date: 2010-08-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  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: activesupport
+  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
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Extends ActiveRecord with enumeration capabilites.
-email: carr@infinum.hr
+email:
+- tomislav@infinum.hr
+- nikica.jokic@infinum.hr
+- nikola.santic@infinum.hr
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- init.rb
-homepage: http://rubygems.org/gems/enumerations
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- Rakefile
+- Readme.md
+- enumerations.gemspec
+- lib/enumerations.rb
+- lib/enumerations/base.rb
+- lib/enumerations/reflection.rb
+- lib/enumerations/version.rb
+- test/base_test.rb
+- test/enumerations_test.rb
+- test/reflection_test.rb
+- test/test_helper.rb
+- test/version_test.rb
+homepage: https://github.com/infinum/enumerations
 licenses: []
-post_install_message: 
+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'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.23
-signing_key: 
-specification_version: 3
-summary: Enumerations for activerecord!
-test_files: []
+rubygems_version: 3.0.3
+signing_key:
+specification_version: 4
+summary: Enumerations for ActiveRecord!
+test_files:
+- test/base_test.rb
+- test/enumerations_test.rb
+- test/reflection_test.rb
+- test/test_helper.rb
+- test/version_test.rb

data/init.rb

@@ -1 +0,0 @@
-ActiveRecord::Base.send(:include, Enumeration)