nokogiri 1.11.1 → 1.12.0.rc1

data/lib/nokogiri/xml/document.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 # frozen_string_literal: true
 
 require 'pathname'
@@ -13,11 +14,12 @@ module Nokogiri
     # 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.
@@ -79,6 +81,35 @@ module Nokogiri
         return doc
       end
 
+      ##
+      # @!method wrap(java_document)
+      # @!scope class
+      #
+      # 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.
+      #
+      # @param java_document [Java::OrgW3cDom::Document]
+      # @return [Nokogiri::XML::Document]
+      # @note This method is only available when running JRuby.
+      # @note The class +Java::OrgW3cDom::Document+ is also accessible as +org.w3c.dom.Document+.
+      # @see #to_java
+
+      ##
+      # @!method to_java()
+      #
+      # Returns the underlying Java DOM document object for the {Document}.
+      #
+      # The returned Java object shares the same underlying data structure as the {Document}, so
+      # changes in one are reflected in the other.
+      #
+      # @return [Java::OrgW3cDom::Document]
+      # @note This method is only available when running JRuby.
+      # @note The class +Java::OrgW3cDom::Document+ is also accessible as +org.w3c.dom.Document+.
+      # @see .wrap
+
+
       # A list of Nokogiri::XML::SyntaxError found when parsing a document
       attr_accessor :errors
 
@@ -88,33 +119,58 @@ module Nokogiri
       end
 
       ##
-      # Create an element with +name+, and optionally setting the content and attributes.
+      # Create a new +Element+ with +name+ sharing GC lifecycle with the document, optionally
+      # setting contents or attributes.
+      #
+      # 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
       #
-      #   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>
+      # A block may be passed to mutate the node.
       #
-      def create_element name, *args, &block
+      # @param name [String]
+      # @param contents_or_attrs [#to_s,Hash]
+      # @yieldparam node [Nokogiri::XML::Element]
+      # @return [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
@@ -262,24 +318,14 @@ module Nokogiri
       end
       alias :<< :add_child
 
-      ##
-      # +JRuby+
-      # Wraps Java's org.w3c.dom.document and returns Nokogiri::XML::Document
-      def self.wrap(document) end if false # native-ext provides Document.wrap
-
-      ##
-      # +JRuby+
-      # Returns Java's org.w3c.dom.document of this Document.
-      def to_java; end if false # JRuby provides #to_java
-
       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?)
       end
 
-      # @private
       IMPLIED_XPATH_CONTEXTS = [ '//'.freeze ].freeze # :nodoc:
 
       def inspect_attributes

data/lib/nokogiri/xml/node.rb

@@ -1,68 +1,57 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 require "stringio"
-require "nokogiri/xml/node/save_options"
 
 module Nokogiri
   module XML
-    ####
-    # Nokogiri::XML::Node is your window to the fun filled world of dealing
-    # with XML and HTML tags.  A Nokogiri::XML::Node may be treated similarly
-    # to a hash with regard to attributes.  For example (from irb):
+    ##
+    # {Nokogiri::XML::Node} is your window to the fun filled world of dealing with XML and HTML
+    # tags. A {Nokogiri::XML::Node} may be treated similarly to a hash with regard to attributes. For
+    # example:
     #
-    #   irb(main):004:0> node
-    #   => <a href="#foo" id="link">link</a>
-    #   irb(main):005:0> node['href']
-    #   => "#foo"
-    #   irb(main):006:0> node.keys
-    #   => ["href", "id"]
-    #   irb(main):007:0> node.values
-    #   => ["#foo", "link"]
-    #   irb(main):008:0> node['class'] = 'green'
-    #   => "green"
-    #   irb(main):009:0> node
-    #   => <a href="#foo" id="link" class="green">link</a>
-    #   irb(main):010:0>
+    #   node = Nokogiri::XML::DocumentFragment.parse("<a href='#foo' id='link'>link</a>").at_css("a")
+    #   node.to_html # => "<a href=\"#foo\" id=\"link\">link</a>"
+    #   node['href'] # => "#foo"
+    #   node.keys # => ["href", "id"]
+    #   node.values # => ["#foo", "link"]
+    #   node['class'] = 'green' # => "green"
+    #   node.to_html # => "<a href=\"#foo\" id=\"link\" class=\"green\">link</a>"
     #
