nokogiri 1.5.10 → 1.13.0

data/lib/nokogiri/xml/document.rb

@@ -1,19 +1,23 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+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.
-    #
-    # For searching a Document, see Nokogiri::XML::Node#css and
-    # Nokogiri::XML::Node#xpath
+    # 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.
     #
+    # For searching a Document, see Nokogiri::XML::Searchable#css and
+    # Nokogiri::XML::Searchable#xpath
     class Document < Nokogiri::XML::Node
-      # I'm ignoring unicode characters here.
-      # See http://www.w3.org/TR/REC-xml-names/#ns-decl for more details.
+      # 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
+      # characters in NCNAMEs.
       NCNAME_START_CHAR = "A-Za-z_"
-      NCNAME_CHAR       = NCNAME_START_CHAR + "\\-.0-9"
-      NCNAME_RE         = /^xmlns(:[#{NCNAME_START_CHAR}][#{NCNAME_CHAR}]*)?$/
+      NCNAME_CHAR       = NCNAME_START_CHAR + "\\-\\.0-9"
+      NCNAME_RE         = /^xmlns(?::([#{NCNAME_START_CHAR}][#{NCNAME_CHAR}]*))?$/
 
       ##
       # Parse an XML file.
@@ -33,22 +37,35 @@ module Nokogiri
       # +block+ (optional) is passed a configuration object on which
       # parse options may be set.
       #
-      # When parsing untrusted documents, it's recommended that the
-      # +nonet+ option be used, as shown in this example code:
-      #
-      #   Nokogiri::XML::Document.parse(xml_string) { |config| config.nonet }
+      # 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, &block
-        options = Nokogiri::XML::ParseOptions.new(options) if Fixnum === options
-        # Give the options to the user
+      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?
 
-        return new if empty_doc?(string_or_io)
+        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
 
         doc = if string_or_io.respond_to?(:read)
-          url ||= string_or_io.respond_to?(:path) ? string_or_io.path : nil
+          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
+
           read_io(string_or_io, url, encoding, options.to_i)
         else
           # read_memory pukes on empty docs
@@ -58,68 +75,192 @@ module Nokogiri
         # do xinclude processing
         doc.do_xinclude(options) if options.xinclude?
 
-        return doc
+        doc
       end
 
-      # A list of Nokogiri::XML::SyntaxError found when parsing a document
+      ##
+      # :singleton-method: wrap
+      # :call-seq: wrap(java_document) → Nokogiri::XML::Document
+      #
+      # ⚠ This method is only available when running JRuby.
+      #
+      # Create a Document using an existing Java DOM document object.
+      #
+      # The returned Document shares the same underlying data structure as the Java object, so
+      # changes in one are reflected in the other.
+      #
+      # [Parameters]
+      # - `java_document` (Java::OrgW3cDom::Document)
+      #   (The class `Java::OrgW3cDom::Document` is also accessible as `org.w3c.dom.Document`.)
+      #
+      # [Returns] Nokogiri::XML::Document
+      #
+      # See also \#to_java
+
+      # :method: to_java
+      # :call-seq: to_java() → Java::OrgW3cDom::Document
+      #
+      # ⚠ This method is only available when running JRuby.
+      #
+      # Returns the underlying Java DOM document object for this document.
+      #
+      # The returned Java object shares the same underlying data structure as this document, so
+      # changes in one are reflected in the other.
+      #
+      # [Returns]
+      #   Java::OrgW3cDom::Document
+      #   (The class `Java::OrgW3cDom::Document` is also accessible as `org.w3c.dom.Document`.)
+      #
+      # See also Document.wrap
+
+      # The errors found while parsing a document.
+      #
+      # [Returns] Array<Nokogiri::XML::SyntaxError>
       attr_accessor :errors
 
-      def initialize *args # :nodoc:
+      # When `true`, reparented elements without a namespace will inherit their new parent's
+      # namespace (if one exists). Defaults to `false`.
+      #
+      # [Returns] Boolean
+      #
+      # *Example:* Default behavior of namespace inheritance
+      #
+      #   xml = <<~EOF
+      #           <root xmlns:foo="http://nokogiri.org/default_ns/test/foo">
+      #             <foo:parent>
+      #             </foo:parent>
+      #           </root>
+      #         EOF
+      #   doc = Nokogiri::XML(xml)
+      #   parent = doc.at_xpath("//foo:parent", "foo" => "http://nokogiri.org/default_ns/test/foo")
+      #   parent.add_child("<child></child>")
+      #   doc.to_xml
+      #   # => <?xml version="1.0"?>
+      #   #    <root xmlns:foo="http://nokogiri.org/default_ns/test/foo">
+      #   #      <foo:parent>
+      #   #        <child/>
+      #   #      </foo:parent>
+      #   #    </root>
+      #
+      # *Example:* Setting namespace inheritance to `true`
+      #
+      #   xml = <<~EOF
+      #           <root xmlns:foo="http://nokogiri.org/default_ns/test/foo">
+      #             <foo:parent>
+      #             </foo:parent>
+      #           </root>
+      #         EOF
+      #   doc = Nokogiri::XML(xml)
+      #   doc.namespace_inheritance = true
+      #   parent = doc.at_xpath("//foo:parent", "foo" => "http://nokogiri.org/default_ns/test/foo")
+      #   parent.add_child("<child></child>")
+      #   doc.to_xml
+      #   # => <?xml version="1.0"?>
+      #   #    <root xmlns:foo="http://nokogiri.org/default_ns/test/foo">
+      #   #      <foo:parent>
+      #   #        <foo:child/>
+      #   #      </foo:parent>
+      #   #    </root>
+      #
+      # Since v1.12.4
+      attr_accessor :namespace_inheritance
+
+      def initialize(*args) # :nodoc:
         @errors     = []
         @decorators = nil
+        @namespace_inheritance = false
       end
 
-      ##
-      # Create an element with +name+, and optionally setting the content and attributes.
+      # :call-seq:
+      #   create_element(name, *contents_or_attrs, &block) → Nokogiri::XML::Element
       #
-      #   doc.create_element "div" # <div></div>
-      #   doc.create_element "div", :class => "container" # <div class='container'></div>
-      #   doc.create_element "div", "contents" # <div>contents</div>
-      #   doc.create_element "div", "contents", :class => "container" # <div class='container'>contents</div>
-      #   doc.create_element "div" { |node| node['class'] = "container" } # <div class='container'></div>
+      # Create a new Element with `name` belonging to this document, optionally setting contents or
+      # attributes.
       #
-      def create_element name, *args, &block
+      # This method is _not_ the most user-friendly option if your intention is to add a node to the
+      # document tree. Prefer one of the Nokogiri::XML::Node methods like Node#add_child,
+      # Node#add_next_sibling, Node#replace, etc. which will both create an element (or subtree) and
+      # place it in the document tree.
+      #
+      # Arguments may be passed to initialize the element:
+      #
+      # - a Hash argument will be used to set attributes
+      # - a non-Hash object that responds to \#to_s will be used to set the new node's contents
+      #
+      # A block may be passed to mutate the node.
+      #
+      # [Parameters]
+      # - `name` (String)
+      # - `contents_or_attrs` (\#to_s, Hash)
+      # [Yields] `node` (Nokogiri::XML::Element)
+      # [Returns] Nokogiri::XML::Element
+      #
+      # *Example:* An empty element without attributes
+      #
+      #   doc.create_element("div")
+      #   # => <div></div>
+      #
+      # *Example:* An element with contents
+      #
+      #   doc.create_element("div", "contents")
+      #   # => <div>contents</div>
+      #
+      # *Example:* An element with attributes
+      #
+      #   doc.create_element("div", {"class" => "container"})
+      #   # => <div class='container'></div>
+      #
+      # *Example:* An element with contents and attributes
+      #
+      #   doc.create_element("div", "contents", {"class" => "container"})
+      #   # => <div class='container'>contents</div>
+      #
+      # *Example:* Passing a block to mutate the element
+      #
+      #   doc.create_element("div") { |node| node["class"] = "blue" if before_noon? }
+      #
+      def create_element(name, *contents_or_attrs, &block)
         elm = Nokogiri::XML::Element.new(name, self, &block)
-        args.each do |arg|
+        contents_or_attrs.each do |arg|
           case arg
           when Hash
-            arg.each { |k,v|
+            arg.each do |k, v|
               key = k.to_s
               if key =~ NCNAME_RE
-                ns_name = key.split(":", 2)[1]
-                elm.add_namespace_definition ns_name, v
+                ns_name = Regexp.last_match(1)
+                elm.add_namespace_definition(ns_name, v)
               else
                 elm[k.to_s] = v.to_s
               end
-            }
+            end
           else
             elm.content = arg
           end
         end
-        if ns = elm.namespace_definitions.find { |n| n.prefix.nil? or n.prefix == '' }
+        if (ns = elm.namespace_definitions.find { |n| n.prefix.nil? || (n.prefix == "") })
           elm.namespace = ns
         end
         elm
       end
 
       # Create a Text Node with +string+
-      def create_text_node string, &block
-        Nokogiri::XML::Text.new string.to_s, self, &block
+      def create_text_node(string, &block)
+        Nokogiri::XML::Text.new(string.to_s, self, &block)
       end
 
       # Create a CDATA Node containing +string+
-      def create_cdata string, &block
-        Nokogiri::XML::CDATA.new self, string.to_s, &block
+      def create_cdata(string, &block)
+        Nokogiri::XML::CDATA.new(self, string.to_s, &block)
       end
 
       # Create a Comment Node containing +string+
-      def create_comment string, &block
-        Nokogiri::XML::Comment.new self, string.to_s, &block
+      def create_comment(string, &block)
+        Nokogiri::XML::Comment.new(self, string.to_s, &block)
       end
 
       # The name of this document.  Always returns "document"
       def name
-        'document'
+        "document"
       end
 
       # A reference to +self+
@@ -127,46 +268,51 @@ module Nokogiri
         self
       end
 
-      ##
-      # Recursively get all namespaces from this node and its subtree and
-      # return them as a hash.
+      # :call-seq:
+      #   collect_namespaces() → Hash<String(Namespace#prefix) ⇒ String(Namespace#href)>
       #
-      # For example, given this document:
+      # Recursively get all namespaces from this node and its subtree and return them as a
+      # hash.
       #
-      #   <root xmlns:foo="bar">
+      # ⚠ This method will not handle duplicate namespace prefixes, since the return value is a hash.
+      #
+      # Note that this method does an xpath lookup for nodes with namespaces, and as a result the
+      # order (and which duplicate prefix "wins") may be dependent on the implementation of the
+      # underlying XML library.
+      #
+      # *Example:* Basic usage
+      #
+      # Given this document:
+      #
+      #   <root xmlns="default" xmlns:foo="bar">
       #     <bar xmlns:hello="world" />
       #   </root>
       #
       # This method will return:
       #
-      #   { 'xmlns:foo' => 'bar', 'xmlns:hello' => 'world' }
+      #   {"xmlns:foo"=>"bar", "xmlns"=>"default", "xmlns:hello"=>"world"}
+      #
+      # *Example:* Duplicate prefixes
       #
-      # WARNING: this method will clobber duplicate names in the keys.
-      # For example, given this document:
+      # Given this document:
       #
       #   <root xmlns:foo="bar">
       #     <bar xmlns:foo="baz" />
       #   </root>
       #
-      # The hash returned will look like this: { 'xmlns:foo' => 'bar' }
+      # The hash returned will be something like:
       #
-      # Non-prefixed default namespaces (as in "xmlns=") are not included
-      # in the hash.
-      #
-      # Note that this method does an xpath lookup for nodes with
-      # namespaces, and as a result the order may be dependent on the
-      # implementation of the underlying XML library.
+      #   {"xmlns:foo" => "baz"}
       #
       def collect_namespaces
-        xpath("//namespace::*").inject({}) do |hash, ns|
-          hash[["xmlns",ns.prefix].compact.join(":")] = ns.href if ns.prefix != "xml"
-          hash
+        xpath("//namespace::*").each_with_object({}) do |ns, hash|
+          hash[["xmlns", ns.prefix].compact.join(":")] = ns.href if ns.prefix != "xml"
         end
       end
 
       # Get the list of decorators given +key+
-      def decorators key
-        @decorators ||= Hash.new
+      def decorators(key)
+        @decorators ||= {}
         @decorators[key] ||= []
       end
 
@@ -175,7 +321,7 @@ module Nokogiri
       # the document or +nil+ when there is no DTD.
       def validate
         return nil unless internal_subset
-        internal_subset.validate self
+        internal_subset.validate(self)
       end
 
       ##
@@ -195,7 +341,7 @@ module Nokogiri
       #   ... which does absolutely nothing.
       #
       def slop!
-        unless decorators(XML::Node).include? Nokogiri::Decorators::Slop
+        unless decorators(XML::Node).include?(Nokogiri::Decorators::Slop)
           decorators(XML::Node) << Nokogiri::Decorators::Slop
           decorate!
         end
@@ -205,16 +351,16 @@ module Nokogiri
 
       ##
       # Apply any decorators to +node+
-      def decorate node
+      def decorate(node)
         return unless @decorators
-        @decorators.each { |klass,list|
+        @decorators.each do |klass, list|
           next unless node.is_a?(klass)
           list.each { |moodule| node.extend(moodule) }
-        }
+        end
       end
 
-      alias :to_xml :serialize
-      alias :clone :dup
+      alias_method :to_xml, :serialize
+      alias_method :clone, :dup
 
       # Get the hash of namespaces on the root Nokogiri::XML::Node
       def namespaces
@@ -224,52 +370,45 @@ module Nokogiri
       ##
       # Create a Nokogiri::XML::DocumentFragment from +tags+
       # Returns an empty fragment if +tags+ is nil.
-      def fragment tags = nil
-        DocumentFragment.new(self, tags, self.root)
+      def fragment(tags = nil)
+        DocumentFragment.new(self, tags, root)
       end
 
       undef_method :swap, :parent, :namespace, :default_namespace=
       undef_method :add_namespace_definition, :attributes
       undef_method :namespace_definitions, :line, :add_namespace
 
-      def add_child node_or_tags
-        raise "Document already has a root node" if root
+      def add_child(node_or_tags)
+        raise "A document may not have multiple root nodes." if (root && root.name != "nokogiri_text_wrapper") && !(node_or_tags.comment? || node_or_tags.processing_instruction?)
         node_or_tags = coerce(node_or_tags)
         if node_or_tags.is_a?(XML::NodeSet)
-          raise "Document cannot have multiple root nodes" if node_or_tags.size > 1
+          raise "A document may not have multiple root nodes." if node_or_tags.size > 1
           super(node_or_tags.first)
         else
           super
         end
       end
-      alias :<< :add_child
+      alias_method :<<, :add_child
 
-      ##
-      # +JRuby+
-      # Wraps Java's org.w3c.dom.document and returns Nokogiri::XML::Document
-      def self.wrap document
-        raise "JRuby only method" unless Nokogiri.jruby?
-        return wrapJavaDocument(document)
-      end
-
-      ##
-      # +JRuby+
-      # Returns Java's org.w3c.dom.document of this Document.
-      def to_java
-        raise "JRuby only method" unless Nokogiri.jruby?
-        return toJavaDocument()
+      # :call-seq:
+      #   xpath_doctype() → Nokogiri::CSS::XPathVisitor::DoctypeConfig
+      #
+      # [Returns] The document type which determines CSS-to-XPath translation.
+      #
+      # See XPathVisitor for more information.
+      def xpath_doctype
+        Nokogiri::CSS::XPathVisitor::DoctypeConfig::XML
       end
 
       private
-      def self.empty_doc? string_or_io
+
+      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?)
       end
 
-      def implied_xpath_context
-        "/"
-      end
+      IMPLIED_XPATH_CONTEXTS = ["//"].freeze # :nodoc:
 
       def inspect_attributes
         [:name, :children]

data/lib/nokogiri/xml/document_fragment.rb

@@ -1,34 +1,57 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     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)
+      end
+
       ##
       #  Create a new DocumentFragment from +tags+.
       #
       #  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
+      def initialize(document, tags = nil, ctx = nil, options = ParseOptions::DEFAULT_XML)
         return self unless tags
 
+        options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
+        yield options if block_given?
+
         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
+          # Fix for issue#490
+          if Nokogiri.jruby?
+            # fix for issue #770
+            ctx.parse("<root #{namespace_declarations(ctx)}>#{tags}</root>", options).children
+          else
+            ctx.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
 
+      if Nokogiri.uses_libxml?
+        def dup
+          new_document = document.dup
+          new_fragment = self.class.new(new_document)
+          children.each do |child|
+            child.dup(1, new_document).parent = new_fragment
+          end
+          new_fragment
+        end
+      end
+
       ###
       # return the name for DocumentFragment
       def name
-        '#document-fragment'
+        "#document-fragment"
       end
 
       ###
@@ -40,10 +63,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]
+          unless options[:save_with]
             options[:save_with] = Node::SaveOptions::NO_DECLARATION | Node::SaveOptions::NO_EMPTY_TAGS | Node::SaveOptions::AS_HTML
           end
           args.insert(0, options)
@@ -54,10 +77,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]
+          unless options[:save_with]
             options[:save_with] = Node::SaveOptions::NO_DECLARATION | Node::SaveOptions::NO_EMPTY_TAGS | Node::SaveOptions::AS_XHTML
           end
           args.insert(0, options)
@@ -68,44 +91,71 @@ 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
 
       ###
-      # Search this fragment.  See Nokogiri::XML::Node#css
-      def css *args
+      # call-seq: css *rules, [namespace-bindings, custom-pseudo-class]
+      #
+      # Search this fragment for CSS +rules+. +rules+ must be one or more CSS
+      # selectors. For example:
+      #
+      # For more information see Nokogiri::XML::Searchable#css
+      def css(*args)
         if children.any?
-          children.css(*args)
+          children.css(*args) # 'children' is a smell here
         else
           NodeSet.new(document)
         end
       end
 
-      alias :serialize :to_s
+      #
+      #  NOTE that we don't delegate #xpath to children ... another smell.
+      #  def xpath ; end
+      #
+
+      ###
+      # call-seq: search *paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class]
+      #
+      # 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)
+        rules, handler, ns, binds = extract_params(rules)
 
-      class << self
-        ####
-        # Create a Nokogiri::XML::DocumentFragment from +tags+
-        def parse tags
-          self.new(XML::Document.new, tags)
+        rules.inject(NodeSet.new(document)) do |set, rule|
+          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_method :serialize, :to_s
+
+      # A list of Nokogiri::XML::SyntaxError found when parsing a document
+      def errors
+        document.errors
+      end
+
+      def errors=(things) # :nodoc:
+        document.errors = things
+      end
+
+      def fragment(data)
+        document.fragment(data)
+      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