enum-x 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b8f9f8f44090850e7af6d54f9d6ed30816053a25
+  data.tar.gz: be58187f64fc5fa9b350597619bc5b367671dd4f
+SHA512:
+  metadata.gz: 4633fcb4bd2f51bf0d751a2140fee3c963bffecfaf547aa73b409c206295e46979fcd0507ef25a32274255c56811fce08d4d4c8c741a81e4d8ac65cc0248f67a
+  data.tar.gz: ac105833237ace3f033fd259fe1c506857378604219d70a355e0c7fb25696ae08a7480f181d387a03e462d82383978b425fcf7ff0f38e2c51d1139fe37027c48

data/.gitignore

@@ -0,0 +1,29 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile ~/.gitignore_global
+
+# Ignore .DS_Store
+.DS_Store
+
+# Ignore the output files.
+/pkg
+
+# Ignore bundler and database config and precompiled assets
+/.bundle
+/.env
+
+# Ignore all logfiles and tempfiles.
+/tmp
+
+# Ignore TextMate projects
+*.tmproj
+*.sublime-project
+*.sublime-workspace
+
+# Documentation files and other stuff
+.yardoc
+/doc
+/nbproject
+/coverage

data/.ruby-gemset

@@ -0,0 +1 @@
+flux

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0-p247

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+* First version.

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,42 @@
+PATH
+  remote: .
+  specs:
+    enum-x (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.2.14)
+      activesupport (= 3.2.14)
+      builder (~> 3.0.0)
+    activesupport (3.2.14)
+      i18n (~> 0.6, >= 0.6.4)
+      multi_json (~> 1.0)
+    builder (3.0.4)
+    diff-lcs (1.2.4)
+    i18n (0.6.5)
+    multi_json (1.8.2)
+    rake (10.1.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.5)
+    rspec-expectations (2.14.2)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.3)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activemodel (~> 3.2)
+  bundler (~> 1.3)
+  enum-x!
+  rake
+  rspec (~> 2.14)
+  simplecov

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Joost Lubach
+
+MIT License
+
+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.md

@@ -0,0 +1,74 @@
+# EnumX
+
+Add an easy way to define a finite set of values for a certain field.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'enum-x'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install enum-x
+
+## Usage
+
+In the simplest form, you can use the `EnumX` class by itself:
+
+    enum = EnumX.new(:my_enum, %w[ one two three ])
+    my_variable = enum[:one]
+    my_variable.class    # => EnumX::Value
+    my_variable.to_s     # => 'one'
+    my_variable == :one  # => true
+
+Using the DSL, you can assign an enum to some attribute, much like most other enum-libraries:
+
+    class Post < ActiveRecord::Base
+      include EnumX::DSL
+
+      enum :status, %w[ draft published ]
+    end
+
+If you wish to re-use enums, you can share them by defining them centrally, e.g.
+
+**config/enums.yml:**
+
+    post_statuses: [ draft, published ]
+
+**app/models/post.rb:**
+
+    class Post < ActiveRecord::Base
+      include EnumX::DSL
+
+      enum :status, :post_statuses
+    end
+
+If you don't provide a second argument, the plural form is used:
+
+**config/enums.yml:**
+
+    currencies: [ euro, dollar ]
+
+**app/models/post.rb:**
+
+    class Price < ActiveRecord::Base
+      include EnumX::DSL
+
+      enum :currency
+      # => equivalent to 'enum :currency, :currencies'
+    end
+
+When using the DSL, a shortcut to the enum is created on the class. `Price.currencies` is a shortcut to `EnumX.currencies`, and `Post.statuses` is a shortcut to `EnumX.post_statuses`.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/enum-x.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'enum_x/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "enum-x"
+  spec.version       = EnumX::VERSION
+  spec.authors       = ["Joost Lubach"]
+  spec.email         = ["joost@yoazt.com"]
+  spec.description   = %q[Allows a finite set of values for any attribute.]
+  spec.summary       = %q[Allows a finite set of values for any attribute.]
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^test/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "activemodel", "~> 3.2"
+  spec.add_development_dependency "rspec", "~> 2.14"
+  spec.add_development_dependency "simplecov"
+end

