nokogiri 1.12.5 → 1.13.0

data/lib/nokogiri/xml/attr.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
     class Attr < Node
-      alias :value :content
-      alias :to_s :content
-      alias :content= :value=
+      alias_method :value, :content
+      alias_method :to_s, :content
+      alias_method :content=, :value=
 
       private
+
       def inspect_attributes
         [:name, :namespace, :value]
       end

data/lib/nokogiri/xml/attribute_decl.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
     ###
@@ -12,7 +13,7 @@ module Nokogiri
       undef_method :line if method_defined?(:line)
 
       def inspect
-        "#<#{self.class.name}:#{sprintf("0x%x", object_id)} #{to_s.inspect}>"
+        "#<#{self.class.name}:#{format("0x%x", object_id)} #{to_s.inspect}>"
       end
     end
   end

data/lib/nokogiri/xml/builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
     ###
@@ -261,7 +262,9 @@ module Nokogiri
     #   </root>
     #
     class Builder
-      DEFAULT_DOCUMENT_OPTIONS = {namespace_inheritance: true}
+      include Nokogiri::ClassResolver
+
+      DEFAULT_DOCUMENT_OPTIONS = { namespace_inheritance: true }
 
       # The current Document object being built
       attr_accessor :doc
@@ -306,13 +309,7 @@ module Nokogiri
           @doc = root.document
           @parent = root
         else
-          klassname = "::" + (self.class.name.split("::")[0..-2] + ["Document"]).join("::")
-          klass = begin
-                    Object.const_get(klassname)
-                  rescue NameError
-                    Nokogiri::XML::Document
-                  end
-          @parent = @doc = klass.new
+          @parent = @doc = related_class("Document").new
         end
 
         @context = nil
@@ -324,7 +321,7 @@ module Nokogiri
           @doc.send(:"#{k}=", v)
         end
 
-        return unless block_given?
+        return unless block
 
         @arity = block.arity
         if @arity <= 0
@@ -340,19 +337,19 @@ module Nokogiri
       ###
       # Create a Text Node with content of +string+
       def text(string)
-        insert @doc.create_text_node(string)
+        insert(@doc.create_text_node(string))
       end
 
       ###
       # Create a CDATA Node with content of +string+
       def cdata(string)
-        insert doc.create_cdata(string)
+        insert(doc.create_cdata(string))
       end
 
       ###
       # Create a Comment Node with content of +string+
       def comment(string)
-        insert doc.create_comment(string)
+        insert(doc.create_comment(string))
       end
 
       ###
@@ -370,8 +367,8 @@ module Nokogiri
           return self if @ns
         end
 
-        @ns = { :pending => ns.to_s }
-        return self
+        @ns = { pending: ns.to_s }
+        self
       end
 
       ###
@@ -379,7 +376,7 @@ module Nokogiri
       def to_xml(*args)
         if Nokogiri.jruby?
           options = args.first.is_a?(Hash) ? args.shift : {}
-          if !options[:save_with]
+          unless options[:save_with]
             options[:save_with] = Node::SaveOptions::AS_BUILDER
           end
           args.insert(0, options)
@@ -394,18 +391,18 @@ module Nokogiri
       end
 
       def method_missing(method, *args, &block) # :nodoc:
-        if @context && @context.respond_to?(method)
+        if @context&.respond_to?(method)
           @context.send(method, *args, &block)
         else
-          node = @doc.create_element(method.to_s.sub(/[_!]$/, ""), *args) { |n|
+          node = @doc.create_element(method.to_s.sub(/[_!]$/, ""), *args) do |n|
             # Set up the namespace
-            if @ns.is_a? Nokogiri::XML::Namespace
+            if @ns.is_a?(Nokogiri::XML::Namespace)
               n.namespace = @ns
               @ns = nil
             end
-          }
+          end
 
-          if @ns.is_a? Hash
+          if @ns.is_a?(Hash)
             node.namespace = node.namespace_definitions.find { |x| x.prefix == @ns[:pending] }
             if node.namespace.nil?
               raise ArgumentError, "Namespace #{@ns[:pending]} has not been defined"
@@ -423,16 +420,19 @@ module Nokogiri
       # Insert +node+ as a child of the current Node
       def insert(node, &block)
         node = @parent.add_child(node)
