nokogiri 1.16.8-x86_64-linux → 1.17.0-x86_64-linux

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
@@ -180,6 +193,38 @@ module Nokogiri
         @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
       #
@@ -326,7 +371,7 @@ 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 unless internal_subset
@@ -367,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

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.
+      #
+      # [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.
       #
-      #  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
+      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)

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
@@ -1051,9 +1126,11 @@ module Nokogiri
 
         error_count = document.errors.length
         node_set = in_context(contents, options.to_i)
+
         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
@@ -1080,6 +1157,7 @@ module Nokogiri
             node_set = fragment.children
           end
         end
+
         node_set
       end
 
@@ -1542,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
 
@@ -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

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,33 @@
 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.
     #
-    # The Reader parser might be good for when you need the speed and low memory usage of the SAX
-    # parser, but do not want to write a Document handler.
+    # 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
     #
     # ⚠ 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.
     #
-    # ⚠ libxml2 does not support error recovery in the Reader parser. The `RECOVER` ParseOption is
+    # ⚠ 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
@@ -66,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.
       #