nokogiri 1.10.9 → 1.18.3

data/lib/nokogiri/xml/searchable.rb

@@ -1,19 +1,25 @@
+# coding: utf-8
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     #
     #  The Searchable module declares the interface used for searching your DOM.
     #
-    #  It implements the public methods `search`, `css`, and `xpath`,
+    #  It implements the public methods #search, #css, and #xpath,
     #  as well as allowing specific implementations to specialize some
     #  of the important behaviors.
     #
     module Searchable
       # Regular expression used by Searchable#search to determine if a query
       # string is CSS or XPath
-      LOOKS_LIKE_XPATH = /^(\.\/|\/|\.\.|\.$)/
-      
+      LOOKS_LIKE_XPATH = %r{^(\./|/|\.\.|\.$)}
+
+      # :section: Searching via XPath or CSS Queries
+
       ###
-      # call-seq: search *paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class]
+      # call-seq:
+      #   search(*paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class])
       #
       # Search this object for +paths+. +paths+ must be one or more XPath or CSS queries:
       #
@@ -24,52 +30,56 @@ module Nokogiri
       #   node.search('.//bike:tire', {'bike' => 'http://schwinn.com/'})
       #   node.search('bike|tire', {'bike' => 'http://schwinn.com/'})
       #
-      # For XPath queries, a hash of variable bindings may also be
-      # appended to the namespace bindings. For example:
+      # For XPath queries, a hash of variable bindings may also be appended to the namespace
+      # bindings. For example:
       #
       #   node.search('.//address[@domestic=$value]', nil, {:value => 'Yes'})
       #
-      # Custom XPath functions and CSS pseudo-selectors may also be
-      # defined. To define custom functions create a class and
-      # implement the function you want to define.  The first argument
-      # to the method will be the current matching NodeSet.  Any other
-      # arguments are ones that you pass in.  Note that this class may
-      # appear anywhere in the argument list.  For example:
-      #
-      #   node.search('.//title[regex(., "\w+")]', 'div.employee:regex("[0-9]+")'
-      #     Class.new {
-      #       def regex node_set, regex
-      #         node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ }
-      #       end
-      #     }.new
-      #   )
+      # 💡 Custom XPath functions and CSS pseudo-selectors may also be defined. To define custom
+      # functions create a class and implement the function you want to define, which will be in the
+      # `nokogiri` namespace in XPath queries.
+      #
+      # The first argument to the method will be the current matching NodeSet. Any other arguments
+      # are ones that you pass in. Note that this class may appear anywhere in the argument
+      # list. For example:
+      #
+      #   handler = Class.new {
+      #     def regex node_set, regex
+      #       node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ }
+      #     end
+      #   }.new
+      #   node.search('.//title[nokogiri:regex(., "\w+")]', 'div.employee:regex("[0-9]+")', handler)
       #
       # See Searchable#xpath and Searchable#css for further usage help.
-      def search *args
+      def search(*args)
         paths, handler, ns, binds = extract_params(args)
 
         xpaths = paths.map(&:to_s).map do |path|
-          (path =~ LOOKS_LIKE_XPATH) ? path : xpath_query_from_css_rule(path, ns)
+          LOOKS_LIKE_XPATH.match?(path) ? path : xpath_query_from_css_rule(path, ns)
         end.flatten.uniq
 
         xpath(*(xpaths + [ns, handler, binds].compact))
       end
-      alias :/ :search
+
+      alias_method :/, :search
 
       ###
-      # call-seq: search *paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class]
+      # call-seq:
+      #   at(*paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class])
       #
       # Search this object for +paths+, and return only the first
       # result. +paths+ must be one or more XPath or CSS queries.
       #
       # See Searchable#search for more information.
-      def at *args
+      def at(*args)
         search(*args).first
       end
-      alias :% :at
+
+      alias_method :%, :at
 
       ###
-      # call-seq: css *rules, [namespace-bindings, custom-pseudo-class]
+      # call-seq:
+      #   css(*rules, [namespace-bindings, custom-pseudo-class])
       #
       # Search this object for CSS +rules+. +rules+ must be one or more CSS
       # selectors. For example:
@@ -82,44 +92,61 @@ module Nokogiri
       #
       #   node.css('bike|tire', {'bike' => 'http://schwinn.com/'})
       #
