nokogiri 1.16.3 → 1.18.1

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

@@ -4,15 +4,123 @@ module Nokogiri
   module XML
     module SAX
       ###
-      # Context for XML SAX parsers.  This class is usually not instantiated
-      # by the user.  Instead, you should be looking at
-      # Nokogiri::XML::SAX::Parser
+      # Context object to invoke the XML SAX parser on the SAX::Document handler.
+      #
+      # 💡 This class is usually not instantiated by the user. Use Nokogiri::XML::SAX::Parser
+      # instead.
       class ParserContext
-        def self.new(thing, encoding = "UTF-8")
-          if [:read, :close].all? { |x| thing.respond_to?(x) }
-            io(thing, Parser::ENCODINGS[encoding])
-          else
-            memory(thing)
+        class << self
+          ###
+          # :call-seq:
+          #   new(input)
+          #   new(input, encoding)
+          #
+          # Create a parser context for an IO or a String. This is a shorthand method for
+          # ParserContext.io and ParserContext.memory.
+          #
+          # [Parameters]
+          # - +input+ (IO, String) A String or a readable IO object
+          # - +encoding+ (optional) (Encoding) The +Encoding+ to use, or the name of an
+          #   encoding to use (default +nil+, encoding will be autodetected)
+          #
+          # If +input+ quacks like a readable IO object, this method forwards to ParserContext.io,
+          # otherwise it forwards to ParserContext.memory.
+          #
+          # [Returns] Nokogiri::XML::SAX::ParserContext
+          #
+          def new(input, encoding = nil)
+            if [:read, :close].all? { |x| input.respond_to?(x) }
+              io(input, encoding)
+            else
+              memory(input, encoding)
+            end
+          end
+
+          ###
+          # :call-seq:
+          #   io(input)
+          #   io(input, encoding)
+          #
+          # Create a parser context for an +input+ IO which will assume +encoding+
+          #
+          # [Parameters]
+          # - +io+ (IO) The readable IO object from which to read input
+          # - +encoding+ (optional) (Encoding) The +Encoding+ to use, or the name of an
+          #   encoding to use (default +nil+, encoding will be autodetected)
+          #
+          # [Returns] Nokogiri::XML::SAX::ParserContext
+          #
+          # 💡 Calling this method directly is discouraged. Use Nokogiri::XML::SAX::Parser parse
+          # methods which are more convenient for most use cases.
+          #
+          def io(input, encoding = nil)
+            native_io(input, resolve_encoding(encoding))
+          end
+
+          ###
+          # :call-seq:
+          #   memory(input)
+          #   memory(input, encoding)
+          #
+          # Create a parser context for the +input+ String.
+          #
+          # [Parameters]
+          # - +input+ (String) The input string to be parsed.
+          # - +encoding+ (optional) (Encoding, String) The +Encoding+ to use, or the name of an encoding to
+          #   use (default +nil+, encoding will be autodetected)
+          #
+          # [Returns] Nokogiri::XML::SAX::ParserContext
+          #
+          # 💡 Calling this method directly is discouraged. Use Nokogiri::XML::SAX::Parser parse methods
+          # which are more convenient for most use cases.
+          #
+          def memory(input, encoding = nil)
+            native_memory(input, resolve_encoding(encoding))
+          end
+
+          ###
+          # :call-seq:
+          #   file(path)
+          #   file(path, encoding)
+          #
+          # Create a parser context for the file at +path+.
+          #
+          # [Parameters]
+          # - +path+ (String) The path to the input file
+          # - +encoding+ (optional) (Encoding, String) The +Encoding+ to use, or the name of an encoding to
+          #   use (default +nil+, encoding will be autodetected)
+          #
+          # [Returns] Nokogiri::XML::SAX::ParserContext
+          #
+          # 💡 Calling this method directly is discouraged. Use Nokogiri::XML::SAX::Parser.parse_file which
+          # is more convenient for most use cases.
+          def file(input, encoding = nil)
+            native_file(input, resolve_encoding(encoding))
+          end
+
+          private def resolve_encoding(encoding)
+            case encoding
+            when Encoding
+              encoding
+
+            when nil
+              nil # totally fine, parser will guess encoding
+
+            when Integer
+              warn("Passing an integer to Nokogiri::XML::SAX::ParserContext.io is deprecated. Use an Encoding object instead. This will become an error in a future release.", uplevel: 2, category: :deprecated)
+
+              return nil if encoding == Parser::ENCODINGS["NONE"]
+
+              encoding = Parser::REVERSE_ENCODINGS[encoding]
+              raise ArgumentError, "Invalid libxml2 encoding id #{encoding}" if encoding.nil?
+              Encoding.find(encoding)
+
+            when String
+              Encoding.find(encoding)
+
+            else
+              raise ArgumentError, "Cannot resolve #{encoding.inspect} to an Encoding"
+            end
           end
         end
       end

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