-    # See Nokogiri::XML::Node#[] and Nokogiri::XML#[]= for more information.
+    # See the method group entitled "Working With Node Attributes" for the full set of methods.
     #
-    # Nokogiri::XML::Node also has methods that let you move around your
+    # {Nokogiri::XML::Node} also has methods that let you move around your
     # tree.  For navigating your tree, see:
     #
-    # * Nokogiri::XML::Node#parent
-    # * Nokogiri::XML::Node#children
-    # * Nokogiri::XML::Node#next
-    # * Nokogiri::XML::Node#previous
-    #
+    # * {#parent}
+    # * {#children}
+    # * {#next}
+    # * {#previous}
     #
     # When printing or otherwise emitting a document or a node (and
     # its subtree), there are a few methods you might want to use:
     #
-    # * content, text, inner_text, to_str: emit plaintext
-    #
-    #   These methods will all emit the plaintext version of your
-    #   document, meaning that entities will be replaced (e.g., "&lt;"
-    #   will be replaced with "<"), meaning that any sanitizing will
-    #   likely be un-done in the output.
+    # * {#content}, {#text}, {#inner_text}, {#to_str}: These methods will all <b>emit plaintext</b>,
+    #   meaning that entities will be replaced (e.g., "&lt;" will be replaced with "<"), meaning
+    #   that any sanitizing will likely be un-done in the output.
     #
-    # * to_s, to_xml, to_html, inner_html: emit well-formed markup
+    # * {#to_s}, {#to_xml}, {#to_html}, {#inner_html}: These methods will all <b>emit
+    #   properly-escaped markup</b>, meaning that it's suitable for consumption by browsers,
+    #   parsers, etc.
     #
-    #   These methods will all emit properly-escaped markup, meaning
-    #   that it's suitable for consumption by browsers, parsers, etc.
+    # You may search this node's subtree using {#xpath} and {#css}
     #
-    # You may search this node's subtree using Searchable#xpath and Searchable#css
     class Node
       include Nokogiri::XML::PP::Node
       include Nokogiri::XML::Searchable
       include Enumerable
 
-      # Element node type, see Nokogiri::XML::Node#element?
+      # Element node type, see {Nokogiri::XML::Node#element?}
       ELEMENT_NODE = 1
       # Attribute node type
       ATTRIBUTE_NODE = 2
-      # Text node type, see Nokogiri::XML::Node#text?
+      # Text node type, see {Nokogiri::XML::Node#text?}
       TEXT_NODE = 3
-      # CDATA node type, see Nokogiri::XML::Node#cdata?
+      # CDATA node type, see {Nokogiri::XML::Node#cdata?}
       CDATA_SECTION_NODE = 4
       # Entity reference node type
       ENTITY_REF_NODE = 5
@@ -70,9 +59,9 @@ module Nokogiri
       ENTITY_NODE = 6
       # PI node type
       PI_NODE = 7
-      # Comment node type, see Nokogiri::XML::Node#comment?
+      # Comment node type, see {Nokogiri::XML::Node#comment?}
       COMMENT_NODE = 8
-      # Document node type, see Nokogiri::XML::Node#xml?
+      # Document node type, see {Nokogiri::XML::Node#xml?}
       DOCUMENT_NODE = 9
       # Document type node type
       DOCUMENT_TYPE_NODE = 10
@@ -80,7 +69,7 @@ module Nokogiri
       DOCUMENT_FRAG_NODE = 11
       # Notation node type
       NOTATION_NODE = 12
-      # HTML document node type, see Nokogiri::XML::Node#html?
+      # HTML document node type, see {Nokogiri::XML::Node#html?}
       HTML_DOCUMENT_NODE = 13
       # DTD node type
       DTD_NODE = 14
@@ -99,8 +88,15 @@ module Nokogiri
       # DOCB document node type
       DOCB_DOCUMENT_NODE = 21
 
