Merge pull request #603 from DatabaseCleaner/tighten_up_public_api

Tighten up Public API

Author: botandrose-machine

lib/database_cleaner.rb

@@ -1,5 +1,6 @@
 $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__))) unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__)))
 require 'database_cleaner/configuration'
+require 'database_cleaner/deprecation'
 require 'forwardable'
 
 module DatabaseCleaner
@@ -20,12 +21,9 @@ class << self
       :clean_with,
       :cleaning,
 
-      # TODO deprecate
+      # TODO remove in 2.0
       :clean!,
       :clean_with!,
-
-      # TODO deprecate and then privatize the following methods:
-
       :init_cleaners,
       :add_cleaner,
       :connections,
@@ -35,6 +33,7 @@ class << self
     attr_accessor :allow_remote_database_url, :allow_production, :url_whitelist
 
     def can_detect_orm?
+      DatabaseCleaner.deprecate "Calling `DatabaseCleaner.can_detect_orm?` is deprecated, and will be removed in database_cleaner 2.0 with no replacement."
       DatabaseCleaner::Base.autodetect_orm
     end
 

lib/database_cleaner/base.rb

@@ -1,7 +1,9 @@
+require 'database_cleaner/deprecation'
 require 'database_cleaner/null_strategy'
 require 'database_cleaner/safeguard'
 require 'database_cleaner/orm_autodetector'
 require 'active_support/core_ext/string/inflections'
+require 'forwardable'
 
 module DatabaseCleaner
   class Base
@@ -23,36 +25,10 @@ def db=(desired_db)
       @db = self.strategy_db = desired_db
     end
 
-    def strategy_db=(desired_db)
-      set_strategy_db(strategy, desired_db)
-    end
-
     def db
       @db ||= :default
     end
 
-    def create_strategy(*args)
-      strategy, *strategy_args = args
-      orm_strategy(strategy).new(*strategy_args)
-    end
-
-    def clean_with(*args)
-      strategy = create_strategy(*args)
-      set_strategy_db strategy, db
-      strategy.clean
-      strategy
-    end
-
-    alias clean_with! clean_with
-
-    def set_strategy_db(strategy, desired_db)
-      if strategy.respond_to? :db=
-        strategy.db = desired_db
-      elsif desired_db != :default
-        raise ArgumentError, "You must provide a strategy object that supports non default databases when you specify a database"
-      end
-    end
-
     def strategy=(args)
       strategy, *strategy_args = args
       @strategy = if strategy.is_a?(Symbol)
@@ -77,26 +53,64 @@ def orm=(desired_orm)
       @orm = @orm_autodetector.orm if @orm == :autodetect
     end
 
+    extend Forwardable
+    delegate [:start, :clean, :cleaning] => :strategy
+
+    def clean_with(*args)
+      strategy = create_strategy(*args)
+      set_strategy_db strategy, db
+      strategy.clean
+      strategy
+    end
+
+    # TODO remove the following methods in 2.0
+
     def auto_detected?
+      DatabaseCleaner.deprecate "Calling `DatabaseCleaner[...].auto_detected?` is deprecated, and will be removed in database_cleaner 2.0 with no replacement."
       @orm_autodetector.autodetected?
     end
 
     def autodetect_orm
+      DatabaseCleaner.deprecate "Calling `DatabaseCleaner[...].autodetect_orm` is deprecated, and will be removed in database_cleaner 2.0 with no replacement."
       @orm_autodetector.orm
     end
 
-    def start
-      strategy.start
+    def clean!
+      DatabaseCleaner.deprecate "Calling `DatabaseCleaner[...].clean!` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner[...].clean instead."
+      clean
     end
 
-    def clean
-      strategy.clean
+    def clean_with!
+      DatabaseCleaner.deprecate "Calling `DatabaseCleaner[...].clean_with!` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner[...].clean_with instead."
+      clean_with
     end
 
-    alias clean! clean
+    # TODO privatize the following methods in 2.0
 
-    def cleaning(&block)
-      strategy.cleaning(&block)
+    def strategy_db=(desired_db)
+      if called_externally?(caller)
+        DatabaseCleaner.deprecate "Calling `DatabaseCleaner[...].strategy_db=` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner[...].db=` instead."
+      end
+      set_strategy_db(strategy, desired_db)
+    end
+
+    def set_strategy_db(strategy, desired_db)
+      if called_externally?(caller)
+        DatabaseCleaner.deprecate "Calling `DatabaseCleaner[...].set_strategy_db=` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner[...].db=` instead."
+      end
+      if strategy.respond_to? :db=
+        strategy.db = desired_db
+      elsif desired_db != :default
+        raise ArgumentError, "You must provide a strategy object that supports non default databases when you specify a database"
+      end
+    end
+
+    def create_strategy(*args)
+      if called_externally?(caller)
+        DatabaseCleaner.deprecate "Calling `DatabaseCleaner[...].create_strategy` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner[...].strategy=` instead."
+      end
+      strategy, *strategy_args = args
+      orm_strategy(strategy).new(*strategy_args)
     end
 
     private
