lib/rexml/xpath.rb

   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                 # Itterates 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