nokogiri 1.10.9 → 1.18.3

data/lib/nokogiri/xml/document_fragment.rb

@@ -1,27 +1,111 @@
+# coding: utf-8
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
+    # DocumentFragment represents a fragment of an \XML document. It provides the same functionality
+    # exposed by XML::Node and can be used to contain one or more \XML subtrees.
     class DocumentFragment < Nokogiri::XML::Node
-      ##
-      #  Create a new DocumentFragment from +tags+.
+      # The options used to parse the document fragment. Returns the value of any options that were
+      # passed into the constructor as a parameter or set in a config block, else the default
+      # options for the specific subclass.
+      attr_reader :parse_options
+
+      class << self
+        # :call-seq:
+        #   parse(input) { |options| ... } → XML::DocumentFragment
+        #   parse(input, options:) → XML::DocumentFragment
+        #
+        # Parse \XML fragment input from a String, and return a new XML::DocumentFragment. This
+        # method creates a new, empty XML::Document to contain the fragment.
+        #
+        # [Required Parameters]
+        # - +input+ (String) The content to be parsed.
+        #
+        # [Optional Keyword Arguments]
+        # - +options+ (Nokogiri::XML::ParseOptions) Configuration object that determines some
+        #   behaviors during parsing. See ParseOptions for more information. The default value is
+        #   +ParseOptions::DEFAULT_XML+.
+        #
+        # [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.
+        #
+        # [Returns] Nokogiri::XML::DocumentFragment
+        def parse(tags, options_ = ParseOptions::DEFAULT_XML, options: options_, &block)
+          new(XML::Document.new, tags, options: options, &block)
+        end
+
+        # Wrapper method to separate the concerns of:
+        # - the native object allocator's parameter (it only requires `document`)
+        # - the initializer's parameters
+        def new(document, ...) # :nodoc:
+          instance = native_new(document)
+          instance.send(:initialize, document, ...)
+          instance
+        end
+      end
+
+      # :call-seq:
+      #   new(document, input=nil) { |options| ... } → DocumentFragment
+      #   new(document, input=nil, context:, options:) → DocumentFragment
+      #
+      # Parse \XML fragment input from a String, and return a new DocumentFragment that is
+      # associated with the given +document+.
+      #
+      # 💡 It's recommended to use either XML::DocumentFragment.parse or Node#parse rather than call
+      # this method directly.
+      #
+      # [Required Parameters]
+      # - +document+ (XML::Document) The parent document to associate the returned fragment with.
+      #
+      # [Optional Parameters]
+      # - +input+ (String) The content to be parsed.
       #
-      #  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
+      # [Optional Keyword Arguments]
+      # - +context:+ (Nokogiri::XML::Node) The <b>context node</b> for the subtree created. See
+      #   below for more information.
+      #
+      # - +options:+ (Nokogiri::XML::ParseOptions) Configuration object that determines some
+      #   behaviors during parsing. See ParseOptions for more information. The default value is
+      #   +ParseOptions::DEFAULT_XML+.
+      #
+      # [Yields]
+      #   If a block is given, a Nokogiri::XML::ParseOptions object is yielded to the block which
+      #   can be configured before parsing. See ParseOptions for more information.
+      #
+      # [Returns] XML::DocumentFragment
+      #
+      # === Context \Node
+      #
+      # If a context node is specified using +context:+, then the fragment will be created by
+      # calling Node#parse on that node, so the parser will behave as if that Node is the parent of
+      # the fragment subtree, and will resolve namespaces relative to that node.
+      #
+      def initialize(
+        document, tags = nil,
+        context_ = nil, options_ = ParseOptions::DEFAULT_XML,
+        context: context_, options: options_
+      ) # rubocop:disable Lint/MissingSuper
         return self unless tags
 
-        children = if ctx
-                     # Fix for issue#490
-                     if Nokogiri.jruby?
-                       # fix for issue #770
-                       ctx.parse("<root #{namespace_declarations(ctx)}>#{tags}</root>").children
-                     else
-                       ctx.parse(tags)
-                     end
-                   else
-                     XML::Document.parse("<root>#{tags}</root>") \
-                       .xpath("/root/node()")
-                   end
+        options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
+        @parse_options = options
+        yield options if block_given?
+
+        children = if context
+          # Fix for issue#490
+          if Nokogiri.jruby?
+            # fix for issue #770
+            context.parse("<root #{namespace_declarations(context)}>#{tags}</root>", options).children
+          else
+            context.parse(tags, options)
+          end
+        else
+          wrapper_doc = XML::Document.parse("<root>#{tags}</root>", nil, nil, options)
+          self.errors = wrapper_doc.errors
+          wrapper_doc.xpath("/root/node()")
+        end
         children.each { |child| child.parent = self }
       end
 
@@ -39,7 +123,7 @@ module Nokogiri
       ###
       # return the name for DocumentFragment
       def name
-        '#document-fragment'
+        "#document-fragment"
       end
 
       ###
@@ -51,12 +135,10 @@ module Nokogiri
       ###
       # Convert this DocumentFragment to html
       # See Nokogiri::XML::NodeSet#to_html
-      def to_html *args
+      def to_html(*args)
         if Nokogiri.jruby?
           options = args.first.is_a?(Hash) ? args.shift : {}
