nokogiri 1.16.3 → 1.18.1

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

@@ -2,106 +2,168 @@
 
 module Nokogiri
   module XML
-    ###
-    # SAX Parsers are event driven parsers. Nokogiri provides two different event based parsers when
-    # dealing with XML. If you want to do SAX style parsing using 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, you simply 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 MyDocument < 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(MyDocument.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.
-    #
-    # 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 lets you spoon feed it XML. 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.
     module SAX
-      ###
-      # This class is used for registering types of events you are interested in handling. All of
-      # the methods on this class are available as possible events while parsing an XML document. To
-      # register for any particular event, just subclass this class and implement the methods you
-      # are interested in knowing about.
+      # :markup: markdown
+      #
+      # The SAX::Document class is used for registering types of events you are interested in
+      # handling. All of the methods on this class are available as possible events while parsing an
+      # \XML document. To register for any particular event, subclass this class and implement the
+      # methods you are interested in knowing about.
       #
       # To only be notified about start and end element events, write a class like this:
       #
-      #   class MyDocument < Nokogiri::XML::SAX::Document
-      #     def start_element name, attrs = []
-      #       puts "#{name} started!"
-      #     end
+      #     class MyHandler < Nokogiri::XML::SAX::Document
+      #       def start_element name, attrs = []
+      #         puts "#{name} started!"
+      #       end
       #
-      #     def end_element name
-      #       puts "#{name} ended"
+      #       def end_element name
+      #         puts "#{name} ended"
+      #       end
       #     end
-      #   end
       #
-      # You can use this event handler for any SAX style parser included with Nokogiri. See
-      # Nokogiri::XML::SAX, and Nokogiri::HTML4::SAX.
+      # You can use this event handler for any SAX-style parser included with Nokogiri.
+      #
+      # See also:
+      #
+      # - Nokogiri::XML::SAX
+      # - Nokogiri::HTML4::SAX
+      #
+      # ### Entity Handling
+      #
+      # ⚠ Entity handling is complicated in a SAX parser! Please read this section carefully if
+      # you're not getting the behavior you expect.
+      #
+      # Entities will be reported to the user via callbacks to #characters, to #reference, or
+      # possibly to both. The behavior is determined by a combination of _entity type_ and the value
+      # of ParserContext#replace_entities. (Recall that the default value of
+      # ParserContext#replace_entities is `false`.)
+      #
+      # ⚠ <b>It is UNSAFE to set ParserContext#replace_entities to `true`</b> when parsing untrusted
+      # documents.
+      #
+      # 💡 For more information on entity types, see [Wikipedia's page on
+      # DTDs](https://en.wikipedia.org/wiki/Document_type_definition#Entity_declarations).
+      #
+      # | Entity type                          | #characters                        | #reference                          |
+      # |--------------------------------------|------------------------------------|-------------------------------------|
+      # | Char ref (e.g., <tt>&#146;</tt>)     | always                             | never                               |
+      # | Predefined (e.g., <tt>&amp;</tt>)    | always                             | never                               |
+      # | Undeclared †                         | never                              | <tt>#replace_entities == false</tt> |
+      # | Internal                             | always                             | <tt>#replace_entities == false</tt> |
+      # | External †                           | <tt>#replace_entities == true</tt> | <tt>#replace_entities == false</tt> |
+      #
+      # &nbsp;
+      #
+      # † In the case where the replacement text for the entity is unknown (e.g., an undeclared entity
+      # or an external entity that could not be resolved because of network issues), then the
+      # replacement text will not be reported. If ParserContext#replace_entities is `true`, this
+      # means the #characters callback will not be invoked. If ParserContext#replace_entities is
+      # `false`, then the #reference callback will be invoked, but with `nil` for the `content`
+      # argument.
+      #
       class Document
         ###
-        # Called when an XML declaration is parsed
+        # Called when an \XML declaration is parsed.
+        #
+        # [Parameters]
+        # - +version+ (String) the version attribute
+        # - +encoding+ (String, nil) the encoding of the document if present, else +nil+
+        # - +standalone+ ("yes", "no", nil) the standalone attribute if present, else +nil+
         def xmldecl(version, encoding, standalone)
         end
 
         ###
-        # Called when document starts parsing
+        # Called when document starts parsing.
         def start_document
         end
 
         ###
-        # Called when document ends parsing
+        # Called when document ends parsing.
         def end_document
         end
 
         ###
-        # Called at the beginning of an element
-        # * +name+ is the name of the tag
-        # * +attrs+ are an assoc list of namespaces and attributes, e.g.:
+        # Called at the beginning of an element.
+        #
+        # [Parameters]
+        # - +name+ (String) the name of the element
+        # - +attrs+ (Array<Array<String>>) an assoc list of namespace declarations and attributes, e.g.:
         #     [ ["xmlns:foo", "http://sample.net"], ["size", "large"] ]
