nokogiri 1.10.9 → 1.18.3

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,70 @@
+# 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
+          # 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?)
+          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}:#{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,32 +1,36 @@
+# frozen_string_literal: true
+
 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.
     #
-    # Here is an example of usage:
+    # 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.
     #
-    #   reader = Nokogiri::XML::Reader(<<-eoxml)
-    #     <x xmlns:tenderlove='http://tenderlovemaking.com/'>
-    #       <tenderlove:foo awesome='true'>snuggles!</tenderlove:foo>
-    #     </x>
-    #   eoxml
+    # 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.
     #
-    #   reader.each do |node|
+    # Here is an example of usage:
     #
-    #     # node is an instance of Nokogiri::XML::Reader
-    #     puts node.name
+    #     reader = Nokogiri::XML::Reader.new <<~XML
+    #       <x xmlns:tenderlove='http://tenderlovemaking.com/'>
+    #         <tenderlove:foo awesome='true'>snuggles!</tenderlove:foo>
+    #       </x>
+    #     XML
     #
-    #   end
+    #     reader.each do |node|
+    #       # node is an instance of Nokogiri::XML::Reader
+    #       puts node.name
+    #     end
     #
-    # Note that Nokogiri::XML::Reader#each can only be called once!!  Once
-    # the cursor moves through the entire document, you must parse the
-    # document again.  So make sure that you capture any information you
-    # need during the first iteration.
+    # ⚠ 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.
     #
-    # The Reader parser is good for when you need the speed of a SAX parser,
-    # but do not want to write a Document handler.
+    # ⚠ 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
 
@@ -63,47 +67,70 @@ 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 encoding for the document
-      attr_reader :encoding
-
-      # The XML source
+      # The \XML source
       attr_reader :source
 
-      alias :self_closing? :empty_element?
+      alias_method :self_closing?, :empty_element?
+
+      # :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
 
-      def initialize source, url = nil, encoding = nil # :nodoc:
+        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 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,32 +1,75 @@
+# 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)
+      # :call-seq:
+      #   RelaxNG(input) → Nokogiri::XML::RelaxNG
+      #   RelaxNG(input, options:) → Nokogiri::XML::RelaxNG
+      #
+      # Convenience method for Nokogiri::XML::RelaxNG.new
+      def RelaxNG(...)
+        RelaxNG.new(...)
       end
     end
 
-    ###
-    # Nokogiri::XML::RelaxNG is used for validating XML against a
-    # RelaxNG schema.
+    # Nokogiri::XML::RelaxNG is used for validating \XML against a RELAX NG schema definition.
+    #
+    # 🛡 <b>Do not use this class for untrusted schema documents.</b> RELAX NG input is always
+    # treated as *trusted*, meaning that the underlying parsing libraries <b>will access network
+    # resources</b>. This is counter to Nokogiri's "untrusted by default" security policy, but is an
+    # unfortunate limitation of the underlying libraries.
+    #
+    # *Example:* Determine whether an \XML document is valid.
+    #
+    #   schema = Nokogiri::XML::RelaxNG.new(File.read(RELAX_NG_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   schema.valid?(doc) # Boolean
     #
-    # == Synopsis
+    # *Example:* Validate an \XML document against a \RelaxNG schema, and capture any errors that are found.
     #
-    # Validate an XML document against a RelaxNG schema.  Loop over the errors
-    # that are returned and print them out:
+    #   schema = Nokogiri::XML::RelaxNG.new(File.open(RELAX_NG_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.open(XML_FILE))
+    #   errors = schema.validate(doc) # Array<SyntaxError>
     #
-    #   schema  = Nokogiri::XML::RelaxNG(File.open(ADDRESS_SCHEMA_FILE))
-    #   doc     = Nokogiri::XML(File.open(ADDRESS_XML_FILE))
+    # *Example:* Validate an \XML document using a Document containing a RELAX NG schema definition.
     #
-    #   schema.validate(doc).each do |error|
-    #     puts error.message
-    #   end
+    #   schema_doc = Nokogiri::XML::Document.parse(File.read(RELAX_NG_FILE))
+    #   schema = Nokogiri::XML::RelaxNG.from_document(schema_doc)
+    #   doc = Nokogiri::XML::Document.parse(File.open(XML_FILE))
+    #   schema.valid?(doc) # Boolean
     #
-    # The list of errors are Nokogiri::XML::SyntaxError objects.
     class RelaxNG < Nokogiri::XML::Schema
+      # :call-seq:
+      #   new(input) → Nokogiri::XML::RelaxNG
+      #   new(input, options:) → Nokogiri::XML::RelaxNG
+      #
+      # Parse a RELAX NG schema definition from a String or IO to create a new Nokogiri::XML::RelaxNG.
+      #
+      # [Parameters]
+      # - +input+ (String | IO) RELAX NG schema definition
+      # - +options:+ (Nokogiri::XML::ParseOptions)
+      #   Defaults to Nokogiri::XML::ParseOptions::DEFAULT_SCHEMA ⚠ Unused
+      #
+      # [Returns] Nokogiri::XML::RelaxNG
+      #
+      # ⚠ +parse_options+ is currently unused by this method and is present only as a placeholder for
+      # future functionality.
+      #
+      # Also see convenience method Nokogiri::XML::RelaxNG()
+      def self.new(input, parse_options_ = ParseOptions::DEFAULT_SCHEMA, options: parse_options_)
+        from_document(Nokogiri::XML::Document.parse(input), options)
+      end
+
+      # :call-seq:
+      #   read_memory(input) → Nokogiri::XML::RelaxNG
+      #   read_memory(input, options:) → Nokogiri::XML::RelaxNG
+      #
+      # Convenience method for Nokogiri::XML::RelaxNG.new.
+      def self.read_memory(...)
+        # TODO deprecate this method
+        new(...)
+      end
     end
   end
 end