nokogiri 1.15.3 → 1.18.7

data/lib/nokogiri/xml/document_fragment.rb

@@ -3,32 +3,103 @@
 
 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 Nokogiri::XML::DocumentFragment from +tags+
-      def self.parse(tags, options = ParseOptions::DEFAULT_XML, &block)
-        new(XML::Document.new, tags, nil, options, &block)
+      # 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
 
-      ##
-      #  Create a new DocumentFragment from +tags+.
+      # :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, options = ParseOptions::DEFAULT_XML) # rubocop:disable Lint/MissingSuper
+      # [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
 
         options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
+        @parse_options = options
         yield options if block_given?
 
-        children = if ctx
+        children = if context
           # Fix for issue#490
           if Nokogiri.jruby?
             # fix for issue #770
-            ctx.parse("<root #{namespace_declarations(ctx)}>#{tags}</root>", options).children
+            context.parse("<root #{namespace_declarations(context)}>#{tags}</root>", options).children
           else
-            ctx.parse(tags, options)
+            context.parse(tags, options)
           end
         else
           wrapper_doc = XML::Document.parse("<root>#{tags}</root>", nil, nil, options)
@@ -154,8 +225,6 @@ module Nokogiri
       #  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)
@@ -187,6 +256,8 @@ module Nokogiri
       #    #       }),
       #    #     #(Element:0x398 { name = "div", children = [ #(Text "End")] })]
       #
+      #  Since v1.14.0
+      #
       def deconstruct
         children.to_a
       end

data/lib/nokogiri/xml/namespace.rb

@@ -16,8 +16,6 @@ module Nokogiri
       #  - +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)
@@ -43,6 +41,7 @@ module Nokogiri
       #    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 }

data/lib/nokogiri/xml/node.rb

@@ -127,6 +127,42 @@ module Nokogiri
         # This is intentionally empty, and sets the method signature for subclasses.
       end
 
+      #
+      # :call-seq:
+      #   dup → Nokogiri::XML::Node
+      #   dup(level) → Nokogiri::XML::Node
+      #   dup(level, new_parent_doc) → Nokogiri::XML::Node
+      #
+      # Duplicate this node.
+      #
+      # [Parameters]
+      # - +level+ (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.
+      # - +new_parent_doc+ (optional Nokogiri::XML::Document)
+      #   The new node's parent Document. Defaults to the the Document of the current node.
+      # [Returns] The new Nokogiri::XML::Node
+      #
+      def dup(level = 1, new_parent_doc = document)
+        super().initialize_copy_with_args(self, level, new_parent_doc)
+      end
+
+      #
+      # :call-seq:
+      #   clone → Nokogiri::XML::Node
+      #   clone(level) → Nokogiri::XML::Node
+      #   clone(level, new_parent_doc) → Nokogiri::XML::Node
+      #
+      # Clone this node.
+      #
+      # [Parameters]
+      # - +level+ (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.
+      # - +new_parent_doc+
+      #   The new node's parent Document. Defaults to the the Document of the current node.
+      # [Returns] The new Nokogiri::XML::Node
+      #
+      def clone(level = 1, new_parent_doc = document)
+        super().initialize_copy_with_args(self, level, new_parent_doc)
+      end
+
       ###
       # Decorate this node with the decorators set up in this node's Document
       def decorate!
@@ -228,7 +264,7 @@ module Nokogiri
           if new_parent.nil?
             raise "Failed to parse '#{node_or_tags}' in the context of a '#{context_node.name}' element"
           end
-        when XML::Node
+        when Node
           new_parent = node_or_tags.dup
         else
           raise ArgumentError, "Requires a String or Node argument, and cannot accept a #{node_or_tags.class}"
@@ -406,8 +442,48 @@ module Nokogiri
       end
 
       ####
