Merge pull request #264 from rails/3.x-deprecations

Deprecation Branch for 3.X

Author: schneems

.gitignore

@@ -6,3 +6,4 @@ doc
 docs
 pkg
 tmp
+.DS_Store

lib/sprockets.rb

@@ -4,6 +4,7 @@
 require 'sprockets/environment'
 require 'sprockets/errors'
 require 'sprockets/manifest'
+require 'sprockets/deprecation'
 
 module Sprockets
   require 'sprockets/processor_utils'
@@ -122,25 +123,31 @@ module Sprockets
 
   # Mmm, CoffeeScript
   require 'sprockets/coffee_script_processor'
-  register_engine '.coffee', CoffeeScriptProcessor, mime_type: 'application/javascript'
+  Deprecation.silence do
+    register_engine '.coffee', CoffeeScriptProcessor, mime_type: 'application/javascript', silence_deprecation: true
+  end
 
   # JST engines
   require 'sprockets/eco_processor'
   require 'sprockets/ejs_processor'
   require 'sprockets/jst_processor'
-  register_engine '.jst', JstProcessor, mime_type: 'application/javascript'
-  register_engine '.eco', EcoProcessor, mime_type: 'application/javascript'
-  register_engine '.ejs', EjsProcessor, mime_type: 'application/javascript'
+  Deprecation.silence do
+    register_engine '.jst', JstProcessor, mime_type: 'application/javascript', silence_deprecation: true
+    register_engine '.eco', EcoProcessor, mime_type: 'application/javascript', silence_deprecation: true
+    register_engine '.ejs', EjsProcessor, mime_type: 'application/javascript', silence_deprecation: true
+  end
 
   # CSS engines
   require 'sprockets/sass_processor'
-  register_engine '.sass', SassProcessor, mime_type: 'text/css'
-  register_engine '.scss', ScssProcessor, mime_type: 'text/css'
+  Deprecation.silence do
+    register_engine '.sass', SassProcessor, mime_type: 'text/css', silence_deprecation: true
+    register_engine '.scss', ScssProcessor, mime_type: 'text/css', silence_deprecation: true
+  end
   register_bundle_metadata_reducer 'text/css', :sass_dependencies, Set.new, :+
 
   # Other
   require 'sprockets/erb_processor'
-  register_engine '.erb', ERBProcessor, mime_type: 'text/plain'
+  register_engine '.erb', ERBProcessor, mime_type: 'text/plain', silence_deprecation: true
 
   register_dependency_resolver 'environment-version' do |env|
     env.version

lib/sprockets/coffee_script_template.rb

@@ -2,5 +2,16 @@
 
 module Sprockets
   # Deprecated
-  CoffeeScriptTemplate = CoffeeScriptProcessor
+  module CoffeeScriptTemplate
+    VERSION = CoffeeScriptProcessor::VERSION
+
+    def self.cache_key
+      CoffeeScriptProcessor.cache_key
+    end
+
+    def self.call(*args)
+      Deprecation.new.warn "CoffeeScriptTemplate is deprecated please use CoffeeScriptProcessor instead"
+      CoffeeScriptProcessor.call(*args)
+    end
+  end
 end

lib/sprockets/deprecation.rb

