nokogiri 1.15.3 → 1.18.7

data/lib/nokogiri/html5.rb

@@ -1,66 +1,71 @@
 # coding: utf-8
 # frozen_string_literal: true
 
+# This file includes code from the Nokogumbo project, whose license follows.
 #
-#  Copyright 2013-2021 Sam Ruby, Stephen Checkoway
+#   Copyright 2013-2021 Sam Ruby, Stephen Checkoway
 #
-#  Licensed under the Apache License, Version 2.0 (the "License");
-#  you may not use this file except in compliance with the License.
-#  You may obtain a copy of the License at
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
 #
-#      http://www.apache.org/licenses/LICENSE-2.0
+#       http://www.apache.org/licenses/LICENSE-2.0
 #
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS,
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#  See the License for the specific language governing permissions and
-#  limitations under the License.
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
 #
 
 require_relative "html5/document"
 require_relative "html5/document_fragment"
 require_relative "html5/node"
+require_relative "html5/builder"
 
 module Nokogiri
-  # Since v1.12.0
-  #
-  # ⚠ HTML5 functionality is not available when running JRuby.
-  #
-  # Parse an HTML5 document. Convenience method for {Nokogiri::HTML5::Document.parse}
-  def self.HTML5(input, url = nil, encoding = nil, **options, &block)
-    Nokogiri::HTML5::Document.parse(input, url, encoding, **options, &block)
+  # Convenience method for Nokogiri::HTML5::Document.parse
+  def self.HTML5(...)
+    Nokogiri::HTML5::Document.parse(...)
   end
 
   # == Usage
   #
-  # ⚠ HTML5 functionality is not available when running JRuby.
-  #
   # Parse an HTML5 document:
   #
-  #   doc = Nokogiri.HTML5(string)
+  #   doc = Nokogiri.HTML5(input)
   #
   # Parse an HTML5 fragment:
   #
-  #   fragment = Nokogiri::HTML5.fragment(string)
+  #   fragment = Nokogiri::HTML5.fragment(input)
+  #
+  # ⚠ HTML5 functionality is not available when running JRuby.
   #
   # == Parsing options
   #
-  # The document and fragment parsing methods support options that are different from Nokogiri's.
+  # The document and fragment parsing methods support options that are different from
+  # Nokogiri::HTML4::Document or Nokogiri::XML::Document.
+  #
+  # - <tt>Nokogiri.HTML5(input, url:, encoding:, **parse_options)</tt>
+  # - <tt>Nokogiri::HTML5.parse(input, url:, encoding:, **parse_options)</tt>
+  # - <tt>Nokogiri::HTML5::Document.parse(input, url:, encoding:, **parse_options)</tt>
+  # - <tt>Nokogiri::HTML5.fragment(input, encoding:, **parse_options)</tt>
+  # - <tt>Nokogiri::HTML5::DocumentFragment.parse(input, encoding:, **parse_options)</tt>
   #
-  # - <tt>Nokogiri.HTML5(html, url = nil, encoding = nil, options = {})</tt>
-  # - <tt>Nokogiri::HTML5.parse(html, url = nil, encoding = nil, options = {})</tt>
-  # - <tt>Nokogiri::HTML5::Document.parse(html, url = nil, encoding = nil, options = {})</tt>
-  # - <tt>Nokogiri::HTML5.fragment(html, encoding = nil, options = {})</tt>
-  # - <tt>Nokogiri::HTML5::DocumentFragment.parse(html, encoding = nil, options = {})</tt>
+  # The four currently supported parse options are
   #
-  # The three currently supported options are +:max_errors+, +:max_tree_depth+ and
-  # +:max_attributes+, described below.
+  # - +max_errors:+ (Integer, default 0) Maximum number of parse errors to report in HTML5::Document#errors.
+  # - +max_tree_depth:+ (Integer, default +Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH+) Maximum tree depth to parse.
+  # - +max_attributes:+ (Integer, default +Nokogiri::Gumbo::DEFAULT_MAX_ATTRIBUTES+) Maximum number of attributes to parse per element.
+  # - +parse_noscript_content_as_text:+ (Boolean, default false) When enabled, parse +noscript+ tag content as text, mimicking the behavior of web browsers.
   #