-      # Set the Node's content to a Text node containing +string+. The string gets XML escaped, not
-      # interpreted as markup.
+      # call-seq:
+      #   content=(input)
+      #
+      # Set the content of this node to +input+.
+      #
+      # [Parameters]
+      # - +input+ (String) The new content for this node. Input is considered to be raw content, and
+      #   so will be entity-escaped in the final DOM string.
+      #
+      # [Example]
+      # Note how entities are handled:
+      #
+      #   doc = Nokogiri::HTML::Document.parse(<<~HTML)
+      #     <html>
+      #       <body>
+      #         <div id="first">asdf</div>
+      #         <div id="second">asdf</div>
+      #   HTML
+      #
+      #   text_node = doc.at_css("div#first").children.first
+      #   div_node = doc.at_css("div#second")
+      #
+      #   value = "You &amp; Me"
+      #
+      #   text_node.content = value
+      #   div_node.content = value
+      #
+      #   doc.css("div").to_html
+      #   # => "<div id=\"first\">You &amp;amp; Me</div>
+      #   #     <div id=\"second\">You &amp;amp; Me</div>"
+      #
+      # For content that is already entity-escaped, use CGI::unescapeHTML to decode it:
+      #
+      #   text_node.content = CGI::unescapeHTML(value)
+      #   div_node.content = CGI::unescapeHTML(value)
+      #
+      #   doc.css("div").to_html
+      #   # => "<div id=\"first\">You &amp; Me</div>
+      #   #     <div id=\"second\">You &amp; Me</div>"
+      #
+      # See also: #native_content=
+      #
       def content=(string)
         self.native_content = encode_special_chars(string.to_s)
       end
@@ -474,7 +550,6 @@ module Nokogiri
       alias_method :to_str, :content
       alias_method :name, :node_name
       alias_method :type, :node_type
-      alias_method :clone, :dup
       alias_method :elements, :element_children
 
       # :section: Working With Node Attributes
@@ -1049,31 +1124,40 @@ module Nokogiri
 
         return Nokogiri::XML::NodeSet.new(document) if contents.empty?
 
-        # libxml2 does not obey the +recover+ option after encountering errors during +in_context+
-        # parsing, and so this horrible hack is here to try to emulate recovery behavior.
-        #
-        # Unfortunately, this means we're no longer parsing "in context" and so namespaces that
-        # would have been inherited from the context node won't be handled correctly. This hack was
-        # written in 2010, and I regret it, because it's silently degrading functionality in a way
-        # that's not easily prevented (or even detected).
-        #
-        # I think preferable behavior would be to either:
-        #
-        # a. add an error noting that we "fell back" and pointing the user to turning off the +recover+ option
-        # b. don't recover, but raise a sensible exception
-        #
-        # For context and background: https://github.com/sparklemotion/nokogiri/issues/313
-        # FIXME bug report: https://github.com/sparklemotion/nokogiri/issues/2092
         error_count = document.errors.length
         node_set = in_context(contents, options.to_i)
-        if node_set.empty? && (document.errors.length > error_count)
-          if options.recover?
+
+        if document.errors.length > error_count
+          raise document.errors[error_count] unless options.recover?
+
+          # TODO: remove this block when libxml2 < 2.13 is no longer supported
+          if node_set.empty?
+            # libxml2 < 2.13 does not obey the +recover+ option after encountering errors during
+            # +in_context+ parsing, and so this horrible hack is here to try to emulate recovery
+            # behavior.
+            #
+            # (Note that HTML4 fragment parsing seems to have been fixed in abd74186, and XML
+            # fragment parsing is fixed in 1c106edf. Both are in 2.13.)
+            #
+            # Unfortunately, this means we're no longer parsing "in context" and so namespaces that
+            # would have been inherited from the context node won't be handled correctly. This hack
+            # was written in 2010, and I regret it, because it's silently degrading functionality in
+            # a way that's not easily prevented (or even detected).
+            #
+            # I think preferable behavior would be to either:
+            #
+            # a. add an error noting that we "fell back" and pointing the user to turning off the
+            #    +recover+ option
+            # b. don't recover, but raise a sensible exception
+            #
+            # For context and background:
+            # - https://github.com/sparklemotion/nokogiri/issues/313
+            # - https://github.com/sparklemotion/nokogiri/issues/2092
             fragment = document.related_class("DocumentFragment").parse(contents)
             node_set = fragment.children
-          else
-            raise document.errors[error_count]
           end
         end
+
         node_set
       end
 
@@ -1165,7 +1249,7 @@ module Nokogiri
       # Fetch the Nokogiri::HTML4::ElementDescription for this node.  Returns
       # nil on XML documents and on unknown tags.
       def description
-        return nil if document.xml?
+        return if document.xml?
 
         Nokogiri::HTML4::ElementDescription[name]
       end
@@ -1254,8 +1338,8 @@ module Nokogiri
       # Compare two Node objects with respect to their Document.  Nodes from
       # different documents cannot be compared.
       def <=>(other)
-        return nil unless other.is_a?(Nokogiri::XML::Node)
-        return nil unless document == other.document
+        return unless other.is_a?(Nokogiri::XML::Node)
+        return unless document == other.document
 
         compare(other)
       end
@@ -1278,6 +1362,7 @@ module Nokogiri
       #   end
       #
       def serialize(*args, &block)
