magic_enum 0.0.1

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009-2012, Dmytro Shteflyuk, Oleksiy Kovyrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,79 @@
+= MagicEnum
+
+MagicEnum is a simple ActiveRecord plugin that makes it easier to maintain ENUM-like attributes in your models.
+
+Examples:
+
+   Statuses = {
+     :draft => 0,
+     :published => 1,
+     :approved => 2
+   }
+   define_enum :status
+
+== How to Use
+ 
+Before using <tt>define_enum</tt>, you should define constant with ENUM options.
+Constant name would be pluralized enum attribute name. Additional constant named
+like YourEnumInverted would be created automatically and would contain
+inverted hash.
+ 
+<b>Please note</b>: nil and 0 are not the same values!
+ 
+You could specify additional options:
+
+* <tt>:default</tt> - value which will be used when current state of ENUM attribute is invalid or wrong value received. If it has not been specified, min value of the ENUM would be used.
+* <tt>:raise_on_invalid</tt> - if +true+ an exception would be raised on invalid enum value received. If it is +false+, default value would be used instead of wrong one.
+* <tt>:simple_accessors</tt> - if +true+, additional methods for each ENUM value would be defined in form value?. Methods returns +true+ when ENUM attribute has corresponding value.
+* <tt>:enum</tt> - string with name of the ENUM hash.
+ 
+Look the following example:
+ 
+   Statuses = {
+     :unknown => 0,
+     :draft => 1,
+     :published => 2,
+     :approved => 3
+   }
+   define_enum :status, :default => 1, :raise_on_invalid => true, :simple_accessors => true
+   
+This example is identical to:
+ 
+   Statuses = {
+     :unknown => 0,
+     :draft => 1,
+     :published => 2,
+     :approved => 3
+   }
+   StatusesInverted = Statuses.invert
+   
+   def status
+     return StatusesInverted[self[:status].to_i] || StatusesInverted[1]
+   end
+   
+   def status=(value)
+     raise ArgumentError, "Invalid value \"#{value}\" for :status attribute of the #{self.class} model" if Statuses[value].nil?
+     self[:status] = Statuses[value]
+   end
+   
+   def unknown?
+     status == :unknown
+   end
+   
+   def draft?
+     status == :draft
+   end
+   
+   def published?
+     status == :published
+   end
+   
+   def approved?
+     status == :approved
+   end
+
+== Who are the authors?
+
+This plugin was originally developed for BestTechVideos project (http://www.bestechvideos.com) by Dmytro Shteflyuk (http://kpumuk.info)
+and later cleaned up in Scribd repository and released to the public by Oleksiy Kovyrin. All the code in this package is released under
+the MIT license. For more details, see the LICENSE file.

data/Rakefile

@@ -0,0 +1,21 @@
+require 'rake'
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'rdoc/task'
+
+desc 'Default: run unit tests.'
+task :default => :spec
+
+desc 'Test the magic_enum plugin.'
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'Generate documentation for the magic_enum plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'MagicEnum'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1,3 @@
+require File.dirname(__FILE__) + '/lib/magic_enum'
+
+ActiveRecord::Base.send(:include, MagicEnum)

data/lib/magic_enum/version.rb

@@ -0,0 +1,11 @@
+# Version info
+module MagicEnum
+  module Version
+    MAJOR = 0
+    MINOR = 0
+    PATCH = 1
+    BUILD = nil
+
+    STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
+  end
+end

data/lib/magic_enum.rb

@@ -0,0 +1,154 @@
+module MagicEnum
+  def self.append_features(base) #:nodoc:
+    super
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    # Method used to define ENUM attributes in your model. Examples:
+    #
+    #   Statuses = {
+    #     :draft => 0,
+    #     :published => 1,
+    #     :approved => 2
+    #   }
+    #   define_enum :status
+    #
+    # Before using <tt>define_enum</tt>, you should define constant with ENUM options.
+    # Constant name would be pluralized enum attribute name. Additional constant named
+    # like <tt>YourEnumInverted</tt> would be created automatically and would contain
+    # inverted hash.
+    #
+    # <b>Please note</b>: <tt>nil</tt> and <tt>0</tt> are not the same values!
+    #
+    # You could specify additional options:
+    #
+    # * <tt>:default</tt> - value which will be used when current state of ENUM attribute is
+    #   invalid or wrong value received. If it has not been specified, min value of the ENUM would
+    #   be used.
+    # * <tt>:raise_on_invalid</tt> - if <tt>true</tt> an exception would be raised on invalid
+    #   enum value received. If it is <tt>false</tt>, default value would be used instead of
+    #   wrong one.
+    # * <tt>:simple_accessors</tt> - if <tt>true</tt>, additional methods for each ENUM value
+    #   would be defined in form <tt>value?</tt>. Methods returns <tt>true</tt> when
+    #   ENUM attribute has corresponding value.
+    # * <tt>:enum</tt> - string with name of the ENUM hash.
+    #
+    # Look the following example:
+    #
+    #   Statuses = {
+    #     :unknown => 0,
+    #     :draft => 1,
+    #     :published => 2,
+    #     :approved => 3
+    #   }
+    #   define_enum :status, :default => 1, :raise_on_invalid => true, :simple_accessors => true
+    #
+    # This example is identical to:
+    #
+    #   Statuses = {
+    #     :unknown => 0,
+    #     :draft => 1,
+    #     :published => 2,
+    #     :approved => 3
+    #   }
+    #   StatusesInverted = Statuses.invert
+    #
+    #   def status
+    #     return StatusesInverted[self[:status].to_i] || StatusesInverted[1]
+    #   end
+    #
+    #   def status=(value)
+    #     raise ArgumentError, "Invalid value \"#{value}\" for :status attribute of the #{self.class} model" if Statuses[value].nil?
+    #     self[:status] = Statuses[value]
+    #   end
+    #
+    #   def unknown?
+    #     status == :unknown
+    #   end
+    #
+    #   def draft?
+    #     status == :draft
+    #   end
+    #
+    #   def published?
+    #     status == :published
+    #   end
+    #
+    #   def approved?
+    #     status == :approved
+    #   end
+    #
+    def define_enum(name, opts = {})
+      default_opts = {  :raise_on_invalid => false,
+                        :simple_accessors => false,
+                        :named_scopes => false,
+                        :scope_extensions => false
+                        }
+      opts = default_opts.merge(opts)
+      name = name.to_sym
+
+      # bug in Rails 1.2.2
+      opts[:enum] = name.to_s.pluralize.classify.pluralize unless opts[:enum]
+      enum = opts[:enum]
+      enum_inverted = "#{enum}Inverted"
+
+      opts[:default] = const_get(enum).values.sort do |a, b|
+        if a.nil? and b.nil?
+          0
+        elsif a.nil?
+          -1
+        elsif b.nil?
+          1
+        else
+          a <=> b
+        end
+      end.first unless opts[:default]
+
+      const_set(enum_inverted, const_get(enum).invert)
+
+      define_method name do
+        self.class.const_get(enum_inverted)[self[name]] || self.class.const_get(enum_inverted)[opts[:default]]
+      end
+
+      define_method "#{name}_name" do
+        send(name).to_s
+      end
+
+      define_method "#{name}=" do |value|
+        value = value.to_sym if value.is_a?(String)
+        raise ArgumentError, "Invalid value \"#{value}\" for :#{name} attribute of the #{self.class} model" if opts[:raise_on_invalid] and self.class.const_get(enum)[value].nil?
+        if value.is_a?(Integer)
+          self[name] = value
+        else
+          self[name] = self.class.const_get(enum)[value] || opts[:default]
+        end
+      end
+
+      if opts[:simple_accessors]
+        const_get(enum).keys.each do |key|
+          define_method "#{key}?" do
+            send(name) == key
+          end
+        end
+      end
+
+      # Create named scopes for each enum value
+      if opts[:named_scopes]
+        const_get(enum).keys.each do |key|
+          named_scope key.to_s.pluralize.to_sym, :conditions => ["#{name} = ?", const_get(enum)[key]] do
+            opts[:scope_extensions].each do |ext_name, ext_block|
+              define_method ext_name, ext_block
+            end if opts[:scope_extensions] and opts[:scope_extensions].is_a?(Hash)
+          end
+        end
+        named_scope "of_#{name}".to_sym, lambda { |t| { :conditions => ["#{name} = ?", const_get(enum)[t]] } } do
+          opts[:scope_extensions].each do |ext_name, ext_block|
+            define_method ext_name, ext_block
+          end if opts[:scope_extensions] and opts[:scope_extensions].is_a?(Hash)
+        end
+      end
+
+    end
+  end
+end

data/magic_enum.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'magic_enum/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'magic_enum'
+  s.version       = MagicEnum::Version::STRING
+  s.platform      = Gem::Platform::RUBY
+
+  s.authors       = [ 'Dmytro Shteflyuk', 'Oleksiy Kovyrin' ]
+  s.email         = 'alexey@kovyrin.net'
+  s.homepage      = 'https://github.com/kovyrin/magic-enum'
+  s.summary       = 'ActiveRecord plugin that makes it easier to maintain ENUM-like attributes in your models'
+  s.description   = 'MagicEnum is a simple ActiveRecord plugin that makes it easier to maintain ENUM-like attributes in your models.'
+
+  s.rdoc_options = [ '--charset=UTF-8' ]
+
+  s.files            = `git ls-files`.split("\n")
+  s.require_paths    = [ 'lib' ]
+  s.extra_rdoc_files = [ 'LICENSE', 'README.rdoc' ]
+
+  # Dependencies
+  s.add_dependency 'activerecord', '<= 3.2'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'yard'
+end

data/spec/magic_enum_spec.rb

@@ -0,0 +1,221 @@
+require 'rubygems'
+require 'active_record'
+
+require File.dirname(__FILE__) + '/../init'
+
+module MagicEnumHelper
+  class TestModelBase
+    include MagicEnum
+    Statuses = { :unknown => 0, :draft => 1, :published => 2 }
+
+    def [](attr_name)
+      @status
+    end
+
+    def []=(attr_name, value)
+      @status = value
+    end
+  end
+end
+
+describe 'Model with magic enum' do
+  include MagicEnumHelper
+
+  class TestModel1 < MagicEnumHelper::TestModelBase
+    define_enum :status
+  end
+
+  before do
+    @model = TestModel1.new
+  end
+
+  specify 'should define methods to get and set enum field' do
+    TestModel1.should be_method_defined(:status)
+    TestModel1.should be_method_defined(:status=)
+  end
+
+  specify 'should store enum value using [] operation on model' do
+    @model.status = :draft
+    @model[:status].should == 1
+    @model.status.should == :draft
+    @model.status = :unknown
+    @model[:status].should == 0
+    @model.status.should == :unknown
+  end
+
+  specify 'should store enum value if key is given as string' do
+    @model.status = 'draft'
+    @model[:status].should == 1
+    @model.status.should == :draft
+    @model.status = 'unknown'
+    @model[:status].should == 0
+    @model.status.should == :unknown
+  end
+
+  specify 'should store enum value if key is given as integer equivalent' do
+    @model.status = 1
+    @model[:status].should == 1
+    @model.status.should == :draft
+    @model.status = 0
+    @model[:status].should == 0
+    @model.status.should == :unknown
+  end
+
+  specify 'should not define simple accessors by default' do
+    @model.methods.should_not include('unknown?')
+    @model.methods.should_not include('draft?')
+    @model.methods.should_not include('published?')
+  end
+
+  specify 'should not raise error when invalid value received' do
+    lambda { @model.status = :invalid }.should_not raise_error(ArgumentError)
+  end
+
+  specify 'should use default value 0 when invalid value received or current state invalid' do
+    @model[:status] = -1
+    @model.status.should == :unknown
+    @model.status = :published
+    @model.status.should == :published
+    @model.status = :invalid
+    @model[:status].should == 0
+    @model.status.should == :unknown
+  end
+
+  specify 'should return string value when _name method called' do
+    @model.status_name.should == 'unknown'
+    @model.status = :published
+    @model.status_name.should == 'published'
+  end
+
+  specify 'should not define named scopes by default' do
+    TestModel1.should_not_receive(:named_scope)
+  end
+
+end
+
+describe 'Model with magic enum and default value specified' do
+  include MagicEnumHelper
+
+  class TestModel2 < MagicEnumHelper::TestModelBase
+    define_enum :status, :default => 2
+  end
+
+  before do
+    @model = TestModel2.new
+  end
+
+  specify 'should use default value when current state is invalid' do
+    @model[:status] = -1
+    @model.status.should == :published
+  end
+
+  specify 'should use default value when invalid value received' do
+    @model.status = nil
+    @model.status.should == :published
+    @model.status = :invalid
+    @model.status.should == :published
+    @model[:status].should == 2
+  end
+
+  specify 'should not interpret nil in the same way as 0' do
+    @model[:status].should be_nil
+    @model.status.should == :published
+    @model[:status] = 0
+    @model.status.should == :unknown
+  end
+end
+
+describe 'Model with magic enum and raise_on_invalid option specified' do
+  include MagicEnumHelper
+
+  class TestModel3 < MagicEnumHelper::TestModelBase
+    define_enum :status, :raise_on_invalid => true
+  end
+
+  before do
+    @model = TestModel3.new
+  end
+
+  specify 'should raise error when invalid value received' do
+    lambda { @model.status = :invalid }.should raise_error(ArgumentError)
+  end
+
+  specify 'should show error description when invalid value received' do
+    begin
+      @model.status = :invalid
+    rescue => e
+      e.message.should == 'Invalid value "invalid" for :status attribute of the TestModel3 model'
+    end
+  end
+end
+
+
+describe 'Model with magic enum and simple_accessors option specified' do
+  include MagicEnumHelper
+
+  class TestModel4 < MagicEnumHelper::TestModelBase
+    define_enum :status, :simple_accessors => true
+  end
+
+  before do
+    @model = TestModel4.new
+  end
+
+  specify 'should define simple accessors by default' do
+    @model.methods.should include('unknown?')
+    @model.methods.should include('draft?')
+    @model.methods.should include('published?')
+  end
+end
+
+describe 'Model with magic enum and named_scopes option specified' do
+  include MagicEnumHelper
+
+  class TestModel5 < MagicEnumHelper::TestModelBase
+  end
+
+  specify 'should define named_scopes' do
+    TestModel5.should_receive(:named_scope).with(:unknowns, {:conditions=>["status = ?", 0]}).once
+    TestModel5.should_receive(:named_scope).with(:drafts, {:conditions=>["status = ?", 1]}).once
+    TestModel5.should_receive(:named_scope).with(:publisheds, {:conditions=>["status = ?", 2]}).once
+    TestModel5.should_receive(:named_scope).once # to handle the :of_status named_scope,
+                                                 # since we can't set an expectation with a Proc argument
+    TestModel5.send(:define_enum, :status, :named_scopes => true)
+  end
+end
+
+describe 'Model with magic enum and enum option specified' do
+  include MagicEnumHelper
+
+  class TestModel7 < MagicEnumHelper::TestModelBase
+    Roles = {
+      :user => 'u',
+      :admin => 'a'
+    }
+    define_enum :status, :enum => 'Roles'
+  end
+
+  before do
+    @model = TestModel7.new
+  end
+
+  specify 'should use custom enum' do
+    @model.status = :user
+    @model.status.should == :user
+    @model[:status].should == 'u'
+    @model.status = :admin
+    @model.status.should == :admin
+    @model[:status].should == 'a'
+  end
+
+  specify 'should use option with min value as default' do
+    @model.status = :invalid
+    @model.status.should == :admin
+  end
+end
+
+describe 'ActiveRecord::Base class' do
+  specify 'should include MagicEnum module' do
+    ActiveRecord::Base.included_modules.should include(MagicEnum)
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification 
+name: magic_enum
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Dmytro Shteflyuk
+- Oleksiy Kovyrin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-30 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - <=
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 3
+        - 2
+        version: "3.2"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: MagicEnum is a simple ActiveRecord plugin that makes it easier to maintain ENUM-like attributes in your models.
+email: alexey@kovyrin.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- init.rb
+- lib/magic_enum.rb
+- lib/magic_enum/version.rb
+- magic_enum.gemspec
+- spec/magic_enum_spec.rb
+homepage: https://github.com/kovyrin/magic-enum
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: ActiveRecord plugin that makes it easier to maintain ENUM-like attributes in your models
+test_files: []
+