enumbler 0.5.0 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2eb7435b5b57b7fa3b04f7201bc41b3caaea6f148af6998fbdad02bdd44794bd
-  data.tar.gz: cf198237307efcbc457e55c3b046e612ba44a9fef52b86bb47f02a0989350df0
+  metadata.gz: 29989e16025afc87b0db8fd70347b21978c683ab44c6ffa2d1f44a22c20fb166
+  data.tar.gz: 807a16dd6e6ff6e8c95b3f5337acf2f1ea456d07378dc702b8f2672c0b862276
 SHA512:
-  metadata.gz: e39538cefdfe366d8c944732796c0354c49f7fbc9930d7f3a4fb7912b6088188a1b1dbbd9f9395a4ea67f2c857a1ea7490f3631285daec68c388c19779b95602
-  data.tar.gz: f490870fc3d1bfe7f7a10bad501619668929f351f2882455e5e7da0581511957bd95fa08c77c09715e4b54f659212f742736256e9bca4706e906d1e0b3629551
+  metadata.gz: 2c8dbf495025d467ee30172289097169d84d23776320a1624d5e3920f2f66e738f606a15e61e2bbce696051c6d87ec99c811c45b3d9cdcb631f7e3bd1b961409
+  data.tar.gz: 3a6d12fe63ff37e1274b5ec3ec31023aa08f520f455b44695746a5555a20bc063283fbd6afaf2f9831d740588bcf090426647f052c1bc87e98d829a071a9fc7d

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    enumbler (0.5.0)
-      activerecord (~> 6.0.2)
-      activesupport (~> 6.0.2)
+    enumbler (0.6.3)
+      activerecord (>= 5.2.3, < 6.1)
+      activesupport (>= 5.2.3, < 6.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -26,6 +26,7 @@ Suppose you have a `House` and you want to add some `colors` to the house.  You
 ActiveRecord::Schema.define do
   create_table :colors|t|
     t.string :label, null: false, index: { unique: true }
+    t.string :hex, null: true
   end
 
   create_table :houses|t|
@@ -42,8 +43,8 @@ end
 class Color < ApplicationRecord
   include Enumbler::Enabler
 
-  enumble :black, 1
-  enumble :white, 2
+  enumble :black, 1, hex: '000000'
+  enumble :white, 2, hex: 'ffffff'
   enumble :dark_brown, 3
   enumble :infinity, 4, label: 'Infinity - and beyond!'
 end
@@ -60,17 +61,43 @@ Color.black.black?         # => true
 Color.black.is_black       # => true
 Color.white.not_black?     # => true
 
+# Get attributes without hitting the database
 Color.black(:id)           # => 1
 Color.black(:enum)         # => :black
 Color.black(:label)        # => 'black'
 Color.black(:graphql_enum) # => 'BLACK'
 
+# Get an Enumble object from an id, label, enum, or ActiveRecord model
+Color.find_enumbles(:black, 'white') # => [Enumbler::Enumble<:black>, Enumbler::Enumble<:white>]
+Color.find_enumbles(:black, 'does-not-exist') # => [Enumbler::Enumble<:black>, nil]
+
+Color.find_enumble(:black) # => Enumbler::Enumble<:black>
+
+# raises errors if none found
+Color.find_enumbles!!(:black, 'does-no-exist') # => raises Enumbler::Error
+Color.find_enumble!(:does_not_exist) # => raises Enumbler::Error
+
+# Get ids flexibly, without raising an error if none found
+Color.ids_from_enumbler(:black, 'white') # => [1, 2]
+Color.ids_from_enumbler(:black, 'does-no-exist') # => [1, nil]
+
+# Raise an error if none found
+Color.ids_from_enumbler!(:black, 'does-no-exist') # => raises Enumbler::Error
+Color.id_from_enumbler!(:does_not_exist) # => raises Enumbler::Error
+
+# Get enumble object by id
 house = House.create!(color: Color.black)
-house.black?
-house.not_black?
+
+# These are all db-free lookups
+house.color_label        # => 'black'
+house.color_enum         # => :black
+house.color_graphql_enum # => 'BLACK'
+house.black?             # => true
+house.not_black?         # => false
 
 house2 = House.create!(color: Color.white)
-House.color(:black, :white) # => [house, house2]
+House.color(:black, :white)      # => ActiveRecord::Relation<house, house2>
+House.color(Color.black, :white) # => ActiveRecord::Relation<house, house2>
 ```
 
 ### Use a column other than `label`

data/enumbler.gemspec

@@ -29,8 +29,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'activerecord', '~> 6.0.2'
-  spec.add_dependency 'activesupport', '~> 6.0.2'
+  spec.add_dependency 'activerecord', ['>= 5.2.3', '< 6.1']
+  spec.add_dependency 'activesupport', ['>= 5.2.3', '< 6.1']
 
   spec.add_development_dependency 'database_cleaner-active_record', '~> 1.8.0'
   spec.add_development_dependency 'fuubar', '~> 2.5'

data/lib/enumbler.rb

@@ -65,6 +65,7 @@ module Enumbler
 
       belongs_to(name, scope, **options)
 
+      define_helper_attributes(name)
       define_dynamic_methods_for_enumbled_to_models(enumbled_model, prefix: prefix, scope_prefix: scope_prefix)
     rescue NameError
       raise Error, "The model #{class_name} cannot be found.  Uninitialized constant."
@@ -86,6 +87,10 @@ module Enumbler
         where(column_name => enumbled_model.ids_from_enumbler(args))
       end
 
+      define_singleton_method("#{cmethod}!") do |*args|
+        where(column_name => enumbled_model.ids_from_enumbler!(args))
+      end
+
       enumbled_model.enumbles.each do |enumble|
         method_name = prefix ? "#{model_name}_#{enumble.enum}?" : "#{enumble.enum}?"
         not_method_name = prefix ? "#{model_name}_not_#{enumble.enum}?" : "not_#{enumble.enum}?"
@@ -93,5 +98,16 @@ module Enumbler
         define_method(not_method_name) { self[column_name] != enumble.id }
       end
     end
+
+    # Add the attirbutes:
+    #
+    #   house.color_label #=> 'black'
+    #   house.color_enum  #=> :black
+    #   house.color_graphql_enum #=> 'BLACK'
+    def define_helper_attributes(name)
+      %i[label enum graphql_enum].each do |sym|
+        define_method("#{name}_#{sym}") { send(name).enumble.send(sym) }
+      end
+    end
   end
 end

data/lib/enumbler/enabler.rb

@@ -40,8 +40,8 @@ module Enumbler
       #   class Color < ApplicationRecord
       #     include Enumbler::Enabler
       #
-      #     enumble :black, 1
-      #     enumble :white, 2
+      #     enumble :black, 1, hex: '000000'
+      #     enumble :white, 2, hex: 'ffffff'
       #     enumble :dark_brown, 3, # label: 'dark-brown'
       #     enumble :black_hole, 3, label: 'Oh my! It is a black hole!'
       #   end
@@ -55,14 +55,16 @@ module Enumbler
       # @param enum [Symbol] the enum representation
       # @param id [Integer] the primary key value
       # @param label [String] optional: label for humans
-      # @param **options [Hash] optional: additional attributes and values that
+      # @param **attributes [Hash] optional: additional attributes and values that
       #   will be saved to the database for this enumble record
-      def enumble(enum, id, label: nil, **options)
+      def enumble(enum, id, label: nil, **attributes)
         @enumbles ||= Enumbler::Collection.new
         @enumbled_model = self
         @enumbler_label_column_name ||= :label
 
-        enumble = Enumble.new(enum, id, label: label, label_column_name: @enumbler_label_column_name, **options)
+        raise_error_if_model_does_not_support_attributes(attributes)
+
+        enumble = Enumble.new(enum, id, label: label, label_column_name: @enumbler_label_column_name, **attributes)
 
         if @enumbles.include?(enumble)
           raise Error, "You cannot add the same Enumble twice! Attempted to add: #{enum}, #{id}."
@@ -97,6 +99,93 @@ module Enumbler
         @enumbler_label_column_name = label_column_name
       end
 
+      # See {.find_enumbles}.  Simply returns the first object.  Use when you
+      # want one argument to be found and not returned in an array.
+      # @raise [Error] when there is no [Enumbler::Enumble] to be found and
+      #   `raise_error: true`
+      # @param args [Integer, String, Symbol]
+      # @param case_sensitive [Boolean] should a String search be case sensitive
+      #   (default: false)
+      # @param raise_error [Boolean] raise an error if not found (default:
+      #   false)
+      # @return [Enumbler::Enumble]
+      def find_enumble(arg, case_sensitive: false, raise_error: false)
+        find_enumbles(arg, case_sensitive: case_sensitive, raise_error: raise_error).first
+      end
+
+      # See {.find_enumbles}.  Simply returns the first object.  Use when you
+      # want one argument to be found and not returned in an array. Raises error
+      # if none found.
+      # @raise [Error] when there is no [Enumbler::Enumble] to be found and
+      #   `raise_error: true`
+      # @param args [Integer, String, Symbol]
+      # @param case_sensitive [Boolean] should a String search be case sensitive
+      #   (default: false)
+      # @return [Enumbler::Enumble]
+      def find_enumble!(arg, case_sensitive: false)
+        find_enumbles(arg, case_sensitive: case_sensitive, raise_error: true).first
+      end
+
+      # Finds an array of {Enumbler::Enumble} objects matching the given
+      # argument. Accepts an Integer, String, Symbol, or ActiveRecord instance.
+      #
+      # This method is designed to let you get information about the record
+      # without having to hit the database.  Returns `nil` when none found
+      # unless `raise_error` is `true`.
+      #
+      #    Color.find_enumbles(:black, 'white', 'not-found')
+      #      #=> [Enumbler::Enumble<:black>, Enumbler::Enumble<:white>, nil]
+      #
+      # @raise [Error] when there is no [Enumbler::Enumble] to be found and
+      #   `raise_error: true`
+      # @param args [Integer, String, Symbol]
+      # @param case_sensitive [Boolean] should a String search be case sensitive
+      #   (default: false)
+      # @param raise_error [Boolean] raise an error if not found (default:
+      #   false)
+      # @return [Array<Enumbler::Enumble>]
+      def find_enumbles(*args, case_sensitive: false, raise_error: false)
+        args.flatten.compact.uniq.map do |arg|
+          err = "Unable to find a #{@enumbled_model}#enumble with #{arg}"
+
+          begin
+            arg = Integer(arg) # raises Type error if not a real integer
+            enumble = @enumbled_model.enumbles.find { |e| e.id == arg }
+          rescue TypeError, ArgumentError
+            enumble =
+              if arg.is_a?(Symbol)
+                @enumbled_model.enumbles.find { |e| e.enum == arg }
+              elsif arg.is_a?(String)
+                @enumbled_model.enumbles.find do |e|
+                  case_sensitive ? e.label == arg : arg.casecmp?(e.label)
+                end
+              elsif arg.instance_of?(@enumbled_model)
+                arg.enumble
+              end
+          end
+
+          if enumble.present?
+            enumble
+          else
+            raise Error if raise_error
+
+            nil
+          end
+        rescue Error
+          raise Error, err
+        end
+      end
+
+      # See {.find_enumbles}.  Same method, only raises error when none found.
+      # @raise [Error] when there is no [Enumbler::Enumble] to be found
+      # @param args [Integer, String, Symbol]
+      # @param case_sensitive [Boolean] should a String search be case sensitive
+      #   (default: false)
+      # @return [Array<Enumbler::Enumble>]
+      def find_enumbles!(*args, case_sensitive: false)
+        find_enumbles(*args, case_sensitive: case_sensitive, raise_error: true)
+      end
+
       # Return the record id for a given argument.  Can accept an Integer, a
       # Symbol, or an instance of Enumbled model.  This lookup is a database-free
       # lookup.
@@ -107,9 +196,25 @@ module Enumbler
       #
       # @raise [Error] when there is no enumble to be found
       # @param arg [Integer, Symbol, Class]
+      # @param case_sensitive [Boolean] should a string search be performed with
+      #   case sensitivity (default: false)
+      # @param raise_error [Boolean] raise an error if not found (default:
+      #   false)
       # @return [Integer]
-      def id_from_enumbler(arg)
-        ids_from_enumbler(arg).first
+      def id_from_enumbler(arg, case_sensitive: false, raise_error: false)
+        ids_from_enumbler(arg, case_sensitive: case_sensitive, raise_error: raise_error).first
+      end
+
+      # See {.ids_from_enumbler}.  Raises error if none found.
+      # @raise [Error] when there is no enumble to be found
+      # @param arg [Integer, Symbol, Class]
+      # @param case_sensitive [Boolean] should a string search be performed with
+      #   case sensitivity (default: false)
+      # @param raise_error [Boolean] raise an error if not found (default:
+      #   false)
+      # @return [Integer]
+      def id_from_enumbler!(arg, case_sensitive: false)
+        ids_from_enumbler(arg, case_sensitive: case_sensitive, raise_error: true).first
       end
 
       # Return the record id(s) based on different argument types.  Can accept
@@ -118,30 +223,30 @@ module Enumbler
       #
       #   Color.ids_from_enumbler(1, 2) # => [1, 2]
       #   Color.ids_from_enumbler(:black, :white) # => [1, 2]
+      #   Color.ids_from_enumbler('black', :white) # => [1, 2]
       #   Color.ids_from_enumbler(Color.black, Color.white) # => [1, 2]
       #
       # @raise [Error] when there is no enumble to be found
       # @param *args [Integer, Symbol, Class]
+      # @param case_sensitive [Boolean] should a string search be performed with
+      #   case sensitivity (default: false)
+      # @param raise_error [Boolean] raise an error if not found (default:
+      #   false)
       # @return [Array<Integer>]
-      def ids_from_enumbler(*args)
-        args.flatten.compact.uniq.map do |arg|
-          err = "Unable to find a #{@enumbled_model}#enumble with #{arg}"
-
-          begin
-            arg = Integer(arg) # raises Type error if not a real integer
-            enumble = @enumbled_model.enumbles.find { |e| e.id == arg }
-          rescue TypeError
-            enumble = if arg.is_a?(Symbol)
-                        @enumbled_model.enumbles.find { |e| e.enum == arg }
-                      elsif arg.instance_of?(@enumbled_model)
-                        arg.enumble
-                      end
-          end
+      def ids_from_enumbler(*args, case_sensitive: false, raise_error: false)
+        enumbles = find_enumbles(*args, case_sensitive: case_sensitive, raise_error: raise_error)
+        enumbles.map { |e| e&.id }
+      end
 
-          enumble&.id || raise(Error, err)
-        rescue Error
-          raise Error, err
-        end
+      # See {.ids_from_enumbler}.  Raises error when none found.
+      # @raise [Error] when there is no enumble to be found
+      # @param *args [Integer, Symbol, Class]
+      # @param case_sensitive [Boolean] should a string search be performed with
+      #   case sensitivity (default: false)
+      # @return [Array<Integer>]
+      def ids_from_enumbler!(*args, case_sensitive: false)
+        enumbles = find_enumbles!(*args, case_sensitive: case_sensitive)
+        enumbles.map(&:id)
       end
 
       # Seeds the database with the Enumbler data.
@@ -150,7 +255,7 @@ module Enumbler
       # @param validate [Boolean] validate on save?
       def seed_the_enumbler(delete_missing_records: false, validate: true)
         max_database_id = all.order('id desc').take&.id || 0
-        max_enumble_id = enumbles.map(&:id).max
+        max_enumble_id = @enumbles.map(&:id).max
 
         # If we are not deleting records, we just need to update each listed
         # enumble and skip anything else in the database.  If we are deleting
@@ -207,6 +312,20 @@ module Enumbler
           raise Enumbler::Error, "The attribute #{attr} is not supported on this Enumble."
         end
       end
+
+      def raise_error_if_model_does_not_support_attributes(attributes)
+        return if attributes.blank?
+
+        unsupported_attrs = attributes.reject { |key, _value| has_attribute?(key) }
+
+        return if unsupported_attrs.blank?
+
+        raise Enumbler::Error,
+          "The model #{self} does not support the attribute(s): #{unsupported_attrs.keys.map(&:to_s).to_sentence}"
+      rescue ActiveRecord::StatementInvalid
+        warn "[Enumbler Warning] => Unable to find a table for #{self}."\
+          'This is to be expected if there is a pending migration; however, if there is not then something is amiss.'
+      end
     end
   end
 end

data/lib/enumbler/enumble.rb

@@ -2,18 +2,15 @@
 
 module Enumbler
   # Class that holds each row of Enumble data.
-  #
-  # @todo We need to support additional options/attributes beyond the id/label
-  #   pairs.  Is on the backburner for a moment.
   class Enumble
-    attr_reader :id, :enum, :label, :label_column_name, :options
+    attr_reader :id, :enum, :label, :label_column_name
 
-    def initialize(enum, id, label: nil, label_column_name: :label, **options)
+    def initialize(enum, id, label: nil, label_column_name: :label, **attributes)
       @id = id
       @enum = enum
       @label = label || enum.to_s.dasherize
       @label_column_name = label_column_name
-      @options = options
+      @additional_attributes = attributes || {}
     end
 
     def ==(other)
@@ -22,10 +19,20 @@ module Enumbler
     end
 
     def attributes
-      {
+      @additional_attributes.merge({
         id: id,
         label_column_name => label,
-      }
+      })
+    end
+
+    # Used to return itself from a class method.
+    #
+    # ```
+    # Color.black(:enumble) #=> <Enumble:0x00007fb4396a78c8>
+    # ```
+    # @return [Enumbler::Enumble]
+    def enumble
+      self
     end
 
     def eql?(other)

data/lib/enumbler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Enumbler
-  VERSION = '0.5.0'
+  VERSION = '0.6.3'
 end

metadata

@@ -1,43 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: enumbler
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.3
 platform: ruby
 authors:
 - Damon Timm
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-01 00:00:00.000000000 Z
+date: 2020-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.3
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 6.0.2
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.3
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 6.0.2
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.3
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 6.0.2
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.3
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 6.0.2
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: database_cleaner-active_record
   requirement: !ruby/object:Gem::Requirement