nokogiri 1.12.5 → 1.14.3

data/lib/nokogiri/xml/searchable.rb

@@ -1,22 +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{^(\./|/|\.\.|\.$)}
 
-      # @!group Searching via XPath or CSS Queries
+      # :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:
       #
@@ -27,41 +30,39 @@ 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. 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[regex(., "\w+")]', 'div.employee:regex("[0-9]+")', handler)
       #
       # See Searchable#xpath and Searchable#css for further usage help.
       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.
@@ -71,10 +72,11 @@ module Nokogiri
         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:
@@ -87,33 +89,49 @@ 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')
       #
-      # 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").
+      #   node.css
       #
+      # 💡 Array-like syntax is supported in CSS queries as an alternative to using +:nth-child()+.
+      #
+      # ⚠ NOTE that indices are 1-based like +:nth-child+ and not 0-based like Ruby Arrays. For
+      # example:
+      #
+      #   # 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.
@@ -124,7 +142,8 @@ module Nokogiri
       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.
@@ -140,27 +159,27 @@ 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. 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.xpath('.//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.xpath('.//title[regex(., "\w+")]', handler)
       #
       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.
@@ -170,12 +189,21 @@ module Nokogiri
         xpath(*args).first
       end
 
-      # @!endgroup
+      # :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
+
+      # :section:
 
       private
 
       def css_internal(node, rules, handler, ns)
-        xpath_internal node, css_rules_to_xpath(rules, ns), handler, ns, nil
+        xpath_internal(node, css_rules_to_xpath(rules, ns), handler, ns, nil)
       end
 
       def xpath_internal(node, paths, handler, ns, binds)
@@ -198,9 +226,9 @@ module Nokogiri
         ctx.register_namespaces(ns)
         path = path.gsub(/xmlns:/, " :") unless Nokogiri.uses_libxml?
 
-        binds.each do |key, value|
-          ctx.register_variable key.to_s, value
-        end if binds
+        binds&.each do |key, value|
+          ctx.register_variable(key.to_s, value)
+        end
 
         ctx.evaluate(path, handler)
       end
@@ -210,10 +238,13 @@ module Nokogiri
       end
 
       def xpath_query_from_css_rule(rule, ns)
-        visitor = Nokogiri::CSS::XPathVisitorOptimallyUseBuiltins.new
+        visitor = Nokogiri::CSS::XPathVisitor.new(
+          builtins: Nokogiri::CSS::XPathVisitor::BuiltinsConfig::OPTIMAL,
+          doctype: document.xpath_doctype,
+        )
         self.class::IMPLIED_XPATH_CONTEXTS.map do |implied_xpath_context|
-          CSS.xpath_for(rule.to_s, {:prefix => implied_xpath_context, :ns => ns,
-                                    :visitor => visitor})
+          CSS.xpath_for(rule.to_s, { prefix: implied_xpath_context, ns: ns,
+                                     visitor: visitor, })
         end.join(" | ")
       end
 
@@ -230,7 +261,7 @@ module Nokogiri
         end
         ns, binds = hashes.reverse
 
-        ns ||= document.root ? document.root.namespaces : {}
+        ns ||= (document.root&.namespaces || {})
 
         [params, handler, ns, binds]
       end

data/lib/nokogiri/xml/syntax_error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
     ###
@@ -42,9 +43,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
@@ -54,7 +55,6 @@ module Nokogiri
         when 3 then "FATAL"
         when 2 then "ERROR"
         when 1 then "WARNING"
-        else nil
         end
       end
 
@@ -64,6 +64,7 @@ module Nokogiri
 
       def location_to_s
         return nil if nil_or_zero?(line) && nil_or_zero?(column)
+
         "#{line}:#{column}"
       end
     end

data/lib/nokogiri/xml/text.rb

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

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

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
     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,7 +1,19 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
     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

data/lib/nokogiri/xml/xpath_context.rb

@@ -1,17 +1,16 @@
 # 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:'
+          k = k.to_s.gsub(/.*:/, "") # strip off 'xmlns:' or 'xml:'
           register_ns(k, v)
         end
       end
-
     end
   end
 end

data/lib/nokogiri/xml.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Nokogiri
   class << self
     ###
@@ -21,12 +22,12 @@ module Nokogiri
       # 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)
       end
 
@@ -38,8 +39,8 @@ module Nokogiri
 
       ####
       # Parse a fragment from +string+ in to a NodeSet.
-      def fragment(string)
-        XML::DocumentFragment.parse(string)
+      def fragment(string, options = ParseOptions::DEFAULT_XML, &block)
+        XML::DocumentFragment.parse(string, options, &block)
       end
     end
   end

data/lib/nokogiri/xslt/stylesheet.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XSLT
     ###

data/lib/nokogiri/xslt.rb

@@ -1,4 +1,6 @@
+# coding: utf-8
 # frozen_string_literal: true
+
 module Nokogiri
   class << self
     ###
@@ -8,7 +10,7 @@ module Nokogiri
     #
     #   xslt = Nokogiri::XSLT(File.read(ARGV[0]))
     #
-    def XSLT stylesheet, modules = {}
+    def XSLT(stylesheet, modules = {})
       XSLT.parse(stylesheet, modules)
     end
   end
@@ -33,22 +35,28 @@ module Nokogiri
         end
       end
 
-      ###
-      # Quote parameters in +params+ for stylesheet safety
+      # :call-seq:
+      #   quote_params(params) → Array
+      #
+      # Quote parameters in +params+ for stylesheet safety.
+      # See Nokogiri::XSLT::Stylesheet.transform for example usage.
+      #
+      # [Parameters]
+      # - +params+ (Hash, Array) XSLT parameters (key->value, or tuples of [key, value])
+      #
+      # [Returns] Array of string parameters, with quotes correctly escaped for use with XSLT::Stylesheet.transform
+      #
       def quote_params(params)
-        parray = (params.instance_of?(Hash) ? params.to_a.flatten : params).dup
-        parray.each_with_index do |v, i|
-          parray[i] = if i % 2 > 0
-            if v =~ /'/
-              "concat('#{v.gsub(/'/, %q{', "'", '})}')"
-            else
-              "'#{v}'"
-            end
+        params.flatten.each_slice(2).with_object([]) do |kv, quoted_params|
+          key, value = kv.map(&:to_s)
+          value = if /'/.match?(value)
+            "concat('#{value.gsub(/'/, %q{', "'", '})}')"
           else
