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

# class Nokogiri::XML::DocumentFragment

`DocumentFragment` represents a fragment of an XML document. It provides the same functionality exposed by `XML::Node` and can be used to contain one or more XML subtrees.

### Attributes

parse_options[R]

The options used to parse the document fragment. Returns the value of any options that were passed into the constructor as a parameter or set in a config block, else the default options for the specific subclass.

### Public Class Methods

new(document, input=nil) { |options| ... } → DocumentFragment click to toggle source
new(document, input=nil, context:, options:) → DocumentFragment

Parse XML fragment input from a String, and return a new `DocumentFragment` that is associated with the given `document`.

💡 It’s recommended to use either `XML::DocumentFragment.parse` or `Node#parse` rather than call this method directly.

Required Parameters

- `document` (`XML::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_XML`.

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

  `XML::DocumentFragment`

### Context Node¶ ↑

If a context node is specified using `context:`, then the fragment will be created by calling `Node#parse` on that node, so the parser will behave as if that `Node` is the parent of the fragment subtree, and will resolve namespaces relative to that node.

    # File lib/nokogiri/xml/document_fragment.rb, line 85
    def initialize(
      document, tags = nil,
      context_ = nil, options_ = ParseOptions::DEFAULT_XML,
      context: context_, options: options_
    ) # rubocop:disable Lint/MissingSuper
      return self unless tags

      options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
      @parse_options = options
      yield options if block_given?

      children = if context
        # Fix for issue#490
        if Nokogiri.jruby?
          # fix for issue #770
          context.parse("<root #{namespace_declarations(context)}>#{tags}</root>", options).children
        else
          context.parse(tags, options)
        end
      else
        wrapper_doc = XML::Document.parse("<root>#{tags}</root>", nil, nil, options)
        self.errors = wrapper_doc.errors
        wrapper_doc.xpath("/root/node()")
      end
      children.each { |child| child.parent = self }
    end

parse(input) { |options| ... } → XML::DocumentFragment click to toggle source
parse(input, options:) → XML::DocumentFragment

Parse XML fragment input from a String, and return a new `XML::DocumentFragment`. This method creates a new, empty `XML::Document` to contain the fragment.

Required Parameters

- `input` (String) The content to be parsed.

Optional Keyword Arguments

- `options` (`Nokogiri::XML::ParseOptions`) Configuration object that determines some behaviors during parsing. See `ParseOptions` for more information. The default value is `ParseOptions::DEFAULT_XML`.

Yields

  If a block is given, a `Nokogiri::XML::ParseOptions` object is yielded to the block which can be configured before parsing. See `Nokogiri::XML::ParseOptions` for more information.

Returns

  `Nokogiri::XML::DocumentFragment`

    # File lib/nokogiri/xml/document_fragment.rb, line 35
    def parse(tags, options_ = ParseOptions::DEFAULT_XML, options: options_, &block)
      new(XML::Document.new, tags, options: options, &block)
    end

### Public Instance Methods

css *rules, [namespace-bindings, custom-pseudo-class] click to toggle source

Search this fragment for `CSS` `rules`. `rules` must be one or more `CSS` selectors. For example:

For more information see `Nokogiri::XML::Searchable#css`

    # File lib/nokogiri/xml/document_fragment.rb, line 173
    def css(*args)
      if children.any?
        children.css(*args) # 'children' is a smell here
      else
        NodeSet.new(document)
      end
    end

deconstruct() → Array click to toggle source

Returns the root nodes of this document fragment as an array, to use in pattern matching.

💡 Note that text nodes are returned as well as elements. If you wish to operate only on root elements, you should deconstruct the array returned by `DocumentFragment#elements`.

Example

    frag = Nokogiri::HTML5.fragment(<<~HTML)
      <div>Start</div>
      This is a <a href="#jump">shortcut</a> for you.
      <div>End</div>
    HTML

    frag.deconstruct
    # => [#(Element:0x35c { name = "div", children = [ #(Text "Start")] }),
    #     #(Text "\n" + "This is a "),
    #     #(Element:0x370 {
    #       name = "a",
    #       attributes = [ #(Attr:0x384 { name = "href", value = "#jump" })],
    #       children = [ #(Text "shortcut")]
    #       }),
    #     #(Text " for you.\n"),
    #     #(Element:0x398 { name = "div", children = [ #(Text "End")] }),
    #     #(Text "\n")]

Example only the elements, not the text nodes.

    frag.elements.deconstruct
    # => [#(Element:0x35c { name = "div", children = [ #(Text "Start")] }),
    #     #(Element:0x370 {
    #       name = "a",
    #       attributes = [ #(Attr:0x384 { name = "href", value = "#jump" })],
    #       children = [ #(Text "shortcut")]
    #       }),
    #     #(Element:0x398 { name = "div", children = [ #(Text "End")] })]

Since v1.14.0

    # File lib/nokogiri/xml/document_fragment.rb, line 261
    def deconstruct
      children.to_a
    end

dup() click to toggle source

    # File lib/nokogiri/xml/document_fragment.rb, line 113
    def dup
      new_document = document.dup
      new_fragment = self.class.new(new_document)
      children.each do |child|
        child.dup(1, new_document).parent = new_fragment
      end
      new_fragment
    end

errors() click to toggle source

A list of `Nokogiri::XML::SyntaxError` found when parsing a document

    # File lib/nokogiri/xml/document_fragment.rb, line 207
    def errors
      document.errors
    end

fragment(data) click to toggle source

    # File lib/nokogiri/xml/document_fragment.rb, line 215
    def fragment(data)
      document.fragment(data)
    end

name() click to toggle source

return the name for `DocumentFragment`

    # File lib/nokogiri/xml/document_fragment.rb, line 125
    def name
      "#document-fragment"
    end

search *paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class] click to toggle source