-        if block_given?
-          old_parent = @parent
-          @parent = node
-          @arity ||= block.arity
-          if @arity <= 0
-            instance_eval(&block)
-          else
-            block.call(self)
+        if block
+          begin
+            old_parent = @parent
+            @parent = node
+            @arity ||= block.arity
+            if @arity <= 0
+              instance_eval(&block)
+            else
+              yield(self)
+            end
+          ensure
+            @parent = old_parent
           end
-          @parent = old_parent
         end
         NodeBuilder.new(node, self)
       end
@@ -455,10 +455,10 @@ module Nokogiri
           opts = args.last.is_a?(Hash) ? args.pop : {}
           case method.to_s
           when /^(.*)!$/
-            @node["id"] = $1
+            @node["id"] = Regexp.last_match(1)
             @node.content = args.first if args.first
           when /^(.*)=/
-            @node[$1] = args.first
+            @node[Regexp.last_match(1)] = args.first
           else
             @node["class"] =
               ((@node["class"] || "").split(/\s/) + [method.to_s]).join(" ")
@@ -470,7 +470,7 @@ module Nokogiri
             @node[k.to_s] = ((@node[k.to_s] || "").split(/\s/) + [v]).join(" ")
           end
 
-          if block_given?
+          if block
             old_parent = @doc_builder.parent
             @doc_builder.parent = @node
             value = @doc_builder.instance_eval(&block)

data/lib/nokogiri/xml/cdata.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
     class CDATA < Nokogiri::XML::Text
       ###
       # Get the name of this CDATA node
       def name
-        '#cdata-section'
+        "#cdata-section"
       end
     end
   end

data/lib/nokogiri/xml/character_data.rb

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

data/lib/nokogiri/xml/document.rb

@@ -1,18 +1,16 @@
 # coding: utf-8
 # frozen_string_literal: true
 
-require 'pathname'
+require "pathname"
 
 module Nokogiri
   module XML
-    ##
-    # Nokogiri::XML::Document is the main entry point for dealing with
-    # XML documents.  The Document is created by parsing an XML document.
-    # See Nokogiri::XML::Document.parse() for more information on parsing.
+    # Nokogiri::XML::Document is the main entry point for dealing with XML documents.  The Document
+    # is created by parsing an XML document.  See Nokogiri::XML::Document.parse for more information
+    # on parsing.
     #
     # For searching a Document, see Nokogiri::XML::Searchable#css and
     # Nokogiri::XML::Searchable#xpath
-    #
     class Document < Nokogiri::XML::Node
       # See http://www.w3.org/TR/REC-xml-names/#ns-decl for more details. Note that we're not
       # attempting to handle unicode characters partly because libxml2 doesn't handle unicode
@@ -47,76 +45,86 @@ module Nokogiri
       #
       # Nokogiri.XML() is a convenience method which will call this method.
       #
-      def self.parse string_or_io, url = nil, encoding = nil, options = ParseOptions::DEFAULT_XML
+      def self.parse(string_or_io, url = nil, encoding = nil, options = ParseOptions::DEFAULT_XML)
         options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
-
         yield options if block_given?
 
         url ||= string_or_io.respond_to?(:path) ? string_or_io.path : nil
 
         if empty_doc?(string_or_io)
           if options.strict?
-            raise Nokogiri::XML::SyntaxError.new("Empty document")
+            raise Nokogiri::XML::SyntaxError, "Empty document"
           else
             return encoding ? new.tap { |i| i.encoding = encoding } : new
           end
         end
 
         doc = if string_or_io.respond_to?(:read)
-                if string_or_io.is_a?(Pathname)
-                  # resolve the Pathname to the file and open it as an IO object, see #2110
-                  string_or_io = string_or_io.expand_path.open
-                  url ||= string_or_io.path
-                end
+          if string_or_io.is_a?(Pathname)
+            # resolve the Pathname to the file and open it as an IO object, see #2110
+            string_or_io = string_or_io.expand_path.open
+            url ||= string_or_io.path
+          end
 
-                read_io(string_or_io, url, encoding, options.to_i)
-              else
-                # read_memory pukes on empty docs
-                read_memory(string_or_io, url, encoding, options.to_i)
-              end
+          read_io(string_or_io, url, encoding, options.to_i)
+        else
+          # read_memory pukes on empty docs
+          read_memory(string_or_io, url, encoding, options.to_i)
+        end
 
         # do xinclude processing
         doc.do_xinclude(options) if options.xinclude?
 
-        return doc
+        doc
       end
 
       ##
-      # @!method wrap(java_document)
-      # @!scope class
+      # :singleton-method: wrap
+      # :call-seq: wrap(java_document) → Nokogiri::XML::Document
+      #
+      # ⚠ This method is only available when running JRuby.
       #