-          if !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)
@@ -65,12 +147,10 @@ module Nokogiri
       ###
       # Convert this DocumentFragment to xhtml
       # See Nokogiri::XML::NodeSet#to_xhtml
-      def to_xhtml *args
+      def to_xhtml(*args)
         if Nokogiri.jruby?
           options = args.first.is_a?(Hash) ? args.shift : {}
-          if !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)
@@ -79,7 +159,7 @@ module Nokogiri
       ###
       # Convert this DocumentFragment to xml
       # See Nokogiri::XML::NodeSet#to_xml
-      def to_xml *args
+      def to_xml(*args)
         children.to_xml(*args)
       end
 
@@ -90,7 +170,7 @@ module Nokogiri
       # selectors. For example:
       #
       # For more information see Nokogiri::XML::Searchable#css
-      def css *args
+      def css(*args)
         if children.any?
           children.css(*args) # 'children' is a smell here
         else
@@ -109,51 +189,87 @@ module Nokogiri
       # Search this fragment for +paths+. +paths+ must be one or more XPath or CSS queries.
       #
       # For more information see Nokogiri::XML::Searchable#search
-      def search *rules
+      def search(*rules)
         rules, handler, ns, binds = extract_params(rules)
 
         rules.inject(NodeSet.new(document)) do |set, rule|
-          set += if rule =~ Searchable::LOOKS_LIKE_XPATH
-                   xpath(*([rule, ns, handler, binds].compact))
-                 else
-                   children.css(*([rule, ns, handler].compact)) # 'children' is a smell here
-                 end
+          set + if Searchable::LOOKS_LIKE_XPATH.match?(rule)
+            xpath(*[rule, ns, handler, binds].compact)
+          else
+            children.css(*[rule, ns, handler].compact) # 'children' is a smell here
+          end
         end
       end
 
-      alias :serialize :to_s
-
-      class << self
-        ####
-        # Create a Nokogiri::XML::DocumentFragment from +tags+
-        def parse tags
-          self.new(XML::Document.new, tags)
-        end
-      end
+      alias_method :serialize, :to_s
 
       # A list of Nokogiri::XML::SyntaxError found when parsing a document
       def errors
         document.errors
       end
 
-      def errors= things # :nodoc:
+      def errors=(things) # :nodoc:
         document.errors = things
       end
 
+      def fragment(data)
+        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
-      def namespace_declarations ctx
+      def namespace_declarations(ctx)
         ctx.namespace_scopes.map do |namespace|
           prefix = namespace.prefix.nil? ? "" : ":#{namespace.prefix}"
-          %Q{xmlns#{prefix}="#{namespace.href}"}
-        end.join ' '
-      end
-
-      def coerce data
-        return super unless String === data
-
-        document.fragment(data).children
+          %{xmlns#{prefix}="#{namespace.href}"}
+        end.join(" ")
       end
     end
   end

data/lib/nokogiri/xml/dtd.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class DTD < Nokogiri::XML::Node
@@ -19,13 +21,13 @@ module Nokogiri
       end
 
       def html_dtd?
-        name.casecmp('html').zero?
+        name.casecmp("html").zero?
       end
 
       def html5_dtd?
         html_dtd? &&
           external_id.nil? &&
-          (system_id.nil? || system_id == 'about:legacy-compat')
+          (system_id.nil? || system_id == "about:legacy-compat")
       end
     end
   end

data/lib/nokogiri/xml/element_content.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     ###
@@ -9,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
@@ -31,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

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

data/lib/nokogiri/xml/entity_decl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class EntityDecl < Nokogiri::XML::Node
@@ -7,12 +9,14 @@ module Nokogiri
       undef_method :namespace_definitions
       undef_method :line if method_defined?(:line)
 
-      def self.new name, doc, *args
+      def self.new(name, doc, *args)
         doc.create_entity(name, *args)
       end
 
-      def inspect
-        "#<#{self.class.name}:#{sprintf("0x%x", object_id)} #{to_s.inspect}>"
+      private
+
+      def inspect_attributes
+        [:to_s]
       end
     end
   end

data/lib/nokogiri/xml/entity_reference.rb

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

data/lib/nokogiri/xml/namespace.rb

@@ -1,10 +1,54 @@
+# coding: utf-8
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class Namespace
       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
         [:prefix, :href]
       end

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

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class Node
       ###
-      # Save options for serializing nodes
+      # Save options for serializing nodes.
+      # See the method group entitled Node@Serialization+and+Generating+Output for usage.
       class SaveOptions
         # Format serialized xml
         FORMAT          = 1
@@ -21,28 +24,32 @@ module Nokogiri
 
         if Nokogiri.jruby?
           # Save builder created document
-          AS_BUILDER    = 128
+          AS_BUILDER = 128
           # the default for XML documents
           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 | NO_EMPTY_TAGS | AS_XHTML
 
         # Integer representation of the SaveOptions
         attr_reader :options
 
         # Create a new SaveOptions object with +options+
-        def initialize options = 0; @options = options; end
+        def initialize(options = 0)
+          @options = options
+        end
 
         constants.each do |constant|
-          class_eval %{
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{constant.downcase}
               @options |= #{constant}
               self
@@ -51,10 +58,18 @@ module Nokogiri
             def #{constant.downcase}?
               #{constant} & @options == #{constant}
             end
-          }
+          RUBY
         end
 
-        alias :to_i :options
+        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