-  # === Error reporting
+  # These options are explained in the following sections.
+  #
+  # === Error reporting: +max_errors:+
   #
   # Nokogiri contains an experimental HTML5 parse error reporting facility. By default, no parse
   # errors are reported but this can be configured by passing the +:max_errors+ option to
-  # {HTML5.parse} or {HTML5.fragment}.
+  # HTML5.parse or HTML5.fragment.
   #
   # For example, this script:
   #
@@ -86,20 +91,21 @@ module Nokogiri
   #
   # Using <tt>max_errors: -1</tt> results in an unlimited number of errors being returned.
   #
-  # The errors returned by {HTML5::Document#errors} are instances of {Nokogiri::XML::SyntaxError}.
+  # The errors returned by HTML5::Document#errors are instances of Nokogiri::XML::SyntaxError.
   #
-  # The {https://html.spec.whatwg.org/multipage/parsing.html#parse-errors HTML standard} defines a
+  # The {HTML standard}[https://html.spec.whatwg.org/multipage/parsing.html#parse-errors] defines a
   # number of standard parse error codes. These error codes only cover the "tokenization" stage of
   # parsing HTML. The parse errors in the "tree construction" stage do not have standardized error
   # codes (yet).
   #
-  # As a convenience to Nokogiri users, the defined error codes are available via
-  # {Nokogiri::XML::SyntaxError#str1} method.
+  # As a convenience to Nokogiri users, the defined error codes are available
+  # via Nokogiri::XML::SyntaxError#str1 method.
   #
   #   doc = Nokogiri::HTML5.parse('<span/>Hi there!</span foo=bar />', max_errors: 10)
   #   doc.errors.each do |err|
   #     puts("#{err.line}:#{err.column}: #{err.str1}")
   #   end
+  #   doc = Nokogiri::HTML5.parse('<span/>Hi there!</span foo=bar />',
   #   # => 1:1: generic-parser
   #   #    1:1: non-void-html-element-start-tag-with-trailing-solidus
   #   #    1:17: end-tag-with-trailing-solidus
@@ -112,40 +118,75 @@ module Nokogiri
   # are not part of Nokogiri's public API. That is, these are subject to change without Nokogiri's
   # major version number changing. These may be stabilized in the future.
   #
-  # === Maximum tree depth
+  # === Maximum tree depth: +max_tree_depth:+
   #
   # The maximum depth of the DOM tree parsed by the various parsing methods is configurable by the
   # +:max_tree_depth+ option. If the depth of the tree would exceed this limit, then an
-  # {::ArgumentError} is thrown.
+  # +ArgumentError+ is thrown.
   #
-  # This limit (which defaults to <tt>Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH = 400</tt>) can be
-  # removed by giving the option <tt>max_tree_depth: -1</tt>.
+  # This limit (which defaults to +Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH+) can be removed by
+  # giving the option <tt>max_tree_depth: -1</tt>.
   #
   #   html = '<!DOCTYPE html>' + '<div>' * 1000
   #   doc = Nokogiri.HTML5(html)
   #   # raises ArgumentError: Document tree depth limit exceeded
   #   doc = Nokogiri.HTML5(html, max_tree_depth: -1)
   #
-  # === Attribute limit per element
+  # === Attribute limit per element: +max_attributes:+
   #
   # The maximum number of attributes per DOM element is configurable by the +:max_attributes+
-  # option. If a given element would exceed this limit, then an {::ArgumentError} is thrown.
+  # option. If a given element would exceed this limit, then an +ArgumentError+ is thrown.
   #
-  # This limit (which defaults to <tt>Nokogiri::Gumbo::DEFAULT_MAX_ATTRIBUTES = 400</tt>) can be
-  # removed by giving the option <tt>max_attributes: -1</tt>.
+  # This limit (which defaults to +Nokogiri::Gumbo::DEFAULT_MAX_ATTRIBUTES+) can be removed by
+  # giving the option <tt>max_attributes: -1</tt>.
   #
-  #   html = '<!DOCTYPE html><div ' + (1..1000).map { |x| "attr-#{x}" }.join(' ') + '>'
+  #   html = '<!DOCTYPE html><div ' + (1..1000).map { |x| "attr-#{x}" }.join(' # ') + '>'
   #   # "<!DOCTYPE html><div attr-1 attr-2 attr-3 ... attr-1000>"
   #   doc = Nokogiri.HTML5(html)
   #   # raises ArgumentError: Attributes per element limit exceeded