@@ -52,6 +52,9 @@ module Nokogiri
         ###
         # Finish the parsing.  This method is only necessary for
         # Nokogiri::XML::SAX::Document#end_document to be called.
+        #
+        # ⚠ Note that empty documents are treated as an error when using the libxml2-based
+        # implementation (CRuby), but are fine when using the Xerces-based implementation (JRuby).
         def finish
           write("", true)
         end

data/lib/nokogiri/xml/sax.rb

@@ -1,5 +1,53 @@
 # frozen_string_literal: true
 
+module Nokogiri
+  module XML
+    ###
+    # SAX Parsers are event-driven parsers.
+    #
+    # 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 you explicitly feed XML in chunks. 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.
+    #
+    # If you want to do SAX style parsing of 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.
+    #
+    # To register for events, 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:
+    #
+    #   class MyHandler < Nokogiri::XML::SAX::Document
+    #     def end_document
+    #       puts "the document has ended"
+    #     end
+    #
+    #     def start_element name, attributes = []
+    #       puts "#{name} started"
+    #     end
+    #   end
+    #
+    # 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(MyHandler.new)
+    #
+    #   # 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.
+    #
+    module SAX
+    end
+  end
+end
+
 require_relative "sax/document"
 require_relative "sax/parser_context"
 require_relative "sax/parser"

data/lib/nokogiri/xml/schema.rb

@@ -3,70 +3,137 @@
 module Nokogiri
   module XML
     class << self
-      ###
-      # Create a new Nokogiri::XML::Schema object using a +string_or_io+
-      # object.
-      def Schema(string_or_io, options = ParseOptions::DEFAULT_SCHEMA)
-        Schema.new(string_or_io, options)
+      # :call-seq:
+      #   Schema(input) → Nokogiri::XML::Schema
+      #   Schema(input, parse_options) → Nokogiri::XML::Schema
+      #
+      # Convenience method for Nokogiri::XML::Schema.new
+      def Schema(...)
+        Schema.new(...)
       end
     end
 
-    ###
-    # Nokogiri::XML::Schema is used for validating XML against a schema
-    # (usually from an xsd file).
+    # Nokogiri::XML::Schema is used for validating \XML against an \XSD schema definition.
     #
-    # == Synopsis
+    # ⚠ Since v1.11.0, Schema treats inputs as *untrusted* by default, and so external entities are
+    # not resolved from the network (+http://+ or +ftp://+). When parsing a trusted document, the
+    # caller may turn off the +NONET+ option via the ParseOptions to (re-)enable external entity
+    # resolution over a network connection.
     #
-    # Validate an XML document against a Schema.  Loop over the errors that
-    # are returned and print them out:
+    # 🛡 Before v1.11.0, documents were "trusted" by default during schema parsing which was counter
+    # to Nokogiri's "untrusted by default" security policy.
     #
-    #   xsd = Nokogiri::XML::Schema(File.read(PO_SCHEMA_FILE))
-    #   doc = Nokogiri::XML(File.read(PO_XML_FILE))
+    # *Example:* Determine whether an \XML document is valid.
     #
-    #   xsd.validate(doc).each do |error|
-    #     puts error.message
-    #   end
+    #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   schema.valid?(doc) # Boolean
     #
-    # The list of errors are Nokogiri::XML::SyntaxError objects.
+    # *Example:* Validate an \XML document against an \XSD schema, and capture any errors that are found.
+    #
+    #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   errors = schema.validate(doc) # Array<SyntaxError>
+    #
+    # *Example:* Validate an \XML document using a Document containing an \XSD schema definition.
+    #
+    #   schema_doc = Nokogiri::XML::Document.parse(File.read(RELAX_NG_FILE))
+    #   schema = Nokogiri::XML::Schema.from_document(schema_doc)
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   schema.valid?(doc) # Boolean
     #
-    # NOTE: As of v1.11.0, Schema treats inputs as UNTRUSTED by default, and so external entities
-    # are not resolved from the network (`http://` or `ftp://`). Previously, parsing treated
-    # documents as "trusted" by default which was counter to Nokogiri's "untrusted by default"
-    # security policy. If a document is trusted, then the caller may turn off the NONET option via
-    # the ParseOptions to re-enable external entity resolution over a network connection.
     class Schema