-      # Create a {Document} using an existing Java DOM document object.
+      # Create a Document using an existing Java DOM document object.
       #
-      # The returned {Document} shares the same underlying data structure as the Java object, so
+      # The returned Document shares the same underlying data structure as the Java object, so
       # changes in one are reflected in the other.
       #
-      # @param java_document [Java::OrgW3cDom::Document]
-      # @return [Nokogiri::XML::Document]
-      # @note This method is only available when running JRuby.
-      # @note The class +Java::OrgW3cDom::Document+ is also accessible as +org.w3c.dom.Document+.
-      # @see #to_java
+      # [Parameters]
+      # - `java_document` (Java::OrgW3cDom::Document)
+      #   (The class `Java::OrgW3cDom::Document` is also accessible as `org.w3c.dom.Document`.)
+      #
+      # [Returns] Nokogiri::XML::Document
+      #
+      # See also \#to_java
 
-      ##
-      # @!method to_java()
+      # :method: to_java
+      # :call-seq: to_java() → Java::OrgW3cDom::Document
       #
-      # Returns the underlying Java DOM document object for the {Document}.
+      # ⚠ This method is only available when running JRuby.
       #
-      # The returned Java object shares the same underlying data structure as the {Document}, so
+      # Returns the underlying Java DOM document object for this document.
+      #
+      # The returned Java object shares the same underlying data structure as this document, so
       # changes in one are reflected in the other.
       #
-      # @return [Java::OrgW3cDom::Document]
-      # @note This method is only available when running JRuby.
-      # @note The class +Java::OrgW3cDom::Document+ is also accessible as +org.w3c.dom.Document+.
-      # @see .wrap
-
+      # [Returns]
+      #   Java::OrgW3cDom::Document
+      #   (The class `Java::OrgW3cDom::Document` is also accessible as `org.w3c.dom.Document`.)
+      #
+      # See also Document.wrap
 
-      # A list of Nokogiri::XML::SyntaxError found when parsing a document
+      # The errors found while parsing a document.
+      #
+      # [Returns] Array<Nokogiri::XML::SyntaxError>
       attr_accessor :errors
 
-      # When true, reparented elements without a namespace will inherit their new parent's
-      # namespace (if one exists). Defaults to +false+.
+      # When `true`, reparented elements without a namespace will inherit their new parent's
+      # namespace (if one exists). Defaults to `false`.
+      #
+      # [Returns] Boolean
+      #
+      # *Example:* Default behavior of namespace inheritance
       #
-      # @example Default behavior of namespace inheritance
       #   xml = <<~EOF
       #           <root xmlns:foo="http://nokogiri.org/default_ns/test/foo">
       #             <foo:parent>
@@ -134,7 +142,8 @@ module Nokogiri
       #   #      </foo:parent>
       #   #    </root>
       #
-      # @example Setting namespace inheritance to +true+
+      # *Example:* Setting namespace inheritance to `true`
+      #
       #   xml = <<~EOF
       #           <root xmlns:foo="http://nokogiri.org/default_ns/test/foo">
       #             <foo:parent>
@@ -153,49 +162,61 @@ module Nokogiri
       #   #      </foo:parent>
       #   #    </root>
       #
-      # @return [Boolean]
-      #
-      # @since v1.12.4
+      # Since v1.12.4
       attr_accessor :namespace_inheritance
 
-      def initialize *args # :nodoc:
+      def initialize(*args) # :nodoc:
         @errors     = []
         @decorators = nil
         @namespace_inheritance = false
       end
 
-      ##
-      # Create a new +Element+ with +name+ sharing GC lifecycle with the document, optionally
-      # setting contents or attributes.
+      # :call-seq:
+      #   create_element(name, *contents_or_attrs, &block) → Nokogiri::XML::Element
+      #
+      # Create a new Element with `name` belonging to this document, optionally setting contents or
+      # attributes.
+      #
+      # This method is _not_ the most user-friendly option if your intention is to add a node to the
+      # document tree. Prefer one of the Nokogiri::XML::Node methods like Node#add_child,
+      # Node#add_next_sibling, Node#replace, etc. which will both create an element (or subtree) and
+      # place it in the document tree.
       #
       # Arguments may be passed to initialize the element:
-      # - a +Hash+ argument will be used to set attributes
-      # - a non-Hash object that responds to +#to_s+ will be used to set the new node's contents
+      #
+      # - a Hash argument will be used to set attributes
+      # - a non-Hash object that responds to \#to_s will be used to set the new node's contents
       #
       # A block may be passed to mutate the node.
       #