-      def initialize(name, document) # :nodoc:
-        # ... Ya.  This is empty on purpose.
+      ##
+      # Create a new node with +name+ sharing GC lifecycle with +document+.
+      # @param name [String]
+      # @param document [Nokogiri::XML::Document]
+      # @yieldparam node [Nokogiri::XML::Node]
+      # @return [Nokogiri::XML::Node]
+      # @see Nokogiri::XML::Node.new
+      def initialize(name, document)
+        # This is intentionally empty.
       end
 
       ###
@@ -840,7 +836,7 @@ module Nokogiri
         node_set = in_context(contents, options.to_i)
         if (node_set.empty? && (document.errors.length > error_count))
           if options.recover?
-            fragment = Nokogiri::HTML::DocumentFragment.parse contents
+            fragment = Nokogiri::HTML4::DocumentFragment.parse contents
             node_set = fragment.children
           else
             raise document.errors[error_count]
@@ -886,7 +882,7 @@ module Nokogiri
         type == DOCUMENT_NODE
       end
 
-      # Returns true if this is an HTML::Document node
+      # Returns true if this is an HTML4::Document node
       def html?
         type == HTML_DOCUMENT_NODE
       end
@@ -912,11 +908,11 @@ module Nokogiri
       end
 
       ###
-      # Fetch the Nokogiri::HTML::ElementDescription for this node.  Returns
+      # Fetch the Nokogiri::HTML4::ElementDescription for this node.  Returns
       # nil on XML documents and on unknown tags.
       def description
         return nil if document.xml?
-        Nokogiri::HTML::ElementDescription[name]
+        Nokogiri::HTML4::ElementDescription[name]
       end
 
       ###
@@ -1238,3 +1234,5 @@ Requires a Node, NodeSet or String argument, and cannot accept a #{data.class}.
     end
   end
 end
+
+require_relative "node/save_options"

data/lib/nokogiri/xml/parse_options.rb

@@ -71,6 +71,8 @@ module Nokogiri
 
       # the default options used for parsing XML documents
       DEFAULT_XML  = RECOVER | NONET
+      # the default options used for parsing XSLT stylesheets
+      DEFAULT_XSLT = RECOVER | NONET | NOENT | DTDLOAD | DTDATTR | NOCDATA
       # the default options used for parsing HTML documents
       DEFAULT_HTML = RECOVER | NOERROR | NOWARNING | NONET
       # the default options used for parsing XML schemas

data/lib/nokogiri/xml/pp.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
-require 'nokogiri/xml/pp/node'
-require 'nokogiri/xml/pp/character_data'
+require_relative "pp/node"
+require_relative "pp/character_data"

data/lib/nokogiri/xml/reader.rb

@@ -86,7 +86,8 @@ module Nokogiri
       private :initialize
 
       ###
-      # Get a list of attributes for the current node.
+      # Get the attributes of the current node as a Hash
+      # @return [Hash<String, String>] Attribute names and values
       def attributes
         attrs_hash = attribute_nodes.each_with_object({}) do |node, hash|
                        hash[node.name] = node.to_s
@@ -96,14 +97,6 @@ module Nokogiri
         attrs_hash
       end
 
-      ###
-      # Get a list of attributes for the current node
-      def attribute_nodes
-        nodes = attr_nodes
-        nodes.each { |v| v.instance_variable_set(:@_r, self) }
-        nodes
-      end
-
       ###
       # Move the cursor through the document yielding the cursor to the block
       def each

data/lib/nokogiri/xml/sax.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-require 'nokogiri/xml/sax/document'
-require 'nokogiri/xml/sax/parser_context'
-require 'nokogiri/xml/sax/parser'
-require 'nokogiri/xml/sax/push_parser'
+require_relative "sax/document"
+require_relative "sax/parser_context"
+require_relative "sax/parser"
+require_relative "sax/push_parser"

data/lib/nokogiri/xml/sax/document.rb

@@ -2,20 +2,19 @@
 module Nokogiri
   module XML
     ###
-    # SAX Parsers are event driven parsers.  Nokogiri provides two different
-    # event based parsers when dealing with XML.  If you want to do SAX style
-    # parsing using HTML, check out Nokogiri::HTML::SAX.
+    # SAX Parsers are event driven parsers. Nokogiri provides two different event based parsers when
+    # dealing with XML. If you want to do SAX style parsing using HTML, check out
+    # Nokogiri::HTML4::SAX.
     #
