mongoid_enum 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b67dcfd5fb5d061dd20797d9ebe7dc54114030d2
+  data.tar.gz: 982b2d073dd01bb563f8446b05f37a9e30dee7a7
+SHA512:
+  metadata.gz: 19171e4d95f8c56c387306f2745af4a685ac3122e5d9804dfe9bc1db84866a32fdde3fa90f5d2805abe8a6522f9d44d2d63122c94739412a24378bccbd92f13d
+  data.tar.gz: 0732be4b09f52e3b8a6b3896d52c61b51aa5fbdcf31a3d9212ca7b26e7bc92e8f06733c22b30a251025119b5150309981a638d5ea23c91122c025cb16cd55ebe

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2013 David Heinemeier Hansson and other Rails contributors
+Copyright (c) 2015 Adam Wróbel
+
+
+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,71 @@
+# Introduction
+
+Enum implementation for Mongoid. Similar to that found in ActiveRecord.
+
+# Installation
+
+    gem "mongoid_enum"
+
+# Usage
+
+By default values saved to DB are strings matching enum labels.
+
+    class Conversation
+      include Mongoid::Document
+      include Mongoid::Enum
+
+      enum status: [ :active, :archived ]
+    end
+
+    conversation = Conversation.active.first
+    conversation.active?   # true
+    conversation.archived! # immediately saves document
+    conversation.active?   # false
+    conversation["status"] # "archived"
+
+You can use other Mongo value types (numbers, booleans, nil) when explicitly defining
+the enum mapping:
+
+    class Part
+      include Mongoid::Document
+      include Mongoid::Enum
+
+      enum quality_control: {pending: nil, passed: true, failed: false}, _prefix: :qc
+    end
+
+    part = Part.qc_pending.first
+    part.quality_control    # "pending"
+    part.qc_passed!
+    part.quality_control    # "passed"
+    part["quality_control"] # true
+
+Enum values are validated.
+
+    part.quality_control = "unknown value"
+    part.valid? # false
+
+You can access the mapping as hash with indifferent access via class level constant.
+Constant name is a pluralized field name set in SCREAMING\_SNAKE\_CASE.
+
+    Part::QUALITY_CONTROLS["passed"] # true
+    Part::QUALITY_CONTROLS[:failed]  # false
+
+# Differences from ActiveRecord
+
+1. Default values are strings, not integers. I think it fits MongoDB better.
+
+2. Mapping hash is accessible via class constant instead of class method. I prefer
+   constant because it is accessible without prefix both on class methods and instance
+   methods. Also I think SCREAMING\_SNAKE\_CASE is less likely to cause name conflicts.
+
+3. I do not raise exception when invalid value is assigned. Instead document fails
+   validation. Assigned invalid value is remembered and can be corrected in forms.
+   Exception will still be raised if you try to save invalid label by skipping validation
+   (`save validate: false`). That's because the document does not know how to convert
+   invalid enum option to database value.
+
+# Credits
+
+Original implementation for ActiveRecord was created by David Heinemeier Hansson.
+Following modifications by other Rails contributors. Port to Mongoid prepared by Adam
+Wróbel.

data/lib/mongoid/enum/enum_type.rb

@@ -0,0 +1,43 @@
+module Mongoid
+  module Enum
+    # Internal: Mapping wrapper used as type for enum fields.
+    #
+    # Handles label-value conversion.
+    class EnumType # :nodoc:
+      attr_reader :mappings
+
+      def initialize(mappings)
+        @mappings = mappings
+      end
+
+      def mongoize(key)
+        if key.blank?
+          value = nil
+        elsif mappings.key? key
+          value = mappings[key]
+        elsif mappings.value? key
+          # XXX Mongoid may try to mongoize multiple times so if key is a valid value
+          # assume that it has already been converted to value.
+          value = key
+        else
+          value = Enum::InvalidKey.new(key)
+        end
+        value
+      end
+      alias_method :evolve, :mongoize
+
+      def demongoize(value)
+        if mappings.value? value
+          key = mappings.key value
+        elsif value.blank?
+          key = nil
+        elsif value.is_a? Enum::InvalidKey
+          key = value.original_key
+        else
+          key = Enum::InvalidValue.new(value)
+        end
+        key
+      end
+    end
+  end
+end

data/lib/mongoid/enum/invalid_key.rb

@@ -0,0 +1,22 @@
+module Mongoid
+  module Enum
+    # raised when InvalidKey is forced to be saved in DB (skipping validation)
+    class InvalidKeyError < StandardError
+    end
+
+    # Internal: Wraps invalid keys passed to setter so that getter returns the same key.
+    class InvalidKey # :nodoc:
+      attr_reader :original_key
+
+      def initialize(key)
+        @original_key = key
+      end
+
+      def raise_error
+        raise InvalidKeyError, "invalid enum key: #{original_key}"
+      end
+      alias_method :bson_type, :raise_error
+      alias_method :to_bson, :raise_error
+    end
+  end
+end

