enumbler 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac96c64c119c34aa4efbc77eaa1caa227d213e1efd631fac9089dbcb70f3f04b
-  data.tar.gz: 5e2d1125473c01f1e05728cf0f26f7dea219a7755da4db844535164156a6b104
+  metadata.gz: 7cd7368add18afee559a79a18b15a28f3aa19514ce3037f88dc1425781a9dd85
+  data.tar.gz: d76ebcf6de0265bdd3cee78e745cafb9e81fe6edbdf6ff91ca93cf968d3243e4
 SHA512:
-  metadata.gz: 40297daeee09865736136e47095f68e7540e91bed081da0613e2e33558c127c7fe4521c8233e6d1d426cc7c37bb3e147d1216ed9f0684a039a89ab59199c3256
-  data.tar.gz: cff2b4a1a1d94cd67dba49f141a0ed3b8820ffed03de69edebee6a59a47a0a84b4e3a581d418bf174ebb523353e9ffc03e27de3ebaa61e408c10d1ed9a17c580
+  metadata.gz: f66a6d30caeced56ca38e50d70c4d892ae96c91a11208693c6a23e6561f02ffdce820f6dfb85deabb8a96bed52927e88d4321c9b0891041f4085495a7c1293a0
+  data.tar.gz: 38d99ad670bbf880cc7f3ef5bf5775f8aa3eec1b8511518f61fbfeaafa5ede38be3d7db49a1c67cd99386b199be132e205764b30a095eccf841e6fe44b481f63

data/.github/workflows/ruby.yml

@@ -13,7 +13,7 @@ jobs:
 
     strategy:
       matrix:
-        ruby_version: [2.5, 2.6]
+        ruby_version: [2.5, 2.6, 2.7]
 
     steps:
     - uses: actions/checkout@v2
@@ -37,6 +37,8 @@ jobs:
         bundle exec rspec
 
   build:
+    needs: rspec
+
     name: Publish Gem
     runs-on: ubuntu-latest
 
@@ -46,7 +48,7 @@ jobs:
     - name: Set up Ruby
       uses: actions/setup-ruby@v1
       with:
-        version: 2.7.x
+        ruby-version: 2.7.x
 
     - name: Publish to RubyGems
       run: |

data/.rubocop.yml

@@ -21,6 +21,9 @@ Lint/RaiseException:
 Lint/StructNewOverride:
   Enabled: true
 
+Style/Documentation:
+  Enabled: false
+
 Style/HashEachMethods:
   Enabled: true
 
@@ -38,20 +41,5 @@ Style/TrailingCommaInArrayLiteral:
   Enabled: true
   EnforcedStyleForMultiline: consistent_comma
 
-Metrics/BlockLength:
+Metrics:
   Enabled: false
-
-Metrics/AbcSize:
-  Enabled: false
-
-Metrics/CyclomaticComplexity:
-  Enabled: false
-
-Metrics/MethodLength:
-  Max: 30
-
-Metrics/ModuleLength:
-  Max: 300
-
-Metrics/ClassLength:
-  Max: 300

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    enumbler (0.1.0)
+    enumbler (0.2.0)
       activerecord (>= 6.0)
       activesupport (>= 6.0)
 

data/README.md

@@ -1,6 +1,56 @@
 # Enumbler
 
-`Enums` are terrific, but they lack integrity.  Enumbler!
+`Enums` are terrific, but they lack integrity.  Enumbler! The _enum enabler_!  The goal is to allow one to maintain a true foreign_key database driven relationship that also behaves a little bit like an `enum`.  Best of both worlds?  We hope so.
+
+
+## Example
+
+Suppose you have a `House` and you want to add some `colors` to the house.  You are tempted to use an `enum` but the `Enumbler` is calling!
+
+```ruby
+ActiveRecord::Schema.define do
+  create_table :colors|t|
+    t.string :label, null: false
+  end
+
+  create_table :houses|t|
+    t.references :color, foreign_key: true, null: false
+  end
+end
+
+class ApplicationRecord < ActiveRecord::Base
+  include Enumbler
+  self.abstract_class = true
+end
+
+# Our Color has been Enumbled with some basic colors.
+class Color < ApplicationRecord
+  include Enumbler::Enabler
+
+  enumble :black, 1
+  enumble :white, 2
+  enumble :dark_brown, 3
+  enumble :infinity, 4, label: 'Infinity - and beyond!'
+end
+
+# Our House class, it has a color of course!
+class House < ApplicationRecord
+  enumbled_to :color
+end
+
+# This gives you some power:
+Color::BLACK           # => 1
+Color.black            # => equivalent to Color.find(1)
+Color.black.black?     # => true
+Color.black.is_black   # => true
+Color.white.not_black? # => true
+
+house = House.create!(color: Color.black)
+house.black?
+house.not_black?
+
+House.color(:black) # => [house]
+```
 
 ## Installation
 

