nokogiri 1.13.10 → 1.14.0.rc1

data/lib/nokogiri/xml/document.rb

@@ -19,63 +19,72 @@ module Nokogiri
       NCNAME_CHAR       = NCNAME_START_CHAR + "\\-\\.0-9"
       NCNAME_RE         = /^xmlns(?::([#{NCNAME_START_CHAR}][#{NCNAME_CHAR}]*))?$/
 
-      ##
-      # Parse an XML file.
-      #
-      # +string_or_io+ may be a String, or any object that responds to
-      # _read_ and _close_ such as an IO, or StringIO.
-      #
-      # +url+ (optional) is the URI where this document is located.
-      #
-      # +encoding+ (optional) is the encoding that should be used when processing
-      # the document.
-      #
-      # +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.
-      #
-      # +block+ (optional) is passed a configuration object on which
-      # parse options may be set.
-      #
-      # 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.
-      #
-      # 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)
-        options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
-        yield options if block_given?
+      class << self
+        # Parse an XML file.
+        #
+        # +string_or_io+ may be a String, or any object that responds to
+        # _read_ and _close_ such as an IO, or StringIO.
+        #
+        # +url+ (optional) is the URI where this document is located.
+        #
+        # +encoding+ (optional) is the encoding that should be used when processing
+        # the document.
+        #
+        # +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.
+        #
+        # +block+ (optional) is passed a configuration object on which
+        # parse options may be set.
+        #
+        # 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.
+        #
+        # Nokogiri.XML() is a convenience method which will call this method.
+        #
+        def 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, "Empty document"
+            else
+              return encoding ? new.tap { |i| i.encoding = encoding } : new
+            end
+          end
 
-        url ||= string_or_io.respond_to?(:path) ? string_or_io.path : nil
+          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 empty_doc?(string_or_io)
-          if options.strict?
-            raise Nokogiri::XML::SyntaxError, "Empty document"
+            read_io(string_or_io, url, encoding, options.to_i)
           else
-            return encoding ? new.tap { |i| i.encoding = encoding } : new
+            # read_memory pukes on empty docs
+            read_memory(string_or_io, url, encoding, options.to_i)
           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
+          # do xinclude processing
+          doc.do_xinclude(options) if options.xinclude?
 
-          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)
+          doc
         end
 
-        # do xinclude processing
-        doc.do_xinclude(options) if options.xinclude?
+        private
 
-        doc
+        def 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
       end
 
       ##
@@ -165,6 +174,7 @@ module Nokogiri
       # Since v1.12.4
       attr_accessor :namespace_inheritance
 
+      # rubocop:disable Lint/MissingSuper
       def initialize(*args) # :nodoc:
         @errors     = []
         @decorators = nil
@@ -405,14 +415,52 @@ module Nokogiri
         Nokogiri::CSS::XPathVisitor::DoctypeConfig::XML
       end
 
-      private
-
-      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?)
+      #
+      #  :call-seq: deconstruct_keys(array_of_names) → Hash
+      #
+      #  Returns a hash describing the Document, to use in pattern matching.
+      #
+      #  Valid keys and their values:
+      #  - +root+ → (Node, nil) The root node of the Document, or +nil+ if the document is empty.
+      #
+      #  In the future, other keys may allow accessing things like doctype and processing
+      #  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)
+      #      <?xml version="1.0"?>
+      #      <root>
+      #        <child>
+      #      </root>
+      #    XML
+      #
+      #    doc.deconstruct_keys([:root])
+      #    # => {:root=>
+      #    #      #(Element:0x35c {
+      #    #        name = "root",
+      #    #        children = [
+      #    #          #(Text "\n" + "  "),
+      #    #          #(Element:0x370 { name = "child", children = [ #(Text "\n")] }),
+      #    #          #(Text "\n")]
+      #    #        })}
+      #
+      #  *Example* of an empty document
+      #
+      #    doc = Nokogiri::XML::Document.new
+      #
+      #    doc.deconstruct_keys([:root])
+      #    # => {:root=>nil}
+      #
+      def deconstruct_keys(keys)
+        { root: root }
       end
 
+      private
+
       IMPLIED_XPATH_CONTEXTS = ["//"].freeze # :nodoc:
 
       def inspect_attributes

data/lib/nokogiri/xml/document_fragment.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 # frozen_string_literal: true
 
 module Nokogiri
@@ -66,9 +67,7 @@ module Nokogiri
       def to_html(*args)
         if Nokogiri.jruby?
           options = args.first.is_a?(Hash) ? args.shift : {}
-          unless options[:save_with]
-            options[:save_with] = Node::SaveOptions::NO_DECLARATION | Node::SaveOptions::NO_EMPTY_TAGS | Node::SaveOptions::AS_HTML
-          end
+          options[:save_with] ||= Node::SaveOptions::DEFAULT_HTML
           args.insert(0, options)
         end
         children.to_html(*args)
@@ -80,9 +79,7 @@ module Nokogiri
       def to_xhtml(*args)
         if Nokogiri.jruby?
           options = args.first.is_a?(Hash) ? args.shift : {}
-          unless options[:save_with]
-            options[:save_with] = Node::SaveOptions::NO_DECLARATION | Node::SaveOptions::NO_EMPTY_TAGS | Node::SaveOptions::AS_XHTML
-          end
+          options[:save_with] ||= Node::SaveOptions::DEFAULT_XHTML
           args.insert(0, options)
         end
         children.to_xhtml(*args)
@@ -148,6 +145,52 @@ module Nokogiri
         document.fragment(data)
       end
 
+      #
+      #  :call-seq: deconstruct() → Array
+      #
+      #  Returns the root nodes of this document fragment as an array, to use in pattern matching.
+      #
+      #  💡 Note that text nodes are returned as well as elements. If you wish to operate only on
+      #  root elements, you should deconstruct the array returned by
+      #  <tt>DocumentFragment#elements</tt>.
+      #
+      #  ⚡ This is an experimental feature, available since v1.14.0
+      #
+      #  *Example*
+      #
+      #    frag = Nokogiri::HTML5.fragment(<<~HTML)
+      #      <div>Start</div>
+      #      This is a <a href="#jump">shortcut</a> for you.
+      #      <div>End</div>
+      #    HTML
+      #
+      #    frag.deconstruct
+      #    # => [#(Element:0x35c { name = "div", children = [ #(Text "Start")] }),
+      #    #     #(Text "\n" + "This is a "),
+      #    #     #(Element:0x370 {
+      #    #       name = "a",
+      #    #       attributes = [ #(Attr:0x384 { name = "href", value = "#jump" })],
+      #    #       children = [ #(Text "shortcut")]
+      #    #       }),
+      #    #     #(Text " for you.\n"),
+      #    #     #(Element:0x398 { name = "div", children = [ #(Text "End")] }),
+      #    #     #(Text "\n")]
+      #
+      #  *Example* only the elements, not the text nodes.
+      #
+      #    frag.elements.deconstruct
+      #    # => [#(Element:0x35c { name = "div", children = [ #(Text "Start")] }),
+      #    #     #(Element:0x370 {
+      #    #       name = "a",
+      #    #       attributes = [ #(Attr:0x384 { name = "href", value = "#jump" })],
+      #    #       children = [ #(Text "shortcut")]
+      #    #       }),
+      #    #     #(Element:0x398 { name = "div", children = [ #(Text "End")] })]
+      #
+      def deconstruct
+        children.to_a
+      end
+
       private
 
       # fix for issue 770

data/lib/nokogiri/xml/namespace.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 # frozen_string_literal: true
 
 module Nokogiri
@@ -6,6 +7,47 @@ module Nokogiri
       include Nokogiri::XML::PP::Node
       attr_reader :document
 
+      #
+      #  :call-seq: deconstruct_keys(array_of_names) → Hash
+      #
+      #  Returns a hash describing the Namespace, to use in pattern matching.
+      #
+      #  Valid keys and their values:
+      #  - +prefix+ → (String, nil) The namespace's prefix, or +nil+ if there is no prefix (e.g., default namespace).
+      #  - +href+ → (String) The namespace's URI
+      #
+      #  ⚡ This is an experimental feature, available since v1.14.0
+      #
+      #  *Example*
+      #
+      #    doc = Nokogiri::XML.parse(<<~XML)
+      #      <?xml version="1.0"?>
+      #      <root xmlns="http://nokogiri.org/ns/default" xmlns:noko="http://nokogiri.org/ns/noko">
+      #        <child1 foo="abc" noko:bar="def"/>
+      #        <noko:child2 foo="qwe" noko:bar="rty"/>
+      #      </root>
+      #    XML
+      #
+      #    doc.root.elements.first.namespace
+      #    # => #(Namespace:0x35c { href = "http://nokogiri.org/ns/default" })
+      #
+      #    doc.root.elements.first.namespace.deconstruct_keys([:prefix, :href])
+      #    # => {:prefix=>nil, :href=>"http://nokogiri.org/ns/default"}
+      #
+      #    doc.root.elements.last.namespace
+      #    # => #(Namespace:0x370 {
+      #    #      prefix = "noko",
+      #    #      href = "http://nokogiri.org/ns/noko"
+      #    #      })
+      #
+      #    doc.root.elements.last.namespace.deconstruct_keys([:prefix, :href])
+      #    # => {:prefix=>"noko", :href=>"http://nokogiri.org/ns/noko"}
+      #
+      #
+      def deconstruct_keys(keys)
+        { prefix: prefix, href: href }
+      end
+
       private
 
       def inspect_attributes

data/lib/nokogiri/xml/node/save_options.rb

@@ -29,14 +29,16 @@ module Nokogiri
           DEFAULT_XML  = AS_XML # https://github.com/sparklemotion/nokogiri/issues/#issue/415
           # the default for HTML document
           DEFAULT_HTML = NO_DECLARATION | NO_EMPTY_TAGS | AS_HTML
+          # the default for XHTML document
+          DEFAULT_XHTML = NO_DECLARATION | AS_XHTML
         else
           # the default for XML documents
           DEFAULT_XML  = FORMAT | AS_XML
           # the default for HTML document
           DEFAULT_HTML = FORMAT | NO_DECLARATION | NO_EMPTY_TAGS | AS_HTML
+          # the default for XHTML document
+          DEFAULT_XHTML = FORMAT | NO_DECLARATION | AS_XHTML
         end
-        # the default for XHTML document
-        DEFAULT_XHTML = FORMAT | NO_DECLARATION | AS_XHTML
 
         # Integer representation of the SaveOptions
         attr_reader :options

data/lib/nokogiri/xml/node.rb

@@ -137,9 +137,12 @@ module Nokogiri
 
       ###
       # Add +node_or_tags+ as a child of this Node.
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +<<+.
       def add_child(node_or_tags)
@@ -154,9 +157,12 @@ module Nokogiri
 
       ###
       # Add +node_or_tags+ as the first child of this Node.
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +add_child+.
       def prepend_child(node_or_tags)
@@ -170,22 +176,81 @@ module Nokogiri
         end
       end
 
-      ###
-      # Add html around this node
+      # :call-seq:
+      #   wrap(markup) -> self
+      #   wrap(node) -> self
+      #
+      # Wrap this Node with the node parsed from +markup+ or a dup of the +node+.
+      #
+      # [Parameters]
+      # - *markup* (String)
+      #   Markup that is parsed and used as the wrapper. This node's parent, if it exists, is used
+      #   as the context node for parsing; otherwise the associated document is used. If the parsed
+      #   fragment has multiple roots, the first root node is used as the wrapper.
+      # - *node* (Nokogiri::XML::Node)
+      #   An element that is `#dup`ed and used as the wrapper.
+      #
+      # [Returns] +self+, to support chaining.
+      #
+      # Also see NodeSet#wrap
+      #
+      # *Example* with a +String+ argument:
       #
-      # Returns self
-      def wrap(html)
-        new_parent = document.parse(html).first
-        add_next_sibling(new_parent)
+      #   doc = Nokogiri::HTML5(<<~HTML)
+      #     <html><body>
+      #       <a>asdf</a>
+      #     </body></html>
+      #   HTML
+      #   doc.at_css("a").wrap("<div></div>")
+      #   doc.to_html
+      #   # => <html><head></head><body>
+      #   #      <div><a>asdf</a></div>
+      #   #    </body></html>
+      #
+      # *Example* with a +Node+ argument:
+      #
+      #   doc = Nokogiri::HTML5(<<~HTML)
+      #     <html><body>
+      #       <a>asdf</a>
+      #     </body></html>
+      #   HTML
+      #   doc.at_css("a").wrap(doc.create_element("div"))
+      #   doc.to_html
+      #   # <html><head></head><body>
+      #   #   <div><a>asdf</a></div>
+      #   # </body></html>
+      #
+      def wrap(node_or_tags)
+        case node_or_tags
+        when String
+          context_node = parent || document
+          new_parent = context_node.coerce(node_or_tags).first
+          if new_parent.nil?
+            raise "Failed to parse '#{node_or_tags}' in the context of a '#{context_node.name}' element"
+          end
+        when XML::Node
+          new_parent = node_or_tags.dup
+        else
+          raise ArgumentError, "Requires a String or Node argument, and cannot accept a #{node_or_tags.class}"
+        end
+
+        if parent
+          add_next_sibling(new_parent)
+        else
+          new_parent.unlink
+        end
         new_parent.add_child(self)
+
         self
       end
 
       ###
       # Add +node_or_tags+ as a child of this Node.
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns self, to support chaining of calls (e.g., root << child1 << child2)
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns +self+, to support chaining of calls (e.g., root << child1 << child2)
       #
       # Also see related method +add_child+.
       def <<(node_or_tags)
@@ -195,9 +260,12 @@ module Nokogiri
 
       ###
       # Insert +node_or_tags+ before this Node (as a sibling).
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +before+.
       def add_previous_sibling(node_or_tags)
@@ -209,9 +277,12 @@ module Nokogiri
 
       ###
       # Insert +node_or_tags+ after this Node (as a sibling).
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +after+.
       def add_next_sibling(node_or_tags)
@@ -223,9 +294,11 @@ module Nokogiri
 
       ####
       # Insert +node_or_tags+ before this node (as a sibling).
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns self, to support chaining of calls.
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns +self+, to support chaining of calls.
       #
       # Also see related method +add_previous_sibling+.
       def before(node_or_tags)
@@ -235,9 +308,11 @@ module Nokogiri
 
       ####
       # Insert +node_or_tags+ after this node (as a sibling).
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
       #
-      # Returns self, to support chaining of calls.
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a String
+      # containing markup.
+      #
+      # Returns +self+, to support chaining of calls.
       #
       # Also see related method +add_next_sibling+.
       def after(node_or_tags)
@@ -246,8 +321,18 @@ module Nokogiri
       end
 
       ####
-      # Set the inner html for this Node to +node_or_tags+
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
+      # Set the content for this Node to +node_or_tags+.
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a String
+      # containing markup.
+      #
+      # ⚠ Please note that despite the name, this method will *not* always parse a String argument
+      # as HTML. A String argument will be parsed with the +DocumentFragment+ parser related to this
+      # node's document.
+      #
+      # For example, if the document is an HTML4::Document then the string will be parsed as HTML4
+      # using HTML4::DocumentFragment; but if the document is an XML::Document then it will
+      # parse the string as XML using XML::DocumentFragment.
       #
       # Also see related method +children=+
       def inner_html=(node_or_tags)
@@ -255,8 +340,10 @@ module Nokogiri
       end
 
       ####
-      # Set the inner html for this Node +node_or_tags+
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
+      # Set the content for this Node +node_or_tags+
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a String
+      # containing markup.
       #
       # Also see related method +inner_html=+
       def children=(node_or_tags)
@@ -271,9 +358,12 @@ module Nokogiri
 
       ####
       # Replace this Node with +node_or_tags+.
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
       #
-      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is
+      # a DocumentFragment, NodeSet, or String).
       #
       # Also see related method +swap+.
       def replace(node_or_tags)
@@ -303,7 +393,9 @@ module Nokogiri
 
       ####
       # Swap this Node for +node_or_tags+
-      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a String
+      # Containing markup.
       #
       # Returns self, to support chaining of calls.
       #
@@ -314,7 +406,8 @@ module Nokogiri
       end
 
       ####
-      # Set the Node's content to a Text node containing +string+. The string gets XML escaped, not interpreted as markup.
+      # Set the Node's content to a Text node containing +string+. The string gets XML escaped, not
+      # interpreted as markup.
       def content=(string)
         self.native_content = encode_special_chars(string.to_s)
       end
@@ -1105,9 +1198,9 @@ module Nokogiri
 
       # Get the path to this node as a CSS expression
       def css_path
-        path.split(%r{/}).map do |part|
+        path.split(%r{/}).filter_map do |part|
           part.empty? ? nil : part.gsub(/\[(\d+)\]/, ':nth-of-type(\1)')
-        end.compact.join(" > ")
+        end.join(" > ")
       end
 
       ###
@@ -1194,12 +1287,11 @@ module Nokogiri
           }
         end
 
