guise 0.6.0 → 0.6.1

data/lib/guise/syntax.rb

@@ -5,98 +5,173 @@ require 'active_support/core_ext/string/inflections'
 
 module Guise
   module Syntax
+    # Setup the model's `guises` association. Given the following setup:
+    #
+    # ```ruby
+    # class User < ActiveRecord::Base
+    #   has_guises :DeskWorker, :MailForwarder, association: :roles, attribute: :value
+    # end
+    # ```
+    #
+    # The following is configured:
+    #
+    # * `has_many` association named according to the `:association` option.
+    # * `User.desk_workers` and `User.mail_forwarders` model scopes.
+    # * `User#has_guise?` that checks if a user is a particular type.
+    # * `User#desk_worker?`, `User#mail_forwarder?` that proxy to `User#has_guise?`.
+    # * `User#has_guises?` that checks if a user has records for all the types
+    #   supplied. This is aliased to `User#has_roles?`.
+    # * `User#has_any_guises?` that checks if a user has records for any of the
+    #   types supplied. This is aliased to `User#has_any_roles?`.
+    # * If the association name is not `:guises`:
+    #   * Aliases the association methods to equivalent methods for `guises`
+    #     (i.e. `guises=` to `roles=`).
+    #   * Aliases the introspection methods (i.e. `has_guise?` to `has_role?`
+    #     and `has_any_guises?` to `has_any_roles?`
+    #
+    # @overload has_guises(*guises, options)
+    #   @param [Array<Symbol, String>] *guises names of guises that should be
+    #     allowed
+    #   @param [Hash] options options to configure the association
+    #   @option options [Symbol] :association name of the association to define.
+    #     This option is required.
+    #   @option options [Symbol] :attribute name of the association's column
+    #     where the value of which guise is being represented is stored. This
+    #     option is required.
     def has_guises(*guises)
       include Introspection
 
-      options = guises.last.is_a?(Hash) ? guises.pop : {}
-
-      guises      = guises.map(&:to_s)
-      association = options.fetch(:association)
-      attribute   = options.fetch(:attribute)
-      join_table  = options[:table_name] || association
-
-      Guise.registry[self.name] = {
-        names: guises,
-        association: association,
-        attribute: attribute
-      }
-
-      guises.each do |guise|
-        method_name = guise.underscore
-        scope method_name.pluralize, -> { select("#{self.table_name}.*").joins(association).where(join_table => { attribute => guise }) }
-
-        define_method "#{method_name}?" do
-          has_guise?(guise)
-        end
-      end
-
-      has_many association, options.except(:association, :attribute, :table_name)
-
-      if association != :guises
-        association_singular = association.to_s.singularize
-
-        alias_method :guises, association
-        alias_method :guises=, "#{association}="
-        alias_method :guise_ids, "#{association_singular}_ids"
-        alias_method :guise_ids=, "#{association_singular}_ids="
-        alias_method "has_#{association_singular}?", :has_guise?
-        alias_method "has_#{association}?", :has_guises?
-        alias_method "has_any_#{association}?", :has_any_guises?
-      end
+      Guise.register_source(self, *guises)
     end
 
-    def guise_of(class_name)
-      options = Guise.registry[class_name]
-
-      if options.nil?
-        raise ArgumentError, "no guises defined on #{class_name}"
-      end
-
-      default_scope -> { send(model_name.plural) }
-
-      after_initialize SourceCallback.new(self.name, options[:attribute])
+    # Specifies that the model is a subclass of a model configured with
+    # {#has_guises} specified by `class_name`.
+    #
+    # Configures the caller with the correct `default_scope`. Given the
+    # following definition with `has_guises`:
+    #
+    # ```ruby
+    # class User < ActiveRecord::Base
+    #   has_guises :DeskWorker, :MailForwarder, association: :roles, attribute: :title
+    # end
+    # ```
+    #
+    # The following call to `guise_of`:
+    #
+    # class DeskWorker < User
+    #   guise_of :User
+    # end
+    # ```
+    #
+    # Is equivalent to:
+    #
+    # ```ruby
+    # class DeskWorker < User
+    #   default_scope -> { desk_workers }
+    #
+    #   after_initialize do
+    #     self.guises.build(title: 'DeskWorker')
+    #   end
+    #
+    #   after_create do
+    #     self.guises.create(title: 'DeskWorker')
+    #   end
+    # end
+    # ```
+    #
+    # @param [String, Symbol] source_class_name name of the superclass
+    #   configured with {#has_guises}.
+    def guise_of(source_class_name)
+      options = Guise.registry[source_class_name]
+
+      default_scope GuiseOfScope.new(name, options)
+      after_initialize SourceCallback.new(name, options.attribute)
     end
 
