Filters Manage Dependencies

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

README.md

@@ -98,6 +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
 
+## 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. For example, 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.
+
 ## 3rd Party Extensions
 
 If you have an idea for a filter, propose it as
@@ -107,19 +130,6 @@ built as an external gem.
 
 * [html-pipeline-asciidoc_filter](https://github.com/asciidoctor/html-pipeline-asciidoc_filter) - asciidoc support
 
-
-## Syntax highlighting
-
-`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:
-
-```ruby
-gem 'github-linguist'
-```
-
 ## Examples
 
 We define different pipelines for different parts of our app. Here are a few

bin/html-pipeline

@@ -54,8 +54,6 @@ else
     case name
     when "Text"
       raise NameError # Text filter doesn't work, no call method
-    when "Textile"
-      require "RedCloth" # Textile filter doesn't require RedCloth
     end
 
     HTML::Pipeline.const_get("#{name}Filter")
@@ -77,4 +75,4 @@ context = {
   :gfm        => true
 }
 
-puts HTML::Pipeline.new(filters, context).call(ARGF.read)[:output]
+puts HTML::Pipeline.new(filters, context).call(ARGF.read)[:output]

html-pipeline.gemspec

@@ -15,13 +15,15 @@ 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 "activesupport",   RUBY_VERSION < "1.9.3" ? [">= 2", "< 4"] : ">= 2"
+  gem.add_dependency "nokogiri",      RUBY_VERSION < "1.9.2" ? [">= 1.4", "< 1.6"] : "~> 1.4"
+  gem.add_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!
+You must bundle Filter gem dependencies.
+See html-pipeline README.md for more details.
+https://github.com/jch/html-pipeline#dependencies
+-------------------------------------------------
+msg
 end

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

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

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

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

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)

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

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

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

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

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

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 "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

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 "email_reply_filter", "escape_utils"
+  end
+end

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 "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

test/html/pipeline/markdown_filter_test.rb

@@ -18,6 +18,10 @@ def setup
       "```"
   end
 
+  def test_dependency_management
+    assert_dependency "markdown_filter", "github-markdown"
+  end
+
   def test_fails_when_given_a_documentfragment
     body = "<p>heyo</p>"
     doc  = HTML::Pipeline.parse(body)
@@ -27,26 +31,26 @@ def test_fails_when_given_a_documentfragment
   def test_gfm_enabled_by_default
     doc = MarkdownFilter.to_document(@haiku, {})
     assert doc.kind_of?(HTML::Pipeline::DocumentFragment)
-    assert_equal 2, doc.search('br').size
+    assert_equal 2, doc.search("br").size
   end
 
   def test_disabling_gfm
     doc = MarkdownFilter.to_document(@haiku, :gfm => false)
     assert doc.kind_of?(HTML::Pipeline::DocumentFragment)
-    assert_equal 0, doc.search('br').size
+    assert_equal 0, doc.search("br").size
   end
 
   def test_fenced_code_blocks
     doc = MarkdownFilter.to_document(@code)
     assert doc.kind_of?(HTML::Pipeline::DocumentFragment)
-    assert_equal 1, doc.search('pre').size
+    assert_equal 1, doc.search("pre").size
   end
 
   def test_fenced_code_blocks_with_language
     doc = MarkdownFilter.to_document(@code.sub("```", "``` ruby"))
     assert doc.kind_of?(HTML::Pipeline::DocumentFragment)
-    assert_equal 1, doc.search('pre').size
-    assert_equal 'ruby', doc.search('pre').first['lang']
+    assert_equal 1, doc.search("pre").size
+    assert_equal "ruby", doc.search("pre").first["lang"]
   end
 end
 

test/html/pipeline/plain_text_input_filter_test.rb

@@ -3,6 +3,10 @@
 class HTML::Pipeline::PlainTextInputFilterTest < Test::Unit::TestCase
   PlainTextInputFilter = HTML::Pipeline::PlainTextInputFilter
 
+  def test_dependency_management
+    assert_dependency "plain_text_input_filter", "escape_utils"
+  end
+
   def test_fails_when_given_a_documentfragment
     body = "<p>heyo</p>"
     doc  = Nokogiri::HTML::DocumentFragment.parse(body)

test/html/pipeline/sanitization_filter_test.rb

@@ -3,6 +3,10 @@
 class HTML::Pipeline::SanitizationFilterTest < Test::Unit::TestCase
   SanitizationFilter = HTML::Pipeline::SanitizationFilter
 
+  def test_dependency_management
+    assert_dependency "sanitization_filter", "sanitize"
+  end
+
   def test_removing_script_tags
     orig = %(<p><img src="https://github.com/img.png" /><script></script></p>)
     html = SanitizationFilter.call(orig).to_s

test/html/pipeline/syntax_highlight_filter_test.rb

@@ -3,6 +3,10 @@
 SyntaxHighlightFilter = HTML::Pipeline::SyntaxHighlightFilter
 
 class HTML::Pipeline::SyntaxHighlightFilterTest < Test::Unit::TestCase
+  def test_dependency_management
+    assert_dependency "syntax_highlight_filter", "github-linguist"
+  end
+
   def test_highlight_default
     filter = SyntaxHighlightFilter.new \
       "<pre>hello</pre>", :highlight => "coffeescript"