Deprecate accepting array as an element in XPath.match, first and each (#252)

`XPath.match`, `XPath.first`, `XPath.each`, `XPathParser#parse` and
`XPathParser#match` accepted nodeset as element.
This pull request changes the first parameter of these method to be an
element instead of nodeset.
Passing nodeset will be deprecated.

```ruby
# Documented usage. OK
REXML::XPath.match(element, xpath)

# Undocumented usage. Deprecate in this pull request
nodeset = [element]
REXML::XPath.match(nodeset, xpath)
```

### Background
#249 will introduce a temporary cache.
```ruby
def parse path, nodeset
  path_stack = @parser.parse( path )
  nodeset.first.document.send(:enable_cache) do
    match( path_stack, nodeset )
  end
end
```
But the signature `XPathParser#match(path, nodeset)` does not guarantee
that all nodes in the nodeset has the same root document.
So cache does not work in the code below. It's still slow.
```ruby
REXML::XPath.match(2.times.map { REXML::Document.new('<a>'*400+'</a>'*400) }, 'a//a')
```

The interface is holding our back, so I propose to drop accepting array
as element.
This change is a backward incompatibility, but it just drops
undocumented feature. I think only the test code was unintentionally
using this feature.

### XPath.match with array
XPath.match only traverse the first element of the array for some
selectors.
```ruby
nodeset = [REXML::Document.new("<a><b/></a>"), REXML::Document.new("<a><c/></a>")]

REXML::XPath.match(nodeset, "a/*")
#=> [<b/>, <c/>]

REXML::XPath.match(nodeset, "//a/*")
#=> [<b/>] # I expect [<b/>, <c/>] but the second document is ignored
```
It indicates that `XPath.match` is not designed to search inside
multiple nodes/documents.

---------

Co-authored-by: Sutou Kouhei <kou@cozmixng.org>

Author: tompng

lib/rexml/xpath.rb

@@ -35,7 +35,6 @@ def XPath::first(element, path=nil, namespaces=nil, variables={}, options={})
       parser.namespaces = namespaces
       parser.variables = variables
       path = "*" unless path
-      element = [element] unless element.kind_of? Array
       parser.parse(path, element).flatten[0]
     end
 
@@ -64,7 +63,6 @@ def XPath::each(element, path=nil, namespaces=nil, variables={}, options={}, &bl
       parser.namespaces = namespaces
       parser.variables = variables
       path = "*" unless path
-      element = [element] unless element.kind_of? Array
       parser.parse(path, element).each( &block )
     end
 
@@ -74,7 +72,6 @@ def XPath::match(element, path=nil, namespaces=nil, variables={}, options={})
       parser.namespaces = namespaces
       parser.variables = variables
       path = "*" unless path
-      element = [element] unless element.kind_of? Array
       parser.parse(path,element)
     end
   end

lib/rexml/xpath_parser.rb

@@ -76,19 +76,19 @@ def variables=( vars={} )
       @variables = vars
     end
 
-    def parse path, nodeset
+    def parse path, node
       path_stack = @parser.parse( path )
-      match( path_stack, nodeset )
+      match( path_stack, node )
     end
 
-    def get_first path, nodeset
+    def get_first path, node
       path_stack = @parser.parse( path )
-      first( path_stack, nodeset )
+      first( path_stack, node )
     end
 
-    def predicate path, nodeset
+    def predicate path, node
       path_stack = @parser.parse( path )
-      match( path_stack, nodeset )
+      match( path_stack, node )
     end
 
     def []=( variable_name, value )
@@ -136,11 +136,13 @@ def first( path_stack, node )
     end
 
 
-    def match(path_stack, nodeset)
-      nodeset = nodeset.collect.with_index do |node, i|
-        position = i + 1
-        XPathNode.new(node, position: position)
+    def match(path_stack, node)
+      if node.is_a?(Array)
+        Kernel.warn("REXML::XPath.each, REXML::XPath.first, REXML::XPath.match dropped support for nodeset...", uplevel: 1)
+        return [] if node.empty?
+        node = node.first
       end
+      nodeset = [XPathNode.new(node, position: 1)]
       result = expr(path_stack, nodeset)
       case result
       when Array # nodeset

test/test_jaxen.rb

@@ -56,7 +56,9 @@ def process_test_case(name)
 
     # processes a tests/document/context node
     def process_context(doc, context)
-      test_context = XPath.match(doc, context.attributes["select"])
+      matched = XPath.match(doc, context.attributes["select"])
+      assert_equal(1, matched.size)
+      test_context = matched.first
       namespaces = context.namespaces
       namespaces.delete("var")
       namespaces = nil if namespaces.empty?
@@ -101,10 +103,14 @@ def process_nominal_test(context, variables, namespaces, test)
         assert_equal(Integer(expected, 10),
                      matched.size,
                      user_message(context, xpath, matched))
+      else
+        assert_operator(matched.size, :>, 0, user_message(context, xpath, matched))
       end
 
       XPath.each(test, "valueOf") do |value_of|
-        process_value_of(matched, variables, namespaces, value_of)
+        matched.each do |subcontext|
+          process_value_of(subcontext, variables, namespaces, value_of)
+        end
       end
     end
 
@@ -118,10 +124,8 @@ def process_exceptional_test(context, variables, namespaces, test)
 
     def user_message(context, xpath, matched)
       message = ""
-      context.each_with_index do |node, i|
-        message << "Node#{i}:\n"
-        message << "#{node}\n"
-      end
+      message << "Node:\n"
+      message << "#{context}\n"
       message << "XPath: <#{xpath}>\n"
       message << "Matched <#{matched}>"
       message

test/xpath/test_base.rb

@@ -411,9 +411,10 @@ def test_preceding
 
       s = "<a><b><c id='1'/></b><b><b><c id='2'/><c id='3'/></b><c id='4'/></b><c id='NOMATCH'><c id='5'/></c></a>"
       d = REXML::Document.new(s)
-      c = REXML::XPath.match( d, "//c[@id = '5']")
-      cs = REXML::XPath.match( c, "preceding::c" )
-      assert_equal( 4, cs.length )
+      c = REXML::XPath.match(d, "//c[@id = '5']")
+      assert_equal(1, c.length)
+      cs = REXML::XPath.match(c.first, "preceding::c")
+      assert_equal(4, cs.length)
     end
 
     def test_preceding_multiple
@@ -1255,5 +1256,15 @@ def test_or_and
       end
       assert_equal(["/"], hrefs, "Bug #3842 [ruby-core:32447]")
     end
+
+    def test_match_with_deprecated_usage
+      verbose, $VERBOSE = $VERBOSE, nil
+      doc = Document.new("<a><b/></a>")
+      assert_equal(['b'], XPath.match([doc, doc], '//b').map(&:name))
+      assert_equal(['b'], XPath.match([doc], '//b').map(&:name))
+      assert_equal([], XPath.match([], '//b').map(&:name))
+    ensure
+      $VERBOSE = verbose
+    end
   end
 end