-      # @param name [String]
-      # @param contents_or_attrs [#to_s,Hash]
-      # @yieldparam node [Nokogiri::XML::Element]
-      # @return [Nokogiri::XML::Element]
+      # [Parameters]
+      # - `name` (String)
+      # - `contents_or_attrs` (\#to_s, Hash)
+      # [Yields] `node` (Nokogiri::XML::Element)
+      # [Returns] Nokogiri::XML::Element
+      #
+      # *Example:* An empty element without attributes
       #
-      # @example An empty element without attributes
       #   doc.create_element("div")
       #   # => <div></div>
       #
-      # @example An element with contents
+      # *Example:* An element with contents
+      #
       #   doc.create_element("div", "contents")
       #   # => <div>contents</div>
       #
-      # @example An element with attributes
+      # *Example:* An element with attributes
+      #
       #   doc.create_element("div", {"class" => "container"})
       #   # => <div class='container'></div>
       #
-      # @example An element with contents and attributes
+      # *Example:* An element with contents and attributes
+      #
       #   doc.create_element("div", "contents", {"class" => "container"})
       #   # => <div class='container'>contents</div>
       #
-      # @example Passing a block to mutate the element
+      # *Example:* Passing a block to mutate the element
+      #
       #   doc.create_element("div") { |node| node["class"] = "blue" if before_noon? }
       #
       def create_element(name, *contents_or_attrs, &block)
@@ -216,30 +237,30 @@ module Nokogiri
             elm.content = arg
           end
         end
-        if ns = elm.namespace_definitions.find { |n| n.prefix.nil? || (n.prefix == '') }
+        if (ns = elm.namespace_definitions.find { |n| n.prefix.nil? || (n.prefix == "") })
           elm.namespace = ns
         end
         elm
       end
 
       # Create a Text Node with +string+
-      def create_text_node string, &block
-        Nokogiri::XML::Text.new string.to_s, self, &block
+      def create_text_node(string, &block)
+        Nokogiri::XML::Text.new(string.to_s, self, &block)
       end
 
       # Create a CDATA Node containing +string+
-      def create_cdata string, &block
-        Nokogiri::XML::CDATA.new self, string.to_s, &block
+      def create_cdata(string, &block)
+        Nokogiri::XML::CDATA.new(self, string.to_s, &block)
       end
 
       # Create a Comment Node containing +string+
-      def create_comment string, &block
-        Nokogiri::XML::Comment.new self, string.to_s, &block
+      def create_comment(string, &block)
+        Nokogiri::XML::Comment.new(self, string.to_s, &block)
       end
 
       # The name of this document.  Always returns "document"
       def name
-        'document'
+        "document"
       end
 
       # A reference to +self+
@@ -247,46 +268,51 @@ module Nokogiri
         self
       end
 
-      ##
-      # Recursively get all namespaces from this node and its subtree and
-      # return them as a hash.
+      # :call-seq:
+      #   collect_namespaces() → Hash<String(Namespace#prefix) ⇒ String(Namespace#href)>
       #
-      # For example, given this document:
+      # Recursively get all namespaces from this node and its subtree and return them as a
+      # hash.
       #
-      #   <root xmlns:foo="bar">
+      # ⚠ This method will not handle duplicate namespace prefixes, since the return value is a hash.
+      #
+      # Note that this method does an xpath lookup for nodes with namespaces, and as a result the
+      # order (and which duplicate prefix "wins") may be dependent on the implementation of the
+      # underlying XML library.
+      #
+      # *Example:* Basic usage
+      #
+      # Given this document:
+      #
+      #   <root xmlns="default" xmlns:foo="bar">
       #     <bar xmlns:hello="world" />
       #   </root>
       #
       # This method will return:
       #
-      #   { 'xmlns:foo' => 'bar', 'xmlns:hello' => 'world' }
+      #   {"xmlns:foo"=>"bar", "xmlns"=>"default", "xmlns:hello"=>"world"}
       #
-      # WARNING: this method will clobber duplicate names in the keys.
-      # For example, given this document:
+      # *Example:* Duplicate prefixes
+      #
+      # Given this document:
       #
       #   <root xmlns:foo="bar">
       #     <bar xmlns:foo="baz" />
       #   </root>
       #