-      # Errors while parsing the schema file
+      # The errors found while parsing the \XSD
+      #
+      # [Returns] Array<Nokogiri::XML::SyntaxError>
       attr_accessor :errors
-      # The Nokogiri::XML::ParseOptions used to parse the schema
+
+      # The options used to parse the schema
+      #
+      # [Returns] Nokogiri::XML::ParseOptions
       attr_accessor :parse_options
 
-      ###
-      # Create a new Nokogiri::XML::Schema object using a +string_or_io+
-      # object.
-      def self.new(string_or_io, options = ParseOptions::DEFAULT_SCHEMA)
-        from_document(Nokogiri::XML(string_or_io), options)
+      # :call-seq:
+      #   new(input) → Nokogiri::XML::Schema
+      #   new(input, parse_options) → Nokogiri::XML::Schema
+      #
+      # Parse an \XSD schema definition from a String or IO to create a new Nokogiri::XML::Schema
+      #
+      # [Parameters]
+      # - +input+ (String | IO) \XSD schema definition
+      # - +parse_options+ (Nokogiri::XML::ParseOptions)
+      #   Defaults to Nokogiri::XML::ParseOptions::DEFAULT_SCHEMA
+      #
+      # [Returns] Nokogiri::XML::Schema
+      #
+      def self.new(input, parse_options_ = ParseOptions::DEFAULT_SCHEMA, parse_options: parse_options_)
+        from_document(Nokogiri::XML::Document.parse(input), parse_options)
+      end
+
+      # :call-seq:
+      #   read_memory(input) → Nokogiri::XML::Schema
+      #   read_memory(input, parse_options) → Nokogiri::XML::Schema
+      #
+      # Convenience method for Nokogiri::XML::Schema.new
+      def self.read_memory(...)
+        # TODO deprecate this method
+        new(...)
       end
 
-      ###
-      # Validate +thing+ against this schema.  +thing+ can be a
-      # Nokogiri::XML::Document object, or a filename.  An Array of
-      # Nokogiri::XML::SyntaxError objects found while validating the
-      # +thing+ is returned.
-      def validate(thing)
-        if thing.is_a?(Nokogiri::XML::Document)
-          validate_document(thing)
-        elsif File.file?(thing)
-          validate_file(thing)
+      #
+      # :call-seq: validate(input) → Array<SyntaxError>
+      #
+      # Validate +input+ and return any errors that are found.
+      #
+      # [Parameters]
+      # - +input+ (Nokogiri::XML::Document | String)
+      #   A parsed document, or a string containing a local filename.
+      #
+      # [Returns] Array<SyntaxError>
+      #
+      # *Example:* Validate an existing XML::Document, and capture any errors that are found.
+      #
+      #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+      #   errors = schema.validate(document)
+      #
+      # *Example:* Validate an \XML document on disk, and capture any errors that are found.
+      #
+      #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+      #   errors = schema.validate("/path/to/file.xml")
+      #
+      def validate(input)
+        if input.is_a?(Nokogiri::XML::Document)
+          validate_document(input)
+        elsif File.file?(input)
+          validate_file(input)
         else
-          raise ArgumentError, "Must provide Nokogiri::Xml::Document or the name of an existing file"
+          raise ArgumentError, "Must provide Nokogiri::XML::Document or the name of an existing file"
         end
       end
 
-      ###
-      # Returns true if +thing+ is a valid Nokogiri::XML::Document or
-      # file.
-      def valid?(thing)
-        validate(thing).empty?
+      #
+      # :call-seq: valid?(input) → Boolean
+      #
+      # Validate +input+ and return a Boolean indicating whether the document is valid
+      #
+      # [Parameters]
+      # - +input+ (Nokogiri::XML::Document | String)
+      #   A parsed document, or a string containing a local filename.
+      #
+      # [Returns] Boolean
+      #
+      # *Example:* Validate an existing XML::Document
+      #
+      #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+      #   return unless schema.valid?(document)
+      #
+      # *Example:* Validate an \XML document on disk
+      #
+      #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+      #   return unless schema.valid?("/path/to/file.xml")
+      #
+      def valid?(input)
+        validate(input).empty?
       end
     end
   end

data/lib/nokogiri/xml/searchable.rb

@@ -207,35 +207,26 @@ module Nokogiri
 
       private
 