-    # The basic way a SAX style parser works is by creating a parser,
-    # telling the parser about the events we're interested in, then giving
-    # the parser some XML to process.  The parser will notify you when
-    # it encounters events you said you would like to know about.
+    # The basic way a SAX style parser works is by creating a parser, telling the parser about the
+    # events we're interested in, then giving the parser some XML to process. The parser will notify
+    # you when it encounters events you said you would like to know about.
     #
-    # To register for events, you simply subclass Nokogiri::XML::SAX::Document,
-    # and implement the methods for which you would like notification.
+    # To register for events, you simply subclass Nokogiri::XML::SAX::Document, and implement the
+    # methods for which you would like notification.
     #
-    # For example, if I want to be notified when a document ends, and when an
-    # element starts, I would write a class like this:
+    # For example, if I want to be notified when a document ends, and when an element starts, I
+    # would write a class like this:
     #
     #   class MyDocument < Nokogiri::XML::SAX::Document
     #     def end_document
@@ -27,8 +26,7 @@ module Nokogiri
     #     end
     #   end
     #
-    # Then I would instantiate a SAX parser with this document, and feed the
-    # parser some XML
+    # Then I would instantiate a SAX parser with this document, and feed the parser some XML
     #
     #   # Create a new parser
     #   parser = Nokogiri::XML::SAX::Parser.new(MyDocument.new)
@@ -36,25 +34,21 @@ module Nokogiri
     #   # Feed the parser some XML
     #   parser.parse(File.open(ARGV[0]))
     #
-    # Now my document handler will be called when each node starts, and when
-    # then document ends.  To see what kinds of events are available, take
-    # a look at Nokogiri::XML::SAX::Document.
+    # Now my document handler will be called when each node starts, and when then document ends. To
+    # see what kinds of events are available, take a look at Nokogiri::XML::SAX::Document.
     #
-    # Two SAX parsers for XML are available, a parser that reads from a string
-    # or IO object as it feels necessary, and a parser that lets you spoon
-    # feed it XML.  If you want to let Nokogiri deal with reading your XML,
-    # use the Nokogiri::XML::SAX::Parser.  If you want to have fine grain
+    # Two SAX parsers for XML are available, a parser that reads from a string or IO object as it
+    # feels necessary, and a parser that lets you spoon feed it XML. If you want to let Nokogiri
+    # deal with reading your XML, use the Nokogiri::XML::SAX::Parser. If you want to have fine grain
     # control over the XML input, use the Nokogiri::XML::SAX::PushParser.
     module SAX
       ###
-      # This class is used for registering types of events you are interested
-      # in handling.  All of the methods on this class are available as
-      # possible events while parsing an XML document.  To register for any
-      # particular event, just subclass this class and implement the methods
-      # you are interested in knowing about.
+      # This class is used for registering types of events you are interested in handling. All of
+      # the methods on this class are available as possible events while parsing an XML document. To
+      # register for any particular event, just subclass this class and implement the methods you
+      # are interested in knowing about.
       #
-      # To only be notified about start and end element events, write a class
-      # like this:
+      # To only be notified about start and end element events, write a class like this:
       #
       #   class MyDocument < Nokogiri::XML::SAX::Document
       #     def start_element name, attrs = []
@@ -66,8 +60,8 @@ module Nokogiri
       #     end
       #   end
       #
-      # You can use this event handler for any SAX style parser included with
-      # Nokogiri.  See Nokogiri::XML::SAX, and Nokogiri::HTML::SAX.
+      # You can use this event handler for any SAX style parser included with Nokogiri. See
+      # Nokogiri::XML::SAX, and Nokogiri::HTML4::SAX.
       class Document
         ###
         # Called when an XML declaration is parsed
@@ -129,7 +123,7 @@ module Nokogiri
         end
 
         ###
-        # Characters read between a tag.  This method might be called multiple
+        # Characters read between a tag. This method might be called multiple
         # times given one contiguous string of characters.
         #
         # +string+ contains the character data