-            v.to_s
+            "'#{value}'"
           end
+          quoted_params << key
+          quoted_params << value
         end
-        parray.flatten
       end
     end
   end

data/lib/nokogiri.rb

@@ -1,8 +1,5 @@
-# -*- coding: utf-8 -*-
+# coding: utf-8
 # frozen_string_literal: true
-# Modify the PATH on windows so that the external DLLs will get loaded.
-
-require "rbconfig"
 
 if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby"
   require_relative "nokogiri/jruby/dependencies"
@@ -19,30 +16,32 @@ require_relative "nokogiri/extension"
 #
 # Here is an example:
 #
-#   require 'nokogiri'
-#   require 'open-uri'
+#     require 'nokogiri'
+#     require 'open-uri'
+#
+#     # Get a Nokogiri::HTML4::Document for the page we’re interested in...
 #
-#   # Get a Nokogiri::HTML4::Document for the page we’re interested in...
+#     doc = Nokogiri::HTML4(URI.open('http://www.google.com/search?q=tenderlove'))
 #
-#   doc = Nokogiri::HTML4(URI.open('http://www.google.com/search?q=tenderlove'))
+#     # Do funky things with it using Nokogiri::XML::Node methods...
 #
-#   # Do funky things with it using Nokogiri::XML::Node methods...
+#     ####
+#     # Search for nodes by css
+#     doc.css('h3.r a.l').each do |link|
+#       puts link.content
+#     end
 #
-#   ####
-#   # Search for nodes by css
-#   doc.css('h3.r a.l').each do |link|
-#     puts link.content
-#   end
+# See also:
 #
-# See Nokogiri::XML::Searchable#css for more information about CSS searching.
-# See Nokogiri::XML::Searchable#xpath for more information about XPath searching.
+# - Nokogiri::XML::Searchable#css for more information about CSS searching
+# - Nokogiri::XML::Searchable#xpath for more information about XPath searching
 module Nokogiri
   class << self
     ###
     # Parse an HTML or XML document.  +string+ contains the document.
     def parse(string, url = nil, encoding = nil, options = nil)
       if string.respond_to?(:read) ||
-          /^\s*<(?:!DOCTYPE\s+)?html[\s>]/i === string[0, 512]
+          /^\s*<(?:!DOCTYPE\s+)?html[\s>]/i.match?(string[0, 512])
         # Expect an HTML indicator to appear within the first 512
         # characters of a document. (<?xml ?> + <?xml-stylesheet ?>
         # shouldn't be that long)
@@ -85,18 +84,12 @@ module Nokogiri
       Nokogiri(*args, &block).slop!
     end
 
+    # :nodoc:
     def install_default_aliases
-      # Make sure to support some popular encoding aliases not known by
-      # all iconv implementations.
-      {
-        "Windows-31J" => "CP932",	# Windows-31J is the IANA registered name of CP932.
-      }.each do |alias_name, name|
-        EncodingHandler.alias(name, alias_name) if EncodingHandler[alias_name].nil?
-      end
+      warn("Nokogiri.install_default_aliases is deprecated and will be removed in a future version of Nokogiri. Please call Nokogiri::EncodingHandler.install_default_aliases instead.")
+      Nokogiri::EncodingHandler.install_default_aliases
     end
   end
-
-  Nokogiri.install_default_aliases
 end
 
 ###
@@ -105,7 +98,7 @@ end
 #
 # To specify the type of document, use {Nokogiri.XML}, {Nokogiri.HTML4}, or {Nokogiri.HTML5}.
 def Nokogiri(*args, &block)
-  if block_given?
+  if block
     Nokogiri::HTML4::Builder.new(&block).doc.root
   else
     Nokogiri.parse(*args)
@@ -113,6 +106,7 @@ def Nokogiri(*args, &block)
 end
 
 require_relative "nokogiri/version"
+require_relative "nokogiri/class_resolver"
 require_relative "nokogiri/syntax_error"
 require_relative "nokogiri/xml"
 require_relative "nokogiri/xslt"
@@ -121,5 +115,6 @@ require_relative "nokogiri/html"
 require_relative "nokogiri/decorators/slop"
 require_relative "nokogiri/css"
 require_relative "nokogiri/html4/builder"
+require_relative "nokogiri/encoding_handler"
 
 require_relative "nokogiri/html5" if Nokogiri.uses_gumbo?