Add global XPath functions handler

[jonathanhefner]

What problem is this PR intended to solve?

Allow global definition of XPath functions, e.g.

module MyFunctions
  def regex(node_set, pattern)
    node_set.find_all { |node| node['some_attribute'] =~ /#{pattern}/ }
  end
end

Nokogiri::XML::XPathFunctions.include(MyFunctions)

node.search('.//title[regex(., "\w+")]', 'div.employee:regex("[0-9]+")')

This is a revival of #464 with a different approach. Although that PR is shown as merged, I think that's a GitHub bug. The original implementation was mbklein/nokogiri@8fb3da3 which has not been merged.

Have you included adequate test coverage?

I think so. I refrained from adding tests which would overlap with existing tests, but I would be happy to add more, if you have suggestions.

Does this change affect the C or the Java implementations?

No. Apparently, yes. The Java implementation injects XML namespaces into XPath queries based on the Ruby methods the function handler defines. Previously, that list of methods was derived from the function handler class, which omits methods delegated by SimpleDelegator. Now the list of methods is derived directly from the function handler object.

[codeclimate]

Code Climate has analyzed commit c3376dd and detected 0 issues on this pull request.

The test coverage on the diff in this pull request is 100.0% (80% is the threshold).

This pull request will bring the total coverage in the repository to 93.5% (0.0% change).

View more on Code Climate.

[jonathanhefner]

This condition should now always be true (i.e. handler will always be an instance of XPathFunctions). Should I remove this if?

[flavorjones]

Thank you for submitting this PR! I'll take a look as soon as I can, this is a super-busy week for me.

[flavorjones]

Sorry this has gone so long without review; I'm tagging it for v1.11.0 which I'm hoping to release at the end of 2019, so will review in that timeframe.

[ghost]

เล่นไรกันวะ

[flavorjones]

I've rebased this onto current main.

[flavorjones]

I've added a require "delegate" which was needed to not break downstream CI, e.g.

• https://github.com/sparklemotion/nokogiri/runs/8058997083?check_suite_focus=true
• https://github.com/sparklemotion/nokogiri/runs/8058997115?check_suite_focus=true

[flavorjones]

OK, the method lookup in the XmlXpathContext.java:evalute() block doesn't work properly. I spent a few minutes exploring how to get the public methods out of the block but couldn't quite figure it out.

Here's the failing test that needs to be added:

      def test_search_with_xpath_query_uses_global_custom_selectors_with_arguments_without_namespace
        skip("Testing fallback behavior in JRuby") unless Nokogiri.jruby?

        XPathFunctions.class_eval do
          def our_filter(*args)
            my_filter(*args)
          end
        end

        set = @xml.search('//employee/address[our_filter(., "domestic", "Yes")]', @handler)
        refute_empty(set)
        set.each do |node|
          assert_equal("Yes", node["domestic"])
        end
      end

I also want to point out that the intention is to deprecate use of custom XPath functions without the nokogiri: prefix -- see #2147. We might reasonably wait until that lands and then take another look at this.

[jonathanhefner]

@flavorjones Oh wow, I forgot about this one! I am fine with waiting until after #2147 — no rush. Still, I was curious to see if I could get it working, so I pushed a commit to fix any failing tests, including the one you mentioned (test_search_with_xpath_query_uses_global_custom_selectors_with_arguments_without_namespace).

[flavorjones]

Thank you! I'll take another look

[flavorjones]

OK, I'm sorry this has been open for so long.

After a lot of thought, I'm leaning towards not accepting this feature into Nokogiri.

I think, over the last decade, Nokogiri has moved towards the bottom of most people's stack -- that is, the majority of dependencies on Nokogiri are indirect (via rails-html-sanitizer, for example) and not direct. As a result, I've grown less enthusiastic about introducing global behavior changes, simply because I want to reduce the blast radius should there be some sort of unexpected conflict between two libraries both trying to use this functionality. (I'm imagining two libraries each trying to implement a function with a common name, and a user having no way to diagnose or work around the problem.)

I think that @mbklein's suggestion of making this into a document-specific generator decorator is a better idea from the perspective of a) explicitly mixing in behavior and b) limiting blast radius.

I'm really sorry that this decision took so long to make, and I want to say thanks very much for putting in the work on this PR to try to improve Nokogiri!

I'd be happy to keep discussing this, but I'm going to close this in the meantime.

Thank you again!

Small edits for clarity made on 2026-06-27.

[jonathanhefner]

@flavorjones Thank you for explaining your thought process! 😄