nokogiri 1.12.5 → 1.14.3

data/lib/nokogiri/xml/node_set.rb

@@ -1,4 +1,6 @@
+# coding: utf-8
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
     ####
@@ -12,10 +14,10 @@ module Nokogiri
       # The Document this NodeSet is associated with
       attr_accessor :document
 
-      alias :clone :dup
+      alias_method :clone, :dup
 
       # Create a NodeSet with +document+ defaulting to +list+
-      def initialize document, list = []
+      def initialize(document, list = [])
         @document = document
         document.decorate(self)
         list.each { |x| self << x }
@@ -24,8 +26,9 @@ module Nokogiri
 
       ###
       # Get the first element of the NodeSet.
-      def first n = nil
+      def first(n = nil)
         return self[0] unless n
+
         list = []
         [n, length].min.times { |i| list << self[i] }
         list
@@ -47,7 +50,7 @@ module Nokogiri
       # Returns the index of the first node in self that is == to +node+ or meets the given block. Returns nil if no match is found.
       def index(node = nil)
         if node
-          warn "given block not used" if block_given?
+          warn("given block not used") if block_given?
           each_with_index { |member, j| return j if member == node }
         elsif block_given?
           each_with_index { |member, j| return j if yield(member) }
@@ -57,18 +60,18 @@ module Nokogiri
 
       ###
       # Insert +datum+ before the first Node in this NodeSet
-      def before datum
-        first.before datum
+      def before(datum)
+        first.before(datum)
       end
 
       ###
       # Insert +datum+ after the last Node in this NodeSet
-      def after datum
-        last.after datum
+      def after(datum)
+        last.after(datum)
       end
 
-      alias :<< :push
-      alias :remove :unlink
+      alias_method :<<, :push
+      alias_method :remove, :unlink
 
       ###
       # call-seq: css *rules, [namespace-bindings, custom-pseudo-class]
@@ -77,7 +80,7 @@ module Nokogiri
       # selectors. For example:
       #
       # For more information see Nokogiri::XML::Searchable#css
-      def css *args
+      def css(*args)
         rules, handler, ns, _ = extract_params(args)
         paths = css_rules_to_xpath(rules, ns)
 
@@ -93,7 +96,7 @@ module Nokogiri
       # queries.
       #
       # For more information see Nokogiri::XML::Searchable#xpath
-      def xpath *args
+      def xpath(*args)
         paths, handler, ns, binds = extract_params(args)
 
         inject(NodeSet.new(document)) do |set, node|
@@ -101,13 +104,6 @@ module Nokogiri
         end
       end
 
-      ###
-      # Search this NodeSet's nodes' immediate children using CSS selector +selector+
-      def > selector
-        ns = document.root.namespaces
-        xpath CSS.xpath_for(selector, :prefix => "./", :ns => ns).first
-      end
-
       ###
       # call-seq: search *paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class]
       #
@@ -120,18 +116,18 @@ module Nokogiri
       #
       #   node_set.at(3) # same as node_set[3]
       #
-      def at *args
+      def at(*args)
         if args.length == 1 && args.first.is_a?(Numeric)
           return self[args.first]
         end
 
         super(*args)
       end
-      alias :% :at
+      alias_method :%, :at
 
       ###
       # Filter this list for nodes that match +expr+
-      def filter expr
+      def filter(expr)
         find_all { |node| node.matches?(expr) }
       end
 
@@ -140,7 +136,7 @@ module Nokogiri
       # NodeSet.
       #
       # See Nokogiri::XML::Node#add_class for more information.
-      def add_class name
+      def add_class(name)
         each do |el|
           el.add_class(name)
         end
@@ -152,7 +148,7 @@ module Nokogiri
       # NodeSet.
       #
       # See Nokogiri::XML::Node#append_class for more information.
-      def append_class name
+      def append_class(name)
         each do |el|
           el.append_class(name)
         end
@@ -164,7 +160,7 @@ module Nokogiri
       # NodeSet.
       #
       # See Nokogiri::XML::Node#remove_class for more information.
-      def remove_class name = nil
+      def remove_class(name = nil)
         each do |el|
           el.remove_class(name)
         end
@@ -204,31 +200,31 @@ module Nokogiri
       #
       #   node_set.attr("class") { |node| node.name }
       #
-      def attr key, value = nil, &block
+      def attr(key, value = nil, &block)
         unless key.is_a?(Hash) || (key && (value || block))
-          return first ? first.attribute(key) : nil
+          return first&.attribute(key)
         end
 
         hash = key.is_a?(Hash) ? key : { key => value }
 
-        hash.each do |k,v|
+        hash.each do |k, v|
           each do |node|