data/lib/mongoid/enum/invalid_value.rb

@@ -0,0 +1,14 @@
+module Mongoid
+  module Enum
+    # Public: Wraps invalid values loaded from DB before returning them via getter.
+    class InvalidValue
+      # Public: Holds the value loaded from DB that is not part of defined enum.
+      attr_reader :database_value
+
+      # :nodoc:
+      def initialize(value)
+        @database_value = value
+      end
+    end
+  end
+end

data/lib/mongoid/enum.rb

@@ -0,0 +1,255 @@
+require "mongoid/enum/enum_type"
+require "mongoid/enum/invalid_key"
+require "mongoid/enum/invalid_value"
+
+module Mongoid # :nodoc:
+  # Declare an enum field with scope and value checking helper methods. Example:
+  #
+  #   class Conversation
+  #     include Mongoid::Document
+  #     include Mongoid::Enum
+  #
+  #     enum status: [ :active, :archived ]
+  #   end
+  #
+  #   # conversation.update! status: "active"
+  #   conversation.active!
+  #   conversation.active? # => true
+  #   conversation.status  # => "active"
+  #
+  #   # conversation.update! status: "archived"
+  #   conversation.archived!
+  #   conversation.archived? # => true
+  #   conversation.status    # => "archived"
+  #
+  #   conversation.status = nil
+  #   conversation.status.nil? # => true
+  #   conversation.status      # => nil
+  #
+  # Scopes based on the allowed values of the enum field will be provided
+  # as well. With the above example:
+  #
+  #   Conversation.active
+  #   Conversation.archived
+  #
+  # Of course, you can also query them directly if the scopes don't fit your
+  # needs:
+  #
+  #   Conversation.where(status: [:active, :archived])
+  #   Conversation.not.where(status: :active)
+  #
+  # You can set the default value:
+  #
+  #   class Conversation
+  #     include Mongoid::Document
+  #     include Mongoid::Enum
+  #
+  #     enum status: [ :active, :archived ], _default: :active
+  #   end
+  #
+  # Finally, it's also possible to explicitly map the relation between attribute and
+  # values stored in the database with a hash. The values don't even need to be Strings.
+  # Numbers, Booleans, nil and some others are allowed.
+  #
+  #   class Conversation
+  #     include Mongoid::Document
+  #     include Mongoid::Enum
+  #
+  #     enum status: { active: 0, archived: 1 }
+  #   end
+  #
+  # The mappings are exposed through a class constant with the pluralized attribute
+  # name. It defines the mapping in a +HashWithIndifferentAccess+:
+  #
+  #   Conversation::STATUSES[:active]    # => 0
+  #   Conversation::STATUSES["archived"] # => 1
+  #
+  # Defining an enum automatically adds a validator on its field. Assigning values
+  # not included in enum definition will make the document invalid.
+  #
+  #   conversation = Conversation.new
+  #   conversation.status = :unknown
+  #   conversation.valid? # false
+  #
+  # Default validator allows nil values. Add your own presence validator if you require
+  # a value for the enum field.
+  #
+  #   class Conversation
+  #     include Mongoid::Document
+  #     include Mongoid::Enum
+  #
+  #     enum status: { active: 0, archived: 1 }
+  #
+  #     validates :status, presence: true
+  #   end
+  #
+  #
+  # You can use the +:_prefix+ or +:_suffix+ options when you need to define
+  # multiple enums with same values. If the passed value is +true+, the methods
+  # are prefixed/suffixed with the name of the field. It is also possible to
+  # supply a custom value:
+  #
+  #   class Conversation
+  #     include Mongoid::Document
+  #     include Mongoid::Enum
+  #
+  #     enum status: [:active, :archived], _suffix: true
+  #     enum comments_status: [:active, :inactive], _prefix: :comments
+  #   end
+  #
+  # With the above example, the bang and predicate methods along with the
+  # associated scopes are now prefixed and/or suffixed accordingly:
+  #
+  #   conversation.active_status!
+  #   conversation.archived_status? # => false
+  #
+  #   conversation.comments_inactive!
+  #   conversation.comments_active? # => false
+  #
+  # If you want to you can give nil value an explicit label.
+  #
+  #   class Part
+  #     include Mongoid::Document
+  #     include Mongoid::Enum
+  #
+  #     enum quality_control: {pending: nil, passed: true, failed: false}, _prefix: :qc
+  #   end
+  #
+  #   part = Part.qc_pending.first
+  #   part.qc_pending? # true
+  #   part.qc_passed!
+  #   part.qc_pending? # false
+  module Enum
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute(:enums)
+      self.enums = {}
+    end
+
+    # :nodoc:
+    module ClassMethods
+      # Define enum field on the model. See description of Mongoid::Enum
+      def enum(definitions)
+        klass = self
+        enum_prefix = definitions.delete(:_prefix)
+        enum_suffix = definitions.delete(:_suffix)
+        default_key = definitions.delete(:_default)
+
+        definitions.each do |name, values|
+          enum_values = ActiveSupport::HashWithIndifferentAccess.new
+          name        = name.to_sym
+          const_name  = name.to_s.pluralize.upcase
+
+          if klass.const_defined?(const_name)
+            fail ArgumentError, "Defining enum :#{name} on #{klass} would " \
+              "overwrite existing constant #{klass}::#{const_name}"
+          end
+
+          detect_enum_conflict!(name, name)
+          detect_enum_conflict!(name, "#{name}=")
+
+          if values.respond_to? :each_pair
+            values.each_pair { |key, value| enum_values[key.to_s] = value }
+          else
+            values.each { |v| enum_values[v.to_s] = v.to_s }
+          end
+
+          enum_values.each do |key, value|
+            key.freeze
+            value.freeze
+          end
+          enum_values.freeze
+
+          if default_key && !enum_values.key?(default_key)
+            fail ArgumentError, "default key #{default_key} is not among enum options"
+          end
+
+          field name, type: EnumType.new(enum_values), default: default_key
+
+          klass.const_set const_name, enum_values
+          klass.validates name,
+                          inclusion: {
+                            in: enum_values.keys,
+                            allow_nil: true,
+                            message: "is invalid"
+                          }
+
+          _enum_methods_module.module_eval do
+            enum_values.each do |key, value|
+              if enum_prefix == true
+                prefix = "#{name}_"
+              elsif enum_prefix
+                prefix = "#{enum_prefix}_"
+              end
+              if enum_suffix == true
+                suffix = "_#{name}"
+              elsif enum_suffix
+                suffix = "_#{enum_suffix}"
+              end
+
+              value_method_name = "#{prefix}#{key}#{suffix}"
+
+              # def active?() status == 0 end
+              klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
+              define_method("#{value_method_name}?") { self[name] == value }
+
+              # def active!() update! status: :active end
+              klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
+              define_method("#{value_method_name}!") { update! name => key }
+
+              # scope :active, -> { where status: 0 }
+              klass.send(:detect_enum_conflict!, name, value_method_name, true)
+              klass.scope value_method_name, -> { klass.where name => key }
+            end
+          end
+
+          # dup so children classes don't add their own enums to parent definitions
+          self.enums = enums.dup
+
+          enums[name] = enum_values
+          enums.freeze
+        end
+      end
+
+      private
+
+      def _enum_methods_module
+        @_enum_methods_module ||= begin
+          mod = Module.new
+          include mod
+          mod
+        end
+      end
+
+      # :nodoc:
+      ENUM_CONFLICT_MESSAGE = \
+        "You tried to define an enum named \"%{enum}\" on the model \"%{klass}\", but " \
+        "this will generate %{type} method \"%{method}\", which is already defined."
+
+      def detect_enum_conflict!(enum_name, method_name, class_method = false)
+        method_name = method_name.to_sym
+
+        if class_method
+          if self.respond_to?(method_name, true)
+            raise_conflict_error(enum_name, method_name, "class")
+          end
+        else
+          if Mongoid.destructive_fields.include?(method_name) ||
+             instance_methods.include?(method_name)
+            raise_conflict_error(enum_name, method_name, "instance")
+          end
+        end
+      end
+
+      def raise_conflict_error(enum_name, method_name, type)
+        fail ArgumentError, ENUM_CONFLICT_MESSAGE % {
+          enum: enum_name,
+          klass: name,
+          type: type,
+          method: method_name
+        }
+      end
+    end
+  end
+end

data/lib/mongoid_enum.rb

@@ -0,0 +1 @@
+require "mongoid/enum"

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: mongoid_enum
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Adam Wróbel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-11-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: factory_girl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.35.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.35.1
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+description: Fields with closed set of possible values and helper methods to query/set
+  them by label.
+email: adam@adamwrobel.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- LICENSE
+- README.md
+- lib/mongoid/enum.rb
+- lib/mongoid/enum/enum_type.rb
+- lib/mongoid/enum/invalid_key.rb
+- lib/mongoid/enum/invalid_value.rb
+- lib/mongoid_enum.rb
+homepage: https://github.com/amw/mongoid_enum
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+- "--markup=tomdoc"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Enum fields for Mongoid
+test_files: []
+has_rdoc: