nokogiri 1.15.4 → 1.17.2

data/lib/nokogiri/xml/pp/node.rb

@@ -8,6 +8,11 @@ module Nokogiri
         COLLECTIONS = [:attribute_nodes, :children]
 
         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?)
@@ -21,7 +26,7 @@ module Nokogiri
               "#{attribute}=#{send(attribute).inspect}"
             end.join(" ")
           end
-          "#<#{self.class.name}:#{format("0x%x", object_id)} #{attributes}>"
+          "#<#{self.class}:#{format("0x%x", object_id)} #{attributes}>"
         end
 
         def pretty_print(pp)

data/lib/nokogiri/xml/reader.rb

@@ -3,32 +3,34 @@
 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.
+    #
+    # 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 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.
     #
     # Here is an example of usage:
     #
-    #     reader = Nokogiri::XML::Reader(<<-eoxml)
+    #     reader = Nokogiri::XML::Reader.new <<~XML
     #       <x xmlns:tenderlove='http://tenderlovemaking.com/'>
     #         <tenderlove:foo awesome='true'>snuggles!</tenderlove:foo>
     #       </x>
-    #     eoxml
+    #     XML
     #
     #     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
 
@@ -65,23 +67,55 @@ 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 XML source
+      # The \XML source
       attr_reader :source
 
       alias_method :self_closing?, :empty_element?
 
-      def initialize(source, url = nil, encoding = nil) # :nodoc:
+      # :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
+
+        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 the attributes and namespaces of the current node as a Hash.
       #

data/lib/nokogiri/xml/relax_ng.rb

@@ -3,36 +3,73 @@
 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, options = ParseOptions::DEFAULT_SCHEMA)
-        RelaxNG.new(string_or_io, options)
+      # :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.
     #
-    # == Synopsis
+    # 🛡 <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.
     #
-    # Validate an XML document against a RelaxNG schema.  Loop over the errors
-    # that are returned and print them out:
+    # *Example:* Determine whether an \XML document is valid.
     #
-    #   schema  = Nokogiri::XML::RelaxNG(File.open(ADDRESS_SCHEMA_FILE))
-    #   doc     = Nokogiri::XML(File.open(ADDRESS_XML_FILE))
+    #   schema = Nokogiri::XML::RelaxNG.new(File.read(RELAX_NG_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   schema.valid?(doc) # Boolean
     #
-    #   schema.validate(doc).each do |error|
-    #     puts error.message
-    #   end
+    # *Example:* Validate an \XML document against a \RelaxNG schema, and capture any errors that are found.
     #
-    # The list of errors are Nokogiri::XML::SyntaxError objects.
+    #   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>
+    #
+    # *Example:* Validate an \XML document using a Document containing a RELAX NG schema definition.
+    #
+    #   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
     #
-    # NOTE: RelaxNG input is always treated as TRUSTED documents, meaning that they will cause the
-    # underlying parsing libraries to access network resources. This is counter to Nokogiri's
-    # "untrusted by default" security policy, but is a limitation of the underlying libraries.
     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

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