-      def css_internal(node, rules, handler, ns)
-        xpath_internal(node, css_rules_to_xpath(rules, ns), handler, ns, nil)
-      end
-
-      def xpath_internal(node, paths, handler, ns, binds)
-        document = node.document
-        return NodeSet.new(document) unless document
-
-        if paths.length == 1
-          return xpath_impl(node, paths.first, handler, ns, binds)
+      def extract_params(params) # :nodoc:
+        handler = params.find do |param|
+          ![Hash, String, Symbol].include?(param.class)
         end
+        params -= [handler] if handler
 
-        NodeSet.new(document) do |combined|
-          paths.each do |path|
-            xpath_impl(node, path, handler, ns, binds).each { |set| combined << set }
-          end
+        hashes = []
+        while Hash === params.last || params.last.nil?
+          hashes << params.pop
+          break if params.empty?
         end
-      end
+        ns, binds = hashes.reverse
 
-      def xpath_impl(node, path, handler, ns, binds)
-        ctx = XPathContext.new(node)
-        ctx.register_namespaces(ns)
-        path = path.gsub("xmlns:", " :") unless Nokogiri.uses_libxml?
+        ns ||= document.root&.namespaces || {}
 
-        binds&.each do |key, value|
-          ctx.register_variable(key.to_s, value)
-        end
+        [params, handler, ns, binds]
+      end
 
-        ctx.evaluate(path, handler)
+      def css_internal(node, rules, handler, ns)
+        xpath_internal(node, css_rules_to_xpath(rules, ns), handler, ns, nil)
       end
 
       def css_rules_to_xpath(rules, ns)
@@ -243,35 +234,40 @@ module Nokogiri
       end
 
       def xpath_query_from_css_rule(rule, ns)
-        visitor = Nokogiri::CSS::XPathVisitor.new(
-          builtins: Nokogiri::CSS::XPathVisitor::BuiltinsConfig::OPTIMAL,
-          doctype: document.xpath_doctype,
-        )
         self.class::IMPLIED_XPATH_CONTEXTS.map do |implied_xpath_context|
-          CSS.xpath_for(rule.to_s, {
+          visitor = Nokogiri::CSS::XPathVisitor.new(
+            builtins: Nokogiri::CSS::XPathVisitor::BuiltinsConfig::OPTIMAL,
+            doctype: document.xpath_doctype,
             prefix: implied_xpath_context,
-            ns: ns,
-            visitor: visitor,
-          })
+            namespaces: ns,
+          )
+          CSS.xpath_for(rule.to_s, visitor: visitor)
         end.join(" | ")
       end
 
-      def extract_params(params) # :nodoc:
-        handler = params.find do |param|
-          ![Hash, String, Symbol].include?(param.class)
+      def xpath_internal(node, paths, handler, ns, binds)
+        document = node.document
+        return NodeSet.new(document) unless document
+
+        if paths.length == 1
+          return xpath_impl(node, paths.first, handler, ns, binds)
         end
-        params -= [handler] if handler
 
-        hashes = []
-        while Hash === params.last || params.last.nil?
-          hashes << params.pop
-          break if params.empty?
+        NodeSet.new(document) do |combined|
+          paths.each do |path|
+            xpath_impl(node, path, handler, ns, binds).each { |set| combined << set }
+          end
         end
-        ns, binds = hashes.reverse
+      end
 
-        ns ||= document.root&.namespaces || {}
+      def xpath_impl(node, path, handler, ns, binds)
+        context = XPathContext.new(node)
+        context.register_namespaces(ns)
+        context.register_variables(binds)
 
-        [params, handler, ns, binds]
+        path = path.gsub("xmlns:", " :") unless Nokogiri.uses_libxml?
+
+        context.evaluate(path, handler)
       end
     end
   end

data/lib/nokogiri/xml/syntax_error.rb

@@ -6,11 +6,33 @@ module Nokogiri
     # This class provides information about XML SyntaxErrors.  These
     # exceptions are typically stored on Nokogiri::XML::Document#errors.
     class SyntaxError < ::Nokogiri::SyntaxError
+      class << self
+        def aggregate(errors)
+          return nil if errors.empty?
+          return errors.first if errors.length == 1
+
+          messages = ["Multiple errors encountered:"]
+          errors.each do |error|
+            messages << error.to_s
+          end
+          new(messages.join("\n"))
+        end
+      end
+
       attr_reader :domain
       attr_reader :code
       attr_reader :level
       attr_reader :file
       attr_reader :line