+        # TODO: deprecate non-hash options, see 46c68ed 2009-06-20 for context
         options = if args.first.is_a?(Hash)
           args.shift
         else
@@ -1429,8 +1514,6 @@ module Nokogiri
       #  - +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)
@@ -1465,6 +1548,8 @@ module Nokogiri
       #    #         value = "def"
       #    #         })]}
       #
+      #  Since v1.14.0
+      #
       def deconstruct_keys(keys)
         requested_keys = DECONSTRUCT_KEYS & keys
         {}.tap do |values|
@@ -1535,19 +1620,12 @@ module Nokogiri
         node_or_tags
       end
 
-      USING_LIBXML_WITH_BROKEN_SERIALIZATION = Nokogiri.uses_libxml?("~> 2.6.0").freeze
-      private_constant :USING_LIBXML_WITH_BROKEN_SERIALIZATION
-
       def to_format(save_option, options)
-        return dump_html if USING_LIBXML_WITH_BROKEN_SERIALIZATION
-
         options[:save_with] = save_option unless options[:save_with]
         serialize(options)
       end
 
       def write_format_to(save_option, io, options)
-        return (io << dump_html) if USING_LIBXML_WITH_BROKEN_SERIALIZATION
-
         options[:save_with] ||= save_option
         write_to(io, options)
       end

data/lib/nokogiri/xml/node_set.rb

@@ -4,9 +4,13 @@
 module Nokogiri
   module XML
     ####
-    # A NodeSet contains a list of Nokogiri::XML::Node objects.  Typically
-    # a NodeSet is return as a result of searching a Document via
-    # Nokogiri::XML::Searchable#css or Nokogiri::XML::Searchable#xpath
+    # A NodeSet is an Enumerable that contains a list of Nokogiri::XML::Node objects.
+    #
+    # Typically a NodeSet is returned as a result of searching a Document via
+    # Nokogiri::XML::Searchable#css or Nokogiri::XML::Searchable#xpath.
+    #
+    # Note that the `#dup` and `#clone` methods perform shallow copies; these methods do not copy
+    # the Nodes contained in the NodeSet (similar to how Array and other Enumerable classes work).
     class NodeSet
       include Nokogiri::XML::Searchable
       include Enumerable
@@ -14,8 +18,6 @@ module Nokogiri
       # The Document this NodeSet is associated with
       attr_accessor :document
 
-      alias_method :clone, :dup
-
       # Create a NodeSet with +document+ defaulting to +list+
       def initialize(document, list = [])
         @document = document
@@ -121,7 +123,7 @@ module Nokogiri
           return self[args.first]
         end
 
-        super(*args)
+        super
       end
       alias_method :%, :at
 
@@ -372,7 +374,7 @@ module Nokogiri
       # Removes the last element from set and returns it, or +nil+ if
       # the set is empty
       def pop
-        return nil if length == 0
+        return if length == 0
 
         delete(last)
       end
@@ -381,7 +383,7 @@ module Nokogiri
       # Returns the first element of the NodeSet and removes it.  Returns
       # +nil+ if the set is empty.
       def shift
-        return nil if length == 0
+        return if length == 0
 
         delete(first)
       end
@@ -423,7 +425,7 @@ module Nokogiri
       end
 
       ###
-      # Return a nicely formated string representation
+      # Return a nicely formatted string representation
       def inspect
         "[#{map(&:inspect).join(", ")}]"
       end
@@ -435,7 +437,7 @@ module Nokogiri
       #
       #  Returns the members of this NodeSet as an array, to use in pattern matching.
       #
-      #  ⚡ This is an experimental feature, available since v1.14.0
+      #  Since v1.14.0
       #
       def deconstruct
         to_a

data/lib/nokogiri/xml/parse_options.rb

@@ -140,7 +140,7 @@ module Nokogiri
 
       # Relax any hardcoded limit from the parser. Off by default.
       #
-      # ⚠ There may be a performance penalty when this option is set.
+      # ⚠ <b>It is UNSAFE to set this option</b> when parsing untrusted documents.
       HUGE        = 1 << 19
 
       # Support line numbers up to <code>long int</code> (default is a <code>short int</code>). On

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

@@ -8,6 +8,11 @@ module Nokogiri
         COLLECTIONS = [:attribute_nodes, :children]
 
         def inspect
+          # handle the case where an exception is thrown during object construction
+          if respond_to?(:data_ptr?) && !data_ptr?
+            return "#<#{self.class}:#{format("0x%x", object_id)} (no data)>"
+          end
+
           attributes = inspect_attributes.reject do |x|
             attribute = send(x)
             !attribute || (attribute.respond_to?(:empty?) && attribute.empty?)
