nokogiri 1.16.8-x86_64-linux → 1.17.0-x86_64-linux

data/lib/nokogiri/html4/document_fragment.rb

@@ -3,13 +3,83 @@
 module Nokogiri
   module HTML4
     class DocumentFragment < Nokogiri::XML::DocumentFragment
-      ####
-      # Create a Nokogiri::XML::DocumentFragment from +tags+, using +encoding+
-      def self.parse(tags, encoding = nil, options = XML::ParseOptions::DEFAULT_HTML, &block)
+      #
+      # :call-seq:
+      #   parse(input) { |options| ... } → HTML4::DocumentFragment
+      #   parse(input, encoding:, options:) { |options| ... } → HTML4::DocumentFragment
+      #
+      # Parse \HTML4 fragment input from a String, and return a new HTML4::DocumentFragment. This
+      # method creates a new, empty HTML4::Document to contain the fragment.
+      #
+      # [Required Parameters]
+      # - +input+ (String | IO) The content to be parsed.
+      #
+      # [Optional Keyword Arguments]
+      # - +encoding:+ (String) The name of the encoding that should be used when processing the
+      #   document. When not provided, the encoding will be determined based on the document
+      #   content.
+      #
+      # - +options:+ (Nokogiri::XML::ParseOptions) Configuration object that determines some
+      #   behaviors during parsing. See ParseOptions for more information. The default value is
+      #   +ParseOptions::DEFAULT_HTML+.
+      #
+      # [Yields]
+      #   If a block is given, a Nokogiri::XML::ParseOptions object is yielded to the block which
+      #   can be configured before parsing. See ParseOptions for more information.
+      #
+      # [Returns] HTML4::DocumentFragment
+      #
+      # *Example:* Parsing a string
+      #
+      #   fragment = HTML4::DocumentFragment.parse("<div>Hello World</div>")
+      #
+      # *Example:* Parsing an IO
+      #
+      #   fragment = File.open("fragment.html") do |file|
+      #     HTML4::DocumentFragment.parse(file)
+      #   end
+      #
+      # *Example:* Specifying encoding
+      #
+      #   fragment = HTML4::DocumentFragment.parse(input, encoding: "EUC-JP")
+      #
+      # *Example:* Setting parse options dynamically
+      #
+      #   HTML4::DocumentFragment.parse("<div>Hello World") do |options|
+      #     options.huge.pedantic
+      #   end
+      #
+      def self.parse(
+        input,
+        encoding_ = nil, options_ = XML::ParseOptions::DEFAULT_HTML,
+        encoding: encoding_, options: options_,
+        &block
+      )
+        # TODO: this method should take a context node.
         doc = HTML4::Document.new
 
-        encoding ||= if tags.respond_to?(:encoding)
-          encoding = tags.encoding
+        if input.respond_to?(:read)
+          # Handle IO-like objects (IO, File, StringIO, etc.)
+          # The _read_ method of these objects doesn't accept an +encoding+ parameter.
+          # Encoding is usually set when the IO object is created or opened,
+          # or by using the _set_encoding_ method.
+          #
+          # 1. If +encoding+ is provided and the object supports _set_encoding_,
+          #    set the encoding before reading.
+          # 2. Read the content from the IO-like object.
+          #
+          # Note: After reading, the content's encoding will be:
+          # - The encoding set by _set_encoding_ if it was called
+          # - The default encoding of the IO object otherwise
+          #
+          # For StringIO specifically, _set_encoding_ affects only the internal string,
+          # not how the data is read out.
+          input.set_encoding(encoding) if encoding && input.respond_to?(:set_encoding)
+          input = input.read
+        end
+
+        encoding ||= if input.respond_to?(:encoding)
+          encoding = input.encoding
           if encoding == ::Encoding::ASCII_8BIT
             "UTF-8"
           else
@@ -21,29 +91,71 @@ module Nokogiri
 
         doc.encoding = encoding
 
-        new(doc, tags, nil, options, &block)
+        new(doc, input, options: options, &block)
       end
 
