1 require 'rexml/functions'
2 require 'rexml/xpath_parser'
3
4 module REXML
5 # Wrapper class. Use this class to access the XPath functions.
6 class XPath
7 include Functions
8 EMPTY_HASH = {}
9
10 # Finds and returns the first node that matches the supplied xpath.
11 # element::
12 # The context element
13 # path::
14 # The xpath to search for. If not supplied or nil, returns the first
15 # node matching '*'.
16 # namespaces::
17 # If supplied, a Hash which defines a namespace mapping.
18 #
19 # XPath.first( node )
20 # XPath.first( doc, "//b"} )
21 # XPath.first( node, "a/x:b", { "x"=>"http://doofus" } )
22 def XPath::first element, path=nil, namespaces=nil, variables={}
23 raise "The namespaces argument, if supplied, must be a hash object." unless namespaces.nil? or namespaces.kind_of?(Hash)
24 raise "The variables argument, if supplied, must be a hash object." unless variables.kind_of?(Hash)
25 parser = XPathParser.new
26 parser.namespaces = namespaces
27 parser.variables = variables
28 path = "*" unless path
29 element = [element] unless element.kind_of? Array
30 parser.parse(path, element).flatten[0]
31 end
32
33 # Iterates over nodes that match the given path, calling the supplied
34 # block with the match.
35 # element::
36 # The context element
37 # path::
38 # The xpath to search for. If not supplied or nil, defaults to '*'
39 # namespaces::
40 # If supplied, a Hash which defines a namespace mapping
41 #
42 # XPath.each( node ) { |el| ... }
43 # XPath.each( node, '/*[@attr='v']' ) { |el| ... }
44 # XPath.each( node, 'ancestor::x' ) { |el| ... }
45 def XPath::each element, path=nil, namespaces=nil, variables={}, &block
46 raise "The namespaces argument, if supplied, must be a hash object." unless namespaces.nil? or namespaces.kind_of?(Hash)
47 raise "The variables argument, if supplied, must be a hash object." unless variables.kind_of?(Hash)
48 parser = XPathParser.new
49 parser.namespaces = namespaces
50 parser.variables = variables
51 path = "*" unless path
52 element = [element] unless element.kind_of? Array
53 parser.parse(path, element).each( &block )
54 end
55
56 # Returns an array of nodes matching a given XPath.
57 def XPath::match element, path=nil, namespaces=nil, variables={}
58 parser = XPathParser.new
59 parser.namespaces = namespaces
60 parser.variables = variables
61 path = "*" unless path
62 element = [element] unless element.kind_of? Array
63 parser.parse(path,element)
64 end
65 end
66 end