data/enumbler.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'A more complete description is forthcoming.'
   spec.homepage      = 'https://github.com/linguabee/enumbler'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 

data/lib/enumbler/enabler.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Enumbler
+  module Enabler
+    extend ActiveSupport::Concern
+
+    # The Enumble definition that this record defined.
+    # @return [Enumbler::Enumble]
+    def enumble
+      @enumble = self.class.enumbles.find { |enumble| enumble.id == id }
+
+      raise Error, 'An enumble is not defined for this record!' if @enumble.nil?
+
+      @enumble
+    end
+
+    # These ClassMethods can be included in any model that you wish to
+    # _Enumble_!
+    #
+    #   class Color < ApplicationRecord
+    #     include Enumbler::Enabler
+    #
+    #     enumble :black, 1
+    #     enumble :white, 2
+    #   end
+    #
+    module ClassMethods
+      attr_reader :enumbles
+
+      # Defines an Enumble for this model.  An enum with integrity.
+      #
+      #   # in your migration
+      #   create_table :colors, force: true do |t|
+      #     t.string :label, null: false
+      #   end
+      #
+      #   class Color < ApplicationRecord
+      #     include Enumbler::Enabler
+      #
+      #     enumble :black, 1
+      #     enumble :white, 2
+      #     enumble :dark_brown, 3, # label: 'dark-brown'
+      #     enumble :black_hole, 3, label: 'Oh my! It is a black hole!'
+      #   end
+      #
+      #   # Dynamically adds the following methods:
+      #   Color::BLACK   #=> 1
+      #   Color.black    #=> Color.find(1)
+      #   color.black?   #=> true || false
+      #   color.is_black #=> true || false
+      #
+      # @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
+      #   will be saved to the database for this enumble record
+      def enumble(enum, id, label: nil, **options)
+        @enumbles ||= []
+        @enumbled_model = self
+
+        enumble = Enumble.new(enum, id, label: label, **options)
+
+        if @enumbles.include?(enumble)
+          raise Error, "You cannot add the same Enumble twice! Attempted to add: #{enum}, #{id}."
+        end
+
+        define_dynamic_methods_and_constants_for_enumbled_model(enum, id)
+
+        @enumbles << enumble
+      end
+
+      # Return the record id(s) based on different argument types.  Can accept an
+      # Integer, a Symbol, or an instance of Enumbled model.  This lookup is a
+      # databse-free lookup.
+      #
+      #   Color.ids_from_enumablable(1, 2) # => [1, 2]
+      #   Color.ids_from_enumablable(:black, :white) # => [1, 2]
+      #   Color.ids_from_enumablable(Color.black, Color.white) # => [1, 2]
+      #
+      # @raise [Error] when there is no enumble to be found
+      # @param *args [Integer, Symbol, Class]
+      # @return [Array<Integer>]
+      def ids_from_enumablable(*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
+
+          enumble&.id || raise(Error, err)
+        rescue Error
+          raise Error, err
+        end
+      end
+
+      # Seeds the database with the Enumble data.
+      # @param delete_missing_records [Boolean] remove any records that are no
+      #   longer defined (default: false)
+      def seed_the_enumbler(delete_missing_records: false)
+        max_database_id = all.order('id desc').take&.id || 0
+        max_enumble_id = enumbles.map(&:id).max
+
+        max_id = max_enumble_id > max_database_id ? max_enumble_id : max_database_id
+
+        discarded_ids = []
+
+        (1..max_id).each do |id|
+          enumble = @enumbles.find { |e| e.id == id }
+
+          if enumble.nil?
+            discarded_ids << id
+            next
+          end
+
+          record = find_or_initialize_by(id: id)
+          record.attributes = enumble.attributes
+          record.save!
+        end
+
+        where(id: discarded_ids).delete_all if delete_missing_records
+      end
+
+      # Seeds the database with the Enumble data, removing any records that are no
+      # longer defined.
+      def seed_the_enumbler!
+        seed_the_enumbler(delete_missing_records: true)
+      end
+
+      private
+
+      def define_dynamic_methods_and_constants_for_enumbled_model(enum, id)
+        method_name = "#{enum}?"
+        not_method_name = "not_#{enum}?"
+        alias_method_name = "is_#{enum}"
+
+        const_set(enum.to_s.upcase, id)
+        define_method(method_name) { self.id == id }
+        define_method(not_method_name) { self.id != id }
+        alias_method alias_method_name, method_name
+        define_singleton_method(enum) { find(id) }
+      end
+    end
+  end
+end

data/lib/enumbler/version.rb

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

data/lib/enumbler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'enumbler/enumble'
+require 'enumbler/enabler'
 require 'enumbler/version'
 
 require 'active_support/concern'
@@ -10,65 +11,23 @@ require 'active_support/inflector'
 module Enumbler
   extend ActiveSupport::Concern
 
+  # An error raised by the Enumbler.
   class Error < StandardError; end
 
-  # The Enumble definition that this record defined.
-  # @return [Enumbler::Enumble]
-  def enumble
-    @enumble = self.class.enumbles.find { |enumble| enumble.id == id }
-
-    raise Error, 'An enumble is not defined for this record!' if @enumble.nil?
-
-    @enumble
-  end
-
-  # These are the ClassMethods that are added to an ApplicationRecord model when
-  # `include Enumbler` is added to the class.
+  # Include these ClassMethods in your base ApplicationRecord model to bestow
+  # any of your models with the ability to be connected to an Enumbled relation
+  # in the same way you would use `belongs_to` now you use `enumbled_to`.
+  #
+  #   class ApplicationRecord > ActiveRecord::Base
+  #     include Enumbler
+  #     self.abstract_class = true
+  #   end
+  #
+  #   class House < ApplicationRecord
+  #     enumbled_to :color
+  #   end
+  #
   module ClassMethods
-    attr_reader :enumbles
-
-    # Defines an Enumble for this model.  An enum with integrity.
-    #
-    #   # in your migration
-    #   create_table :colors, force: true do |t|
-    #     t.string :label, null: false
-    #   end
-    #
-    #   class Color < ApplicationRecord
-    #     include Enumbler
-    #
-    #     enumble :black, 1
-    #     enumble :white, 2
-    #     enumble :dark_brown, 3, # label: 'dark-brown'
-    #     enumble :black_hole, 3, label: 'Oh my! It is a black hole!'
-    #   end
-    #
-    #   # Dynamically adds the following methods:
-    #   Color::BLACK   #=> 1
-    #   Color.black    #=> MyRecord.find(1)
-    #   color.black?   #=> true || false
-    #   color.is_black #=> true || false
-    #
-    # @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
-    #   will be saved to the database for this enumble record
-    def enumble(enum, id, label: nil, **options)
-      @enumbles ||= []
-      @enumbled_model = self
-
-      enumble = Enumble.new(enum, id, label: label, **options)
-
-      if @enumbles.include?(enumble)
-        raise Error, "You cannot add the same Enumble twice! Attempted to add: #{enum}, #{id}."
-      end
-
-      define_dynamic_methods_and_constants_for_enumbled_model(enum, id)
-
-      @enumbles << enumble
-    end
-
     # Defines the relationship between a model and the Enumbled class.  Use this
     # in lieu of `belongs_to` to establish that relationship.  It requires a
     # model that has defined one or more `Enumbles`.
@@ -78,117 +37,59 @@ module Enumbler
     #     t.references :color, foreign_key: true, null: false
     #   end
     #
-    #   class House < ApplicationRecord
+    #   class ApplicationRecord > ActiveRecord::Base
     #     include Enumbler
+    #     self.abstract_class = true
+    #   end
+    #
+    #   class House < ApplicationRecord
     #     enumbled_to :color
     #   end
     #
     # @param name [Symbol] symbol representation of the class this belongs_to
-    # @param *args [Array] additional arguments passed to `belongs_to`
-    def enumbled_to(name, scope = nil, prefix: nil, **options)
+    # @param prefix [Boolean] default: false; prefix the instance method
+    #   attributes with the Enumble name, ex: `House.color_black?` instead of
+    #   `House.black?`
+    # @param scope_prefix [string] optional, prefix the class scopes, for
+    #   example: `where_by` will make it `House.where_by_color(:black)`
+    # @param **options [Hash] additional options passed to `belongs_to`
+    def enumbled_to(name, scope = nil, prefix: false, scope_prefix: nil, **options)
       class_name = name.to_s.classify
-      @enumbled_model = class_name.constantize
+      enumbled_model = class_name.constantize
 
-      unless @enumbled_model.respond_to?(:enumbles)
-        raise Error, "The class #{class_name} does not have any enumbles defined."\
+      unless enumbled_model.respond_to?(:enumbles)
+        raise Error, "The model #{class_name} does not have any enumbles defined."\
           " You can add them via `#{class_name}.enumble :blue, 1`."
       end
 
       belongs_to(name, scope, **options)
 
-      define_dynamic_methods_for_enumbled_to_models(prefix: prefix)
+      define_dynamic_methods_for_enumbled_to_models(enumbled_model, prefix: prefix, scope_prefix: scope_prefix)
     rescue NameError
-      raise Error, "The class #{class_name} cannot be found.  Uninitialized constant."
-    end
-
-    # Return the record id(s) based on different argument types.  Can accept an
-    # Integer, a Symbol, or an instance of Enumbled model.  This lookup is a
-    # databse-free lookup.
-    #
-    #   Color.ids_from_enumablable(1, 2) # => [1, 2]
-    #   Color.ids_from_enumablable(:black, :white) # => [1, 2]
-    #   Color.ids_from_enumablable(Color.black, Color.white) # => [1, 2]
-    #
-    # @raise [Error] when there is no enumble to be found
-    # @param *args [Integer, Symbol, Class]
-    # @return [Array<Integer>]
-    def ids_from_enumablable(*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
-
-        enumble&.id || raise(Error, err)
-      rescue Error
-        raise Error, err
-      end
-    end
-
-    # Seeds the database with the Enumble data.
-    # @param delete_missing_records [Boolean] remove any records that are no
-    #   longer defined (default: false)
-    def seed_the_enumbler(delete_missing_records: false)
-      max_database_id = all.order('id desc').take&.id || 0
-      max_enumble_id = enumbles.map(&:id).max
-
-      max_id = max_enumble_id > max_database_id ? max_enumble_id : max_database_id
-
-      discarded_ids = []
-
-      (1..max_id).each do |id|
-        enumble = @enumbles.find { |e| e.id == id }
-
-        if enumble.nil?
-          discarded_ids << id
-          next
-        end
-
-        record = find_or_initialize_by(id: id)
-        record.attributes = enumble.attributes
-        record.save!
-      end
-
-      where(id: discarded_ids).delete_all if delete_missing_records
-    end
-
-    # Seeds the database with the Enumble data, removing any records that are no
-    # longer defined.
-    def seed_the_enumbler!
-      seed_the_enumbler(delete_missing_records: true)
+      raise Error, "The model #{class_name} cannot be found.  Uninitialized constant."
     end
 
     private
 
-    def define_dynamic_methods_and_constants_for_enumbled_model(enum, id)
-      method_name = "#{enum}?"
-      alias_method_name = "is_#{enum}"
-
-      const_set(enum.to_s.upcase, id)
-      define_method(method_name) { self.id == id }
-      alias_method alias_method_name, method_name
-      define_singleton_method(enum) { find(id) }
-    end
-
-    def define_dynamic_methods_for_enumbled_to_models(prefix: nil)
-      model_name = @enumbled_model.to_s.underscore
-
-      method = if prefix.blank?
-                 model_name
-               else
-                 "#{prefix}_#{model_name}"
-               end
+    # Define the dynamic methods for this relationship.
+    #
+    # @todo - we should check for naming conflicts!
+    #     dangerous_attribute_method?(method_name)
+    #     method_defined_within?(method_name, self, Module)
+    def define_dynamic_methods_for_enumbled_to_models(enumbled_model, prefix: false, scope_prefix: nil)
+      model_name = enumbled_model.to_s.underscore
+      column_name = "#{model_name}_id"
+
+      cmethod = scope_prefix.blank? ? model_name : "#{scope_prefix}_#{model_name}"
+      define_singleton_method(cmethod) do |*args|
+        where(column_name => enumbled_model.ids_from_enumablable(args))
+      end
 
-      define_singleton_method(method) do |*args|
-        where("#{model_name}_id": ids_from_enumablable(args))
+      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}?"
+        define_method(method_name) { self[column_name] == enumble.id }
+        define_method(not_method_name) { self[column_name] != enumble.id }
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enumbler
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Damon Timm
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-10 00:00:00.000000000 Z
+date: 2020-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -144,6 +144,7 @@ files:
 - bin/setup
 - enumbler.gemspec
 - lib/enumbler.rb
+- lib/enumbler/enabler.rb
 - lib/enumbler/enumble.rb
 - lib/enumbler/version.rb
 homepage: https://github.com/linguabee/enumbler
@@ -162,7 +163,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="