Filters Manage Dependencies

Simeon F. Willbanks · Simeon F. Willbanks · commit d3fc6d9b470d · 2013-08-25T13:15:14.000-07:00
* Add dependency management test cases for each `Filter` with a
  dependency
* Add `assert_dependency_management_error` custom assertion which
  asserts a custom exception and message are raised if a dependency
  is missing
* Move all `Filter` dependencies to `Gemfile` `:test` block for
  test cases and CI
* Implement `TestingDependency` helper to abstract unloading and
  loading `Gemfile` `:test` block gems when asserting dependency
  management errors
* Implement `MissingDependencyException` custom exception with
 `MESSAGE` constant as a format string, so each `Filter` raises a
  uniform exception
* Add `begin..rescue..end` blocks around each `Filter` `require`
  statement to raise a `MissingDependencyException` when a gem can
  not be loaded
* Update README.md detailing new dependency management with listing
  of `Filter` gem dependencies
* Add gemspec post install message to inform users their apps must
  bundle `Filter` dependencies
diff --git a/Gemfile b/Gemfile
@@ -1,9 +1,24 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in html-pipeline.gemspec
 gemspec
 
 group :development do
-  gem 'bundler'
-  gem 'rake'
+  gem "bundler"
+  gem "rake"
+end
+
+group :test do
+  gem "rinku",            "~> 1.7",   :require => false
+  gem "gemoji",           "~> 1.0",   :require => false
+  gem "RedCloth",         "~> 4.2.9", :require => false
+  gem "escape_utils",     "~> 0.3",   :require => false
+  gem "github-linguist",  "~> 2.6.2", :require => false
+  gem "github-markdown",  "~> 0.5",   :require => false
+
+  if RUBY_VERSION < "1.9.2"
+    gem "sanitize", ">= 2", "< 2.0.4", :require => false
+  else
+    gem "sanitize", "~> 2.0",          :require => false
+  end
 end
diff --git a/README.md b/README.md
@@ -98,18 +98,29 @@ filter.call
 * `TextileFilter` - convert textile to html
 * `TableOfContentsFilter` - anchor headings with name attributes and generate Table of Contents html unordered list linking headings
 
-## Syntax highlighting
+## Dependencies
 