-    def guise_for(class_name, options = {})
-      guise_options = Guise.registry[class_name]
-
-      if guise_options.nil?
-        raise ArgumentError, "no guises defined on #{class_name}"
-      end
-
-      association = class_name.to_s.underscore.to_sym
-      guises      = guise_options[:names]
-      attribute   = guise_options[:attribute]
-      foreign_key = options[:foreign_key] || "#{class_name.to_s.underscore}_id"
-
-      belongs_to association, options.except(:validate)
-
-      guises.each do |guise|
-        scope guise.underscore.pluralize, -> { where(attribute => guise) }
-      end
-
-      if options[:validate] != false
-        validates attribute, uniqueness: { scope: foreign_key }, presence: true, inclusion: { in: guises }
-      end
+    # Configures the other end of the association defined by {#has_guises}.
+    # Defines equivalent scopes defined on the model configured with
+    # {#has_guises}.
+    #
+    # Given the following configuring of `has_guises`:
+    #
+    # ```ruby
+    # class User < ActiveRecord::Base
+    #   has_guises :DeskWorker, :MailForwarder, association: :roles, attribute: :title
+    # end
+    # ```
+    #
+    # The following call to `guise_for`:
+    #
+    # ```ruby
+    # class Role < ActiveRecord::Base
+    #   guise_for :User
+    # end
+    # ```
+    #
+    # Is equivalent to:
+    #
+    # ```ruby
+    # class Role < ActiveRecord::Base
+    #   belongs_to :user
+    #
+    #   validates :title, presence: true, uniqueness: { scope: :user_id }, inclusion: { in: %w( DeskWorker MailForwarder ) }
+    #
+    #   scope :desk_workers, -> { where(title: "DeskWorker") }
+    #   scope :mail_forwarder, -> { where(title: "MailForwarder") }
+    # end
+    # ```
+    #
+    # @param [Symbol, String] source_class_name name of the class configured
+    #   with {#has_guises}
+    # @param [Hash] options options to configure the `belongs_to` association.
+    # @option options [false] :validate specify `false` to skip
+    #   validations for the `:attribute` specified in {#has_guises}
+    # @option options [Symbol] :foreign_key foreign key used to build the
+    #   association.
+    def guise_for(source_class_name, options = {})
+      Guise.register_association(self, source_class_name, options)
     end
 
-    def scoped_guise_for(class_name)
-      guise_options = Guise.registry[class_name]
-
-      if guise_options.nil?
-        raise ArgumentError, "no guises defined on #{class_name}"
-      end
-
-      attribute = guise_options[:attribute]
-      parent_name = table_name.classify
-
-      value = guise_options[:names].detect do |guise|
-        guise == model_name.to_s.chomp(parent_name)
-      end
-
-      default_scope -> { where(attribute => value) }
-
-      after_initialize AssociationCallback.new(value, attribute)
+    # Specifies that the model is a subclass of a model configured with
+    # {#guise_for} specified by `class_name`. The name of the calling class must
+    # be `<value|parent_class_name>`.
+    #
+    # Given the following configuration with `guise_for`:
+    #
+    # ```ruby
+    # class Role < ActiveRecord::Base
+    #   guise_for :User
+    # end
+    # ```
+    #
+    # The following call to `scoped_guise_for`:
+    #
+    # ```ruby
+    # class DeskWorkerRole < Role
+    #   scoped_guise_for :Role
+    # end
+    # ```
+    #
+    # Is equivalent to:
+    #
+    # ```ruby
+    # class DeskWorkerRole < Role
+    #   default_scope -> { desk_workers }
+    #
+    #   after_initialize do
+    #     self.title = "DeskWorker"
+    #   end
+    # end
+    # ```
+    #
+    # @param [Symbol, String] association_class_name name of the superclass
+    #   configured with {#guise_for}.
+    def scoped_guise_for(association_class_name)
+      options = Guise.registry[association_class_name]
+      value = name.chomp(options.association_class.name)
+
+      default_scope options.scope(value, :guise_for)
+      after_initialize AssociationCallback.new(value, options.attribute)
     end
   end
 end