-      # Custom CSS pseudo classes may also be defined.  To define
-      # custom pseudo classes, create a class and implement the custom
-      # pseudo class you want defined.  The first argument to the
-      # method will be the current matching NodeSet.  Any other
-      # arguments are ones that you pass in.  For example:
+      # 💡 Custom CSS pseudo classes may also be defined which are mapped to a custom XPath
+      # function.  To define custom pseudo classes, create a class and implement the custom pseudo
+      # class you want defined. The first argument to the method will be the matching context
+      # NodeSet. Any other arguments are ones that you pass in. For example:
       #
-      #   node.css('title:regex("\w+")', Class.new {
-      #     def regex node_set, regex
+      #   handler = Class.new {
+      #     def regex(node_set, regex)
       #       node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ }
       #     end
-      #   }.new)
+      #   }.new
+      #   node.css('title:regex("\w+")', handler)
+      #
+      # 💡 Some XPath syntax is supported in CSS queries. For example, to query for an attribute:
+      #
+      #   node.css('img > @href') # returns all +href+ attributes on an +img+ element
+      #   node.css('img / @href') # same
+      #
+      #   # ⚠ this returns +class+ attributes from all +div+ elements AND THEIR CHILDREN!
+      #   node.css('div @class')
+      #
+      #   node.css
+      #
+      # 💡 Array-like syntax is supported in CSS queries as an alternative to using +:nth-child()+.
       #
-      # Note that the CSS query string is case-sensitive with regards
-      # to your document type. That is, if you're looking for "H1" in
-      # an HTML document, you'll never find anything, since HTML tags
-      # will match only lowercase CSS queries. However, "H1" might be
-      # found in an XML document, where tags names are case-sensitive
-      # (e.g., "H1" is distinct from "h1").
+      # ⚠ NOTE that indices are 1-based like +:nth-child+ and not 0-based like Ruby Arrays. For
+      # example:
       #
-      def css *args
+      #   # equivalent to 'li:nth-child(2)'
+      #   node.css('li[2]') # retrieve the second li element in a list
+      #
+      # ⚠ NOTE that the CSS query string is case-sensitive with regards to your document type. HTML
+      # tags will match only lowercase CSS queries, so if you search for "H1" in an HTML document,
+      # you'll never find anything. However, "H1" might be found in an XML document, where tags
+      # names are case-sensitive (e.g., "H1" is distinct from "h1").
+      def css(*args)
         rules, handler, ns, _ = extract_params(args)
 
-        css_internal self, rules, handler, ns
+        css_internal(self, rules, handler, ns)
       end
 
       ##
-      # call-seq: css *rules, [namespace-bindings, custom-pseudo-class]
+      # call-seq:
+      #   at_css(*rules, [namespace-bindings, custom-pseudo-class])
       #
       # Search this object for CSS +rules+, and return only the first
       # match. +rules+ must be one or more CSS selectors.
       #
       # See Searchable#css for more information.
-      def at_css *args
+      def at_css(*args)
         css(*args).first
       end
 
       ###
-      # call-seq: xpath *paths, [namespace-bindings, variable-bindings, custom-handler-class]
+      # call-seq:
+      #   xpath(*paths, [namespace-bindings, variable-bindings, custom-handler-class])
       #
       # Search this node for XPath +paths+. +paths+ must be one or more XPath
       # queries.
@@ -135,95 +162,112 @@ module Nokogiri
       #
       #   node.xpath('.//address[@domestic=$value]', nil, {:value => 'Yes'})
       #
-      # Custom XPath functions may also be defined.  To define custom
-      # functions create a class and implement the function you want
-      # to define.  The first argument to the method will be the
-      # current matching NodeSet.  Any other arguments are ones that
-      # you pass in.  Note that this class may appear anywhere in the
-      # argument list.  For example:
+      # 💡 Custom XPath functions may also be defined. To define custom functions create a class and
+      # implement the function you want to define, which will be in the `nokogiri` namespace.
       #
-      #   node.xpath('.//title[regex(., "\w+")]', Class.new {
-      #     def regex node_set, regex
+      # The first argument to the method will be the current matching NodeSet. Any other arguments
+      # are ones that you pass in. Note that this class may appear anywhere in the argument
+      # list. For example:
+      #
+      #   handler = Class.new {
+      #     def regex(node_set, regex)
       #       node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ }
       #     end
-      #   }.new)
+      #   }.new
+      #   node.xpath('.//title[nokogiri:regex(., "\w+")]', handler)
       #
-      def xpath *args
+      def xpath(*args)
         paths, handler, ns, binds = extract_params(args)
 