+        #
+        # 💡If you're dealing with XML and need to handle namespaces, use the
+        # #start_element_namespace method instead.
+        #
+        # Note that the element namespace and any attribute namespaces are not provided, and so any
+        # namespaced elements or attributes will be returned as strings including the prefix:
+        #
+        #   parser.parse(<<~XML)
+        #     <root xmlns:foo='http://foo.example.com/' xmlns='http://example.com/'>
+        #       <foo:bar foo:quux="xxx">hello world</foo:bar>
+        #     </root>
+        #   XML
+        #
+        #   assert_pattern do
+        #     parser.document.start_elements => [
+        #       ["root", [["xmlns:foo", "http://foo.example.com/"], ["xmlns", "http://example.com/"]]],
+        #       ["foo:bar", [["foo:quux", "xxx"]]],
+        #     ]
+        #   end
+        #
         def start_element(name, attrs = [])
         end
 
         ###
-        # Called at the end of an element
-        # +name+ is the tag name
+        # Called at the end of an element.
+        #
+        # [Parameters]
+        # - +name+ (String) the name of the element being closed
+        #
         def end_element(name)
         end
 
         ###
-        # Called at the beginning of an element
-        # +name+ is the element name
-        # +attrs+ is a list of attributes
-        # +prefix+ is the namespace prefix for the element
-        # +uri+ is the associated namespace URI
-        # +ns+ is a hash of namespace prefix:urls associated with the element
+        # Called at the beginning of an element.
+        #
+        # [Parameters]
+        # - +name+ (String) is the name of the element
+        # - +attrs+ (Array<Attribute>) is an array of structs with the following properties:
+        #   - +localname+ (String) the local name of the attribute
+        #   - +value+ (String) the value of the attribute
+        #   - +prefix+ (String, nil) the namespace prefix of the attribute
+        #   - +uri+ (String, nil) the namespace URI of the attribute
+        # - +prefix+ (String, nil) is the namespace prefix for the element
+        # - +uri+ (String, nil) is the associated URI for the element's namespace
+        # - +ns+ (Array<Array<String, String>>) is an assoc list of namespace declarations on the element
+        #
+        # 💡If you're dealing with HTML or don't care about namespaces, try #start_element instead.
+        #
+        # [Example]
+        #   it "start_elements_namespace is called with namespaced attributes" do
+        #     parser.parse(<<~XML)
+        #       <root xmlns:foo='http://foo.example.com/'>
+        #         <foo:a foo:bar='hello' />
+        #       </root>
+        #     XML
+        #
+        #     assert_pattern do
+        #       parser.document.start_elements_namespace => [
+        #         [
+        #           "root",
+        #           [],
+        #           nil, nil,
+        #           [["foo", "http://foo.example.com/"]], # namespace declarations
+        #         ], [
+        #           "a",
+        #           [Nokogiri::XML::SAX::Parser::Attribute(localname: "bar", prefix: "foo", uri: "http://foo.example.com/", value: "hello")], # prefixed attribute
+        #           "foo", "http://foo.example.com/", # prefix and uri for the "a" element
+        #           [],
+        #         ]
+        #       ]
+        #     end
+        #   end
+        #
         def start_element_namespace(name, attrs = [], prefix = nil, uri = nil, ns = []) # rubocop:disable Metrics/ParameterLists
-          ###
           # Deal with SAX v1 interface
           name = [prefix, name].compact.join(":")
           attributes = ns.map do |ns_prefix, ns_uri|
@@ -113,52 +175,81 @@ module Nokogiri
         end
 
         ###
-        # Called at the end of an element
-        # +name+ is the element's name
-        # +prefix+ is the namespace prefix associated with the element
-        # +uri+ is the associated namespace URI
+        # Called at the end of an element.
+        #
+        # [Parameters]
+        # - +name+ (String) is the name of the element
+        # - +prefix+ (String, nil) is the namespace prefix for the element
+        # - +uri+ (String, nil) is the associated URI for the element's namespace
+        #
         def end_element_namespace(name, prefix = nil, uri = nil)
-          ###
           # Deal with SAX v1 interface
           end_element([prefix, name].compact.join(":"))
         end
 
         ###
-        # Characters read between a tag. This method might be called multiple
-        # times given one contiguous string of characters.
+        # Called when character data is parsed, and for parsed entities when
+        # ParserContext#replace_entities is +true+.
+        #
+        # [Parameters]
+        # - +string+ contains the character data or entity replacement text
+        #
+        # ⚠ Please see Document@Entity+Handling for important information about how entities are handled.
+        #
+        # ⚠ This method might be called multiple times for a contiguous string of characters.
         #