-        encoding = options[:encoding] || document.encoding
-        options[:encoding] = encoding
+        options[:encoding] ||= document.encoding
+        encoding = Encoding.find(options[:encoding] || "UTF-8")
+
+        io = StringIO.new(String.new(encoding: encoding))
 
-        outstring = +""
-        outstring.force_encoding(Encoding.find(encoding || "utf-8"))
-        io = StringIO.new(outstring)
         write_to(io, options, &block)
         io.string
       end
@@ -1311,6 +1403,69 @@ module Nokogiri
         end
       end
 
+      DECONSTRUCT_KEYS = [:name, :attributes, :children, :namespace, :content, :elements, :inner_html].freeze # :nodoc:
+      DECONSTRUCT_METHODS = { attributes: :attribute_nodes }.freeze # :nodoc:
+
+      #
+      #  :call-seq: deconstruct_keys(array_of_names) → Hash
+      #
+      #  Returns a hash describing the Node, to use in pattern matching.
+      #
+      #  Valid keys and their values:
+      #  - +name+ → (String) The name of this node, or "text" if it is a Text node.
+      #  - +namespace+ → (Namespace, nil) The namespace of this node, or nil if there is no namespace.
+      #  - +attributes+ → (Array<Attr>) The attributes of this node.
+      #  - +children+ → (Array<Node>) The children of this node. 💡 Note this includes text nodes.
+      #  - +elements+ → (Array<Node>) The child elements of this node. 💡 Note this does not include text nodes.
+      #  - +content+ → (String) The contents of all the text nodes in this node's subtree. See #content.
+      #  - +inner_html+ → (String) The inner markup for the children of this node. See #inner_html.
+      #
+      #  ⚡ This is an experimental feature, available since v1.14.0
+      #
+      #  *Example*
+      #
+      #    doc = Nokogiri::XML.parse(<<~XML)
+      #      <?xml version="1.0"?>
+      #      <parent xmlns="http://nokogiri.org/ns/default" xmlns:noko="http://nokogiri.org/ns/noko">
+      #        <child1 foo="abc" noko:bar="def">First</child1>
+      #        <noko:child2 foo="qwe" noko:bar="rty">Second</noko:child2>
+      #      </parent>
+      #    XML
+      #
+      #    doc.root.deconstruct_keys([:name, :namespace])
+      #    # => {:name=>"parent",
+      #    #     :namespace=>
+      #    #      #(Namespace:0x35c { href = "http://nokogiri.org/ns/default" })}
+      #
+      #    doc.root.deconstruct_keys([:inner_html, :content])
+      #    # => {:content=>"\n" + "  First\n" + "  Second\n",
+      #    #     :inner_html=>
+      #    #      "\n" +
+      #    #      "  <child1 foo=\"abc\" noko:bar=\"def\">First</child1>\n" +
+      #    #      "  <noko:child2 foo=\"qwe\" noko:bar=\"rty\">Second</noko:child2>\n"}
+      #
+      #    doc.root.elements.first.deconstruct_keys([:attributes])
+      #    # => {:attributes=>
+      #    #      [#(Attr:0x370 { name = "foo", value = "abc" }),
+      #    #       #(Attr:0x384 {
+      #    #         name = "bar",
+      #    #         namespace = #(Namespace:0x398 {
+      #    #           prefix = "noko",
+      #    #           href = "http://nokogiri.org/ns/noko"
+      #    #           }),
+      #    #         value = "def"
+      #    #         })]}
+      #
+      def deconstruct_keys(keys)
+        requested_keys = DECONSTRUCT_KEYS & keys
+        {}.tap do |values|
+          requested_keys.each do |key|
+            method = DECONSTRUCT_METHODS[key] || key
+            values[key] = send(method)
+          end
+        end
+      end
+
       # :section:
 
       protected