123456789_123456789_123456789_123456789_123456789_

Module: Nokogiri::CSS

Overview

Translate a CSS selector into an XPath 1.0 query

Class Method Summary

Class Method Details

.parse(selector)

This method is for internal use only.

TODO: Deprecate this method ahead of 2.0 and delete it in 2.0. It is not used by ::Nokogiri and shouldn’t be part of the public API.

[ GitHub ] 

  


# File 'lib/nokogiri/css.rb', line 10



def parse(selector) # :nodoc:
  warn("Nokogiri::CSS.parse is deprecated and will be removed in a future version of Nokogiri. Use Nokogiri::CSS::Parser#parse instead.", uplevel: 1, category: :deprecated)
  Parser.new.parse(selector)
end


  








  

    

      .xpath_for(selector_list) → Array<String>)  
      .xpath_for(selector_list [, prefix:] [, ns:] [, visitor:] [, cache:]) → Array<String>)  
    

  



  

    

Translate a CSS selector list to the equivalent XPath expressions.



💡 Note that translated queries are cached by default for performance concerns.



⚠ Users should prefer XML::Searchable#css, which is mixed into all document and node classes, for querying documents with CSS selectors. This method is the underlying mechanism used by XML::Searchable and is provided solely for advanced users to translate CSS selectors to XPath directly.



Also see XML::Searchable#css for documentation on supported CSS selector features, some extended syntax that ::Nokogiri supports, and advanced CSS features like pseudo-class functions.


Parameters



  • 

    selector_list (String)
    


    The CSS selector to be translated into XPath. This is always a String, but that string value may be a selector list (see examples).
    



Keyword arguments



  • 

    prefix: (String)
    


    The XPath expression prefix which determines the search context. See Nokogiri::XML::XPath for standard options. Default is XPath::GLOBAL_SEARCH_PREFIX.
    

  • 

    ns: (Hash<String ⇒ String>, nil)
    


    Namespaces that are referenced in the query, if any. This is a hash where the keys are the namespace prefix and the values are the namespace URIs. Default is nil indicating an empty set of namespaces.
    

  • 

    visitor: (Nokogiri::CSS::XPathVisitor)
    


    Use this XPathVisitor object to transform the CSS AST into XPath expressions. See Nokogiri::CSS::XPathVisitor for more information on some of the complex behavior that can be customized for your document type. Default is XPathVisitor.new.
    


    ⚠ Note that this option is mutually exclusive with prefix and ns. If visitor is provided, prefix and ns must not be present.
    

  • 

    cache: (Boolean)
    


    Whether to use the SelectorCache for the translated query to ensure that repeated queries don’t incur the overhead of re-parsing the selector. Default is true.
    



Returns



(Array<String>) The equivalent set of XPath expressions for selector_list





Example with a simple selector:



Nokogiri::CSS.xpath_for("div") # => ["//div"]



Example with a compound selector:



Nokogiri::CSS.xpath_for("div.xl") # => ["//div[contains(concat(' ',normalize-space(@class),' '),' xl ')]"]



Example with a complex selector:



Nokogiri::CSS.xpath_for("h1 + div") # => ["//h1/following-sibling::*[1]/self::div"]



Example with a selector list:



Nokogiri::CSS.xpath_for("h1, h2, h3") # => ["//h1", "//h2", "//h3"]


  





  
Raises:


    
  
  • 
    (TypeError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/nokogiri/css.rb', line 83



def xpath_for(
  selector, options = nil,
  prefix: options&.delete(:prefix),
  visitor: options&.delete(:visitor),
  ns: options&.delete(:ns),
  cache: true
)
  unless options.nil?
    warn("Nokogiri::CSS.xpath_for: Passing options as an explicit hash is deprecated. Use keyword arguments instead. This will become an error in a future release.", uplevel: 1, category: :deprecated)
  end

  raise(TypeError, "no implicit conversion of #{selector.inspect} to String") unless selector.respond_to?(:to_str)

  selector = selector.to_str
  raise(Nokogiri::CSS::SyntaxError, "empty CSS selector") if selector.empty?

  if visitor
    raise ArgumentError, "cannot provide both :prefix and :visitor" if prefix
    raise ArgumentError, "cannot provide both :ns and :visitor" if ns
  end

  visitor ||= begin
    visitor_kw = {}
    visitor_kw[:prefix] = prefix if prefix
    visitor_kw[:namespaces] = ns if ns

    Nokogiri::CSS::XPathVisitor.new(**visitor_kw)
  end

  if cache
    key = SelectorCache.key(selector: selector, visitor: visitor)
    SelectorCache[key] ||= Parser.new.xpath_for(selector, visitor)
  else
    Parser.new.xpath_for(selector, visitor)
  end
end