+
+      # The XPath path of the node that caused the error when validating a `Nokogiri::XML::Document`.
+      #
+      # This attribute will only be non-nil when the error is emitted by `Schema#validate` on
+      # Document objects. It will return `nil` for DOM parsing errors and for errors emitted during
+      # Schema validation of files.
+      #
+      # ⚠ `#path` is not supported on JRuby, where it will always return `nil`.
+      attr_reader :path
       attr_reader :str1
       attr_reader :str2
       attr_reader :str3

data/lib/nokogiri/xml/xpath_context.rb

@@ -6,9 +6,20 @@ module Nokogiri
       ###
       # Register namespaces in +namespaces+
       def register_namespaces(namespaces)
-        namespaces.each do |k, v|
-          k = k.to_s.gsub(/.*:/, "") # strip off 'xmlns:' or 'xml:'
-          register_ns(k, v)
+        namespaces.each do |key, value|
+          key = key.to_s.gsub(/.*:/, "") # strip off 'xmlns:' or 'xml:'
+
+          register_ns(key, value)
+        end
+      end
+
+      def register_variables(binds)
+        return if binds.nil?
+
+        binds.each do |key, value|
+          key = key.to_s
+
+          register_variable(key, value)
         end
       end
     end

data/lib/nokogiri/xml.rb

@@ -2,10 +2,9 @@
 
 module Nokogiri
   class << self
-    ###
-    # Parse XML.  Convenience method for Nokogiri::XML::Document.parse
-    def XML(thing, url = nil, encoding = nil, options = XML::ParseOptions::DEFAULT_XML, &block)
-      Nokogiri::XML::Document.parse(thing, url, encoding, options, &block)
+    # Convenience method for Nokogiri::XML::Document.parse
+    def XML(...)
+      Nokogiri::XML::Document.parse(...)
     end
   end
 
@@ -16,31 +15,21 @@ module Nokogiri
     XML_C14N_EXCLUSIVE_1_0 = 1
     # C14N 1.1 spec canonicalization
     XML_C14N_1_1 = 2
-    class << self
-      ###
-      # Parse an XML document using the Nokogiri::XML::Reader API.  See
-      # Nokogiri::XML::Reader for mor information
-      def Reader(string_or_io, url = nil, encoding = nil, options = ParseOptions::STRICT)
-        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
 
-        Reader.from_memory(string_or_io, url, encoding, options.to_i)
+    class << self
+      # Convenience method for Nokogiri::XML::Reader.new
+      def Reader(...)
+        Reader.new(...)
       end
 
-      ###
-      # Parse XML.  Convenience method for Nokogiri::XML::Document.parse
-      def parse(thing, url = nil, encoding = nil, options = ParseOptions::DEFAULT_XML, &block)
-        Document.parse(thing, url, encoding, options, &block)
+      # Convenience method for Nokogiri::XML::Document.parse
+      def parse(...)
+        Document.parse(...)
       end
 
-      ####
-      # Parse a fragment from +string+ in to a NodeSet.
-      def fragment(string, options = ParseOptions::DEFAULT_XML, &block)
-        XML::DocumentFragment.parse(string, options, &block)
+      # Convenience method for Nokogiri::XML::DocumentFragment.parse
+      def fragment(...)
+        XML::DocumentFragment.parse(...)
       end
     end
   end

data/lib/nokogiri/xslt.rb

@@ -3,15 +3,9 @@
 
 module Nokogiri
   class << self
-    ###
-    # Create a Nokogiri::XSLT::Stylesheet with +stylesheet+.
-    #
-    # Example:
-    #
-    #   xslt = Nokogiri::XSLT(File.read(ARGV[0]))
-    #
-    def XSLT(stylesheet, modules = {})
-      XSLT.parse(stylesheet, modules)
+    # Convenience method for Nokogiri::XSLT.parse
+    def XSLT(...)
+      XSLT.parse(...)
     end
   end
 

data/lib/xsd/xmlparser/nokogiri.rb

@@ -7,10 +7,9 @@ module XSD
     ###
     # Nokogiri XML parser for soap4r.
     #
-    # Nokogiri may be used as the XML parser in soap4r.  Simply require
-    # 'xsd/xmlparser/nokogiri' in your soap4r applications, and soap4r
-    # will use Nokogiri as it's XML parser.  No other changes should be
-    # required to use Nokogiri as the XML parser.
+    # Nokogiri may be used as the XML parser in soap4r. Require 'xsd/xmlparser/nokogiri' in your
+    # soap4r applications, and soap4r will use Nokogiri as its XML parser. No other changes should
+    # be required to use Nokogiri as the XML parser.
     #
     # Example (using UW ITS Web Services):
     #