+  #
   #   doc = Nokogiri.HTML5(html, max_attributes: -1)
+  #   # parses successfully
+  #
+  # === Parse +noscript+ elements' content as text: +parse_noscript_content_as_text:+
+  #
+  # By default, the content of +noscript+ elements is parsed as HTML elements. Browsers that
+  # support scripting parse the content of +noscript+ elements as raw text.
+  #
+  # The +:parse_noscript_content_as_text+ option causes Nokogiri to parse the content of +noscript+
+  # elements as a single text node.
+  #
+  #   html = "<!DOCTYPE html><noscript><meta charset='UTF-8'><link rel=stylesheet href=!></noscript>"
+  #   doc = Nokogiri::HTML5.parse(html, parse_noscript_content_as_text: true)
+  #   pp doc.at_xpath("/html/head/noscript")
+  #   # => #(Element:0x878c {
+  #   #        name = "noscript",
+  #   #        children = [ #(Text "<meta charset='UTF-8'><link rel=stylesheet href=!>")]
+  #   #      })
+  #
+  # In contrast, <tt>parse_noscript_content_as_text: false</tt> (the default) causes the +noscript+
+  # element in the previous example to have two children, a +meta+ element and a +link+ element.
+  #
+  #   doc = Nokogiri::HTML5.parse(html)
+  #   puts doc.at_xpath("/html/head/noscript")
+  #   # => #(Element:0x96b4 {
+  #   #      name = "noscript",
+  #   #      children = [
+  #   #        #(Element:0x97e0 { name = "meta", attribute_nodes = [ #(Attr:0x990c { name = "charset", value = "UTF-8" })] }),
+  #   #        #(Element:0x9b00 {
+  #   #          name = "link",
+  #   #          attribute_nodes = [
+  #   #            #(Attr:0x9c2c { name = "rel", value = "stylesheet" }),
+  #   #            #(Attr:0x9dd0 { name = "href", value = "!" })]
+  #   #          })]
+  #   #      })
   #
   # == HTML Serialization
   #
-  # After parsing HTML, it may be serialized using any of the {Nokogiri::XML::Node} serialization
-  # methods. In particular, {XML::Node#serialize}, {XML::Node#to_html}, and {XML::Node#to_s} will
+  # After parsing HTML, it may be serialized using any of the Nokogiri::XML::Node serialization
+  # methods. In particular, XML::Node#serialize, XML::Node#to_html, and XML::Node#to_s will
   # serialize a given node and its children. (This is the equivalent of JavaScript's
-  # +Element.outerHTML+.) Similarly, {XML::Node#inner_html} will serialize the children of a given
+  # +Element.outerHTML+.) Similarly, XML::Node#inner_html will serialize the children of a given
   # node. (This is the equivalent of JavaScript's +Element.innerHTML+.)
   #
   #   doc = Nokogiri::HTML5("<!DOCTYPE html><span>Hello world!</span>")
@@ -153,12 +194,12 @@ module Nokogiri
   #   # => <!DOCTYPE html><html><head></head><body><span>Hello world!</span></body></html>
   #
   # Due to quirks in how HTML is parsed and serialized, it's possible for a DOM tree to be
-  # serialized and then re-parsed, resulting in a different DOM.  Mostly, this happens with DOMs
+  # serialized and then re-parsed, resulting in a different DOM. Mostly, this happens with DOMs
   # produced from invalid HTML. Unfortunately, even valid HTML may not survive serialization and
   # re-parsing.
   #
-  # In particular, a newline at the start of +pre+, +listing+, and +textarea+ elements is ignored by
-  # the parser.
+  # In particular, a newline at the start of +pre+, +listing+, and +textarea+
+  # elements is ignored by the parser.
   #
   #   doc = Nokogiri::HTML5(<<-EOF)
   #   <!DOCTYPE html>
@@ -187,73 +228,57 @@ module Nokogiri
   #
   # == Encodings
   #