data/lib/enum-x.rb

@@ -0,0 +1,2 @@
+# File provided as the gem is called 'enum-x'.
+require 'enum_x'

data/lib/enum_x/dsl.rb

@@ -0,0 +1,389 @@
+class EnumX
+
+  # Mixin for any ActiveRecord or ActiveModel object to support enums.
+  #
+  # == Usage
+  #
+  # First, make sure your model class includes +EnumX::DSL+:
+  #
+  #   include EnumX::DSL
+  #
+  # Then, define any enum-like attribute using the {#enum} method. The best enum is always
+  # inferred. The following are identical:
+  #
+  #   enum :status, :statuses
+  #   enum :status, EnumX.statuses
+  #   enum :status, EnumX[:statuses]
+  #   enum :status
+  #
+  # The latter infers the 'statuses' enum by default. If no applicable enum was found, an
+  # error is thrown.
+  #
+  # == Multi-enums
+  #
+  # Specify the option +:flags => true+ to allow the attribute to contain multiple enum values at
+  # once. The attribute will in essence become an array.
+  #
+  # @see ClassMethods#enum
+  module DSL
+
+    def self.included(target)
+      target.extend ClassMethods
+    end
+
+    ######
+    # DSL methods
+
+      module ClassMethods
+
+        # @!method enum(name, [enum], validation_options = {})
+        #
+        # Defines an enum for an attribute. This works on ActiveRecord objects, but also on other objects. However,
+        # for non-ActiveRecord objects, make sure that the underlying attribute already exists.
+        #
+        # @param [Symbol] attribute  The attribute to add enum support to.
+        # @param [EnumX|Enumerable|Symbol]
+        #   The enum to use. Specify a symbol to look up the enum from the defined enums, or use
+        #   an array to create an ad-hoc enum for this attribute, with name "#{model}_#{attribute.pluralize}",
+        #   e.g. 'post_statuses'.
+        # @param [Hash] validation_options
+        #   Options for the validation routine. The options listed below are extracted from this hash.
+        # @option validation_options :validation
+        #   Set to false to disable validation altogether. TODO SPEC
+        # @option validation_options :flags
+        #   Set to true to enable a flag enum attribute.
+        # @option validation_options :mnemonics
+        #   Set to true to create enum mnemonics on the receiver class. These are question-mark style methods for
+        #   all the values on the enum. Note that these may override existing methods, so use them only for enums
+        #   that define a part of the 'identity' of the receiving class, such as a status or a kind.
+        #
+        # @example The following creates an enum on an ActiveRecord object.
+        #   enum :kind                     # => Uses EnumX.kinds
+        # @example The following creates an enum on an ActiveRecord object, but uses 'account_kinds' as the name.
+        #   enum :kind, :account_kinds     # => Uses EnumX.account_kinds
+        # @example The following creates an enum on an ActiveRecord object, but uses a custom array.
+        #   class Account < ActiveRecord::Base
+        #     enum :kind, %w[ normal special ]  # => Uses an on the fly enum with name 'account_kinds'.
+        #   end
+        # @example The following creates an enum on an ActiveRecord object, but uses a custom array, on an anonymous class.
+        #   Class.new(ActiveRecord::Base) do
+        #     enum :kind, %w[ normal special ]  # => Uses an on the fly enum with name '_kinds'.
+        #   end
+        # @example The following creates an enum on a non-ActiveRecord class.
+        #   class Account
+        #     attr_accessor :kind   # Required first!
+        #     enum :kind
+        #   end
+        #
+        # @example The following creates an enum and creates mnemonics.
+        #   class Account < ActiveRecord::Base
+        #     enum :kind, :mnemonics => true
+        #   end
+        #
+        #   # Given that enum 'kinds' has options %[ normal special ], the following methods are now added:
+        #   Account.new(:kind => :normal).normal? # => true
+        #   Account.new(:kind => :special).normal? # => true
+        #   Account.new(:kind => :normal).special? # => false
+        #   Account.new(:kind => :special).special? # => false
+        #   Account.new(:kind => :special).something_else? # => raises NoMethodError
+        def enum(attribute, *args)
+
+          validation_options = args.extract_options!
+          enum = args.shift
+          raise ArgumentError, "too many arguments (2..3 expected)" if args.length > 0
+
+          flags = validation_options.delete(:flags)
+          mnemonics = validation_options.delete(:mnemonics)
+
+          # Determine the default name of the enum, and the name of the class-level enum reader.
+          enum_reader_name = if flags
+            # The attribute is already specified in the plural form (enum :statuses).
+            attribute.to_s
+          else
+            # The attribute is specified in the singular form - pluralize it (enum :status).
+            attribute.to_s.pluralize
+          end
+
+          enum = case enum_opt = enum
+          when nil then EnumX[enum_reader_name]
+          when EnumX then enum
+          when Symbol, String then EnumX[enum]
+          when Enumerable
+            name = if self.name
+              "#{self.name.demodulize.underscore}_#{enum_reader_name}"
+            else
+              # Anonymous class - use just the attribute name with an underscore in front of it.
+              "_#{enum_reader_name}"
+            end
+
+            EnumX.new(name, enum)
+          end
+          raise ArgumentError, "cannot find enum #{(enum_opt || enum_reader_name).inspect}" unless enum
+
+          # Define a shorthand enum accessor method.
+          unless respond_to?(enum_reader_name)
+            # Regular class. As the class may be inherited, make sure to try superclasses as well.
+            class_eval <<-RUBY, __FILE__, __LINE__+1
+              def self.#{enum_reader_name}
+                @#{enum_reader_name} ||= if superclass.respond_to?(:#{enum_reader_name})
+                  superclass.#{enum_reader_name}
+                end
+              end
+            RUBY
+          end
+
+          # Store the enum on this class.
+          instance_variable_set "@#{enum_reader_name}", enum
+
+          if flags
+            # Define a flags enum.
+
+            # Validation
+            if validation_options[:validation] != false
+
+              validation_options.assert_valid_keys :allow_blank
+              if validation_options[:allow_blank] != false
+                class_eval <<-RUBY, __FILE__, __LINE__+1
+                  validates_each :#{attribute} do |record, attribute, value|
+                    if value.present?
+                      value = [ value ] unless value.is_a?(Enumerable)
+                      if not_included_value = value.find{ |v| !enum.values.include?(v) }
+                        record.errors.add attribute, :inclusion, :value => not_included_value
+                      end
+                    end
+                  end
+                RUBY
+              else
+                class_eval <<-RUBY, __FILE__, __LINE__+1
+                  validates_each :#{attribute} do |record, attribute, value|
+                    value = [ value ] unless value.is_a?(Enumerable) || value.nil?
+                    if value.blank?
+                      record.errors.add attribute, :blank
+                    elsif not_included_value = value.find{ |v| !enum.values.include?(v) }
+                      record.errors.add attribute, :inclusion, :value => not_included_value
+                    end
+                  end
+                RUBY
+              end
+
+            end
+
+            # Serialize the value if this is an ActiveRecord class AND if the database actually contains
+            # this column.
+            if defined?(ActiveRecord) && self < ActiveRecord::Base && self.column_names.include?(attribute.to_s)
+              serialize attribute, FlagsSerializer.new(enum)
+            end
+
+            # Provide a customized reader.
+            DSL.define_multi_reader self, attribute
+            DSL.define_multi_writer self, attribute
+
+            # Provide two Squeel sifters.
+            if respond_to?(:sifter)
+              class_eval <<-RUBY, __FILE__, __LINE__+1
+                sifter(:#{attribute}_include) { |value| instance_eval('#{attribute}') =~ "%|\#{value}|%" }
+                sifter(:#{attribute}_exclude) { |value| instance_eval('#{attribute}') !~ "%|\#{value}|%" }
+              RUBY
+            end
+
+          else
+            # Define a single enum.
+
+            # Validation
+            if validation_options[:validation] != false
+              # Provide validations.
+              validation_options = validation_options.merge(:in => enum.values)
+              validation_options[:allow_blank] = true unless validation_options.key?(:allow_blank)
+
+              validates_inclusion_of attribute, validation_options
+            end
+
+            # Serialize the value if this is an ActiveRecord class AND if the database actually contains
+            # this column.
+            if defined?(ActiveRecord) && self < ActiveRecord::Base && self.column_names.include?(attribute.to_s)
+              serialize attribute, SingleSerializer.new(enum)
+            end
+
+            # Provide a customized reader.
+            DSL.define_single_reader self, attribute
+            DSL.define_single_writer self, attribute
+
+          end
+
+          # Provide mnemonics if requested
+          DSL.define_mnemonics self, attribute, enum if mnemonics
+
+        end
+
+      end
+
+    ######
+    # Generic reader & writer
+
+      # Defines a generic attribute reader ActiveModel-like classes.
+      # @api private
+      def self.define_reader(target, attribute, body)
+        override = target.instance_methods.include?(attribute.to_sym)
+
+        value_reader = case true
+        when override
+          "#{attribute}_without_enums"
+        when target.instance_methods.include?(:read_attribute) || target.private_instance_methods.include?(:read_attribute)
+          "read_attribute(:#{attribute})"
+        else
+          # We need a reader to fall back to.
+          raise "cannot overwrite enum reader - no existing reader found"
+        end
+
+        body.gsub! '%{read_value}', value_reader
+
+        if override
+          target.class_eval <<-RUBY, __FILE__, __LINE__+1
+            def #{attribute}_with_enums
+              #{body}
+            end
+            alias_method_chain :#{attribute}, :enums
+          RUBY
+        else
+          target.class_eval <<-RUBY, __FILE__, __LINE__+1
+            def #{attribute}
+              #{body}
+            end
+          RUBY
+        end
+      end
+
+      # Defines a generic attribute writer ActiveModel-like classes.
+      # @api private
+      def self.define_writer(target, attribute, body)
+        method = :"#{attribute}="
+        override = target.instance_methods.include?(method)
+
+        value_writer = case true
+        when override
+          "self.#{attribute}_without_enums = value"
+        when target.instance_methods.include?(:write_attribute) || target.private_instance_methods.include?(:write_attribute)
+          "write_attribute :#{attribute}, value"
+        else
+          # We need a writer to fall back to.
+          raise "cannot overwrite enum writer - no existing writer found"
+        end
+
+        body.gsub! '%{write_value}', value_writer
+
+        if override
+          target.class_eval <<-RUBY, __FILE__, __LINE__+1
+            def #{attribute}_with_enums=(value)
+              #{body}
+            end
+            alias_method_chain :#{attribute}=, :enums
+          RUBY
+        else
+          target.class_eval <<-RUBY, __FILE__, __LINE__+1
+            def #{attribute}=(value)
+              #{body}
+            end
+          RUBY
+        end
+      end
+
+    ######
+    # Single enum reader & writer
+
+      def self.define_single_reader(target, attribute)
+        define_reader target, attribute, <<-RUBY
+          case value = %{read_value}
+          when EnumX::Value then value
+          when nil then nil
+          else
+            enum = EnumX.find(self.class, :#{attribute.to_s.pluralize})
+            enum[value] || value
+          end
+        RUBY
+      end
+
+      def self.define_single_writer(target, attribute)
+        define_writer target, attribute, <<-RUBY
+          value = case value
+          when EnumX::Value then value
+          when nil then nil
+          else
+            enum = EnumX.find(self.class, :#{attribute.to_s.pluralize})
+            enum[value] || value
+          end
+          %{write_value}
+        RUBY
+      end
+
+    ######
+    # Multi enum reader & writer
+
+      def self.define_multi_reader(target, attribute)
+        define_reader target, attribute, <<-RUBY
+          enum = EnumX.find(self.class, :#{attribute.to_s})
+          case value = %{read_value}
+          when nil then nil
+          when EnumX::ValueList then value
+          when Enumerable then EnumX::ValueList.new(enum, value)
+          else EnumX::ValueList.new(enum, [value])
+          end
+        RUBY
+      end
+
+      def self.define_multi_writer(target, attribute)
+        define_writer target, attribute, <<-RUBY
+          enum = EnumX.find(self.class, :#{attribute.to_s})
+          value = case value
+          when nil then nil
+          when EnumX::ValueList then value
+          when Enumerable then EnumX::ValueList.new(enum, value)
+          else EnumX::ValueList.new(enum, [value])
+          end
+          %{write_value}
+        RUBY
+      end
+
+    ######
+    # Mnemonics (single & multi)
+
+      def self.define_mnemonics(target, attribute, enum)
+        enum.values.each do |value|
+          target.class_eval <<-RUBY, __FILE__, __LINE__+1
+            def #{value}?
+              :#{value} === #{attribute}
+            end
+          RUBY
+        end
+      end
+
+    ######
+    # Serializer
+
+      class SingleSerializer
+        def initialize(enum)
+          @enum = enum
+        end
+
+        def load(text) @enum[text] end
+        def dump(value) value.to_s end
+      end
+
+      class FlagsSerializer
+        def initialize(enum)
+          @enum = enum
+        end
+
+        def load(text)
+          EnumX::ValueList.new(@enum, text.to_s.split('|').reject(&:blank?))
+        end
+
+        def dump(list)
+          # This is the case for using the values from changes and the list is allready a string
+          list = load(list).values unless list.is_a?(EnumX::ValueList)
+          "|#{list.map(&:to_s).join('|')}|"
+        end
+      end
+
+  end
+
+end

data/lib/enum_x/monkey.rb

@@ -0,0 +1,51 @@
+# This file contains extensions to Symbol and String so that enum values can be
+# used in case statementes
+
+# Extend Symbol and String's == and === method to match equal enum values as well
+Symbol.class_eval do
+  def triple_equals_with_enums(arg)
+    if arg.is_a?(EnumX::Value)
+      triple_equals_without_enums arg.symbol
+    elsif arg.is_a?(EnumX::ValueList)
+      arg.include?(self)
+    else
+      triple_equals_without_enums arg
+    end
+  end
+  def double_equals_with_enums(arg)
+    if arg.is_a?(EnumX::Value)
+      double_equals_without_enums arg.symbol
+    else
+      double_equals_without_enums arg
+    end
+  end
+
+  alias :triple_equals_without_enums :===
+  alias :=== :triple_equals_with_enums
+  alias :double_equals_without_enums :==
+  alias :== :double_equals_with_enums
+end
+
+String.class_eval do
+  def triple_equals_with_enums(arg)
+    if arg.is_a?(EnumX::Value)
+      triple_equals_without_enums arg.value
+    elsif arg.is_a?(EnumX::ValueList)
+      arg.include?(self)
+    else
+      triple_equals_without_enums arg
+    end
+  end
+  def double_equals_with_enums(arg)
+    if arg.is_a?(EnumX::Value)
+      double_equals_without_enums arg.value
+    else
+      double_equals_without_enums arg
+    end
+  end
+
+  alias :triple_equals_without_enums :===
+  alias :=== :triple_equals_with_enums
+  alias :double_equals_without_enums :==
+  alias :== :double_equals_with_enums
+end

data/lib/enum_x/railtie.rb

@@ -0,0 +1,14 @@
+require File.expand_path('..', __FILE__)
+
+class EnumX
+  class Railtie < Rails::Railtie
+
+    config.enum_x = ActiveSupport::OrderedOptions.new
+    config.enum_x.load_paths = []
+
+    initializer 'enum.set_load_paths', :before => :finisher_hook do |app|
+      EnumX.load_paths.concat app.config.enum_x.load_paths
+    end
+
+  end
+end