Merge pull request #55 from sleepingkingstudios/chore/deprecate-disam…

…biguation

Chore/Deprecate Relation::Disambiguation.

lib/cuprum/collections/association.rb

@@ -8,14 +8,12 @@ module Cuprum::Collections
   class Association < Resource # rubocop:disable Metrics/ClassLength
     # @overload initialize(entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
     #   @param entity_class [Class, String] the class of entity represented by
-    #     the resource. Aliased as :association_class, :resource_class.
+    #     the resource.
     #   @param inverse [Cuprum::Collections::Resource] the inverse association,
     #     if any.
-    #   @param name [String] the name of the resource. Aliased as
-    #     :association_name, :resource_name.
+    #   @param name [String] the name of the resource.
     #   @param qualified_name [String] a scoped name for the resource.
     #   @param singular_name [String] the name of an entity in the resource.
-    #     Aliased as :singular_resource_name.
     #   @param options [Hash] additional options for the resource.
     #
     #   @option options foreign_key_name [String] the name of the foreign key
@@ -41,12 +39,25 @@ def initialize(**params)
       super(**params)
     end
 
-    alias association_class entity_class
-    alias association_name name
-
     # @return [Cuprum::Collections::Resource] the inverse association, if any.
     attr_reader :inverse
 
+    # @return [Class] the class of entity represented by the resource.
+    def association_class
+      tools.core_tools.deprecate '#association_class method',
+        message: 'Use #entity_class instead'
+
+      entity_class
+    end
+
+    # @return [String] the name of the resource.
+    def association_name
+      tools.core_tools.deprecate '#association_name method',
+        message: 'Use #name instead'
+
+      name
+    end
+
     # Generates a query for finding matching items.
     #
     # @param entities [Array] the entities to query for.

lib/cuprum/collections/collection.rb

@@ -28,11 +28,9 @@ class AbstractCollectionError < StandardError; end
     # @overload initialize(entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
     #   @param entity_class [Class, String] the class of entity represented by
     #     the relation.
-    #   @param name [String] the name of the relation. Aliased as
-    #     :collection_name.
+    #   @param name [String] the name of the relation.
     #   @param qualified_name [String] a scoped name for the relation.
     #   @param singular_name [String] the name of an entity in the relation.
-    #     Aliased as :member_name.
     #   @param options [Hash] additional options for the relation.
     #
     #   @option options primary_key_name [String] the name of the primary key
@@ -56,10 +54,6 @@ def initialize(**parameters) # rubocop:disable Metrics/MethodLength
       @options = ignore_parameters(**parameters)
     end
 
-    alias collection_name name
-
-    alias member_name singular_name
-
     # @return [Hash<Symbol>] additional options for the collection.
     attr_reader :options
 
@@ -73,6 +67,14 @@ def ==(other)
       comparable_options == other.comparable_options
     end
 
+    # @return [String] the name of the collection.
+    def collection_name
+      tools.core_tools.deprecate '#collection_name method',
+        message: 'Use #name instead'
+
+      name
+    end
+
     # @return [Integer] the count of items in the collection.
     def count
       query.count
@@ -95,6 +97,14 @@ def matches?(**expected)
       comparable_options >= expected
     end
 
+    # @return [String] the name of an entity in the relation.
+    def member_name
+      tools.core_tools.deprecate '#member_name method',
+        message: 'Use #singular_name instead'
+
+      singular_name
+    end
+
     # A new Query instance, used for querying against the collection data.
     #
     # @return [Object] the query.