-        xpath_internal self, paths, handler, ns, binds
+        xpath_internal(self, paths, handler, ns, binds)
       end
 
       ##
-      # call-seq: xpath *paths, [namespace-bindings, variable-bindings, custom-handler-class]
+      # call-seq:
+      #   at_xpath(*paths, [namespace-bindings, variable-bindings, custom-handler-class])
       #
       # Search this node for XPath +paths+, and return only the first
       # match. +paths+ must be one or more XPath queries.
       #
       # See Searchable#xpath for more information.
-      def at_xpath *args
+      def at_xpath(*args)
         xpath(*args).first
       end
 
-      private
-
-      def css_internal node, rules, handler, ns
-        xpath_internal node, css_rules_to_xpath(rules, ns), handler, ns, nil
+      # :call-seq:
+      #   >(selector) → NodeSet
+      #
+      # Search this node's immediate children using CSS selector +selector+
+      def >(selector) # rubocop:disable Naming/BinaryOperatorParameterName
+        ns = document.root&.namespaces || {}
+        xpath(CSS.xpath_for(selector, prefix: "./", ns: ns).first)
       end
 
-      def xpath_internal node, paths, handler, ns, binds
-        document = node.document
-        return NodeSet.new(document) unless document
+      # :section:
 
-        if paths.length == 1
-          return xpath_impl(node, paths.first, handler, ns, binds)
+      private
+
+      def extract_params(params) # :nodoc:
+        handler = params.find do |param|
+          ![Hash, String, Symbol].include?(param.class)
         end
+        params -= [handler] if handler
 
-        NodeSet.new(document) do |combined|
-          paths.each do |path|
-            xpath_impl(node, path, handler, ns, binds).each { |set| combined << set }
-          end
+        hashes = []
+        while Hash === params.last || params.last.nil?
+          hashes << params.pop
+          break if params.empty?
         end
-      end
+        ns, binds = hashes.reverse
 
-      def xpath_impl node, path, handler, ns, binds
-        ctx = XPathContext.new(node)
-        ctx.register_namespaces(ns)
-        path = path.gsub(/xmlns:/, ' :') unless Nokogiri.uses_libxml?
+        ns ||= document.root&.namespaces || {}
 
-        binds.each do |key,value|
-          ctx.register_variable key.to_s, value
-        end if binds
+        [params, handler, ns, binds]
+      end
 
-        ctx.evaluate(path, handler)
+      def css_internal(node, rules, handler, ns)
+        xpath_internal(node, css_rules_to_xpath(rules, ns), handler, ns, nil)
       end
 
       def css_rules_to_xpath(rules, ns)
         rules.map { |rule| xpath_query_from_css_rule(rule, ns) }
       end
 
-      def xpath_query_from_css_rule rule, ns
+      def xpath_query_from_css_rule(rule, ns)
         self.class::IMPLIED_XPATH_CONTEXTS.map do |implied_xpath_context|
-          CSS.xpath_for(rule.to_s, :prefix => implied_xpath_context, :ns => ns)
-        end.join(' | ')
+          visitor = Nokogiri::CSS::XPathVisitor.new(
+            builtins: Nokogiri::CSS::XPathVisitor::BuiltinsConfig::OPTIMAL,
+            doctype: document.xpath_doctype,
+            prefix: implied_xpath_context,
+            namespaces: ns,
+          )
+          CSS.xpath_for(rule.to_s, visitor: visitor)
+        end.join(" | ")
       end
 
-      def extract_params params # :nodoc:
-        handler = params.find do |param|
-          ![Hash, String, Symbol].include?(param.class)
+      def xpath_internal(node, paths, handler, ns, binds)
+        document = node.document
+        return NodeSet.new(document) unless document
+
+        if paths.length == 1
+          return xpath_impl(node, paths.first, handler, ns, binds)
         end
-        params -= [handler] if handler
 
-        hashes = []
-        while Hash === params.last || params.last.nil?
-          hashes << params.pop
-          break if params.empty?
+        NodeSet.new(document) do |combined|
+          paths.each do |path|
+            xpath_impl(node, path, handler, ns, binds).each { |set| combined << set }
+          end
         end
-        ns, binds = hashes.reverse
+      end
 
-        ns ||= document.root ? document.root.namespaces : {}
+      def xpath_impl(node, path, handler, ns, binds)
+        context = XPathContext.new(node)
+        context.register_namespaces(ns)
+        context.register_variables(binds)
 
-        [params, handler, ns, binds]
+        path = path.gsub("xmlns:", " :") unless Nokogiri.uses_libxml?
+
+        context.evaluate(path, handler)
       end
     end
   end