-  # Nokogiri always parses HTML5 using {https://en.wikipedia.org/wiki/UTF-8 UTF-8}; however, the
+  # Nokogiri always parses HTML5 using {UTF-8}[https://en.wikipedia.org/wiki/UTF-8]; however, the
   # encoding of the input can be explicitly selected via the optional +encoding+ parameter. This is
   # most useful when the input comes not from a string but from an IO object.
   #
   # When serializing a document or node, the encoding of the output string can be specified via the
   # +:encoding+ options. Characters that cannot be encoded in the selected encoding will be encoded
-  # as {https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references HTML numeric
-  # entities}.
+  # as {HTML numeric
+  # entities}[https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references].
   #
   #   frag = Nokogiri::HTML5.fragment('<span>아는 길도 물어가라</span>')
   #   html = frag.serialize(encoding: 'US-ASCII')
   #   puts html
   #   # => <span>&#xc544;&#xb294; &#xae38;&#xb3c4; &#xbb3c;&#xc5b4;&#xac00;&#xb77c;</span>
+  #
   #   frag = Nokogiri::HTML5.fragment(html)
   #   puts frag.serialize
   #   # => <span>아는 길도 물어가라</span>
   #
-  # (There's a {https://bugs.ruby-lang.org/issues/15033 bug} in all current versions of Ruby that
+  # (There's a {bug}[https://bugs.ruby-lang.org/issues/15033] in all current versions of Ruby that
   # can cause the entity encoding to fail. Of the mandated supported encodings for HTML, the only
   # encoding I'm aware of that has this bug is <tt>'ISO-2022-JP'</tt>. We recommend avoiding this
   # encoding.)
   #
   # == Notes
   #
-  # * The {Nokogiri::HTML5.fragment} function takes a string and parses it
-  #   as a HTML5 document.  The +<html>+, +<head>+, and +<body>+ elements are
-  #   removed from this document, and any children of these elements that remain
-  #   are returned as a {Nokogiri::HTML5::DocumentFragment}.
+  # * The Nokogiri::HTML5.fragment function takes a String or IO and parses it as a HTML5 document
+  #   in a +body+ context. As a result, the +html+, +head+, and +body+ elements are removed from
+  #   this document, and any children of these elements that remain are returned as a
+  #   Nokogiri::HTML5::DocumentFragment; but you can pass in a different context (e.g., "html" to
+  #   get +head+ and +body+ tags in the result).
   #
-  # * The {Nokogiri::HTML5.parse} function takes a string and passes it to the
-  #   <code>gumbo_parse_with_options</code> method, using the default options.
-  #   The resulting Gumbo parse tree is then walked.
+  # * The Nokogiri::HTML5.parse function takes a String or IO and passes it to the
+  #   <code>gumbo_parse_with_options</code> method, using the default options.  The resulting Gumbo
+  #   parse tree is then walked.
   #
   # * Instead of uppercase element names, lowercase element names are produced.
   #
-  # * Instead of returning +unknown+ as the element name for unknown tags, the
-  #   original tag name is returned verbatim.
+  # * Instead of returning +unknown+ as the element name for unknown tags, the original tag name is
+  #   returned verbatim.
   #
   # Since v1.12.0
   module HTML5
     class << self
-      # Parse an HTML 5 document. Convenience method for {Nokogiri::HTML5::Document.parse}
-      def parse(string, url = nil, encoding = nil, **options, &block)
-        Document.parse(string, url, encoding, **options, &block)
-      end
-
-      # Parse a fragment from +string+. Convenience method for
-      # {Nokogiri::HTML5::DocumentFragment.parse}.
-      def fragment(string, encoding = nil, **options)
-        DocumentFragment.parse(string, encoding, options)
+      # Convenience method for Nokogiri::HTML5::Document.parse
+      def parse(...)
+        Document.parse(...)
       end
 
-      # Fetch and parse a HTML document from the web, following redirects,
-      # handling https, and determining the character encoding using HTML5
-      # rules.  +uri+ may be a +String+ or a +URI+.  +options+ contains
-      # http headers and special options.  Everything which is not a
-      # special option is considered a header.  Special options include:
-      #  * :follow_limit => number of redirects which are followed
-      #  * :basic_auth => [username, password]
-      def get(uri, options = {})
-        # TODO: deprecate
-        warn(
-          "Nokogiri::HTML5.get is deprecated and will be removed in a future version of Nokogiri.",
-          uplevel: 1,
-          category: :deprecated,
-        )
-        get_impl(uri, options)
+      # Convenience method for Nokogiri::HTML5::DocumentFragment.parse
+      def fragment(...)
+        DocumentFragment.parse(...)
       end
 
       # :nodoc:
@@ -283,61 +308,12 @@ module Nokogiri
 
       private
 
-      def get_impl(uri, options = {})
-        headers = options.clone
-        headers = { follow_limit: headers } if Numeric === headers # deprecated
-        limit = headers[:follow_limit] ? headers.delete(:follow_limit).to_i : 10
-
-        require "net/http"
-        uri = URI(uri) unless URI === uri
-
-        http = Net::HTTP.new(uri.host, uri.port)
-
-        # TLS / SSL support
-        http.use_ssl = true if uri.scheme == "https"
-
-        # Pass through Net::HTTP override values, which currently include:
-        #   :ca_file, :ca_path, :cert, :cert_store, :ciphers,
-        #   :close_on_empty_response, :continue_timeout, :key, :open_timeout,
-        #   :read_timeout, :ssl_timeout, :ssl_version, :use_ssl,
-        #   :verify_callback, :verify_depth, :verify_mode
-        options.each do |key, _value|
-          http.send("#{key}=", headers.delete(key)) if http.respond_to?("#{key}=")
-        end
-
-        request = Net::HTTP::Get.new(uri.request_uri)
-
-        # basic authentication
-        auth = headers.delete(:basic_auth)
-        auth ||= [uri.user, uri.password] if uri.user && uri.password
-        request.basic_auth(auth.first, auth.last) if auth
-
-        # remaining options are treated as headers
-        headers.each { |key, value| request[key.to_s] = value.to_s }
-
-        response = http.request(request)
-
-        case response
-        when Net::HTTPSuccess
-          doc = parse(reencode(response.body, response["content-type"]), options)
-          doc.instance_variable_set(:@response, response)
-          doc.class.send(:attr_reader, :response)
-          doc
-        when Net::HTTPRedirection
-          response.value if limit <= 1
-          location = URI.join(uri, response["location"])
-          get_impl(location, options.merge(follow_limit: limit - 1))
-        else
-          response.value
-        end
-      end
-
       # Charset sniffing is a complex and controversial topic that understandably isn't done _by
-      # default_ by the Ruby Net::HTTP library.  This being said, it is a very real problem for
+      # default_ by the Ruby Net::HTTP library. This being said, it is a very real problem for
       # consumers of HTML as the default for HTML is iso-8859-1, most "good" producers use utf-8, and
       # the Gumbo parser *only* supports utf-8.
       #
-      # Accordingly, Nokogiri::HTML4::Document.parse provides limited encoding detection.  Following
+      # Accordingly, Nokogiri::HTML4::Document.parse provides limited encoding detection. Following
       # this lead, Nokogiri::HTML5 attempts to do likewise, while attempting to more closely follow
       # the HTML5 standard.
       #

data/lib/nokogiri/version/constant.rb

@@ -2,5 +2,5 @@
 
 module Nokogiri
   # The version of Nokogiri you are using
-  VERSION = "1.15.3"
+  VERSION = "1.18.7"
 end

data/lib/nokogiri/version/info.rb

@@ -94,11 +94,14 @@ module Nokogiri
           nokogiri["version"] = Nokogiri::VERSION
 
           unless jruby?
-            #  enable gems like nokogumbo to build with the following in their extconf.rb:
+            #  enable gems to build against Nokogiri with the following in their extconf.rb:
             #
             #    append_cflags(Nokogiri::VERSION_INFO["nokogiri"]["cppflags"])
             #    append_ldflags(Nokogiri::VERSION_INFO["nokogiri"]["ldflags"])
             #
+            #  though, this won't work on all platform and versions of Ruby, and won't be supported
+            #  forever, see https://github.com/sparklemotion/nokogiri/discussions/2746 for context.
+            #
             cppflags = ["-I#{header_directory.shellescape}"]
             ldflags = []
 
@@ -108,7 +111,8 @@ module Nokogiri
             end
 
             if windows?