Search this fragment for `paths`. `paths` must be one or more `XPath` or `CSS` queries.

For more information see `Nokogiri::XML::Searchable#search`

    # File lib/nokogiri/xml/document_fragment.rb, line 192
    def search(*rules)
      rules, handler, ns, binds = extract_params(rules)

      rules.inject(NodeSet.new(document)) do |set, rule|
        set + if Searchable::LOOKS_LIKE_XPATH.match?(rule)
          xpath(*[rule, ns, handler, binds].compact)
        else
          children.css(*[rule, ns, handler].compact) # 'children' is a smell here
        end
      end
    end

serialize()
Alias for: to_s
to_html(*args) click to toggle source

Convert this `DocumentFragment` to html See `Nokogiri::XML::NodeSet#to_html`

    # File lib/nokogiri/xml/document_fragment.rb, line 138
    def to_html(*args)
      if Nokogiri.jruby?
        options = args.first.is_a?(Hash) ? args.shift : {}
        options[:save_with] ||= Node::SaveOptions::DEFAULT_HTML
        args.insert(0, options)
      end
      children.to_html(*args)
    end

to_s() click to toggle source

Convert this `DocumentFragment` to a string

    # File lib/nokogiri/xml/document_fragment.rb, line 131
    def to_s
      children.to_s
    end

Also aliased as: serialize
to_xhtml(*args) click to toggle source

Convert this `DocumentFragment` to xhtml See `Nokogiri::XML::NodeSet#to_xhtml`

    # File lib/nokogiri/xml/document_fragment.rb, line 150
    def to_xhtml(*args)
      if Nokogiri.jruby?
        options = args.first.is_a?(Hash) ? args.shift : {}
        options[:save_with] ||= Node::SaveOptions::DEFAULT_XHTML
        args.insert(0, options)
      end
      children.to_xhtml(*args)
    end

to_xml(*args) click to toggle source

Convert this `DocumentFragment` to xml See `Nokogiri::XML::NodeSet#to_xml`

    # File lib/nokogiri/xml/document_fragment.rb, line 162
    def to_xml(*args)
      children.to_xml(*args)
    end

### Private Instance Methods

namespace_declarations(ctx) click to toggle source

fix for issue 770

    # File lib/nokogiri/xml/document_fragment.rb, line 268
    def namespace_declarations(ctx)
      ctx.namespace_scopes.map do |namespace|
        prefix = namespace.prefix.nil? ? "" : ":#{namespace.prefix}"
        %{xmlns#{prefix}="#{namespace.href}"}
      end.join(" ")
    end