@@ -109,7 +123,7 @@ def orm_module
     def orm_strategy(strategy)
       orm_module.const_get(strategy.to_s.capitalize)
     rescue NameError
-      $stderr.puts <<-TEXT
+      DatabaseCleaner.deprecate <<-TEXT
         Requiring the `database_cleaner` gem directly is deprecated, and will raise an error in database_cleaner 2.0. Instead, please require the specific gem (or gems) for your ORM.
         For example, replace `gem "database_cleaner"` with `gem "database_cleaner-#{orm}"` in your Gemfile.
       TEXT
@@ -132,5 +146,9 @@ def default_orm_strategy
         :truncation
       end
     end
+
+    def called_externally?(caller)
+      __FILE__ != caller.first.split(":").first
+    end
   end
 end

lib/database_cleaner/configuration.rb

@@ -1,4 +1,5 @@
 require 'database_cleaner/base'
+require 'database_cleaner/deprecation'
 require 'forwardable'
 
 module DatabaseCleaner
@@ -49,9 +50,6 @@ def initialize
       :[],
       :strategy=,
       :orm=,
-
-      :add_cleaner,
-      :remove_duplicates,
     ] => :cleaners
 
     attr_accessor :app_root, :logger, :cleaners
@@ -82,25 +80,46 @@ def clean_with(*args)
       connections.each { |connection| connection.clean_with(*args) }
     end
 
-    # TODO deprecate and remove the following aliases:
+    # TODO remove the following methods in 2.0
 
-    alias clean! clean
-    alias clean_with! clean_with
+    def clean!
+      DatabaseCleaner.deprecate "Calling `DatabaseCleaner.clean!` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner.clean`, instead."
+      clean
+    end
 
-    # TODO deprecate and then privatize the following methods:
+    def clean_with!(*args)
+      DatabaseCleaner.deprecate "Calling `DatabaseCleaner.clean_with!` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner.clean_with`, instead."
+      clean_with(*args)
+    end
 
     def init_cleaners
-      $stderr.puts "Calling `DatabaseCleaner.init_cleaners` is deprecated, and will be removed in database_cleaner 2.0 with no replacement."
+      DatabaseCleaner.deprecate "Calling `DatabaseCleaner.init_cleaners` is deprecated, and will be removed in database_cleaner 2.0 with no replacement."
     end
 
     def connections
       if called_externally?(caller)
-        $stderr.puts "Calling `DatabaseCleaner.connections` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner.cleaners`, instead."
+        DatabaseCleaner.deprecate "Calling `DatabaseCleaner.connections` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner.cleaners`, instead."
       end
       add_cleaner(:autodetect) if @cleaners.none?
       @cleaners.values
     end
 
+    # TODO privatize the following methods in 2.0
+
+    def add_cleaner(orm, opts = {})
+      if called_externally?(caller)
+        DatabaseCleaner.deprecate "Calling `DatabaseCleaner.add_cleaner` is deprecated, and will be removed in database_cleaner 2.0. Use `DatabaseCleaner.[]`, instead."
+      end
+      @cleaners.add_cleaner(orm, opts = {})
+    end
+
+    def remove_duplicates
+      if called_externally?(caller)
+        DatabaseCleaner.deprecate "Calling `DatabaseCleaner.remove_duplicates` is deprecated, and will be removed in database_cleaner 2.0 with no replacement."
+      end
+      @cleaners.remove_duplicates
+    end
+
     private
 
     def called_externally?(caller)

lib/database_cleaner/deprecation.rb

@@ -0,0 +1,21 @@
+module DatabaseCleaner
+  def deprecate message
+    method = caller.first[/\d+:in `(.*)'$/, 1].to_sym
+    @@deprecator ||= Deprecator.new
+    @@deprecator.deprecate method, message
+  end
+  module_function :deprecate
+
+  class Deprecator
+    def initialize
+      @methods_already_warned = {}
+    end
+
+    def deprecate method, message
+      return if @methods_already_warned.key?(method)
+      $stderr.puts message
+      @methods_already_warned[method] = true
+    end
+  end
+end
+