@@ -0,0 +1,90 @@
+module Sprockets
+  class Deprecation
+    THREAD_LOCAL__SILENCE_KEY = "_sprockets_deprecation_silence".freeze
+    DEFAULT_BEHAVIORS = {
+      raise: ->(message, callstack) {
+        e = DeprecationException.new(message)
+        e.set_backtrace(callstack.map(&:to_s))
+        raise e
+      },
+
+      stderr: ->(message, callstack) {
+        $stderr.puts(message)
+      },
+    }
+
+    attr_reader :callstack
+
+    def self.silence(&block)
+      Thread.current[THREAD_LOCAL__SILENCE_KEY] = true
+      block.call
+    ensure
+      Thread.current[THREAD_LOCAL__SILENCE_KEY] = false
+    end
+
+    def initialize(callstack = nil)
+      @callstack = callstack || caller(2)
+    end
+
+    def warn(message)
+      return if Thread.current[THREAD_LOCAL__SILENCE_KEY]
+      deprecation_message(message).tap do |m|
+        behavior.each { |b| b.call(m, callstack) }
+      end
+    end
+
+    private
+      def behavior
+        @behavior ||= [DEFAULT_BEHAVIORS[:stderr]]
+      end
+
+      def behavior=(behavior)
+        @behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || b }
+      end
+
+      def deprecation_message(message = nil)
+        message ||= "You are using deprecated behavior which will be removed from the next major or minor release."
+        "DEPRECATION WARNING: #{message} #{ deprecation_caller_message }"
+      end
+
+      def deprecation_caller_message
+        file, line, method = extract_callstack
+        if file
+          if line && method
+            "(called from #{method} at #{file}:#{line})"
+          else
+            "(called from #{file}:#{line})"
+          end
+        end
+      end
+
+      SPROCKETS_GEM_ROOT = File.expand_path("../../../../..", __FILE__) + "/"
+
+      def ignored_callstack(path)
+        path.start_with?(SPROCKETS_GEM_ROOT) || path.start_with?(RbConfig::CONFIG['rubylibdir'])
+      end
+
+      def extract_callstack
+        return _extract_callstack if callstack.first.is_a? String
+
+        offending_line = callstack.find { |frame|
+          frame.absolute_path && !ignored_callstack(frame.absolute_path)
+        } || callstack.first
+
+        [offending_line.path, offending_line.lineno, offending_line.label]
+      end
+
+      def _extract_callstack
+        offending_line = callstack.find { |line| !ignored_callstack(line) } || callstack.first
+
+        if offending_line
+          if md = offending_line.match(/^(.+?):(\d+)(?::in `(.*?)')?/)
+            md.captures
+          else
+            offending_line
+          end
+        end
+      end
+  end
+  private_constant :Deprecation
+end

lib/sprockets/eco_template.rb

@@ -2,5 +2,16 @@
 
 module Sprockets
   # Deprecated
-  EcoTemplate = EcoProcessor
+  module EcoTemplate
+    VERSION = EcoProcessor::VERSION
+
+    def self.cache_key
+      EcoProcessor.cache_key
+    end
+
+    def self.call(*args)
+      Deprecation.new.warn "EcoTemplate is deprecated please use EcoProcessor instead"
+      EcoProcessor.call(*args)
+    end
+  end
 end

lib/sprockets/ejs_template.rb

@@ -2,5 +2,16 @@
 
 module Sprockets
   # Deprecated
-  EjsTemplate = EjsProcessor
+  module EjsTemplate
+    VERSION = EjsProcessor::VERSION
+
+    def self.cache_key
+      EjsProcessor.cache_key
+    end
+
+    def self.call(*args)
+      Deprecation.new.warn "EjsTemplate is deprecated please use EjsProcessor instead"
+      EjsProcessor.call(*args)
+    end
+  end
 end

lib/sprockets/engines.rb

@@ -51,6 +51,17 @@ def engine_mime_types
     #     environment.register_engine '.coffee', CoffeeScriptProcessor
     #
     def register_engine(ext, klass, options = {})
+      unless options[:silence_deprecation]
+        msg = <<-MSG
+Sprockets method `register_engine` is deprecated.
+Please register a mime type using `register_mime_type` then
+use `register_compressor` or `register_transformer`.
+https://github.com/rails/sprockets/blob/master/guides/extending_sprockets.md#supporting-all-versions-of-sprockets-in-processors
+        MSG
+
+        Deprecation.new([caller.first]).warn(msg)
+      end
+
       ext = Sprockets::Utils.normalize_extension(ext)
 
       self.computed_config = {}

lib/sprockets/erb_template.rb

@@ -2,5 +2,10 @@
 
 module Sprockets
   # Deprecated
-  ERBTemplate = ERBProcessor
+  class ERBTemplate < ERBProcessor
+    def call(*args)
+      Deprecation.new.warn "ERBTemplate is deprecated please use ERBProcessor instead"
+      super
+    end
+  end
 end

lib/sprockets/processing.rb

@@ -231,14 +231,24 @@ def unregister_config_processor(type, mime_type, klass)
         compute_transformers!
       end
 
+      def deprecate_legacy_processor_interface(interface)
+        msg = "You are using the a deprecated processor interface #{ interface.inspect }.\n" +
+        "Please update your processor interface:\n" +
+        "https://github.com/rails/sprockets/blob/master/guides/extending_sprockets.md#supporting-all-versions-of-sprockets-in-processors\n"
+
+        Deprecation.new([caller[3]]).warn msg
+      end
+
       def wrap_processor(klass, proc)
         if !proc
           if klass.respond_to?(:call)
             klass
           else
+            deprecate_legacy_processor_interface(klass)
             LegacyTiltProcessor.new(klass)
           end
         elsif proc.respond_to?(:arity) && proc.arity == 2
+          deprecate_legacy_processor_interface(proc)
           LegacyProcProcessor.new(klass.to_s, proc)
         else
           proc

lib/sprockets/sass_cache_store.rb

@@ -25,5 +25,10 @@ def path_to(key)
   end
 
   # Deprecated: Use Sprockets::SassProcessor::CacheStore instead.
-  SassCacheStore = SassProcessor::CacheStore
+  class SassCacheStore < SassProcessor::CacheStore
+    def initialize(*args)
+      Deprecation.new.warn "SassCacheStore is deprecated please use SassProcessor::CacheStore instead"
+      super
+    end
+  end
 end