data/lib/guise/version.rb

@@ -1,3 +1,3 @@
 module Guise
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/spec/guise_spec.rb

@@ -1,9 +1,15 @@
 require 'spec_helper'
 
 describe Guise do
-  let!(:user) { create(:user) }
-  let!(:supervisor) { create(:supervisor) }
-  let!(:technician) { create(:technician) }
+  let!(:user) { User.create!(email: "bob@bob.bob") }
+  let!(:supervisor) { Supervisor.create!(email: "jane@manag.er") }
+  let!(:technician) { Technician.create!(email: "sarah@fix.it") }
+
+  def self.active_record_has_pluck_and_not_version_4_0?
+    ActiveRecord::VERSION::STRING >= "4.1" ||
+      ActiveRecord::VERSION::STRING <= "3.2" &&
+      ActiveRecord::Relation.method_defined?(:pluck)
+  end
 
   after do
     User.delete_all
@@ -12,28 +18,76 @@ describe Guise do
 
   describe ".has_guises" do
     it "sets up has_many association" do
-      expect(user).to have_many :user_roles
+      reflection = User.reflect_on_association(:user_roles)
+
+      expect(reflection).not_to be_nil
     end
 
     it "adds scopes for each type" do
-      technicians = User.technicians
+      technicians = User.technicians.map(&:id)
+
+      expect(technicians).to include technician.id
+      expect(technicians).not_to include user.id
+      expect(technicians).not_to include supervisor.id
+    end
+
+    shared_examples(
+      "building and saving associated records"
+    ) do |source, strategy|
+      it "sets up scopes to correctly create associated records" do
+        technician = source.public_send(strategy)
+
+        expect(technician).to be_technician
+        expect(technician.user_roles.map(&:name)).to eq ["Technician"]
+
+        if technician.new_record?
+          technician.save!
+
+          expect(technician.reload).to be_technician
+        end
+      end
+    end
 
-      expect(technicians).to include technician
-      expect(technicians).not_to include user
-      expect(technicians).not_to include supervisor
+    include_examples(
+      "building and saving associated records",
+      User.technicians,
+      :new
+    )
+
+    include_examples(
+      "building and saving associated records",
+      User.technicians,
+      :create
+    )
+
+    include_examples(
+      "building and saving associated records",
+      Technician,
+      :new
+    )
+
+    include_examples(
+      "building and saving associated records",
+      Technician,
+      :create
+    )
+
+    if active_record_has_pluck_and_not_version_4_0?
+      it "sets up scopes to correctly handle `ActiveRecord::Relation#pluck`" do
+        expect(Technician.all.pluck(:id)).to eq [technician.id]
+      end
     end
 
     it 'aliases the association methods to `guise=` and `guises=`' do
-      record = create(:user)
+      record = User.create!
 
       expect(record.guises).to eq []
 
-      # NOTE: The user is assigned in factory_girl to deal with a Rails 3.1
-      # issue
-      record.guises = [build(:user_role, user: record)]
-      record.guises << build(:user_role, name: 'Supervisor', user: record)
+      # NOTE: The user is assigned to deal with a Rails 3.1 issue
+      record.guises = [UserRole.new(name: "Technician", user: record)]
+      record.guises << UserRole.new(name: "Supervisor", user: record)
 
-      expect(record.guises(true).length).to eq 2
+      expect(record.reload.guises.length).to eq 2
 
       expect(record.guise_ids.length).to eq 2
 
@@ -43,10 +97,11 @@ describe Guise do
     end
 
     it 'handles non-standard table names and foreign key attributes' do
-      person = create(:person)
-      create(:permission, person: person)
+      person = Person.create!
+      Permission.create!(person: person, privilege: "Admin")
+      reflection = Person.reflect_on_association(:permissions)
 
-      expect(person).to have_many :permissions
+      expect(reflection).not_to be_nil
       expect(Person.admins).to include person
     end
   end
@@ -67,8 +122,8 @@ describe Guise do
     end
 
     it 'ignores records marked for destruction' do