@@ -21,7 +26,7 @@ module Nokogiri
               "#{attribute}=#{send(attribute).inspect}"
             end.join(" ")
           end
-          "#<#{self.class.name}:#{format("0x%x", object_id)} #{attributes}>"
+          "#<#{self.class}:#{format("0x%x", object_id)} #{attributes}>"
         end
 
         def pretty_print(pp)

data/lib/nokogiri/xml/reader.rb

@@ -3,32 +3,34 @@
 module Nokogiri
   module XML
     ###
-    # Nokogiri::XML::Reader parses an XML document similar to the way a cursor
-    # would move.  The Reader is given an XML document, and yields nodes
-    # to an each block.
+    # The Reader parser allows you to effectively pull parse an \XML document.  Once instantiated,
+    # call Nokogiri::XML::Reader#each to iterate over each node.
+    #
+    # Nokogiri::XML::Reader parses an \XML document similar to the way a cursor would move. The
+    # Reader is given an \XML document, and yields nodes to an each block.
+    #
+    # The Reader parser might be good for when you need the speed and low memory usage of a \SAX
+    # parser, but do not want to write a SAX::Document handler.
     #
     # Here is an example of usage:
     #
-    #     reader = Nokogiri::XML::Reader(<<-eoxml)
+    #     reader = Nokogiri::XML::Reader.new <<~XML
     #       <x xmlns:tenderlove='http://tenderlovemaking.com/'>
     #         <tenderlove:foo awesome='true'>snuggles!</tenderlove:foo>
     #       </x>
-    #     eoxml
+    #     XML
     #
     #     reader.each do |node|
-    #
     #       # node is an instance of Nokogiri::XML::Reader
     #       puts node.name
-    #
     #     end
     #
-    # Note that Nokogiri::XML::Reader#each can only be called once!!  Once
-    # the cursor moves through the entire document, you must parse the
-    # document again.  So make sure that you capture any information you
-    # need during the first iteration.
+    # ⚠ Nokogiri::XML::Reader#each can only be called once! Once the cursor moves through the entire
+    # document, you must parse the document again. It may be better to capture all information you
+    # need during a single iteration.
     #
-    # The Reader parser is good for when you need the speed of a SAX parser,
-    # but do not want to write a Document handler.
+    # ⚠ libxml2 does not support error recovery in the Reader parser. The +RECOVER+ ParseOption is
+    # ignored. If a syntax error is encountered during parsing, an exception will be raised.
     class Reader
       include Enumerable
 
@@ -65,23 +67,55 @@ module Nokogiri
       TYPE_END_ELEMENT = 15
       # Entity end node type
       TYPE_END_ENTITY = 16
-      # XML Declaration node type
+      # \XML Declaration node type
       TYPE_XML_DECLARATION = 17
 
       # A list of errors encountered while parsing
       attr_accessor :errors
 
-      # The XML source
+      # The \XML source
       attr_reader :source
 
       alias_method :self_closing?, :empty_element?
 
-      def initialize(source, url = nil, encoding = nil) # :nodoc:
+      # :call-seq:
+      #   Reader.new(input) { |options| ... } → Reader
+      #   Reader.new(input, url:, encoding:, options:) { |options| ... } → Reader
+      #
+      # Create a new Reader to parse an \XML document.
+      #
+      # [Required Parameters]
+      # - +input+ (String | IO): The \XML document to parse.
+      #
+      # [Optional Parameters]
+      # - +url:+ (String) The base URL of the document.
+      # - +encoding:+ (String) The name of the encoding of the document.
+      # - +options:+ (Integer | ParseOptions) Options to control the parser behavior.
+      #   Defaults to +ParseOptions::STRICT+.
+      #
+      # [Yields]
+      # If present, the block will be passed a Nokogiri::XML::ParseOptions object to modify before
+      # the fragment is parsed. See Nokogiri::XML::ParseOptions for more information.
+      def self.new(
+        string_or_io,
+        url_ = nil, encoding_ = nil, options_ = ParseOptions::STRICT,
+        url: url_, encoding: encoding_, options: options_
+      )
+        options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
+        yield options if block_given?
+
+        if string_or_io.respond_to?(:read)
+          return Reader.from_io(string_or_io, url, encoding, options.to_i)
+        end
+
+        Reader.from_memory(string_or_io, url, encoding, options.to_i)
+      end
+
+      private def initialize(source, url = nil, encoding = nil) # :nodoc:
         @source   = source
         @errors   = []
         @encoding = encoding
       end
-      private :initialize
 
       # Get the attributes and namespaces of the current node as a Hash.
       #