nokogiri 1.16.0 → 1.18.1

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)

data/lib/nokogiri/html5/document_fragment.rb

@@ -25,27 +25,145 @@ module Nokogiri
     #
     # 💡 HTML5 functionality is not available when running JRuby.
     class DocumentFragment < Nokogiri::HTML4::DocumentFragment
+      class << self
+        # :call-seq:
+        #   parse(input, **options) → HTML5::DocumentFragment
+        #
+        # Parse \HTML5 fragment input from a String, and return a new HTML5::DocumentFragment. This
+        # method creates a new, empty HTML5::Document to contain the fragment.
+        #
+        # [Parameters]
+        # - +input+ (String | IO) The HTML5 document fragment to parse.
+        #
+        # [Optional Keyword Arguments]
+        # - +encoding:+ (String | Encoding) The encoding, or 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. Also see Nokogiri::HTML5 for a longer explanation of how
+        #   encoding is handled by the parser.
+        #
+        # - +context:+ (String | Nokogiri::XML::Node) The node, or the name of an HTML5 element, "in
+        #   context" of which to parse the document fragment. See below for more
+        #   information. (default +"body"+)
+        #
+        # - +max_errors:+ (Integer) The maximum number of parse errors to record. (default
+        #   +Nokogiri::Gumbo::DEFAULT_MAX_ERRORS+ which is currently 0)
+        #
+        # - +max_tree_depth:+ (Integer) The maximum depth of the parse tree. (default
+        #   +Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH+)
+        #
+        # - +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.
+        #
+        # [Returns] Nokogiri::HTML5::DocumentFragment
+        #
+        # === Context \Node
+        #
+        # If a context node is specified using +context:+, then the parser will behave as if that
+        # Node, or a hypothetical tag named as specified, is the parent of the fragment subtree.
+        #
+        def parse(
+          input,
+          encoding_ = nil, positional_options_hash = nil,
+          encoding: encoding_, **options
+        )
+          unless positional_options_hash.nil? || positional_options_hash.empty?
+            options.merge!(positional_options_hash)
+          end
+
+          context = options.delete(:context)
+
+          document = HTML5::Document.new
+          document.encoding = "UTF-8"
+          input = HTML5.read_and_encode(input, encoding)
+
+          new(document, input, context, options)
+        end
+      end
+
       attr_accessor :document
       attr_accessor :errors
 
       # Get the parser's quirks mode value. See HTML5::QuirksMode.
       #
-      # This method returns `nil` if the parser was not invoked (e.g., `Nokogiri::HTML5::DocumentFragment.new(doc)`).
+      # This method returns `nil` if the parser was not invoked (e.g.,
+      # `Nokogiri::HTML5::DocumentFragment.new(doc)`).
       #
       # Since v1.14.0
       attr_reader :quirks_mode
 