-        # +string+ contains the character data
         def characters(string)
         end
 
+        ###
+        # Called when a parsed entity is referenced and not replaced.
+        #
+        # [Parameters]
+        # - +name+ (String) is the name of the entity
+        # - +content+ (String, nil) is the replacement text for the entity, if known
+        #
+        # ⚠ Please see Document@Entity+Handling for important information about how entities are handled.
+        #
+        # ⚠ An internal entity may result in a call to both #characters and #reference.
+        #
+        # Since v1.17.0
+        #
+        def reference(name, content)
+        end
+
         ###
         # Called when comments are encountered
-        # +string+ contains the comment data
+        # [Parameters]
+        # - +string+ contains the comment data
         def comment(string)
         end
 
         ###
         # Called on document warnings
-        # +string+ contains the warning
+        # [Parameters]
+        # - +string+ contains the warning
         def warning(string)
         end
 
         ###
         # Called on document errors
-        # +string+ contains the error
+        # [Parameters]
+        # - +string+ contains the error
         def error(string)
         end
 
         ###
         # Called when cdata blocks are found
-        # +string+ contains the cdata content
+        # [Parameters]
+        # - +string+ contains the cdata content
         def cdata_block(string)
         end
 
         ###
         # Called when processing instructions are found
-        # +name+ is the target of the instruction
-        # +content+ is the value of the instruction
+        # [Parameters]
+        # - +name+ is the target of the instruction
+        # - +content+ is the value of the instruction
         def processing_instruction(name, content)
         end
       end

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

@@ -4,16 +4,15 @@ module Nokogiri
   module XML
     module SAX
       ###
-      # This parser is a SAX style parser that reads it's 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.
+      # 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 MyDoc < Nokogiri::XML::SAX::Document
+      #   class MyHandler < Nokogiri::XML::SAX::Document
       #     def start_element name, attrs = []
       #       puts "starting: #{name}"
       #     end
@@ -23,20 +22,28 @@ module Nokogiri
       #     end
       #   end
       #
-      #   # Create our parser
-      #   parser = Nokogiri::XML::SAX::Parser.new(MyDoc.new)
+      #   parser = Nokogiri::XML::SAX::Parser.new(MyHandler.new)
       #
-      #   # Send some XML to the parser
-      #   parser.parse(File.open(ARGV[0]))
+      #   # 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.
       #
-      # For more information about SAX parsers, see Nokogiri::XML::SAX.  Also
-      # see Nokogiri::XML::SAX::Document for the available events.
       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
 
-        # Encodinds this parser supports
-        ENCODINGS = {
+        ENCODINGS = { # :nodoc:
           "NONE" => 0, # No char encoding detected
           "UTF-8" => 1, # UTF-8
           "UTF16LE" => 2, # UTF-16 little endian
@@ -61,6 +68,8 @@ module Nokogiri
           "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
@@ -68,57 +77,122 @@ module Nokogiri
         # The encoding beings used for this document.
         attr_accessor :encoding
 
-        # Create a new Parser with +doc+ and +encoding+
-        def initialize(doc = Nokogiri::XML::SAX::Document.new, encoding = "UTF-8")
-          @encoding = check_encoding(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
 
         ###
-        # Parse given +thing+ which may be a string containing xml, or an
-        # IO object.
-        def parse(thing, &block)
-          if thing.respond_to?(:read) && thing.respond_to?(:close)
-            parse_io(thing, &block)
+        # :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(thing, &block)
+            parse_memory(input, &block)
           end
         end
 
         ###
-        # Parse given +io+
+        # :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 = ParserContext.io(io, ENCODINGS[check_encoding(encoding)])
+          ctx = related_class("ParserContext").io(io, encoding)
           yield ctx if block_given?
           ctx.parse_with(self)
         end
 
         ###
-        # Parse a file with +filename+
-        def parse_file(filename)
-          raise ArgumentError unless filename
-          raise Errno::ENOENT unless File.exist?(filename)
-          raise Errno::EISDIR if File.directory?(filename)
-
-          ctx = ParserContext.file(filename)
+        # :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
 
-        def parse_memory(data)
-          ctx = ParserContext.memory(data)
+        ###
+        # :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
-
-        private
-
-        def check_encoding(encoding)
-          encoding.upcase.tap do |enc|
-            raise ArgumentError, "'#{enc}' is not a valid encoding" unless ENCODINGS[enc]
-          end
-        end
       end
     end
   end