-      # The hash returned will look like this: { 'xmlns:foo' => 'bar' }
-      #
-      # Non-prefixed default namespaces (as in "xmlns=") are not included
-      # in the hash.
+      # The hash returned will be something like:
       #
-      # Note that this method does an xpath lookup for nodes with
-      # namespaces, and as a result the order may be dependent on the
-      # implementation of the underlying XML library.
+      #   {"xmlns:foo" => "baz"}
       #
       def collect_namespaces
-        xpath("//namespace::*").inject({}) do |hash, ns|
-          hash[["xmlns",ns.prefix].compact.join(":")] = ns.href if ns.prefix != "xml"
-          hash
+        xpath("//namespace::*").each_with_object({}) do |ns, hash|
+          hash[["xmlns", ns.prefix].compact.join(":")] = ns.href if ns.prefix != "xml"
         end
       end
 
       # Get the list of decorators given +key+
-      def decorators key
-        @decorators ||= Hash.new
+      def decorators(key)
+        @decorators ||= {}
         @decorators[key] ||= []
       end
 
@@ -295,7 +321,7 @@ module Nokogiri
       # the document or +nil+ when there is no DTD.
       def validate
         return nil unless internal_subset
-        internal_subset.validate self
+        internal_subset.validate(self)
       end
 
       ##
@@ -315,7 +341,7 @@ module Nokogiri
       #   ... which does absolutely nothing.
       #
       def slop!
-        unless decorators(XML::Node).include? Nokogiri::Decorators::Slop
+        unless decorators(XML::Node).include?(Nokogiri::Decorators::Slop)
           decorators(XML::Node) << Nokogiri::Decorators::Slop
           decorate!
         end
@@ -325,16 +351,16 @@ module Nokogiri
 
       ##
       # Apply any decorators to +node+
-      def decorate node
+      def decorate(node)
         return unless @decorators
-        @decorators.each { |klass,list|
+        @decorators.each do |klass, list|
           next unless node.is_a?(klass)
           list.each { |moodule| node.extend(moodule) }
-        }
+        end
       end
 
-      alias :to_xml :serialize
-      alias :clone :dup
+      alias_method :to_xml, :serialize
+      alias_method :clone, :dup
 
       # Get the hash of namespaces on the root Nokogiri::XML::Node
       def namespaces
@@ -344,16 +370,16 @@ module Nokogiri
       ##
       # Create a Nokogiri::XML::DocumentFragment from +tags+
       # Returns an empty fragment if +tags+ is nil.
-      def fragment tags = nil
-        DocumentFragment.new(self, tags, self.root)
+      def fragment(tags = nil)
+        DocumentFragment.new(self, tags, root)
       end
 
       undef_method :swap, :parent, :namespace, :default_namespace=
       undef_method :add_namespace_definition, :attributes
       undef_method :namespace_definitions, :line, :add_namespace
 
-      def add_child node_or_tags
-        raise "A document may not have multiple root nodes." if (root && root.name != 'nokogiri_text_wrapper') && !(node_or_tags.comment? || node_or_tags.processing_instruction?)
+      def add_child(node_or_tags)
+        raise "A document may not have multiple root nodes." if (root && root.name != "nokogiri_text_wrapper") && !(node_or_tags.comment? || node_or_tags.processing_instruction?)
         node_or_tags = coerce(node_or_tags)
         if node_or_tags.is_a?(XML::NodeSet)
           raise "A document may not have multiple root nodes." if node_or_tags.size > 1
@@ -362,17 +388,27 @@ module Nokogiri
           super
         end
       end
-      alias :<< :add_child
+      alias_method :<<, :add_child
+
+      # :call-seq:
+      #   xpath_doctype() → Nokogiri::CSS::XPathVisitor::DoctypeConfig
+      #
+      # [Returns] The document type which determines CSS-to-XPath translation.
+      #
+      # See XPathVisitor for more information.
+      def xpath_doctype
+        Nokogiri::CSS::XPathVisitor::DoctypeConfig::XML
+      end
 
       private
 
-      def self.empty_doc? string_or_io
+      def self.empty_doc?(string_or_io)
         string_or_io.nil? ||
           (string_or_io.respond_to?(:empty?) && string_or_io.empty?) ||
           (string_or_io.respond_to?(:eof?) && string_or_io.eof?)
       end
 
-      IMPLIED_XPATH_CONTEXTS = [ '//'.freeze ].freeze # :nodoc:
+      IMPLIED_XPATH_CONTEXTS = ["//"].freeze # :nodoc:
 
       def inspect_attributes
         [:name, :children]