nokogiri 1.18.0.rc1-aarch64-linux-gnu

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    module SAX
+      ###
+      # This parser is a SAX style parser that reads its input as it deems necessary. The parser
+      # takes a Nokogiri::XML::SAX::Document, an optional encoding, then given an XML input, sends
+      # messages to the Nokogiri::XML::SAX::Document.
+      #
+      # Here is an example of using this parser:
+      #
+      #   # Create a subclass of Nokogiri::XML::SAX::Document and implement
+      #   # the events we care about:
+      #   class MyHandler < Nokogiri::XML::SAX::Document
+      #     def start_element name, attrs = []
+      #       puts "starting: #{name}"
+      #     end
+      #
+      #     def end_element name
+      #       puts "ending: #{name}"
+      #     end
+      #   end
+      #
+      #   parser = Nokogiri::XML::SAX::Parser.new(MyHandler.new)
+      #
+      #   # Hand an IO object to the parser, which will read the XML from the IO.
+      #   File.open(path_to_xml) do |f|
+      #     parser.parse(f)
+      #   end
+      #
+      # For more information about \SAX parsers, see Nokogiri::XML::SAX.
+      #
+      # Also see Nokogiri::XML::SAX::Document for the available events.
+      #
+      # For \HTML documents, use the subclass Nokogiri::HTML4::SAX::Parser.
+      #
+      class Parser
+        # to dynamically resolve ParserContext in inherited methods
+        include Nokogiri::ClassResolver
+
+        # Structure used for marshalling attributes for some callbacks in XML::SAX::Document.
+        class Attribute < Struct.new(:localname, :prefix, :uri, :value)
+        end
+
+        ENCODINGS = { # :nodoc:
+          "NONE" => 0, # No char encoding detected
+          "UTF-8" => 1, # UTF-8
+          "UTF16LE" => 2, # UTF-16 little endian
+          "UTF16BE" => 3, # UTF-16 big endian
+          "UCS4LE" => 4, # UCS-4 little endian
+          "UCS4BE" => 5, # UCS-4 big endian
+          "EBCDIC" => 6, # EBCDIC uh!
+          "UCS4-2143" => 7, # UCS-4 unusual ordering
+          "UCS4-3412" => 8, # UCS-4 unusual ordering
+          "UCS2" => 9, # UCS-2
+          "ISO-8859-1" => 10, # ISO-8859-1 ISO Latin 1
+          "ISO-8859-2" => 11, # ISO-8859-2 ISO Latin 2
+          "ISO-8859-3" => 12, # ISO-8859-3
+          "ISO-8859-4" => 13, # ISO-8859-4
+          "ISO-8859-5" => 14, # ISO-8859-5
+          "ISO-8859-6" => 15, # ISO-8859-6
+          "ISO-8859-7" => 16, # ISO-8859-7
+          "ISO-8859-8" => 17, # ISO-8859-8
+          "ISO-8859-9" => 18, # ISO-8859-9
+          "ISO-2022-JP" => 19, # ISO-2022-JP
+          "SHIFT-JIS" => 20, # Shift_JIS
+          "EUC-JP" => 21, # EUC-JP
+          "ASCII" => 22, # pure ASCII
+        }
+        REVERSE_ENCODINGS = ENCODINGS.invert # :nodoc:
+        deprecate_constant :ENCODINGS
+
+        # The Nokogiri::XML::SAX::Document where events will be sent.
+        attr_accessor :document
+
+        # The encoding beings used for this document.
+        attr_accessor :encoding
+
+        ###
+        # :call-seq:
+        #   new ⇒ SAX::Parser
+        #   new(handler) ⇒ SAX::Parser
+        #   new(handler, encoding) ⇒ SAX::Parser
+        #
+        # Create a new Parser.
+        #
+        # [Parameters]
+        # - +handler+ (optional Nokogiri::XML::SAX::Document) The document that will receive
+        #   events. Will create a new Nokogiri::XML::SAX::Document if not given, which is accessible
+        #   through the #document attribute.
+        # - +encoding+ (optional Encoding, String, nil) An Encoding or encoding name to use when
+        #   parsing the input. (default +nil+ for auto-detection)
+        #
+        def initialize(doc = Nokogiri::XML::SAX::Document.new, encoding = nil)
+          @encoding = encoding
+          @document = doc
+          @warned   = false
+
+          initialize_native unless Nokogiri.jruby?
+        end
+
+        ###
+        # :call-seq:
+        #   parse(input) { |parser_context| ... }
+        #
+        # Parse the input, sending events to the SAX::Document at #document.
+        #
+        # [Parameters]
+        # - +input+ (String, IO) The input to parse.
+        #
+        # If +input+ quacks like a readable IO object, this method forwards to Parser.parse_io,
+        # otherwise it forwards to Parser.parse_memory.
+        #
+        # [Yields]
+        # If a block is given, the underlying ParserContext object will be yielded. This can be used
+        # to set options on the parser context before parsing begins.
+        #
+        def parse(input, &block)
+          if input.respond_to?(:read) && input.respond_to?(:close)
+            parse_io(input, &block)
+          else
+            parse_memory(input, &block)
+          end
+        end
+
+        ###
+        # :call-seq:
+        #   parse_io(io) { |parser_context| ... }
+        #   parse_io(io, encoding) { |parser_context| ... }
+        #
+        # Parse an input stream.
+        #
+        # [Parameters]
+        # - +io+ (IO) The readable IO object from which to read input
+        # - +encoding+ (optional Encoding, String, nil) An Encoding or encoding name to use when
+        #   parsing the input, or +nil+ for auto-detection. (default #encoding)
+        #
+        # [Yields]
+        # If a block is given, the underlying ParserContext object will be yielded. This can be used
+        # to set options on the parser context before parsing begins.
+        #
+        def parse_io(io, encoding = @encoding)
+          ctx = related_class("ParserContext").io(io, encoding)
+          yield ctx if block_given?
+          ctx.parse_with(self)
+        end
+
+        ###
+        # :call-seq:
+        #   parse_memory(input) { |parser_context| ... }
+        #   parse_memory(input, encoding) { |parser_context| ... }
+        #
+        # Parse an input string.
+        #
+        # [Parameters]
+        # - +input+ (String) The input string to be parsed.
+        # - +encoding+ (optional Encoding, String, nil) An Encoding or encoding name to use when
+        #   parsing the input, or +nil+ for auto-detection. (default #encoding)
+        #
+        # [Yields]
+        # If a block is given, the underlying ParserContext object will be yielded. This can be used
+        # to set options on the parser context before parsing begins.
+        #
+        def parse_memory(input, encoding = @encoding)
+          ctx = related_class("ParserContext").memory(input, encoding)
+          yield ctx if block_given?
+          ctx.parse_with(self)
+        end
+
+        ###
+        # :call-seq:
+        #   parse_file(filename) { |parser_context| ... }
+        #   parse_file(filename, encoding) { |parser_context| ... }
+        #
+        # Parse a file.
+        #
+        # [Parameters]
+        # - +filename+ (String) The path to the file to be parsed.
+        # - +encoding+ (optional Encoding, String, nil) An Encoding or encoding name to use when
+        #   parsing the input, or +nil+ for auto-detection. (default #encoding)
+        #
+        # [Yields]
+        # If a block is given, the underlying ParserContext object will be yielded. This can be used
+        # to set options on the parser context before parsing begins.
+        #
+        def parse_file(filename, encoding = @encoding)
+          raise ArgumentError, "no filename provided" unless filename
+          raise Errno::ENOENT unless File.exist?(filename)
+          raise Errno::EISDIR if File.directory?(filename)
+
+          ctx = related_class("ParserContext").file(filename, encoding)
+          yield ctx if block_given?
+          ctx.parse_with(self)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    module SAX
+      ###
+      # 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
+        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
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    module SAX
+      ###
+      # PushParser can parse a document that is fed to it manually.  It
+      # must be given a SAX::Document object which will be called with
+      # SAX events as the document is being parsed.
+      #
+      # Calling PushParser#<< writes XML to the parser, calling any SAX
+      # callbacks it can.
+      #
+      # PushParser#finish tells the parser that the document is finished
+      # and calls the end_document SAX method.
+      #
+      # Example:
+      #
+      #   parser = PushParser.new(Class.new(XML::SAX::Document) {
+      #     def start_document
+      #       puts "start document called"
+      #     end
+      #   }.new)
+      #   parser << "<div>hello<"
+      #   parser << "/div>"
+      #   parser.finish
+      class PushParser
+        # The Nokogiri::XML::SAX::Document on which the PushParser will be
+        # operating
+        attr_accessor :document
+
+        ###
+        # 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")
+          @document = doc
+          @encoding = encoding
+          @sax_parser = XML::SAX::Parser.new(doc)
+
+          ## Create our push parser context
+          initialize_native(@sax_parser, file_name)
+        end
+
+        ###
+        # 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)
+          native_write(chunk, last_chunk)
+        end
+        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)
+        end
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/sax.rb

@@ -0,0 +1,54 @@
+# 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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    class << self
+      # :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 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.
+    #
+    #   schema = Nokogiri::XML::Schema.new(File.read(XSD_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   schema.valid?(doc) # Boolean
+    #
+    # *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
+    #
+    class Schema
+      # The errors found while parsing the \XSD
+      #
+      # [Returns] Array<Nokogiri::XML::SyntaxError>
+      attr_accessor :errors
+
+      # 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
+
+      #
+      # :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"
+        end
+      end
+
+      #
+      # :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
+end