nokogiri 1.10.9 → 1.18.3

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

@@ -1,14 +1,127 @@
+# frozen_string_literal: true
+
 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'
-          [:read, :close].all? { |x| thing.respond_to?(x) } ?
-            io(thing, Parser::ENCODINGS[encoding]) : 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
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     module SAX
@@ -23,7 +25,6 @@ module Nokogiri
       #   parser << "/div>"
       #   parser.finish
       class PushParser
-
         # The Nokogiri::XML::SAX::Document on which the PushParser will be
         # operating
         attr_accessor :document
@@ -31,7 +32,7 @@ module Nokogiri
         ###
         # Create a new PushParser with +doc+ as the SAX Document, providing
         # an optional +file_name+ and +encoding+
-        def initialize(doc = XML::SAX::Document.new, file_name = nil, encoding = 'UTF-8')
+        def initialize(doc = XML::SAX::Document.new, file_name = nil, encoding = "UTF-8")
           @document = doc
           @encoding = encoding
           @sax_parser = XML::SAX::Parser.new(doc)
@@ -43,16 +44,19 @@ module Nokogiri
         ###
         # Write a +chunk+ of XML to the PushParser.  Any callback methods
         # that can be called will be called immediately.
-        def write chunk, last_chunk = false
+        def write(chunk, last_chunk = false)
           native_write(chunk, last_chunk)
         end
-        alias :<< :write
+        alias_method :<<, :write
 
         ###
         # 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
+          write("", true)
         end
       end
     end

data/lib/nokogiri/xml/sax.rb

@@ -1,4 +1,54 @@
-require 'nokogiri/xml/sax/document'
-require 'nokogiri/xml/sax/parser_context'
-require 'nokogiri/xml/sax/parser'
-require 'nokogiri/xml/sax/push_parser'
+# 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"
+require_relative "sax/push_parser"

data/lib/nokogiri/xml/schema.rb

@@ -1,62 +1,139 @@
+# frozen_string_literal: true
+
 module Nokogiri
   module XML
     class << self
-      ###
-      # Create a new Nokogiri::XML::Schema object using a +string_or_io+
-      # object.
-      def Schema string_or_io
-        Schema.new(string_or_io)
+      # :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.
+    #
+    # ⚠ 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.
+    #
+    # 🛡 Before v1.11.0, documents were "trusted" by default during schema parsing which was counter
+    # to Nokogiri's "untrusted by default" security policy.
+    #
+    # *Example:* Determine whether an \XML document is valid.
     #
-    # == Synopsis
+    #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   schema.valid?(doc) # Boolean
     #
-    # Validate an XML document against a Schema.  Loop over the errors that
-    # are returned and print them out:
+    # *Example:* Validate an \XML document against an \XSD schema, and capture any errors that are found.
     #
-    #   xsd = Nokogiri::XML::Schema(File.read(PO_SCHEMA_FILE))
-    #   doc = Nokogiri::XML(File.read(PO_XML_FILE))
+    #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   errors = schema.validate(doc) # Array<SyntaxError>
     #
-    #   xsd.validate(doc).each do |error|
-    #     puts error.message
-    #   end
+    # *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
     #
-    # The list of errors are Nokogiri::XML::SyntaxError objects.
     class Schema
-      # Errors while parsing the schema file
+      # The errors found while parsing the \XSD
+      #
+      # [Returns] Array<Nokogiri::XML::SyntaxError>
       attr_accessor :errors
 
-      ###
-      # Create a new Nokogiri::XML::Schema object using a +string_or_io+
-      # object.
-      def self.new string_or_io
-        from_document Nokogiri::XML(string_or_io)
+      # The options used to parse the schema
+      #
+      # [Returns] Nokogiri::XML::ParseOptions
+      attr_accessor :parse_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).length == 0
+      #
+      # :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