Allow for register_engine without deprecation

Frustratingly you may need to use both `register_engine` to get the behavior your want in Sprockets 3 even if you're using the new API (i.e. `register_transformer` etc.). I think this is because the different APIs have a different backend but I haven't looked into it enough to know exactly why they diverged.

Here's a PR that shows the problem: sass/sassc-rails#65

If you only call `register_transformer` then the Sprockets 3 tests will fail. I think this is because the processor built into `lib/sprockets.rb` and registered via `register_engine` still gets executed. By registering the sassc processor again with `register_engine` we're writing over the built in processor to ensure ours takes priority. I'm not 100% on this cause but it seems reasonable.

This PR introduces a way to silence the deprecation for `register_engine` so that libraries that still need the `register_engine` API to function correctly (such as sassc-rails) can operate without deprecations. This is an opt-in flag, we assume if you use the flag that you're aware of the new API and have updated your library appropriately.

After this PR I'm going to change the docs to show how to use both `register_transformer` and `register_engine` at the same time.

Author: schneems

.gitignore

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

lib/sprockets.rb

@@ -124,32 +124,30 @@ module Sprockets
   # Mmm, CoffeeScript
   require 'sprockets/coffee_script_processor'
   Deprecation.silence do
-    register_engine '.coffee', CoffeeScriptProcessor, mime_type: 'application/javascript'
+    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'
   Deprecation.silence do
-    register_engine '.jst', JstProcessor, mime_type: 'application/javascript'
-    register_engine '.eco', EcoProcessor, mime_type: 'application/javascript'
-    register_engine '.ejs', EjsProcessor, mime_type: 'application/javascript'
+    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'
   Deprecation.silence do
-    register_engine '.sass', SassProcessor, mime_type: 'text/css'
-    register_engine '.scss', ScssProcessor, mime_type: 'text/css'
+    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'
-  Deprecation.silence do
-    register_engine '.erb', ERBProcessor, mime_type: 'text/plain'
-  end
+  register_engine '.erb', ERBProcessor, mime_type: 'text/plain', silence_deprecation: true
 
   register_dependency_resolver 'environment-version' do |env|
     env.version

lib/sprockets/engines.rb

@@ -51,7 +51,16 @@ def engine_mime_types
     #     environment.register_engine '.coffee', CoffeeScriptProcessor
     #
     def register_engine(ext, klass, options = {})
-      Deprecation.new([caller.first]).warn("`register_engine` is deprecated please register a mime type and use `register_compressor` or `register_transformer`")
+      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)
 

test/sprockets_test.rb

@@ -23,7 +23,7 @@ def silence_warnings
 
 NoopProcessor = proc { |input| input[:data] }
 # Sprockets.register_mime_type 'text/haml', extensions: ['.haml']
-Sprockets.register_engine '.haml', NoopProcessor, mime_type: 'text/html'
+Sprockets.register_engine '.haml', NoopProcessor, mime_type: 'text/html', silence_deprecation: true
 
 # Sprockets.register_mime_type 'text/ng-template', extensions: ['.ngt']
 AngularProcessor = proc { |input|
@@ -33,19 +33,19 @@ def silence_warnings
 });
   EOS
 }
-Sprockets.register_engine '.ngt', AngularProcessor, mime_type: 'application/javascript'
+Sprockets.register_engine '.ngt', AngularProcessor, mime_type: 'application/javascript', silence_deprecation: true
 
 # Sprockets.register_mime_type 'text/mustache', extensions: ['.mustache']
-Sprockets.register_engine '.mustache', NoopProcessor, mime_type: 'application/javascript'
+Sprockets.register_engine '.mustache', NoopProcessor, mime_type: 'application/javascript', silence_deprecation: true
 
 # Sprockets.register_mime_type 'text/x-handlebars-template', extensions: ['.handlebars']
-Sprockets.register_engine '.handlebars', NoopProcessor, mime_type: 'application/javascript'
+Sprockets.register_engine '.handlebars', NoopProcessor, mime_type: 'application/javascript', silence_deprecation: true
 
 # Sprockets.register_mime_type 'application/javascript-module', extensions: ['.es6']
-Sprockets.register_engine '.es6', NoopProcessor, mime_type: 'application/javascript'
+Sprockets.register_engine '.es6', NoopProcessor, mime_type: 'application/javascript', silence_deprecation: true
 
 # Sprockets.register_mime_type 'application/dart', extensions: ['.dart']
-Sprockets.register_engine '.dart', NoopProcessor, mime_type: 'application/javascript'
+Sprockets.register_engine '.dart', NoopProcessor, mime_type: 'application/javascript', silence_deprecation: true
 
 require 'nokogiri'
 
@@ -72,7 +72,7 @@ def silence_warnings
 Sprockets.register_transformer 'application/xml+builder', 'application/xml', XmlBuilderProcessor
 
 require 'sprockets/jst_processor'
-Sprockets.register_engine '.jst2', Sprockets::JstProcessor.new(namespace: 'this.JST2'), mime_type: 'application/javascript'
+Sprockets.register_engine '.jst2', Sprockets::JstProcessor.new(namespace: 'this.JST2'), mime_type: 'application/javascript', silence_deprecation: true
 
 SVG2PNG = proc { |input|
   "\x89\x50\x4e\x47\xd\xa\x1a\xa#{input[:data]}"

test/test_engines.rb

@@ -30,7 +30,7 @@ class TestEngines < Sprockets::TestCase
     env = new_environment
 
     Sprockets::SilenceDeprecation.silence do
-      env.register_engine ".alert", AlertProcessor
+      env.register_engine ".alert", AlertProcessor, silence_deprecation: true
     end
 
     asset = env["hello.alert"]