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

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

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]

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

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 ()

# 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 ()

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)

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

name ()

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]

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)

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 ()

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)

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)

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