A future version of Nokogiri will provide Nokogumbo's API (see
https://github.com/sparklemotion/nokogiri/issues/2204). This change
will allow Nokogumbo to detect whether Nokogiri provides the HTML5 API
and whether to use Nokogiri's implementation or Nokogumbo's
implementation.
This was discussed in-depth at #170.
What approach did you choose and why?
Some contractual assumptions I'm making about Nokogiri:
Nokogiri will faithfully reproduce the ::Nokogiri::HTML5 singleton
method, module, and namespace (including classes
Nokogiri::HTML5::Node, Nokogiri::HTML5::Document, and
Nokogiri::HTML5::DocumentFragment)
Nokogiri will not provide a ::Nokogumbo module/namespace, but will
provide a similar ::Nokogiri::Gumbo module which will provide the
same public API as ::Nokogumbo.
This change checks for the existence of Nokogiri::HTML5,
Nokogiri::Gumbo, and an expected singleton method on each. We could
do a more- or less-thorough check here.
This change also provides an "escape hatch" using an environment
variable NOKOGUMBO_IGNORE_NOKOGIRI_HTML5 which can be set to force
Nokogumbo to use its own implementation. This escape hatch might be
unnecessary, but this change is invasive enough to make me want to be
cautious.
Nokogumbo will emit a single warning message at require-time when it
is uses Nokogiri's implementation. This message points users to
https://github.com/sparklemotion/nokogiri/issues/2205 which will
explain what's going on and help people migrate their
applications (but is an empty placeholder right now).
What should reviewers focus on?
Please check my assumptions and provide feedback on the decisions made.
What are you trying to accomplish?
A future version of Nokogiri will provide Nokogumbo's API (see https://github.com/sparklemotion/nokogiri/issues/2204). This change will allow Nokogumbo to detect whether Nokogiri provides the HTML5 API and whether to use Nokogiri's implementation or Nokogumbo's implementation.
This was discussed in-depth at #170.
What approach did you choose and why?
Some contractual assumptions I'm making about Nokogiri:
Nokogiri will faithfully reproduce the
::Nokogiri::HTML5singleton method, module, and namespace (including classesNokogiri::HTML5::Node,Nokogiri::HTML5::Document, andNokogiri::HTML5::DocumentFragment)Nokogiri will not provide a
::Nokogumbomodule/namespace, but will provide a similar::Nokogiri::Gumbomodule which will provide the same public API as::Nokogumbo.This change checks for the existence of
Nokogiri::HTML5,Nokogiri::Gumbo, and an expected singleton method on each. We could do a more- or less-thorough check here.This change also provides an "escape hatch" using an environment variable
NOKOGUMBO_IGNORE_NOKOGIRI_HTML5which can be set to force Nokogumbo to use its own implementation. This escape hatch might be unnecessary, but this change is invasive enough to make me want to be cautious.Nokogumbo will emit a single warning message at
require-time when it is uses Nokogiri's implementation. This message points users to https://github.com/sparklemotion/nokogiri/issues/2205 which will explain what's going on and help people migrate their applications (but is an empty placeholder right now).What should reviewers focus on?
Please check my assumptions and provide feedback on the decisions made.