-      def initialize(document, tags = nil, ctx = nil, options = XML::ParseOptions::DEFAULT_HTML) # rubocop:disable Lint/MissingSuper
-        return self unless tags
+      #
+      # :call-seq:
+      #   new(document) { |options| ... } → HTML4::DocumentFragment
+      #   new(document, input) { |options| ... } → HTML4::DocumentFragment
+      #   new(document, input, context:, options:) { |options| ... } → HTML4::DocumentFragment
+      #
+      # Parse \HTML4 fragment input from a String, and return a new HTML4::DocumentFragment.
+      #
+      # 💡 It's recommended to use either HTML4::DocumentFragment.parse or XML::Node#parse rather
+      # than call this method directly.
+      #
+      # [Required Parameters]
+      # - +document+ (HTML4::Document) The parent document to associate the returned fragment with.
+      #
+      # [Optional Parameters]
+      # - +input+ (String) The content to be parsed.
+      #
+      # [Optional Keyword Arguments]
+      # - +context:+ (Nokogiri::XML::Node) The <b>context node</b> for the subtree created. See
+      #   below for more information.
+      #
+      # - +options:+ (Nokogiri::XML::ParseOptions) Configuration object that determines some
+      #   behaviors during parsing. See ParseOptions for more information. The default value is
+      #   +ParseOptions::DEFAULT_HTML+.
+      #
+      # [Yields]
+      #   If a block is given, a Nokogiri::XML::ParseOptions object is yielded to the block which
+      #   can be configured before parsing. See ParseOptions for more information.
+      #
+      # [Returns] HTML4::DocumentFragment
+      #
+      # === Context \Node
+      #
+      # If a context node is specified using +context:+, then the fragment will be created by
+      # calling XML::Node#parse on that node, so the parser will behave as if that Node is the
+      # parent of the fragment subtree.
+      #
+      def initialize(
+        document, input = nil,
+        context_ = nil, options_ = XML::ParseOptions::DEFAULT_HTML,
+        context: context_, options: options_
+      ) # rubocop:disable Lint/MissingSuper
+        return self unless input
 
         options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
+        @parse_options = options
         yield options if block_given?
 
-        if ctx
+        if context
           preexisting_errors = document.errors.dup
-          node_set = ctx.parse("<div>#{tags}</div>", options)
+          node_set = context.parse("<div>#{input}</div>", options)
           node_set.first.children.each { |child| child.parent = self } unless node_set.empty?
           self.errors = document.errors - preexisting_errors
         else
           # This is a horrible hack, but I don't care
-          path = if /^\s*?<body/i.match?(tags)
+          path = if /^\s*?<body/i.match?(input)
             "/html/body"
           else
             "/html/body/node()"
           end
 
-          temp_doc = HTML4::Document.parse("<html><body>#{tags}", nil, document.encoding, options)
+          temp_doc = HTML4::Document.parse("<html><body>#{input}", nil, document.encoding, options)
           temp_doc.xpath(path).each { |child| child.parent = self }
           self.errors = temp_doc.errors
         end

data/lib/nokogiri/html4/encoding_reader.rb

@@ -26,7 +26,7 @@ module Nokogiri
 
         def initialize
           @encoding = nil
-          super()
+          super
         end
 
         def start_element(name, attrs = [])

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

@@ -3,60 +3,45 @@
 module Nokogiri
   module HTML4
     ###
-    # Nokogiri lets you write a SAX parser to process HTML but get HTML correction features.
+    # Nokogiri provides a SAX parser to process HTML4 which will provide HTML recovery
+    # ("autocorrection") features.
     #
     # See Nokogiri::HTML4::SAX::Parser for a basic example of using a SAX parser with HTML.
     #
     # For more information on SAX parsers, see Nokogiri::XML::SAX
+    #
     module SAX
       ###
-      # This class lets you perform SAX style parsing on HTML with HTML error correction.
+      # 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 HTML input, sends
+      # messages to the Nokogiri::XML::SAX::Document.
+      #
+      # ⚠ This is an HTML4 parser and so may not support some HTML5 features and behaviors.
       #
       # Here is a basic usage example:
       #
-      #   class MyDoc < Nokogiri::XML::SAX::Document
+      #   class MyHandler < Nokogiri::XML::SAX::Document
       #     def start_element name, attributes = []
       #       puts "found a #{name}"
       #     end
       #   end
       #