data/lib/nokogiri/xml/syntax_error.rb

@@ -1,14 +1,38 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     ###
     # This class provides information about XML SyntaxErrors.  These
     # exceptions are typically stored on Nokogiri::XML::Document#errors.
     class SyntaxError < ::Nokogiri::SyntaxError
+      class << self
+        def aggregate(errors)
+          return nil if errors.empty?
+          return errors.first if errors.length == 1
+
+          messages = ["Multiple errors encountered:"]
+          errors.each do |error|
+            messages << error.to_s
+          end
+          new(messages.join("\n"))
+        end
+      end
+
       attr_reader :domain
       attr_reader :code
       attr_reader :level
       attr_reader :file
       attr_reader :line
+
+      # The XPath path of the node that caused the error when validating a `Nokogiri::XML::Document`.
+      #
+      # This attribute will only be non-nil when the error is emitted by `Schema#validate` on
+      # Document objects. It will return `nil` for DOM parsing errors and for errors emitted during
+      # Schema validation of files.
+      #
+      # ⚠ `#path` is not supported on JRuby, where it will always return `nil`.
+      attr_reader :path
       attr_reader :str1
       attr_reader :str2
       attr_reader :str3
@@ -41,9 +65,9 @@ module Nokogiri
 
       def to_s
         message = super.chomp
-        [location_to_s, level_to_s, message].
-          compact.join(": ").
-          force_encoding(message.encoding)
+        [location_to_s, level_to_s, message]
+          .compact.join(": ")
+          .force_encoding(message.encoding)
       end
 
       private
@@ -53,7 +77,6 @@ module Nokogiri
         when 3 then "FATAL"
         when 2 then "ERROR"
         when 1 then "WARNING"
-        else nil
         end
       end
 
@@ -62,7 +85,8 @@ module Nokogiri
       end
 
       def location_to_s
-        return nil if nil_or_zero?(line) && nil_or_zero?(column)
+        return if nil_or_zero?(line) && nil_or_zero?(column)
+
         "#{line}:#{column}"
       end
     end

data/lib/nokogiri/xml/text.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class Text < Nokogiri::XML::CharacterData

data/lib/nokogiri/xml/xpath/syntax_error.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
-    class XPath
+    module XPath
       class SyntaxError < XML::SyntaxError
         def to_s
-          [super.chomp, str1].compact.join(': ')
+          [super.chomp, str1].compact.join(": ")
         end
       end
     end

data/lib/nokogiri/xml/xpath.rb

@@ -1,10 +1,21 @@
-require 'nokogiri/xml/xpath/syntax_error'
+# frozen_string_literal: true
 
 module Nokogiri
   module XML
-    class XPath
-      # The Nokogiri::XML::Document tied to this XPath instance
-      attr_accessor :document
+    module XPath
+      # The XPath search prefix to search globally, +//+
+      GLOBAL_SEARCH_PREFIX = "//"
+
+      # The XPath search prefix to search direct descendants of the root element, +/+
+      ROOT_SEARCH_PREFIX = "/"
+
+      # The XPath search prefix to search direct descendants of the current element, +./+
+      CURRENT_SEARCH_PREFIX = "./"
+
+      # The XPath search prefix to search anywhere in the current element's subtree, +.//+
+      SUBTREE_SEARCH_PREFIX = ".//"
     end
   end
 end
+
+require_relative "xpath/syntax_error"

data/lib/nokogiri/xml/xpath_context.rb

@@ -1,16 +1,27 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class XPathContext
-
       ###
       # Register namespaces in +namespaces+
       def register_namespaces(namespaces)
-        namespaces.each do |k, v|
-          k = k.to_s.gsub(/.*:/,'') # strip off 'xmlns:' or 'xml:'
-          register_ns(k, v)
+        namespaces.each do |key, value|
+          key = key.to_s.gsub(/.*:/, "") # strip off 'xmlns:' or 'xml:'
+
+          register_ns(key, value)
         end
       end
 
+      def register_variables(binds)
+        return if binds.nil?
+
+        binds.each do |key, value|
+          key = key.to_s
+
+          register_variable(key, value)
+        end
+      end
     end
   end
 end

data/lib/nokogiri/xml.rb

