nokogiri 1.13.6 → 1.16.7

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,7 +174,7 @@ module Nokogiri
       # Since v1.12.4
       attr_accessor :namespace_inheritance
 
-      def initialize(*args) # :nodoc:
+      def initialize(*args) # :nodoc: # rubocop:disable Lint/MissingSuper
         @errors     = []
         @decorators = nil
         @namespace_inheritance = false
@@ -320,7 +329,7 @@ module Nokogiri
       # Validate this Document against it's 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
@@ -405,14 +414,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.
+      #
+      #  *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}
+      #
+      #  Since v1.14.0
+      #
+      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
@@ -15,7 +16,7 @@ module Nokogiri
       #  If +ctx+ is present, it is used as a context node for the
       #  subtree created, e.g., namespaces will be resolved relative
       #  to +ctx+.
-      def initialize(document, tags = nil, ctx = nil, options = ParseOptions::DEFAULT_XML)
+      def initialize(document, tags = nil, ctx = nil, options = ParseOptions::DEFAULT_XML) # rubocop:disable Lint/MissingSuper
         return self unless tags
 
         options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
@@ -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>.
+      #
+      #  *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")] })]
+      #
+      #  Since v1.14.0
+      #
+      def deconstruct
+        children.to_a
+      end
+
       private
 
       # fix for issue 770

data/lib/nokogiri/xml/element_content.rb

@@ -11,9 +11,11 @@ module Nokogiri
     #   ]>
     #   </root>
     #
-    # ElementContent represents the tree inside the <!ELEMENT> tag shown above
-    # that lists the possible content for the div1 tag.
+    # ElementContent represents the binary tree inside the <!ELEMENT> tag shown above that lists the
+    # possible content for the div1 tag.
     class ElementContent
+      include Nokogiri::XML::PP::Node
+
       # Possible definitions of type
       PCDATA  = 1
       ELEMENT = 2
@@ -33,6 +35,12 @@ module Nokogiri
       def children
         [c1, c2].compact
       end
+
+      private
+
+      def inspect_attributes
+        [:prefix, :name, :type, :occur, :children]
+      end
     end
   end
 end

data/lib/nokogiri/xml/element_decl.rb

@@ -7,8 +7,10 @@ module Nokogiri
       undef_method :namespace_definitions
       undef_method :line if method_defined?(:line)
 
-      def inspect
-        "#<#{self.class.name}:#{format("0x%x", object_id)} #{to_s.inspect}>"
+      private
+
+      def inspect_attributes
+        [:to_s]
       end
     end
   end

data/lib/nokogiri/xml/entity_decl.rb

@@ -13,8 +13,10 @@ module Nokogiri
         doc.create_entity(name, *args)
       end
 
-      def inspect
-        "#<#{self.class.name}:#{format("0x%x", object_id)} #{to_s.inspect}>"
+      private
+
+      def inspect_attributes
+        [:to_s]
       end
     end
   end

data/lib/nokogiri/xml/namespace.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 # frozen_string_literal: true
 
 module Nokogiri
@@ -6,6 +7,46 @@ 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
+      #
+      #  *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"}
+      #
+      #  Since v1.14.0
+      #
+      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
@@ -47,7 +49,7 @@ module Nokogiri
         end
 
         constants.each do |constant|
-          class_eval %{
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{constant.downcase}
               @options |= #{constant}
               self
@@ -56,10 +58,18 @@ module Nokogiri
             def #{constant.downcase}?
               #{constant} & @options == #{constant}
             end
-          }
+          RUBY
         end
 
         alias_method :to_i, :options
+
+        def inspect
+          options = []
+          self.class.constants.each do |k|
+            options << k.downcase if send(:"#{k.downcase}?")
+          end
+          super.sub(/>$/, " " + options.join(", ") + ">")
+        end
       end
     end
   end