nokogiri 1.18.0.rc1-x86_64-linux-gnu

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    # :nodoc: all
+    module PP
+      module Node
+        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?)
+          rescue NoMethodError
+            true
+          end
+          attributes = if inspect_attributes.length == 1
+            send(attributes.first).inspect
+          else
+            attributes.map do |attribute|
+              "#{attribute}=#{send(attribute).inspect}"
+            end.join(" ")
+          end
+          "#<#{self.class}:#{format("0x%x", object_id)} #{attributes}>"
+        end
+
+        def pretty_print(pp)
+          nice_name = self.class.name.split("::").last
+          pp.group(2, "#(#{nice_name}:#{format("0x%x", object_id)} {", "})") do
+            pp.breakable
+
+            attrs = inspect_attributes.filter_map do |t|
+              [t, send(t)] if respond_to?(t)
+            end.find_all do |x|
+              if x.last
+                if COLLECTIONS.include?(x.first)
+                  !x.last.empty?
+                else
+                  true
+                end
+              end
+            end
+
+            if inspect_attributes.length == 1
+              pp.pp(attrs.first.last)
+            else
+              pp.seplist(attrs) do |v|
+                if COLLECTIONS.include?(v.first)
+                  pp.group(2, "#{v.first} = [", "]") do
+                    pp.breakable
+                    pp.seplist(v.last) do |item|
+                      pp.pp(item)
+                    end
+                  end
+                else
+                  pp.text("#{v.first} = ")
+                  pp.pp(v.last)
+                end
+              end
+            end
+
+            pp.breakable
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/pp.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "pp/node"
+require_relative "pp/character_data"

data/lib/nokogiri/xml/processing_instruction.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    class ProcessingInstruction < Node
+      def initialize(document, name, content)
+        super(document, name)
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/reader.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    ###
+    # 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.new <<~XML
+    #       <x xmlns:tenderlove='http://tenderlovemaking.com/'>
+    #         <tenderlove:foo awesome='true'>snuggles!</tenderlove:foo>
+    #       </x>
+    #     XML
+    #
+    #     reader.each do |node|
+    #       # node is an instance of Nokogiri::XML::Reader
+    #       puts node.name
+    #     end
+    #
+    # ⚠ 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.
+    #
+    # ⚠ 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
+
+      TYPE_NONE = 0
+      # Element node type
+      TYPE_ELEMENT = 1
+      # Attribute node type
+      TYPE_ATTRIBUTE = 2
+      # Text node type
+      TYPE_TEXT = 3
+      # CDATA node type
+      TYPE_CDATA = 4
+      # Entity Reference node type
+      TYPE_ENTITY_REFERENCE = 5
+      # Entity node type
+      TYPE_ENTITY = 6
+      # PI node type
+      TYPE_PROCESSING_INSTRUCTION = 7
+      # Comment node type
+      TYPE_COMMENT = 8
+      # Document node type
+      TYPE_DOCUMENT = 9
+      # Document Type node type
+      TYPE_DOCUMENT_TYPE = 10
+      # Document Fragment node type
+      TYPE_DOCUMENT_FRAGMENT = 11
+      # Notation node type
+      TYPE_NOTATION = 12
+      # Whitespace node type
+      TYPE_WHITESPACE = 13
+      # Significant Whitespace node type
+      TYPE_SIGNIFICANT_WHITESPACE = 14
+      # Element end node type
+      TYPE_END_ELEMENT = 15
+      # Entity end node type
+      TYPE_END_ENTITY = 16
+      # \XML Declaration node type
+      TYPE_XML_DECLARATION = 17
+
+      # A list of errors encountered while parsing
+      attr_accessor :errors
+
+      # The \XML source
+      attr_reader :source
+
+      alias_method :self_closing?, :empty_element?
+
+      # :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
+
+      # Get the attributes and namespaces of the current node as a Hash.
+      #
+      # This is the union of Reader#attribute_hash and Reader#namespaces
+      #
+      # [Returns]
+      #   (Hash<String, String>) Attribute names and values, and namespace prefixes and hrefs.
+      def attributes
+        attribute_hash.merge(namespaces)
+      end
+
+      ###
+      # Move the cursor through the document yielding the cursor to the block
+      def each
+        while (cursor = read)
+          yield cursor
+        end
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/relax_ng.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    class << self
+      # :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 RELAX NG schema definition.
+    #
+    # 🛡 <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.
+    #
+    # *Example:* Determine whether an \XML document is valid.
+    #
+    #   schema = Nokogiri::XML::RelaxNG.new(File.read(RELAX_NG_FILE))
+    #   doc = Nokogiri::XML::Document.parse(File.read(XML_FILE))
+    #   schema.valid?(doc) # Boolean
+    #
+    # *Example:* Validate an \XML document against a \RelaxNG schema, and capture any errors that are found.
+    #
+    #   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
+    #
+    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

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module XML
+    module SAX
+      # :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 MyHandler < Nokogiri::XML::SAX::Document
+      #       def start_element name, attrs = []
+      #         puts "#{name} started!"
+      #       end
+      #
+      #       def end_element name
+      #         puts "#{name} ended"
+      #       end
+      #     end
+      #
+      # 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.
+        #
+        # [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.
+        def start_document
+        end
+
+        ###
+        # Called when document ends parsing.
+        def end_document
+        end
+
+        ###
+        # 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.
+        #
+        # [Parameters]
+        # - +name+ (String) the name of the element being closed
+        #
+        def end_element(name)
+        end
+
+        ###
+        # 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|
+            [["xmlns", ns_prefix].compact.join(":"), ns_uri]
+          end + attrs.map do |attr|
+            [[attr.prefix, attr.localname].compact.join(":"), attr.value]
+          end
+          start_element(name, attributes)
+        end
+
+        ###
+        # 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
+
+        ###
+        # 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.
+        #
+        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
+        # [Parameters]
+        # - +string+ contains the comment data
+        def comment(string)
+        end
+
+        ###
+        # Called on document warnings
+        # [Parameters]
+        # - +string+ contains the warning
+        def warning(string)
+        end
+
+        ###
+        # Called on document errors
+        # [Parameters]
+        # - +string+ contains the error
+        def error(string)
+        end
+
+        ###
+        # Called when cdata blocks are found
+        # [Parameters]
+        # - +string+ contains the cdata content
+        def cdata_block(string)
+        end
+
+        ###
+        # Called when processing instructions are found
+        # [Parameters]
+        # - +name+ is the target of the instruction
+        # - +content+ is the value of the instruction
+        def processing_instruction(name, content)
+        end
+      end
+    end
+  end
+end