-            node[k] = v || block.call(node)
+            node[k] = v || yield(node)
           end
         end
 
         self
       end
-      alias :set :attr
-      alias :attribute :attr
+      alias_method :set, :attr
+      alias_method :attribute, :attr
 
       ###
       # Remove the attributed named +name+ from all Node objects in the NodeSet
-      def remove_attr name
-        each { |el| el.delete name }
+      def remove_attr(name)
+        each { |el| el.delete(name) }
         self
       end
-      alias remove_attribute remove_attr
+      alias_method :remove_attribute, :remove_attr
 
       ###
       # Iterate over each node, yielding  to +block+
@@ -255,20 +251,83 @@ module Nokogiri
       #
       # See Nokogiri::XML::Node#content for more information.
       def inner_text
-        collect(&:inner_text).join('')
+        collect(&:inner_text).join("")
       end
-      alias :text :inner_text
+      alias_method :text, :inner_text
 
       ###
       # Get the inner html of all contained Node objects
-      def inner_html *args
-        collect{|j| j.inner_html(*args) }.join('')
+      def inner_html(*args)
+        collect { |j| j.inner_html(*args) }.join("")
       end
 
-      ###
-      # Wrap this NodeSet with +html+
-      def wrap html
-        map { |node| node.wrap html }
+      # :call-seq:
+      #   wrap(markup) -> self
+      #   wrap(node) -> self
+      #
+      # Wrap each member of this NodeSet with the node parsed from +markup+ or a dup of the +node+.
+      #
+      # [Parameters]
+      # - *markup* (String)
+      #   Markup that is parsed, once per member of the NodeSet, and used as the wrapper. Each
+      #   node's parent, if it exists, is used as the context node for parsing; otherwise the
+      #   associated document is used. If the parsed fragment has multiple roots, the first root
+      #   node is used as the wrapper.
+      # - *node* (Nokogiri::XML::Node)
+      #   An element that is `#dup`ed and used as the wrapper.
+      #
+      # [Returns] +self+, to support chaining.
+      #
+      # ⚠ Note that if a +String+ is passed, the markup will be parsed <b>once per node</b> in the
+      # NodeSet. You can avoid this overhead in cases where you know exactly the wrapper you wish to
+      # use by passing a +Node+ instead.
+      #
+      # Also see Node#wrap
+      #
+      # *Example* with a +String+ argument:
+      #
+      #   doc = Nokogiri::HTML5(<<~HTML)
+      #     <html><body>
+      #       <a>a</a>
+      #       <a>b</a>
+      #       <a>c</a>
+      #       <a>d</a>
+      #     </body></html>
+      #   HTML
+      #   doc.css("a").wrap("<div></div>")
+      #   doc.to_html
+      #   # => <html><head></head><body>
+      #   #      <div><a>a</a></div>
+      #   #      <div><a>b</a></div>
+      #   #      <div><a>c</a></div>
+      #   #      <div><a>d</a></div>
+      #   #    </body></html>
+      #
+      # *Example* with a +Node+ argument
+      #
+      # 💡 Note that this is faster than the equivalent call passing a +String+ because it avoids
+      # having to reparse the wrapper markup for each node.
+      #
+      #   doc = Nokogiri::HTML5(<<~HTML)
+      #     <html><body>
+      #       <a>a</a>
+      #       <a>b</a>
+      #       <a>c</a>
+      #       <a>d</a>
+      #     </body></html>
+      #   HTML
+      #   doc.css("a").wrap(doc.create_element("div"))
+      #   doc.to_html
+      #   # => <html><head></head><body>
+      #   #      <div><a>a</a></div>
+      #   #      <div><a>b</a></div>
+      #   #      <div><a>c</a></div>
+      #   #      <div><a>d</a></div>
+      #   #    </body></html>
+      #
+      def wrap(node_or_tags)
+        map { |node| node.wrap(node_or_tags) }
+        self
       end
 
       ###
@@ -279,38 +338,43 @@ module Nokogiri
 
       ###
       # Convert this NodeSet to HTML
-      def to_html *args
+      def to_html(*args)
         if Nokogiri.jruby?
           options = args.first.is_a?(Hash) ? args.shift : {}
-          if !options[:save_with]
-            options[:save_with] = Node::SaveOptions::NO_DECLARATION | Node::SaveOptions::NO_EMPTY_TAGS | Node::SaveOptions::AS_HTML
-          end
+          options[:save_with] ||= Node::SaveOptions::DEFAULT_HTML
           args.insert(0, options)
         end