-      technician_role = build(:user_role, name: 'Technician')
-      technician_user = create(:user, user_roles: [technician_role])
+      technician_role = UserRole.new(name: "Technician")
+      technician_user = User.create(user_roles: [technician_role])
 
       expect(technician_user).to have_guise :technician
 
@@ -84,12 +139,15 @@ describe Guise do
     it 'is wrapped for each guise specified' do
       expect(user).not_to be_technician
       expect(technician).to be_technician
+
+      expect(user).not_to be_explorer
+      expect(technician).not_to be_explorer
     end
   end
 
   describe "#has_guises?" do
     before do
-      @role = create(:user_role, name: 'Technician', user: supervisor)
+      @role = UserRole.create!(name: "Technician", user: supervisor)
     end
 
     after do
@@ -102,9 +160,9 @@ describe Guise do
     end
 
     it 'ignores records marked for destruction' do
-      technician_role = build(:user_role, name: 'Technician')
-      supervisor_role = build(:user_role, name: 'Supervisor')
-      user = create(:user, user_roles: [technician_role, supervisor_role])
+      technician_role = UserRole.new(name: "Technician")
+      supervisor_role = UserRole.new(name: "Supervisor")
+      user = User.create!(user_roles: [technician_role, supervisor_role])
 
       expect(user).to have_guises :technician, :supervisor
 
@@ -128,8 +186,8 @@ describe Guise do
     end
 
     it 'ignores records marked for destruction' do
-      technician_role = build(:user_role, name: 'Technician')
-      technician_user = create(:user, user_roles: [technician_role])
+      technician_role = UserRole.new(name: "Technician")
+      technician_user = User.create!(user_roles: [technician_role])
 
       expect(technician_user).to have_any_guises :technician, :supervisor
 
@@ -145,7 +203,7 @@ describe Guise do
 
   describe '.guise_of' do
     it "sets default scope to limit to records of the class's type" do
-      technician_ids = User.technicians.map(&:id)
+      technician_ids = Technician.all.map(&:id)
 
       expect(technician_ids).to eq [technician.id]
     end
@@ -171,20 +229,20 @@ describe Guise do
         Class.new(ActiveRecord::Base) do
           guise_of :Model
         end
-      end
+      end.to raise_error Guise::DefinitionNotFound
     end
   end
 
   describe ".guise_for" do
-    subject { UserRole.new }
-
     it "sets up belongs_to" do
-      should belong_to(:user)
+      reflection = UserRole.reflect_on_association(:user)
+
+      expect(reflection).not_to be_nil
     end
 
     it 'defines scopes for each guise' do
-      technician_role = create(:technician_role)
-      supervisor_role = create(:supervisor_role)
+      technician_role = UserRole.create(name: "Technician")
+      supervisor_role = UserRole.create(name: "Supervisor")
 
       technician_roles = UserRole.technicians
 
@@ -202,21 +260,29 @@ describe Guise do
         Class.new(ActiveRecord::Base) do
           guise_for :Model
         end
-      end
+      end.to raise_error Guise::DefinitionNotFound
     end
 
-    describe "adds validations to ensure guise attribute is" do
-      it "present" do
-        should validate_presence_of(:name)
-      end
-
-      it "unique per resource" do
-        should validate_uniqueness_of(:name).scoped_to(:user_id)
-      end
-
-      it "is one of the guise names provided" do
-        expect { create(:user_role, name: 'Farmer') }.to raise_error ActiveRecord::RecordInvalid
-      end
+    it "adds validations to ensure presence, inclusion and uniqueness " \
+      "of the guise attribute" do
+      user_role = UserRole.new
+      user_role.valid?
+
+      expect(user_role.errors[:name]).to match_array [
+        I18n.t("errors.messages.blank"),
+        I18n.t("errors.messages.inclusion")
+      ]
+
+      user_role.user = technician
+      user_role.name = "Technician"
+      user_role.valid?
+
+      expect(user_role.errors[:name]).to eq [
+        I18n.t(
+          "activerecord.errors.messages.taken",
+          default: :"errors.messages.taken"
+        )
+      ]
     end
   end
 
@@ -240,7 +306,7 @@ describe Guise do
         Class.new(ActiveRecord::Base) do
           scoped_guise_for :Model
         end
-      end.to raise_error
+      end.to raise_error Guise::DefinitionNotFound
     end
   end
 end