-      #   parser = Nokogiri::HTML4::SAX::Parser.new(MyDoc.new)
-      #   parser.parse(File.read(ARGV[0], mode: 'rb'))
+      #   parser = Nokogiri::HTML4::SAX::Parser.new(MyHandler.new)
+      #
+      #   # Hand an IO object to the parser, which will read the HTML from the IO.
+      #   File.open(path_to_html) do |f|
+      #     parser.parse(f)
+      #   end
+      #
+      # For more information on \SAX parsers, see Nokogiri::XML::SAX or the parent class
+      # Nokogiri::XML::SAX::Parser.
+      #
+      # Also see Nokogiri::XML::SAX::Document for the available events.
       #
-      # For more information on SAX parsers, see Nokogiri::XML::SAX
       class Parser < Nokogiri::XML::SAX::Parser
-        ###
-        # Parse html stored in +data+ using +encoding+
-        def parse_memory(data, encoding = "UTF-8")
-          raise TypeError unless String === data
-          return if data.empty?
-
-          ctx = ParserContext.memory(data, encoding)
-          yield ctx if block_given?
-          ctx.parse_with(self)
-        end
-
-        ###
-        # Parse given +io+
-        def parse_io(io, encoding = "UTF-8")
-          check_encoding(encoding)
-          @encoding = encoding
-          ctx = ParserContext.io(io, ENCODINGS[encoding])
-          yield ctx if block_given?
-          ctx.parse_with(self)
-        end
-
-        ###
-        # Parse a file with +filename+
-        def parse_file(filename, encoding = "UTF-8")
-          raise ArgumentError unless filename
-          raise Errno::ENOENT unless File.exist?(filename)
-          raise Errno::EISDIR if File.directory?(filename)
-
-          ctx = ParserContext.file(filename, encoding)
-          yield ctx if block_given?
-          ctx.parse_with(self)
-        end
+        # this class inherits its behavior from Nokogiri::XML::SAX::Parser, but note that superclass
+        # uses Nokogiri::ClassResolver to use HTML4::SAX::ParserContext as the context class for
+        # this class, which is where the real behavioral differences are implemented.
       end
     end
   end

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

@@ -4,16 +4,11 @@ module Nokogiri
   module HTML4
     module SAX
       ###
-      # Context for HTML SAX parsers. This class is usually not instantiated by the user. Instead,
-      # you should be looking at Nokogiri::HTML4::SAX::Parser
+      # Context object to invoke the HTML4 SAX parser on the SAX::Document handler.
+      #
+      # 💡 This class is usually not instantiated by the user. Use Nokogiri::HTML4::SAX::Parser
+      # instead.
       class ParserContext < Nokogiri::XML::SAX::ParserContext
-        def self.new(thing, encoding = "UTF-8")
-          if [:read, :close].all? { |x| thing.respond_to?(x) }
-            super
-          else
-            memory(thing, encoding)
-          end
-        end
       end
     end
   end

data/lib/nokogiri/html4.rb

@@ -3,12 +3,9 @@
 
 module Nokogiri
   class << self
-    # :call-seq:
-    #   HTML4(input, url = nil, encoding = nil, options = XML::ParseOptions::DEFAULT_HTML, &block) → Nokogiri::HTML4::Document
-    #
-    # Parse HTML. Convenience method for Nokogiri::HTML4::Document.parse
-    def HTML4(input, url = nil, encoding = nil, options = XML::ParseOptions::DEFAULT_HTML, &block)
-      Nokogiri::HTML4::Document.parse(input, url, encoding, options, &block)
+    # Convenience method for Nokogiri::HTML4::Document.parse
+    def HTML4(...)
+      Nokogiri::HTML4::Document.parse(...)
     end
   end
 
@@ -18,16 +15,14 @@ module Nokogiri
   # for parsing HTML.
   module HTML4
     class << self
-      ###
-      # Parse HTML. Convenience method for Nokogiri::HTML4::Document.parse
-      def parse(input, url = nil, encoding = nil, options = XML::ParseOptions::DEFAULT_HTML, &block)
-        Document.parse(input, url, encoding, options, &block)
+      # Convenience method for Nokogiri::HTML4::Document.parse
+      def parse(...)
+        Document.parse(...)
       end
 
-      ####
-      # Parse a fragment from +string+ in to a NodeSet.
-      def fragment(string, encoding = nil, options = XML::ParseOptions::DEFAULT_HTML, &block)
-        HTML4::DocumentFragment.parse(string, encoding, options, &block)
+      # Convenience method for Nokogiri::HTML4::DocumentFragment.parse
+      def fragment(...)
+        HTML4::DocumentFragment.parse(...)
       end
     end
 

