class Nokogiri::XML::DocumentFragment

Parent:: Nokogiri::XML::Node

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 Show source

new(document, input=nil, context:, options:) → DocumentFragment

# 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 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.

parse(input) { |options| ... } → XML::DocumentFragment Show source

parse(input, options:) → 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

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

Public Instance Methods

css *rules, [namespace-bindings, custom-pseudo-class] Show source

# 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

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

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

deconstruct() → Array Show source

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

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

dup () Show 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 () Show source

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

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

fragment (data) Show source

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

name () Show source

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

return the name for DocumentFragment

search *paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class] Show source

# 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

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

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

serialize ()

Alias for: to_s

to_html (*args) Show source

# 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

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

to_s () Show source

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

Convert this DocumentFragment to a string

Also aliased as: serialize

to_xhtml (*args) Show source

# 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

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

to_xml (*args) Show source

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

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

© 2008–2026 by Mike Dalessio, Aaron Patterson, Yoko Harada, Akinori MUSHA, John Shahid,
Karol Bucek, Sam Ruby, Craig Barnes, Stephen Checkoway, Lars Kanis, Sergio Arbeo,
Timothy Elliott, Nobuyoshi Nakada, Charles Nutter, Patrick MahoneyLicensed under the MIT License.
https://nokogiri.org/rdoc/Nokogiri/XML/DocumentFragment.html