-              # on windows, nokogumbo needs to link against nokogiri.so to resolve symbols. see #2167
+              # on windows, third party libraries that wish to link against nokogiri
+              # should link against nokogiri.so to resolve symbols. see #2167
               lib_directory = File.expand_path(File.join(File.dirname(__FILE__), "../#{ruby_minor}"))
               unless File.exist?(lib_directory)
                 lib_directory = File.expand_path(File.join(File.dirname(__FILE__), ".."))
@@ -136,9 +140,6 @@ module Nokogiri
               libxml["source"] = "packaged"
               libxml["precompiled"] = libxml2_precompiled?
               libxml["patches"] = Nokogiri::LIBXML2_PATCHES
-
-              # this is for nokogumbo and shouldn't be forever
-              libxml["libxml2_path"] = header_directory
             else
               libxml["source"] = "system"
             end

data/lib/nokogiri/xml/attr.rb

@@ -18,8 +18,6 @@ module Nokogiri
       #  - +value+ → (String) The value of the attribute.
       #  - +namespace+ → (Namespace, nil) The Namespace of the attribute, or +nil+ if there is no namespace.
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
-      #
       #  *Example*
       #
       #    doc = Nokogiri::XML.parse(<<~XML)
@@ -52,6 +50,8 @@ module Nokogiri
       #    #        href = "http://nokogiri.org/ns/noko"
       #    #        })}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         { name: name, value: value, namespace: namespace }
       end

data/lib/nokogiri/xml/builder.rb

@@ -475,7 +475,14 @@ module Nokogiri
           if block
             old_parent = @doc_builder.parent
             @doc_builder.parent = @node
-            value = @doc_builder.instance_eval(&block)
+
+            arity = @doc_builder.arity || block.arity
+            value = if arity <= 0
+              @doc_builder.instance_eval(&block)
+            else
+              yield(@doc_builder)
+            end
+
             @doc_builder.parent = old_parent
             return value
           end

data/lib/nokogiri/xml/document.rb

@@ -5,12 +5,12 @@ 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 \XML content from a String or an IO object. See
+    # Nokogiri::XML::Document.parse for more information on parsing.
     #
-    # For searching a Document, see Nokogiri::XML::Searchable#css and
-    # Nokogiri::XML::Searchable#xpath
+    # Document inherits a great deal of functionality from its superclass Nokogiri::XML::Node, so
+    # please read that class's documentation as well.
     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