-        map { |x| x.to_html(*args) }.join
+        if empty?
+          encoding = (args.first.is_a?(Hash) ? args.first[:encoding] : nil)
+          encoding ||= document.encoding
+          encoding.nil? ? "" : "".encode(encoding)
+        else
+          map { |x| x.to_html(*args) }.join
+        end
       end
 
       ###
       # Convert this NodeSet to XHTML
-      def to_xhtml *args
+      def to_xhtml(*args)
         map { |x| x.to_xhtml(*args) }.join
       end
 
       ###
       # Convert this NodeSet to XML
-      def to_xml *args
+      def to_xml(*args)
         map { |x| x.to_xml(*args) }.join
       end
 
-      alias :size :length
-      alias :to_ary :to_a
+      alias_method :size, :length
+      alias_method :to_ary, :to_a
 
       ###
       # Removes the last element from set and returns it, or +nil+ if
       # the set is empty
       def pop
         return nil if length == 0
-        delete last
+
+        delete(last)
       end
 
       ###
@@ -318,16 +382,18 @@ module Nokogiri
       # +nil+ if the set is empty.
       def shift
         return nil if length == 0
-        delete first
+
+        delete(first)
       end
 
       ###
       # Equality -- Two NodeSets are equal if the contain the same number
       # of elements and if each element is equal to the corresponding
       # element in the other NodeSet
-      def == other
+      def ==(other)
         return false unless other.is_a?(Nokogiri::XML::NodeSet)
         return false unless length == other.length
+
         each_with_index do |node, i|
           return false unless node == other[i]
         end
@@ -351,7 +417,7 @@ module Nokogiri
       def reverse
         node_set = NodeSet.new(document)
         (length - 1).downto(0) do |x|
-          node_set.push self[x]
+          node_set.push(self[x])
         end
         node_set
       end
@@ -359,14 +425,23 @@ module Nokogiri
       ###
       # Return a nicely formated string representation
       def inspect
-        "[#{map(&:inspect).join ', '}]"
+        "[#{map(&:inspect).join(", ")}]"
       end
 
-      alias :+ :|
+      alias_method :+, :|
 
-      # @private
-      IMPLIED_XPATH_CONTEXTS = [ './/'.freeze, 'self::'.freeze ].freeze # :nodoc:
+      #
+      #  :call-seq: deconstruct() → Array
+      #
+      #  Returns the members of this NodeSet as an array, to use in pattern matching.
+      #
+      #  ⚡ This is an experimental feature, available since v1.14.0
+      #
+      def deconstruct
+        to_a
+      end
 
+      IMPLIED_XPATH_CONTEXTS = [".//", "self::"].freeze # :nodoc:
     end
   end
 end

data/lib/nokogiri/xml/notation.rb

@@ -1,7 +1,19 @@
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
+    # Struct representing an {XML Schema Notation}[https://www.w3.org/TR/xml/#Notations]
     class Notation < Struct.new(:name, :public_id, :system_id)
+      # dead comment to ensure rdoc processing
+
+      # :attr: name (String)
+      # The name for the element.
+
+      # :attr: public_id (String)
+      # The URI corresponding to the public identifier
+
+      # :attr: system_id (String,nil)
+      # The URI corresponding to the system identifier
     end
   end
 end

data/lib/nokogiri/xml/parse_options.rb

@@ -1,91 +1,175 @@
+# coding: utf-8
 # frozen_string_literal: true
+
 module Nokogiri
   module XML
