Deprecate use of non-namespaced XPath custom functions

[flavorjones]

With respect to custom XPath query functions, the Java implementation was forced (by the underlying Java APIs) to implement different behavior from CRuby,, namely that any customer handler functions should be namespaced with the nokogiri prefix, e.g.:

set = if Nokogiri.uses_libxml?
        @xml.search('//employee/address[my_filter(., "domestic", "Yes")]', @handler)
      else
        @xml.search('//employee/address[nokogiri:my_filter(., "domestic", "Yes")]', @handler)
      end

In commit 468c757 we tried to introduce some inference to the JRuby codebase where:

• if a handler is provided,
• but no namespace prefix is used in the query
• then replace any method name in the query with a namespaced equivalent

This inference is problematic in that it led to issues like #1890, and I started planning to deprecate the use of non-namespaced custom XPath functions.

The plan, as of 2022-08-29:

• implement namespace support for customer XPath functions in the C implementation in v1.14
  • feat(cruby): custom XPath functions support nokogiri namespace #2642
• document custom xpath queries everywhere with the nokogiri namespace presented as the preferred syntax
  • deprecate nonnamespaced xpath functions #2867
• start emitting deprecation warnings in v1.15 when non-namespaced functions are used in either the JRuby or CRuby implementation
  • deprecate nonnamespaced xpath functions #2867
• remove support for non-namespaced functions in some future version.

[flavorjones]

Here's the plan I'd like to follow:

Introduce, in v1.14, support for the nokogiri: namespace in the CRuby implementation.

Introduce, in v1.15, a deprecation warning if custom functions are invoked without the nokogiri: namespace. Something like this seems to work:

diff --git a/ext/nokogiri/nokogiri.h b/ext/nokogiri/nokogiri.h
index 63549ec..a81ff66 100644
--- a/ext/nokogiri/nokogiri.h
+++ b/ext/nokogiri/nokogiri.h
@@ -210,9 +210,9 @@ NOKOPUBFUN VALUE Nokogiri_wrap_xml_document(VALUE klass,
 #define DISCARD_CONST_QUAL_XMLCHAR(v) DISCARD_CONST_QUAL(xmlChar *, v)
 
 #if HAVE_RB_CATEGORY_WARNING
-#  define NOKO_WARN_DEPRECATION(message) rb_category_warning(RB_WARN_CATEGORY_DEPRECATED, message)
+#  define NOKO_WARN_DEPRECATION(message...) rb_category_warning(RB_WARN_CATEGORY_DEPRECATED, message)
 #else
-#  define NOKO_WARN_DEPRECATION(message) rb_warning(message)
+#  define NOKO_WARN_DEPRECATION(message...) rb_warning(message)
 #endif
 
 void Nokogiri_structured_error_func_save(libxmlStructuredErrorHandlerState *handler_state);
diff --git a/ext/nokogiri/xml_xpath_context.c b/ext/nokogiri/xml_xpath_context.c
index b8eb633..f412067 100644
--- a/ext/nokogiri/xml_xpath_context.c
+++ b/ext/nokogiri/xml_xpath_context.c
@@ -284,6 +284,13 @@ lookup(void *ctx,
        const xmlChar *ns_uri)
 {
   VALUE xpath_handler = (VALUE)ctx;
+  if (ns_uri == NULL) {
+    NOKO_WARN_DEPRECATION(
+      "A custom XPath or CSS handler function named '%s' is being invoked without a namespace."
+      " Please update your query to reference this function as 'nokogiri:%s'."
+      " Invoking custom handler functions without a namespace is deprecated and support will be removed in a future release of Nokogiri.",
+      name, name);
+  }
   if (rb_respond_to(xpath_handler, rb_intern((const char *)name))) {
     return ruby_funcall;
   }

Then, in some future version of Nokogiri, we'll remove support for non-namespaced custom functions.