@@ -19,33 +19,45 @@ module Nokogiri
       NCNAME_CHAR       = NCNAME_START_CHAR + "\\-\\.0-9"
       NCNAME_RE         = /^xmlns(?::([#{NCNAME_START_CHAR}][#{NCNAME_CHAR}]*))?$/
 
+      OBJECT_DUP_METHOD = Object.instance_method(:dup)
+      OBJECT_CLONE_METHOD = Object.instance_method(:clone)
+      private_constant :OBJECT_DUP_METHOD, :OBJECT_CLONE_METHOD
+
       class << self
-        # Parse an XML file.
+        # call-seq:
+        #   parse(input) { |options| ... } => Nokogiri::XML::Document
+        #   parse(input, url:, encoding:, options:) => Nokogiri::XML::Document
         #
-        # +string_or_io+ may be a String, or any object that responds to
-        # _read_ and _close_ such as an IO, or StringIO.
+        # Parse \XML input from a String or IO object, and return a new XML::Document.
         #
-        # +url+ (optional) is the URI where this document is located.
+        # 🛡 By default, Nokogiri treats documents as untrusted, and so does not attempt to load DTDs
+        # or access the network. See Nokogiri::XML::ParseOptions for a complete list of options; and
+        # that module's DEFAULT_XML constant for what's set (and not set) by default.
         #
-        # +encoding+ (optional) is the encoding that should be used when processing
-        # the document.
+        # [Required Parameters]
+        # - +input+ (String | IO) The content to be parsed.
         #
-        # +options+ (optional) is a configuration object that sets options during
-        # parsing, such as Nokogiri::XML::ParseOptions::RECOVER. See the
-        # Nokogiri::XML::ParseOptions for more information.
+        # [Optional Keyword Arguments]
+        # - +url:+ (String) The base URI for this document.
         #
-        # +block+ (optional) is passed a configuration object on which
-        # parse options may be set.
+        # - +encoding:+ (String) The name of the encoding that should be used when processing the
+        #   document. When not provided, the encoding will be determined based on the document
+        #   content.
         #
-        # By default, Nokogiri treats documents as untrusted, and so
-        # does not attempt to load DTDs or access the network. See
-        # Nokogiri::XML::ParseOptions for a complete list of options;
-        # and that module's DEFAULT_XML constant for what's set (and not
-        # set) by default.
+        # - +options:+ (Nokogiri::XML::ParseOptions) Configuration object that determines some
+        #   behaviors during parsing. See ParseOptions for more information. The default value is
+        #   +ParseOptions::DEFAULT_XML+.
         #
-        # Nokogiri.XML() is a convenience method which will call this method.
+        # [Yields]
+        #   If a block is given, a Nokogiri::XML::ParseOptions object is yielded to the block which
+        #   can be configured before parsing. See Nokogiri::XML::ParseOptions for more information.
         #
-        def parse(string_or_io, url = nil, encoding = nil, options = ParseOptions::DEFAULT_XML)
+        # [Returns] Nokogiri::XML::Document
+        def parse(
+          string_or_io,
+          url_ = nil, encoding_ = nil, options_ = XML::ParseOptions::DEFAULT_XML,
+          url: url_, encoding: encoding_, options: options_
+        )
           options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
           yield options if block_given?
 
@@ -60,6 +72,7 @@ module Nokogiri
           end
 
           doc = if string_or_io.respond_to?(:read)
+            # TODO: should we instead check for respond_to?(:to_path) ?
             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
@@ -174,13 +187,44 @@ module Nokogiri
       # Since v1.12.4
       attr_accessor :namespace_inheritance
 
-      # :nodoc:
-      def initialize(*args) # rubocop:disable Lint/MissingSuper
+      def initialize(*args) # :nodoc: # rubocop:disable Lint/MissingSuper
         @errors     = []
         @decorators = nil
         @namespace_inheritance = false
       end
 
+      #
+      # :call-seq:
+      #   dup → Nokogiri::XML::Document
+      #   dup(level) → Nokogiri::XML::Document
+      #
+      # Duplicate this node.
+      #
+      # [Parameters]
+      # - +level+ (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.
+      # [Returns] The new Nokogiri::XML::Document
+      #
+      def dup(level = 1)
+        copy = OBJECT_DUP_METHOD.bind_call(self)
+        copy.initialize_copy_with_args(self, level)
+      end
+
+      #
+      # :call-seq:
+      #   clone → Nokogiri::XML::Document
+      #   clone(level) → Nokogiri::XML::Document
+      #
+      # Clone this node.
+      #
+      # [Parameters]
+      # - +level+ (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.
+      # [Returns] The new Nokogiri::XML::Document
+      #
+      def clone(level = 1)
+        copy = OBJECT_CLONE_METHOD.bind_call(self)
+        copy.initialize_copy_with_args(self, level)
+      end
+
       # :call-seq:
       #   create_element(name, *contents_or_attrs, &block) → Nokogiri::XML::Element
       #
@@ -327,10 +371,10 @@ module Nokogiri
       end
 
       ##
-      # Validate this Document against it's DTD.  Returns a list of errors on
+      # Validate this Document against its DTD.  Returns a list of errors on
       # the document or +nil+ when there is no DTD.
       def validate
-        return nil unless internal_subset
+        return unless internal_subset
 
         internal_subset.validate(self)
       end
@@ -368,12 +412,11 @@ module Nokogiri
         @decorators.each do |klass, list|
           next unless node.is_a?(klass)
 
-          list.each { |moodule| node.extend(moodule) }
+          list.each { |mod| node.extend(mod) }
         end
       end
 
       alias_method :to_xml, :serialize
-      alias_method :clone, :dup
 
       # Get the hash of namespaces on the root Nokogiri::XML::Node
       def namespaces
@@ -427,8 +470,6 @@ module Nokogiri
       #  instructions. If you have a use case and would like this functionality, please let us know
       #  by opening an issue or a discussion on the github project.
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
-      #
       #  *Example*
       #
       #    doc = Nokogiri::XML.parse(<<~XML)
@@ -455,6 +496,8 @@ module Nokogiri
       #    doc.deconstruct_keys([:root])
       #    # => {:root=>nil}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         { root: root }
       end