-    ###
-    # Parse options for passing to Nokogiri.XML or Nokogiri.HTML
-    #
-    # == Building combinations of parse options
-    # You can build your own combinations of these parse options by using any of the following methods:
-    # *Note*: All examples attempt to set the +RECOVER+ & +NOENT+ options.
-    # [Ruby's bitwise operators] You can use the Ruby bitwise operators to set various combinations.
-    #   Nokogiri.XML('<content>Chapter 1</content', nil, nil, Nokogiri::XML::ParseOptions.new((1 << 0) | (1 << 1)))
-    # [Method chaining] Every option has an equivalent method in lowercase. You can chain these methods together to set various combinations.
-    #   Nokogiri.XML('<content>Chapter 1</content', nil, nil, Nokogiri::XML::ParseOptions.new.recover.noent)
-    # [Using Ruby Blocks] You can also setup parse combinations in the block passed to Nokogiri.XML or Nokogiri.HTML
-    #   Nokogiri.XML('<content>Chapter 1</content') {|config| config.recover.noent}
-    #
-    # == Removing particular parse options
-    # You can also remove options from an instance of +ParseOptions+ dynamically.
-    # Every option has an equivalent <code>no{option}</code> method in lowercase. You can call these methods on an instance of +ParseOptions+ to remove the option.
-    # Note that this is not available for +STRICT+.
-    #
-    #   # Setting the RECOVER & NOENT options...
-    #   options = Nokogiri::XML::ParseOptions.new.recover.noent
-    #   # later...
-    #   options.norecover # Removes the Nokogiri::XML::ParseOptions::RECOVER option
-    #   options.nonoent # Removes the Nokogiri::XML::ParseOptions::NOENT option
+    # Options that control the parsing behavior for XML::Document, XML::DocumentFragment,
+    # HTML4::Document, HTML4::DocumentFragment, XSLT::Stylesheet, and XML::Schema.
+    #
+    # These options directly expose libxml2's parse options, which are all boolean in the sense that
+    # an option is "on" or "off".
+    #
+    # 💡 Note that HTML5 parsing has a separate, orthogonal set of options due to the nature of the
+    # HTML5 specification. See Nokogiri::HTML5.
+    #
+    # ⚠ Not all parse options are supported on JRuby. Nokogiri will attempt to invoke the equivalent
+    # behavior in Xerces/NekoHTML on JRuby when it's possible.
+    #
+    # == Setting and unsetting parse options
+    #
+    # You can build your own combinations of parse options by using any of the following methods:
+    #
+    # [ParseOptions method chaining]
+    #
+    #   Every option has an equivalent method in lowercase. You can chain these methods together to
+    #   set various combinations.
+    #
+    #     # Set the HUGE & PEDANTIC options
+    #     po = Nokogiri::XML::ParseOptions.new.huge.pedantic
+    #     doc = Nokogiri::XML::Document.parse(xml, nil, nil, po)
+    #
+    #   Every option has an equivalent <code>no{option}</code> method in lowercase. You can call these
+    #   methods on an instance of ParseOptions to unset the option.
+    #
+    #     # Set the HUGE & PEDANTIC options
+    #     po = Nokogiri::XML::ParseOptions.new.huge.pedantic
+    #
+    #     # later we want to modify the options
+    #     po.nohuge # Unset the HUGE option
+    #     po.nopedantic # Unset the PEDANTIC option
+    #
+    #   💡 Note that some options begin with "no" leading to the logical but perhaps unintuitive
+    #   double negative:
+    #
+    #     po.nocdata # Set the NOCDATA parse option
+    #     po.nonocdata # Unset the NOCDATA parse option
+    #
+    #   💡 Note that negation is not available for STRICT, which is itself a negation of all other
+    #   features.
+    #
+    #
+    # [Using Ruby Blocks]
+    #
+    #   Most parsing methods will accept a block for configuration of parse options, and we
+    #   recommend chaining the setter methods:
+    #
+    #     doc = Nokogiri::XML::Document.parse(xml) { |config| config.huge.pedantic }
+    #
+    #
+    # [ParseOptions constants]
+    #
+    #   You can also use the constants declared under Nokogiri::XML::ParseOptions to set various
+    #   combinations. They are bits in a bitmask, and so can be combined with bitwise operators:
+    #
+    #     po = Nokogiri::XML::ParseOptions.new(Nokogiri::XML::ParseOptions::HUGE | Nokogiri::XML::ParseOptions::PEDANTIC)
+    #     doc = Nokogiri::XML::Document.parse(xml, nil, nil, po)
     #
     class ParseOptions
       # Strict parsing
       STRICT      = 0
-      # Recover from errors
+
+      # Recover from errors. On by default for XML::Document, XML::DocumentFragment,
+      # HTML4::Document, HTML4::DocumentFragment, XSLT::Stylesheet, and XML::Schema.
       RECOVER     = 1 << 0
-      # Substitute entities
+
+      # Substitute entities. Off by default.
+      #
+      # ⚠ This option enables entity substitution, contrary to what the name implies.
+      #
+      # ⚠ <b>It is UNSAFE to set this option</b> when parsing untrusted documents.
       NOENT       = 1 << 1
-      # Load external subsets
+
+      # Load external subsets. On by default for XSLT::Stylesheet.
+      #
+      # ⚠ <b>It is UNSAFE to set this option</b> when parsing untrusted documents.
       DTDLOAD     = 1 << 2
-      # Default DTD attributes
+
+      # Default DTD attributes. On by default for XSLT::Stylesheet.
       DTDATTR     = 1 << 3
-      # validate with the DTD
+
+      # Validate with the DTD. Off by default.
       DTDVALID    = 1 << 4
-      # suppress error reports
+
+      # Suppress error reports. On by default for HTML4::Document and HTML4::DocumentFragment
       NOERROR     = 1 << 5