data/lib/nokogiri/html5/builder.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Nokogiri
+  module HTML5
+    ###
+    # Nokogiri HTML5 builder is used for building HTML documents. It is very similar to the
+    # Nokogiri::XML::Builder.  In fact, you should go read the documentation for
+    # Nokogiri::XML::Builder before reading this documentation.
+    #
+    # The construction behavior is identical to HTML4::Builder, but HTML5 documents implement the
+    # [HTML5 standard's serialization
+    # algorithm](https://www.w3.org/TR/2008/WD-html5-20080610/serializing.html).
+    #
+    # == Synopsis:
+    #
+    # Create an HTML5 document with a body that has an onload attribute, and a
+    # span tag with a class of "bold" that has content of "Hello world".
+    #
+    #   builder = Nokogiri::HTML5::Builder.new do |doc|
+    #     doc.html {
+    #       doc.body(:onload => 'some_func();') {
+    #         doc.span.bold {
+    #           doc.text "Hello world"
+    #         }
+    #       }
+    #     }
+    #   end
+    #   puts builder.to_html
+    #
+    # The HTML5 builder inherits from the XML builder, so make sure to read the
+    # Nokogiri::XML::Builder documentation.
+    class Builder < Nokogiri::XML::Builder
+      ###
+      # Convert the builder to HTML
+      def to_html
+        @doc.to_html
+      end
+    end
+  end
+end

data/lib/nokogiri/html5/document.rb

@@ -43,41 +43,69 @@ module Nokogiri
 
       # Get the parser's quirks mode value. See HTML5::QuirksMode.
       #
-      # This method returns `nil` if the parser was not invoked (e.g., `Nokogiri::HTML5::Document.new`).
+      # This method returns +nil+ if the parser was not invoked (e.g., Nokogiri::HTML5::Document.new).
       #
       # Since v1.14.0
       attr_reader :quirks_mode
 
       class << self
         # :call-seq:
-        #   parse(input)
-        #   parse(input, url=nil, encoding=nil, **options)
-        #   parse(input, url=nil, encoding=nil) { |options| ... }
+        #   parse(input) { |options| ... } → HTML5::Document
+        #   parse(input, url: encoding:) { |options| ... } → HTML5::Document
+        #   parse(input, **options) → HTML5::Document
         #
-        # Parse HTML5 input.
+        # Parse \HTML input with a parser compliant with the HTML5 spec. This method uses the
+        # encoding of +input+ if it can be determined, or else falls back to the +encoding:+
+        # parameter.
         #
-        # [Parameters]
-        # - +input+ may be a String, or any object that responds to _read_ and _close_ such as an
-        #   IO, or StringIO.
+        # [Required Parameters]
+        # - +input+ (String | IO) the \HTML content to be parsed.
         #
-        # - +url+ (optional) is a String indicating the canonical URI where this document is located.
+        # [Optional Parameters]
+        # - +url:+ (String) the base URI of the document.
         #
-        # - +encoding+ (optional) is the encoding that should be used when processing
-        #   the document.
+        # [Optional Keyword Arguments]
+        # - +encoding:+ (Encoding) The name of the encoding that should be used when processing the
+        #   document. When not provided, the encoding will be determined based on the document
+        #   content.
         #
-        # - +options+ (optional) is a configuration Hash (or keyword arguments) to set options
-        #   during parsing. The three currently supported options are +:max_errors+,
-        #   +:max_tree_depth+ and +:max_attributes+, described at Nokogiri::HTML5.
+        # - +max_errors:+ (Integer) The maximum number of parse errors to record. (default
+        #   +Nokogiri::Gumbo::DEFAULT_MAX_ERRORS+ which is currently 0)
         #
-        #   ⚠ Note that these options are different than those made available by
-        #   Nokogiri::XML::Document and Nokogiri::HTML4::Document.
+        # - +max_tree_depth:+ (Integer) The maximum depth of the parse tree. (default
+        #   +Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH+)
         #
