nokogiri 1.9.1 → 1.15.3

data/lib/nokogiri/xml/parse_options.rb

@@ -1,86 +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. All examples use Ruby 2 optional parameter syntax.
-    # [Ruby's bitwise operators] You can use the Ruby bitwise operators to set various combinations.
-    #   Nokogiri.XML('<content>Chapter 1</content', options: 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', options: 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 HTML documents
-      DEFAULT_HTML = RECOVER | NOERROR | NOWARNING | 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
@@ -94,7 +183,7 @@ module Nokogiri
           def #{constant.downcase}?
             #{constant} & @options == #{constant}
           end
-        }
+        RUBY
       end
 
       def strict
@@ -106,14 +195,18 @@ module Nokogiri
         @options & RECOVER == STRICT
       end
 
-      alias :to_i :options
+      def ==(other)
+        other.to_i == to_i
+      end
+
+      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

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

@@ -1,16 +1,19 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
+    # :nodoc: all
     module PP
       module CharacterData
-        def pretty_print pp # :nodoc:
-          nice_name = self.class.name.split('::').last
-          pp.group(2, "#(#{nice_name} ", ')') do
-            pp.pp text
+        def pretty_print(pp)
+          nice_name = self.class.name.split("::").last
+          pp.group(2, "#(#{nice_name} ", ")") do
+            pp.pp(text)
           end
         end
 
-        def inspect # :nodoc:
-          "#<#{self.class.name}:#{sprintf("0x%x",object_id)} #{text.inspect}>"
+        def inspect
+          "#<#{self.class.name}:#{format("0x%x", object_id)} #{text.inspect}>"
         end
       end
     end

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

@@ -1,53 +1,65 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
+    # :nodoc: all
     module PP
       module Node
-        def inspect # :nodoc:
-          attributes = inspect_attributes.reject { |x|
-            begin
-              attribute = send x
-              !attribute || (attribute.respond_to?(:empty?) && attribute.empty?)
-            rescue NoMethodError
-              true
-            end
-          }.map { |attribute|
-            "#{attribute.to_s.sub(/_\w+/, 's')}=#{send(attribute).inspect}"
-          }.join ' '
-          "#<#{self.class.name}:#{sprintf("0x%x", object_id)} #{attributes}>"
-        end
+        COLLECTIONS = [:attribute_nodes, :children]
 
-        def pretty_print pp # :nodoc:
-          nice_name = self.class.name.split('::').last
-          pp.group(2, "#(#{nice_name}:#{sprintf("0x%x", object_id)} {", '})') do
+        def inspect
+          attributes = inspect_attributes.reject do |x|
+            attribute = send(x)
+            !attribute || (attribute.respond_to?(:empty?) && attribute.empty?)
+          rescue NoMethodError
+            true
+          end
+          attributes = if inspect_attributes.length == 1
+            send(attributes.first).inspect
+          else
+            attributes.map do |attribute|
+              "#{attribute}=#{send(attribute).inspect}"
+            end.join(" ")
+          end
+          "#<#{self.class.name}:#{format("0x%x", object_id)} #{attributes}>"
+        end
 
+        def pretty_print(pp)
+          nice_name = self.class.name.split("::").last
+          pp.group(2, "#(#{nice_name}:#{format("0x%x", object_id)} {", "})") do
             pp.breakable
-            attrs = inspect_attributes.map { |t|
+
+            attrs = inspect_attributes.filter_map do |t|
               [t, send(t)] if respond_to?(t)
-            }.compact.find_all { |x|
+            end.find_all do |x|
               if x.last
-                if [:attribute_nodes, :children].include? x.first
+                if COLLECTIONS.include?(x.first)
                   !x.last.empty?
                 else
                   true
                 end
               end
-            }
+            end
 
-            pp.seplist(attrs) do |v|
-              if [:attribute_nodes, :children].include? v.first
-                pp.group(2, "#{v.first.to_s.sub(/_\w+$/, 's')} = [", "]") do
-                  pp.breakable
-                  pp.seplist(v.last) do |item|
-                    pp.pp item
+            if inspect_attributes.length == 1
+              pp.pp(attrs.first.last)
+            else
+              pp.seplist(attrs) do |v|
+                if COLLECTIONS.include?(v.first)
+                  pp.group(2, "#{v.first} = [", "]") do
+                    pp.breakable
+                    pp.seplist(v.last) do |item|
+                      pp.pp(item)
+                    end
                   end
