Potential class loading conflict with add-on filters

[mojavelinux]

Due to the fact that HTML::Pipeline is a class, not a module, there is risk that an add-on filter will prematurely define this class before it's extended in the core library, which causes the notorious "superclass mismatch" exception.

Here's an example of where this happens. While create a new gem for the BarFilter, we define a version file:

lib/html/pipeline/bar_filter/version.rb

module HTML
  class Pipeline
    class BarFilter
      VERSION = '1.0.0'
    end
  end
end

If we load this at the top of a gemspec file, for instance, then if we attempt to load 'html/pipeline', it goes 💥.

Normally the way these things are defined (as far as I understand it), the top-level type in a gem is a module, not a class. One way to accomplish this without breaking the current API (much), is to define the class method new on the module that instantiates the concrete class. Something like:

module HTML
  module Pipeline
    def self.new filters, default_context = {}, result_class = nil
      Engine.new filters, default_context, result_class
    end

    class Engine
      # relocate Pipeline class definition here
    end
  end
end

The other solution, which I used in html-pipeline-asciidoc_filter, is to put the filter class in a different module for the purpose of holding the VERSION constant.

module HTML_Pipeline
class BarFilter
  VERSION = '1.0.0'
end
end

Either way, I think this is an important issue to address to minimize the challenges of creating an add-on filter.

[jch]

We discussed this issue extensively while extracting the gem. You make a valid point, but I think it's simple enough to catch for extension writers.