-      # Create a document fragment.
-      def initialize(doc, tags = nil, ctx = nil, options = {}) # rubocop:disable Lint/MissingSuper
-        self.document = doc
-        self.errors = []
-        return self unless tags
-
-        max_attributes = options[:max_attributes] || Nokogiri::Gumbo::DEFAULT_MAX_ATTRIBUTES
-        max_errors = options[:max_errors] || Nokogiri::Gumbo::DEFAULT_MAX_ERRORS
-        max_depth = options[:max_tree_depth] || Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH
-        tags = Nokogiri::HTML5.read_and_encode(tags, nil)
-        Nokogiri::Gumbo.fragment(self, tags, ctx, max_attributes, max_errors, max_depth)
+      #
+      # :call-seq:
+      #   new(document, input, **options) → HTML5::DocumentFragment
+      #
+      # Parse \HTML5 fragment input from a String, and return a new HTML5::DocumentFragment.
+      #
+      # 💡 It's recommended to use either HTML5::DocumentFragment.parse or HTML5::Node#fragment
+      # rather than call this method directly.
+      #
+      # [Required Parameters]
+      # - +document+ (HTML5::Document) The parent document to associate the returned fragment with.
+      #
+      # [Optional Parameters]
+      # - +input+ (String) The content to be parsed.
+      #
+      # [Optional Keyword Arguments]
+      # - +encoding:+ (String | Encoding) The encoding, or 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. Also see Nokogiri::HTML5 for a longer explanation of how
+      #   encoding is handled by the parser.
+      #
+      # - +context:+ (String | Nokogiri::XML::Node) The node, or the name of an HTML5 element, in
+      #   which to parse the document fragment. (default +"body"+)
+      #
+      # - +max_errors:+ (Integer) The maximum number of parse errors to record. (default
+      #   +Nokogiri::Gumbo::DEFAULT_MAX_ERRORS+ which is currently 0)
+      #
+      # - +max_tree_depth:+ (Integer) The maximum depth of the parse tree. (default
+      #   +Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH+)
+      #
+      # - +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.
+      #
+      # [Returns] HTML5::DocumentFragment
+      #
+      # === Context \Node
+      #
+      # If a context node is specified using +context:+, then the parser will behave as if that
+      # Node, or a hypothetical tag named as specified, is the parent of the fragment subtree.
+      #
+      def initialize(
+        doc, input = nil,
+        context_ = nil, positional_options_hash = nil,
+        context: context_,
+        **options
+      ) # rubocop:disable Lint/MissingSuper
+        unless positional_options_hash.nil? || positional_options_hash.empty?
+          options.merge!(positional_options_hash)
+        end
+
+        @document = doc
+        @errors = []
+        return self unless input
+
+        input = Nokogiri::HTML5.read_and_encode(input, nil)
+
+        context = options.delete(:context) if options.key?(:context)
+
+        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
+
+        Nokogiri::Gumbo.fragment(self, input, context, **options)
       end
 
       def serialize(options = {}, &block) # :nodoc:
@@ -54,14 +172,6 @@ module Nokogiri
         XML::Node.instance_method(:serialize).bind_call(self, options, &block)
       end
 
-      # Parse a document fragment from +tags+, returning a Nodeset.
-      def self.parse(tags, encoding = nil, options = {})
-        doc = HTML5::Document.new
-        tags = HTML5.read_and_encode(tags, encoding)
-        doc.encoding = "UTF-8"
-        new(doc, tags, nil, options)
-      end
-
       def extract_params(params) # :nodoc:
         handler = params.find do |param|
           ![Hash, String, Symbol].include?(param.class)

data/lib/nokogiri/html5/node.rb

@@ -29,7 +29,7 @@ module Nokogiri
     # 💡 HTML5 functionality is not available when running JRuby.
     module Node
       def inner_html(options = {})
-        return super(options) unless document.is_a?(HTML5::Document)
+        return super unless document.is_a?(HTML5::Document)
 
         result = options[:preserve_newline] && prepend_newline? ? +"\n" : +""
         result << children.map { |child| child.to_html(options) }.join
@@ -37,7 +37,7 @@ module Nokogiri
       end
 
       def write_to(io, *options)
-        return super(io, *options) unless document.is_a?(HTML5::Document)
+        return super unless document.is_a?(HTML5::Document)
 
         options = options.first.is_a?(Hash) ? options.shift : {}
         encoding = options[:encoding] || options[0]
@@ -68,7 +68,7 @@ module Nokogiri
       end
 
       def fragment(tags)
-        return super(tags) unless document.is_a?(HTML5::Document)
+        return super unless document.is_a?(HTML5::Document)
 
         DocumentFragment.new(document, tags, self)
       end
@@ -81,7 +81,7 @@ module Nokogiri
       # annoying with attribute names like xml:lang since libxml2 will
       # actually create the xml namespace if it doesn't exist already.
       def add_child_node_and_reparent_attrs(node)
-        return super(node) unless document.is_a?(HTML5::Document)
+        return super unless document.is_a?(HTML5::Document)
 
         # I'm not sure what this method is supposed to do. Reparenting
         # namespaces is handled by libxml2, including child namespaces which