-        # - +block+ (optional) is passed a configuration Hash on which parse options may be set. See
-        #   Nokogiri::HTML5 for more information and usage.
+        # - +max_attributes:+ (Integer) The maximum number of attributes allowed on an
+        #   element. (default +Nokogiri::Gumbo::DEFAULT_MAX_ATTRIBUTES+)
+        #
+        # - +parse_noscript_content_as_text:+ (Boolean) Whether to parse the content of +noscript+
+        #   elements as text. (default +false+)
+        #
+        # See rdoc-ref:HTML5@Parsing+options for a complete description of these parsing options.
+        #
+        # [Yields]
+        #   If present, the block will be passed a Hash object to modify with parse options before the
+        #   input is parsed. See rdoc-ref:HTML5@Parsing+options for a list of available options.
+        #
+        #   ⚠ Note that +url:+ and +encoding:+ cannot be set by the configuration block.
         #
         # [Returns] Nokogiri::HTML5::Document
         #
-        def parse(string_or_io, url = nil, encoding = nil, **options, &block)
+        # *Example:* Parse a string with a specific encoding and custom max errors limit.
+        #
+        #   Nokogiri::HTML5::Document.parse(socket, encoding: "ISO-8859-1", max_errors: 10)
+        #
+        # *Example:* Parse a string setting the +:parse_noscript_content_as_text+ option using the
+        # configuration block parameter.
+        #
+        #   Nokogiri::HTML5::Document.parse(input) { |c| c[:parse_noscript_content_as_text] = true }
+        #
+        def parse(
+          string_or_io,
+          url_ = nil, encoding_ = nil,
+          url: url_, encoding: encoding_,
+          **options, &block
+        )
           yield options if block
           string_or_io = "" unless string_or_io
 
@@ -92,35 +120,37 @@ module Nokogiri
             raise ArgumentError, "not a string or IO object"
           end
 
-          do_parse(string_or_io, url, encoding, options)
+          do_parse(string_or_io, url, encoding, **options)
         end
 
         # Create a new document from an IO object.
         #
         # 💡 Most users should prefer Document.parse to this method.
-        def read_io(io, url = nil, encoding = nil, **options)
+        def read_io(io, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)
           raise ArgumentError, "io object doesn't respond to :read" unless io.respond_to?(:read)
 
-          do_parse(io, url, encoding, options)
+          do_parse(io, url, encoding, **options)
         end
 
         # Create a new document from a String.
         #
         # 💡 Most users should prefer Document.parse to this method.
-        def read_memory(string, url = nil, encoding = nil, **options)
+        def read_memory(string, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)
           raise ArgumentError, "string object doesn't respond to :to_str" unless string.respond_to?(:to_str)
 
-          do_parse(string, url, encoding, options)
+          do_parse(string, url, encoding, **options)
         end
 
         private
 
-        def do_parse(string_or_io, url, encoding, options)
+        def do_parse(string_or_io, url, encoding, **options)
           string = HTML5.read_and_encode(string_or_io, encoding)
-          max_attributes = options[:max_attributes] || Nokogiri::Gumbo::DEFAULT_MAX_ATTRIBUTES
-          max_errors = options[:max_errors] || options[:max_parse_errors] || Nokogiri::Gumbo::DEFAULT_MAX_ERRORS
-          max_depth = options[:max_tree_depth] || Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH
-          doc = Nokogiri::Gumbo.parse(string, url, max_attributes, max_errors, max_depth, self)
+
+          options[:max_attributes] ||= Nokogiri::Gumbo::DEFAULT_MAX_ATTRIBUTES
+          options[:max_errors] ||= options.delete(:max_parse_errors) || Nokogiri::Gumbo::DEFAULT_MAX_ERRORS
+          options[:max_tree_depth] ||= Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH
+
+          doc = Nokogiri::Gumbo.parse(string, url, self, **options)
           doc.encoding = "UTF-8"
           doc
         end
@@ -142,7 +172,8 @@ module Nokogiri
       # - +markup+ (String) The HTML5 markup fragment to be parsed
       #
       # [Returns]
-      #   Nokogiri::HTML5::DocumentFragment. This object's children will be empty if `markup` is not passed, is empty, or is `nil`.
+      #   Nokogiri::HTML5::DocumentFragment. This object's children will be empty if +markup+ is not
+      #   passed, is empty, or is +nil+.
       #
       def fragment(markup = nil)
         DocumentFragment.new(self, markup)