@@ -118,9 +128,9 @@ def comparable_options
 
     def command_options
       @command_options ||= {
-        collection_name:  collection_name,
+        collection_name:  name,
         entity_class:     entity_class,
-        member_name:      member_name,
+        member_name:      singular_name,
         primary_key_name: primary_key_name,
         primary_key_type: primary_key_type,
         **options
@@ -136,5 +146,9 @@ def ignore_parameters(**parameters)
     def ignored_parameters
       @ignored_parameters ||= Set.new(IGNORED_PARAMETERS)
     end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
   end
 end

lib/cuprum/collections/commands/find_one_matching.rb

@@ -92,7 +92,7 @@ def initialize(collection:)
     private
 
     def error_params_for(attributes: nil, &block)
-      { collection_name: collection.collection_name }.merge(
+      { collection_name: collection.name }.merge(
         if block_given?
           { query: collection.query.where(&block) }
         else

lib/cuprum/collections/relation.rb

@@ -63,14 +63,21 @@ class << self
         # @param alternatives [Symbol, Array<Symbol>] the additional keywords.
         #
         # @return [Hash] the disambiguated keywords.
-        def disambiguate_keyword(params, key, *alternatives)
+        def disambiguate_keyword(params, key, *alternatives) # rubocop:disable Metrics/MethodLength
           params = params.dup
           values = keyword_values(params, key, *alternatives)
 
           return params if values.empty?
 
           if values.size == 1
-            _, value = values.first
+            match, value = values.first
+
+            unless match == key
+              tools.core_tools.deprecate(
+                "#{match.inspect} keyword",
+                message: "Use #{key.inspect} instead"
+              )
+            end
 
             return params.merge(key => value)
           end
@@ -118,6 +125,10 @@ def keyword_values(keywords, *keys)
             .map { |key| [key, keywords.delete(key)] }
             .reject { |_, value| value.nil? } # rubocop:disable Style/CollectionCompact
         end
+
+        def tools
+          SleepingKingStudios::Tools::Toolbelt.instance
+        end
       end
 
       # (see Cuprum::Collections::Relation::Disambiguation.disambiguate_keyword)
@@ -382,5 +393,9 @@ def ignore_parameters(**parameters)
     def ignored_parameters
       @ignored_parameters ||= Set.new(IGNORED_PARAMETERS)
     end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
   end
 end

lib/cuprum/collections/resource.rb

@@ -12,12 +12,11 @@ class Resource < Cuprum::Collections::Relation
 
     # @overload initialize(entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
     #   @param entity_class [Class, String] the class of entity represented by
-    #     the resource. Aliased as :resource_class.
+    #     the resource.
     #   @param name [String] the name of the resource. Aliased as
     #     :resource_name.
     #   @param qualified_name [String] a scoped name for the resource.
     #   @param singular_name [String] the name of an entity in the resource.
-    #     Aliased as :singular_resource_name.
     #   @param options [Hash] additional options for the resource.
     #
     #   @option options plural [Boolean] if true, the resource represents a
@@ -39,8 +38,28 @@ def initialize(**params)
       super(**params)
     end
 
-    alias resource_class entity_class
-    alias resource_name name
-    alias singular_resource_name singular_name
+    # @return [Class] the class of entity represented by the resource.
+    def resource_class
+      tools.core_tools.deprecate '#resource_class method',
+        message: 'Use #entity_class instead'
+
+      entity_class
+    end
+
+    # @return [String] the name of the resource.
+    def resource_name
+      tools.core_tools.deprecate '#resource_name method',
+        message: 'Use #name instead'
+
+      name
+    end
+
+    # @return[String] the name of an entity in the resource.
+    def singular_resource_name
+      tools.core_tools.deprecate '#singular_resource_name method',
+        message: 'Use #singular_name instead'
+
+      singular_name
+    end
   end
 end

lib/cuprum/collections/rspec/collection_contract.rb

@@ -48,6 +48,14 @@ module CollectionContract
           let(:command) do
             collection.const_get(class_name).new(**constructor_options)
           end
+          let(:expected_options) do
+            Hash
+              .new { |_, key| collection.send(key) }
+              .merge(
+                collection_name: collection.name,
+                member_name:     collection.singular_name
+              )
+          end
 
           it { expect(collection).to define_constant(class_name) }
 
@@ -60,15 +68,15 @@ module CollectionContract
           command_options.each do |option_name|
             it "should set the ##{option_name}" do
               expect(command.send(option_name))
-                .to be == collection.send(option_name)
+                .to be == expected_options[option_name]
             end
           end
 
           describe 'with options' do
             let(:constructor_options) do
               super().merge(
                 custom_option: 'value',
-                member_name:   'tome'
+                singular_name: 'tome'
               )
             end
 
@@ -77,9 +85,7 @@ module CollectionContract
             command_options.each do |option_name|
               it "should set the ##{option_name}" do
                 expect(command.send(option_name)).to(
-                  be == constructor_options.fetch(option_name) do
-                    collection.send(option_name)
-                  end
+                  be == expected_options[option_name]
                 )
               end
             end
@@ -91,6 +97,14 @@ module CollectionContract
           let(:command) do
             collection.send(command_name, **constructor_options)
           end
+          let(:expected_options) do
+            Hash
+              .new { |_, key| collection.send(key) }
+              .merge(
+                collection_name: collection.name,
+                member_name:     collection.singular_name
+              )
+          end
 
           it 'should define the command' do
             expect(collection)
@@ -104,15 +118,15 @@ module CollectionContract
           command_options.each do |option_name|
             it "should set the ##{option_name}" do
               expect(command.send(option_name))
-                .to be == collection.send(option_name)
+                .to be == expected_options[option_name]
             end
           end
 
           describe 'with options' do
             let(:constructor_options) do
               super().merge(
                 custom_option: 'value',
-                member_name:   'tome'
+                singular_name: 'tome'
               )
             end
 
@@ -121,9 +135,7 @@ module CollectionContract
             command_options.each do |option_name|
               it "should set the ##{option_name}" do
                 expect(command.send(option_name)).to(
-                  be == constructor_options.fetch(option_name) do
-                    collection.send(option_name)
-                  end
+                  be == expected_options[option_name]
                 )
               end
             end
@@ -164,7 +176,7 @@ module CollectionContract
       include_examples 'should define the command', :validate_one
 
       describe '#==' do
-        let(:other_options)    { { collection_name: name } }
+        let(:other_options)    { { name: name } }
         let(:other_collection) { described_class.new(**other_options) }
 
         describe 'with nil' do
@@ -198,8 +210,8 @@ module CollectionContract
         context 'when initialized with options' do
           let(:constructor_options) do
             super().merge(
-              member_name:    'grimoire',
-              qualified_name: 'spec/scoped_books'
+              qualified_name: 'spec/scoped_books',
+              singular_name:  'grimoire'
             )
           end
 
@@ -210,8 +222,8 @@ module CollectionContract
           describe 'with a collection with matching properties' do
             let(:other_options) do
               super().merge(
-                member_name:    'grimoire',
-                qualified_name: 'spec/scoped_books'
+                qualified_name: 'spec/scoped_books',
+                singular_name:  'grimoire'
               )
             end
 
@@ -299,8 +311,8 @@ def tools
         describe 'with partially-matching options' do
           let(:other_options) do
             {
-              collection_name: name,
-              member_name:     'grimoire'
+              name:          name,
+              singular_name: 'grimoire'
             }
           end