+                else
+                  pp.text("#{v.first} = ")
+                  pp.pp(v.last)
                 end
-              else
-                pp.text "#{v.first} = "
-                pp.pp v.last
               end
             end
-            pp.breakable
 
+            pp.breakable
           end
         end
       end

data/lib/nokogiri/xml/pp.rb

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

data/lib/nokogiri/xml/processing_instruction.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class ProcessingInstruction < Node
-      def initialize document, name, content
+      def initialize(document, name, content)
+        super(document, name)
       end
     end
   end

data/lib/nokogiri/xml/reader.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     ###
@@ -7,18 +9,18 @@ module Nokogiri
     #
     # Here is an example of usage:
     #
-    #   reader = Nokogiri::XML::Reader(<<-eoxml)
-    #     <x xmlns:tenderlove='http://tenderlovemaking.com/'>
-    #       <tenderlove:foo awesome='true'>snuggles!</tenderlove:foo>
-    #     </x>
-    #   eoxml
+    #     reader = Nokogiri::XML::Reader(<<-eoxml)
+    #       <x xmlns:tenderlove='http://tenderlovemaking.com/'>
+    #         <tenderlove:foo awesome='true'>snuggles!</tenderlove:foo>
+    #       </x>
+    #     eoxml
     #
-    #   reader.each do |node|
+    #     reader.each do |node|
     #
-    #     # node is an instance of Nokogiri::XML::Reader
-    #     puts node.name
+    #       # node is an instance of Nokogiri::XML::Reader
+    #       puts node.name
     #
-    #   end
+    #     end
     #
     # Note that Nokogiri::XML::Reader#each can only be called once!!  Once
     # the cursor moves through the entire document, you must parse the
@@ -69,41 +71,32 @@ module Nokogiri
       # A list of errors encountered while parsing
       attr_accessor :errors
 
-      # The encoding for the document
-      attr_reader :encoding
-
       # The XML source
       attr_reader :source
 
-      alias :self_closing? :empty_element?
+      alias_method :self_closing?, :empty_element?
 
-      def initialize source, url = nil, encoding = nil # :nodoc:
+      def initialize(source, url = nil, encoding = nil) # :nodoc:
         @source   = source
         @errors   = []
         @encoding = encoding
       end
       private :initialize
 
-      ###
-      # Get a list of attributes for the current node.
+      # Get the attributes and namespaces of the current node as a Hash.
+      #
+      # This is the union of Reader#attribute_hash and Reader#namespaces
+      #
+      # [Returns]
+      #   (Hash<String, String>) Attribute names and values, and namespace prefixes and hrefs.
       def attributes
-        Hash[attribute_nodes.map { |node|
-          [node.name, node.to_s]
-        }].merge(namespaces || {})
-      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
+        attribute_hash.merge(namespaces)
       end
 
       ###
       # Move the cursor through the document yielding the cursor to the block
       def each
-        while cursor = self.read
+        while (cursor = read)
           yield cursor
         end
       end

data/lib/nokogiri/xml/relax_ng.rb

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class << self
       ###
       # Create a new Nokogiri::XML::RelaxNG document from +string_or_io+.
       # See Nokogiri::XML::RelaxNG for an example.
-      def RelaxNG string_or_io
-        RelaxNG.new(string_or_io)
+      def RelaxNG(string_or_io, options = ParseOptions::DEFAULT_SCHEMA)
+        RelaxNG.new(string_or_io, options)
       end
     end
 
@@ -26,6 +28,10 @@ module Nokogiri
     #   end
     #
     # The list of errors are Nokogiri::XML::SyntaxError objects.
+    #
+    # NOTE: RelaxNG input is always treated as TRUSTED documents, meaning that they will cause the
+    # underlying parsing libraries to access network resources. This is counter to Nokogiri's
+    # "untrusted by default" security policy, but is a limitation of the underlying libraries.
     class RelaxNG < Nokogiri::XML::Schema
     end
   end