-      # suppress warning reports
+
+      # Suppress warning reports. On by default for HTML4::Document and HTML4::DocumentFragment
       NOWARNING   = 1 << 6
-      # pedantic error reporting
+
+      # Enable pedantic error reporting. Off by default.
       PEDANTIC    = 1 << 7
-      # remove blank nodes
+
+      # Remove blank nodes. Off by default.
       NOBLANKS    = 1 << 8
-      # use the SAX1 interface internally
+
+      # Use the SAX1 interface internally. Off by default.
       SAX1        = 1 << 9
-      # Implement XInclude substitution
+
+      # Implement XInclude substitution. Off by default.
       XINCLUDE    = 1 << 10
-      # Forbid network access. Recommended for dealing with untrusted documents.
+
+      # Forbid network access. On by default for XML::Document, XML::DocumentFragment,
+      # HTML4::Document, HTML4::DocumentFragment, XSLT::Stylesheet, and XML::Schema.
+      #
+      # ⚠ <b>It is UNSAFE to unset this option</b> when parsing untrusted documents.
       NONET       = 1 << 11
-      # Do not reuse the context dictionary
+
+      # Do not reuse the context dictionary. Off by default.
       NODICT      = 1 << 12
-      # remove redundant namespaces declarations
+
+      # Remove redundant namespaces declarations. Off by default.
       NSCLEAN     = 1 << 13
-      # merge CDATA as text nodes
+
+      # Merge CDATA as text nodes. On by default for XSLT::Stylesheet.
       NOCDATA     = 1 << 14
-      # do not generate XINCLUDE START/END nodes
+
+      # Do not generate XInclude START/END nodes. Off by default.
       NOXINCNODE  = 1 << 15
-      # compact small text nodes; no modification of the tree allowed afterwards (will possibly crash if you try to modify the tree)
+
+      # Compact small text nodes. Off by default.
+      #
+      # ⚠ No modification of the DOM tree is allowed after parsing. libxml2 may crash if you try to
+      # modify the tree.
       COMPACT     = 1 << 16
-      # parse using XML-1.0 before update 5
+
+      # Parse using XML-1.0 before update 5. Off by default
       OLD10       = 1 << 17
-      # do not fixup XINCLUDE xml:base uris
+
+      # Do not fixup XInclude xml:base uris. Off by default
       NOBASEFIX   = 1 << 18
-      # relax any hardcoded limit from the parser
+
+      # Relax any hardcoded limit from the parser. Off by default.
+      #
+      # ⚠ There may be a performance penalty when this option is set.
       HUGE        = 1 << 19
 
-      # 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
-      DEFAULT_SCHEMA = NONET
+      # Support line numbers up to <code>long int</code> (default is a <code>short int</code>). On
+      # by default for for XML::Document, XML::DocumentFragment, HTML4::Document,
+      # HTML4::DocumentFragment, XSLT::Stylesheet, and XML::Schema.
+      BIG_LINES   = 1 << 22
+
+      # The options mask used by default for parsing XML::Document and XML::DocumentFragment
+      DEFAULT_XML  = RECOVER | NONET | BIG_LINES
+
+      # The options mask used by default used for parsing XSLT::Stylesheet
+      DEFAULT_XSLT = RECOVER | NONET | NOENT | DTDLOAD | DTDATTR | NOCDATA | BIG_LINES
+
+      # The options mask used by default used for parsing HTML4::Document and HTML4::DocumentFragment
+      DEFAULT_HTML = RECOVER | NOERROR | NOWARNING | NONET | BIG_LINES
+
+      # The options mask used by default used for parsing XML::Schema
+      DEFAULT_SCHEMA = NONET | BIG_LINES
 
       attr_accessor :options
-      def initialize options = STRICT
+
+      def initialize(options = STRICT)
         @options = options
       end
 
       constants.each do |constant|
         next if constant.to_sym == :STRICT
-        class_eval %{
+
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
           def #{constant.downcase}
             @options |= #{constant}
             self
@@ -99,7 +183,7 @@ module Nokogiri
           def #{constant.downcase}?
             #{constant} & @options == #{constant}
           end
-        }
+        RUBY
       end
 
       def strict
@@ -115,14 +199,14 @@ module Nokogiri
         other.to_i == to_i
       end
 
-      alias :to_i :options
+      alias_method :to_i, :options
 
       def inspect
         options = []
         self.class.constants.each do |k|
           options << k.downcase if send(:"#{k.downcase}?")
         end
-        super.sub(/>$/, " " + options.join(', ') + ">")
+        super.sub(/>$/, " " + options.join(", ") + ">")
       end
     end
   end