@@ -1,75 +1,65 @@
-require 'nokogiri/xml/pp'
-require 'nokogiri/xml/parse_options'
-require 'nokogiri/xml/sax'
-require 'nokogiri/xml/searchable'
-require 'nokogiri/xml/node'
-require 'nokogiri/xml/attribute_decl'
-require 'nokogiri/xml/element_decl'
-require 'nokogiri/xml/element_content'
-require 'nokogiri/xml/character_data'
-require 'nokogiri/xml/namespace'
-require 'nokogiri/xml/attr'
-require 'nokogiri/xml/dtd'
-require 'nokogiri/xml/cdata'
-require 'nokogiri/xml/text'
-require 'nokogiri/xml/document'
-require 'nokogiri/xml/document_fragment'
-require 'nokogiri/xml/processing_instruction'
-require 'nokogiri/xml/node_set'
-require 'nokogiri/xml/syntax_error'
-require 'nokogiri/xml/xpath'
-require 'nokogiri/xml/xpath_context'
-require 'nokogiri/xml/builder'
-require 'nokogiri/xml/reader'
-require 'nokogiri/xml/notation'
-require 'nokogiri/xml/entity_decl'
-require 'nokogiri/xml/entity_reference'
-require 'nokogiri/xml/schema'
-require 'nokogiri/xml/relax_ng'
+# frozen_string_literal: true
 
 module Nokogiri
   class << self
-    ###
-    # Parse XML.  Convenience method for Nokogiri::XML::Document.parse
-    def XML thing, url = nil, encoding = nil, options = XML::ParseOptions::DEFAULT_XML, &block
-      Nokogiri::XML::Document.parse(thing, url, encoding, options, &block)
+    # Convenience method for Nokogiri::XML::Document.parse
+    def XML(...)
+      Nokogiri::XML::Document.parse(...)
     end
   end
 
   module XML
     # Original C14N 1.0 spec canonicalization
-    XML_C14N_1_0 =       0
+    XML_C14N_1_0 = 0
     # Exclusive C14N 1.0 spec canonicalization
-    XML_C14N_EXCLUSIVE_1_0 =     1
+    XML_C14N_EXCLUSIVE_1_0 = 1
     # C14N 1.1 spec canonicalization
     XML_C14N_1_1 = 2
-    class << self
-      ###
-      # Parse an XML document using the Nokogiri::XML::Reader API.  See
-      # Nokogiri::XML::Reader for mor information
-      def Reader string_or_io, url = nil, encoding = nil, options = ParseOptions::STRICT
-
-        options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
-        # Give the options to the user
-        yield options if block_given?
 
-        if string_or_io.respond_to? :read
-          return Reader.from_io(string_or_io, url, encoding, options.to_i)
-        end
-        Reader.from_memory(string_or_io, url, encoding, options.to_i)
+    class << self
+      # Convenience method for Nokogiri::XML::Reader.new
+      def Reader(...)
+        Reader.new(...)
       end
 
-      ###
-      # Parse XML.  Convenience method for Nokogiri::XML::Document.parse
-      def parse thing, url = nil, encoding = nil, options = ParseOptions::DEFAULT_XML, &block
-        Document.parse(thing, url, encoding, options, &block)
+      # Convenience method for Nokogiri::XML::Document.parse
+      def parse(...)
+        Document.parse(...)
       end
 
-      ####
-      # Parse a fragment from +string+ in to a NodeSet.
-      def fragment string
-        XML::DocumentFragment.parse(string)
+      # Convenience method for Nokogiri::XML::DocumentFragment.parse
+      def fragment(...)
+        XML::DocumentFragment.parse(...)
       end
     end
   end
 end
+
+require_relative "xml/pp"
+require_relative "xml/parse_options"
+require_relative "xml/sax"
+require_relative "xml/searchable"
+require_relative "xml/node"
+require_relative "xml/attribute_decl"
+require_relative "xml/element_decl"
+require_relative "xml/element_content"
+require_relative "xml/character_data"
+require_relative "xml/namespace"
+require_relative "xml/attr"
+require_relative "xml/dtd"
+require_relative "xml/cdata"
+require_relative "xml/text"
+require_relative "xml/document"
+require_relative "xml/document_fragment"
+require_relative "xml/processing_instruction"
+require_relative "xml/node_set"
+require_relative "xml/syntax_error"
+require_relative "xml/xpath"
+require_relative "xml/xpath_context"
+require_relative "xml/builder"
+require_relative "xml/reader"
+require_relative "xml/notation"
+require_relative "xml/entity_decl"
+require_relative "xml/entity_reference"
+require_relative "xml/schema"
+require_relative "xml/relax_ng"