+Filter gem dependencies are not bundled; you must bundle the filter's gem
+dependencies. The below list details filters with dependencies. For example,
 `SyntaxHighlightFilter` uses [github-linguist](https://github.com/github/linguist)
-to detect and highlight languages. It isn't included as a dependency by default
-because it's a large dependency and
-[a hassle to build on heroku](https://github.com/jch/html-pipeline/issues/33).
-To use the filter, add the following to your Gemfile:
+to detect and highlight languages. To use the `SyntaxHighlightFilter`,
+add the following to your Gemfile:
 
 ```ruby
 gem 'github-linguist'
 ```
 
+* `AutolinkFilter` - `rinku`
+* `EmailReplyFilter` - `escape_utils`
+* `EmojiFilter` - `gemoji`
+* `MarkdownFilter` - `github-markdown`
+* `PlainTextInputFilter` - `escape_utils`
+* `SanitizationFilter` - `sanitize`
+* `SyntaxHighlightFilter` - `github-linguist`
+* `TextileFilter` - `RedCloth`
+
+_Note:_ See [Gemfile](https://github.com/jch/html-pipeline/blob/master/Gemfile) `:test` block for version requirements.
+
 ## Examples
 
 We define different pipelines for different parts of our app. Here are a few
diff --git a/html-pipeline.gemspec b/html-pipeline.gemspec
@@ -15,13 +15,17 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^test})
   gem.require_paths = ["lib"]
 
-  gem.add_dependency "gemoji",          "~> 1.0"
-  gem.add_dependency "nokogiri",        RUBY_VERSION < "1.9.2" ? [">= 1.4", "< 1.6"] : "~> 1.4"
-  gem.add_dependency "github-markdown", "~> 0.5"
-  gem.add_dependency "sanitize",        RUBY_VERSION < "1.9.2" ? [">= 2", "< 2.0.4"] : "~> 2.0"
-  gem.add_dependency "rinku",           "~> 1.7"
-  gem.add_dependency "escape_utils",    "~> 0.3"
+  gem.add_dependency "nokogiri", RUBY_VERSION < "1.9.2" ? [">= 1.4", "< 1.6"] : "~> 1.4"
 
   gem.add_development_dependency "activesupport", RUBY_VERSION < "1.9.3" ? [">= 2", "< 4"] : ">= 2"
-  gem.add_development_dependency "github-linguist", "~> 2.6.2"
+
+  gem.post_install_message = <<msg
+----------------------------------------------
+Thank you for installing html-pipeline!
+Filter gem dependencies are no longer bundled.
+You must bundle Filter gem dependencies.
+See html-pipeline README.md for more details.
+https://github.com/jch/html-pipeline
+----------------------------------------------
+msg
 end
diff --git a/lib/html/pipeline.rb b/lib/html/pipeline.rb
@@ -1,6 +1,5 @@
 require "nokogiri"
 require "active_support/xml_mini/nokogiri" # convert Documents to hashes
-require "escape_utils"
 
 module HTML
   # GitHub HTML processing filters and utilities. This module includes a small
diff --git a/lib/html/pipeline/autolink_filter.rb b/lib/html/pipeline/autolink_filter.rb
@@ -1,4 +1,9 @@
-require 'rinku'
+begin
+  require "rinku"
+rescue LoadError => e
+  missing = HTML::Pipeline::Filter::MissingDependencyException
+  raise missing, missing::MESSAGE % "rinku", e.backtrace
+end
 
 module HTML
   class Pipeline
diff --git a/lib/html/pipeline/email_reply_filter.rb b/lib/html/pipeline/email_reply_filter.rb
@@ -1,3 +1,10 @@
+begin
+  require "escape_utils"
+rescue LoadError => e
+  missing = HTML::Pipeline::Filter::MissingDependencyException
+  raise missing, missing::MESSAGE % "escape_utils", e.backtrace
+end
+
 module HTML
   class Pipeline
     # HTML Filter that converts email reply text into an HTML DocumentFragment.
@@ -53,4 +60,4 @@ def call
       end
     end
   end
-end
+end
diff --git a/lib/html/pipeline/emoji_filter.rb b/lib/html/pipeline/emoji_filter.rb
@@ -1,4 +1,9 @@
-require 'emoji'
+begin
+  require "gemoji"
+rescue LoadError => e
+  missing = HTML::Pipeline::Filter::MissingDependencyException
+  raise missing, missing::MESSAGE % "gemoji", e.backtrace
+end
 
 module HTML
   class Pipeline
@@ -51,4 +56,4 @@ def asset_root
       end
     end
   end
-end
+end
diff --git a/lib/html/pipeline/filter.rb b/lib/html/pipeline/filter.rb
@@ -27,6 +27,23 @@ class Pipeline
     # Each filter may define additional options and output values. See the class
     # docs for more info.
     class Filter
+      # Public: Custom Exception raised when a Filter dependency is not installed.
+      #
+      # Examples
+      #
+      #   begin
+      #     require "rinku"
+      #   rescue LoadError => e
+      #     missing = HTML::Pipeline::Filter::MissingDependencyException
+      #     raise missing, missing::MESSAGE % "rinku", e.backtrace
+      #   end
+      class MissingDependencyException < StandardError
+        # Public: Format String for MissingDependencyException message.
+        MESSAGE = "Missing html-pipeline dependency: " +
+                  "Please add `%s` to your Gemfile; " +
+                  "see html-pipeline Gemfile for version."
+      end
+
       class InvalidDocumentException < StandardError; end
 
       def initialize(doc, context = nil, result = nil)
diff --git a/lib/html/pipeline/markdown_filter.rb b/lib/html/pipeline/markdown_filter.rb
@@ -1,4 +1,9 @@
-require 'github/markdown'
+begin
+  require "github/markdown"
+rescue LoadError => e
+  missing = HTML::Pipeline::Filter::MissingDependencyException
+  raise missing, missing::MESSAGE % "github-markdown", e.backtrace
+end
 
 module HTML
   class Pipeline
@@ -26,4 +31,4 @@ def call
       end
     end
   end
-end
+end
diff --git a/lib/html/pipeline/plain_text_input_filter.rb b/lib/html/pipeline/plain_text_input_filter.rb
@@ -1,3 +1,10 @@
+begin
+  require "escape_utils"
+rescue LoadError => e
+  missing = HTML::Pipeline::Filter::MissingDependencyException
+  raise missing, missing::MESSAGE % "escape_utils", e.backtrace
+end
+
 module HTML
   class Pipeline
     # Simple filter for plain text input. HTML escapes the text input and wraps it
@@ -8,4 +15,4 @@ def call
       end
     end
   end
-end
+end
diff --git a/lib/html/pipeline/sanitization_filter.rb b/lib/html/pipeline/sanitization_filter.rb
@@ -1,4 +1,9 @@
-require 'sanitize'
+begin
+  require "sanitize"
+rescue LoadError => e
+  missing = HTML::Pipeline::Filter::MissingDependencyException
+  raise missing, missing::MESSAGE % "sanitize", e.backtrace
+end
 
 module HTML
   class Pipeline
diff --git a/lib/html/pipeline/syntax_highlight_filter.rb b/lib/html/pipeline/syntax_highlight_filter.rb
@@ -1,7 +1,8 @@
 begin
-  require 'linguist'
-rescue LoadError
-  raise LoadError, "You need to install 'github-linguist' before using the SyntaxHighlightFilter. See README.md for details"
+  require "linguist"
+rescue LoadError => e
+  missing = HTML::Pipeline::Filter::MissingDependencyException
+  raise missing, missing::MESSAGE % "github-linguist", e.backtrace
 end
 
 module HTML
@@ -30,4 +31,4 @@ def highlight_with_timeout_handling(lexer, text)
       end
     end
   end
-end
+end
diff --git a/lib/html/pipeline/textile_filter.rb b/lib/html/pipeline/textile_filter.rb
@@ -1,3 +1,10 @@
+begin
+  require "redcloth"
+rescue LoadError => e
+  missing = HTML::Pipeline::Filter::MissingDependencyException
+  raise missing, missing::MESSAGE % "RedCloth", e.backtrace
+end
+
 module HTML
   class Pipeline
     # HTML Filter that converts Textile text into HTML and converts into a
@@ -18,4 +25,4 @@ def call
       end
     end
   end
-end
+end
diff --git a/test/helpers/testing_dependency.rb b/test/helpers/testing_dependency.rb
@@ -0,0 +1,92 @@
+# Public: Methods useful for testing Filter dependencies. All methods are class
+# methods and should be called on the TestingDependency class.
+#
+# Examples
+#
+#   TestingDependency.temporarily_remove_dependency_by gem_name do
+#     exception = assert_raise HTML::Pipeline::Filter::MissingDependencyException do
+#       load TestingDependency.filter_path_from filter_name
+#     end
+#   end
+class TestingDependency
+  # Public: Use to safely test a Filter's gem dependency error handling.
+  # For a certain gem dependency, remove the gem's loaded paths and features.
+  # Once these are removed, yield to a block which can assert a specific
+  # exception. Once the block is finished, add back the gem's paths and
+  # features to the load path and loaded features, so other tests can assert
+  # Filter functionality.
+  #
+  # gem_name - The String of the gem's name.
+  # block    - Required block which asserts gem dependency error handling.
+  #
+  # Examples
+  #
+  #   TestingDependency.temporarily_remove_dependency_by gem_name do
+  #     exception = assert_raise HTML::Pipeline::Filter::MissingDependencyException do
+  #       load TestingDependency.filter_path_from filter_name
+  #     end
+  #   end
+  #
+  # Returns nothing.
+  def self.temporarily_remove_dependency_by(gem_name, &block)
+    paths = gem_load_paths_from gem_name
+    features = gem_loaded_features_from gem_name
+
+    $LOAD_PATH.delete_if { |path| paths.include? path }
+    $LOADED_FEATURES.delete_if { |feature| features.include? feature }
+
+    yield
+
+    $LOAD_PATH.unshift(*paths)
+    $LOADED_FEATURES.unshift(*features)
+  end
+
+  # Public: Find a Filter's load path.
+  #
+  # gem_name - The String of the gem's name.
+  #
+  # Examples
+  #
+  #   filter_path_from("autolink_filter")
+  #   # => "/Users/simeon/Projects/html-pipeline/test/helpers/../../lib/html/pipeline/autolink_filter.rb"
+  #
+  # Returns String of load path.
+  def self.filter_path_from(filter_name)
+    File.join(File.dirname(__FILE__), "..", "..", "lib", "html", "pipeline", "#{filter_name}.rb")
+  end
+
+  private
+  # Internal: Find a gem's load paths.
+  #
+  # gem_name - The String of the gem's name.
+  #
+  # Examples
+  #
+  #   gem_load_paths_from("rinku")
+  #   # => ["/Users/simeon/.rbenv/versions/1.9.3-p429/lib/ruby/gems/1.9.1/gems/rinku-1.7.3/lib"]
+  #
+  # Returns Array of load paths.
+  def self.gem_load_paths_from(gem_name)
+    $LOAD_PATH.select{ |path| /#{gem_name}/i =~ path }
+  end
+
+  # Internal: Find a gem's loaded features.
+  #
+  # gem_name - The String of the gem's name.
+  #
+  # Examples
+  #
+  #   gem_loaded_features_from("rinku")
+  #   # => ["/Users/simeon/.rbenv/versions/1.9.3-p429/lib/ruby/gems/1.9.1/gems/rinku-1.7.3/lib/rinku.bundle",
+  #        "/Users/simeon/.rbenv/versions/1.9.3-p429/lib/ruby/gems/1.9.1/gems/rinku-1.7.3/lib/rinku.rb"]
+  #
+  # Returns Array of loaded features.
+  def self.gem_loaded_features_from(gem_name)
+    # gem github-markdown has a feature "github/markdown.rb".
+    # Replace gem name dashes and underscores with regexp
+    # range to match all features.
+    gem_name_regexp = gem_name.split(/[-_]/).join("[\/_-]")
+
+    $LOADED_FEATURES.select{ |feature| /#{gem_name_regexp}/i =~ feature }
+  end
+end
diff --git a/test/html/pipeline/autolink_filter_test.rb b/test/html/pipeline/autolink_filter_test.rb
@@ -3,6 +3,10 @@
 AutolinkFilter = HTML::Pipeline::AutolinkFilter
 
 class HTML::Pipeline::AutolinkFilterTest < Test::Unit::TestCase
+  def test_dependency_management
+    assert_dependency_management_error "autolink_filter", "rinku"
+  end
+
   def test_uses_rinku_for_autolinking
     # just try to parse a complicated piece of HTML
     # that Rails auto_link cannot handle
diff --git a/test/html/pipeline/email_reply_filter_test.rb b/test/html/pipeline/email_reply_filter_test.rb
@@ -0,0 +1,7 @@
+require "test_helper"
+
+class HTML::Pipeline::EmailReplyFilterTest < Test::Unit::TestCase
+  def test_dependency_management
+    assert_dependency_management_error "email_reply_filter", "escape_utils"
+  end
+end
diff --git a/test/html/pipeline/emoji_filter_test.rb b/test/html/pipeline/emoji_filter_test.rb
@@ -1,12 +1,16 @@
-require 'test_helper'
+require "test_helper"
 
 class HTML::Pipeline::EmojiFilterTest < Test::Unit::TestCase
   EmojiFilter = HTML::Pipeline::EmojiFilter
-  
+
+  def test_dependency_management
+    assert_dependency_management_error "emoji_filter", "gemoji"
+  end
+
   def test_emojify
-    filter = EmojiFilter.new("<p>:shipit:</p>", {:asset_root => 'https://foo.com'})
+    filter = EmojiFilter.new("<p>:shipit:</p>", {:asset_root => "https://foo.com"})
     doc = filter.call
-    assert_match "https://foo.com/emoji/shipit.png", doc.search('img').attr('src').value
+    assert_match "https://foo.com/emoji/shipit.png", doc.search("img").attr("src").value
   end
   
   def test_required_context_validation
@@ -15,4 +19,4 @@ def test_required_context_validation
     }
     assert_match /:asset_root/, exception.message
   end
-end
+end
diff --git a/test/html/pipeline/markdown_filter_test.rb b/test/html/pipeline/markdown_filter_test.rb
diff --git a/test/html/pipeline/plain_text_input_filter_test.rb b/test/html/pipeline/plain_text_input_filter_test.rb
diff --git a/test/html/pipeline/sanitization_filter_test.rb b/test/html/pipeline/sanitization_filter_test.rb
diff --git a/test/html/pipeline/syntax_highlight_filter_test.rb b/test/html/pipeline/syntax_highlight_filter_test.rb
diff --git a/test/html/pipeline/textile_filter_test.rb b/test/html/pipeline/textile_filter_test.rb
diff --git a/test/test_helper.rb b/test/test_helper.rb
