class Nokogiri::HTML4::DocumentFragment - nokogiri-1.18.10 Documentation

# class Nokogiri::HTML4::DocumentFragment

### Public Class Methods

new(document) { |options| ... } → HTML4::DocumentFragment click to toggle source
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 context node 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.

    # File lib/nokogiri/html4/document_fragment.rb, line 134
    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 context
        preexisting_errors = document.errors.dup
        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?(input)
          "/html/body"
        else
          "/html/body/node()"
        end

        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
      children
    end

parse(input) { |options| ... } → HTML4::DocumentFragment click to toggle source
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

    # File lib/nokogiri/html4/document_fragment.rb, line 52
    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

      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
          encoding.name
        end
      else
        "UTF-8"
      end

      doc.encoding = encoding

      new(doc, input, options: options, &block)
    end