class Nokogiri::XML::Document

# File lib/nokogiri/xml/document.rb, line 56
def parse(
  string_or_io,
  url_ = nil, encoding_ = nil, options_ = XML::ParseOptions::DEFAULT_XML,
  url: url_, encoding: encoding_, options: options_
)
  options = Nokogiri::XML::ParseOptions.new(options) if Integer === options
  yield options if block_given?

  url ||= string_or_io.respond_to?(:path) ? string_or_io.path : nil

  if empty_doc?(string_or_io)
    if options.strict?
      raise Nokogiri::XML::SyntaxError, "Empty document"
    else
      return encoding ? new.tap { |i| i.encoding = encoding } : new
    end
  end

  doc = if string_or_io.respond_to?(:read)
    # TODO: should we instead check for respond_to?(:to_path) ?
    if string_or_io.is_a?(Pathname)
      # resolve the Pathname to the file and open it as an IO object, see #2110
      string_or_io = string_or_io.expand_path.open
      url ||= string_or_io.path
    end

    read_io(string_or_io, url, encoding, options.to_i)
  else
    # read_memory pukes on empty docs
    read_memory(string_or_io, url, encoding, options.to_i)
  end

  # do xinclude processing
  doc.do_xinclude(options) if options.xinclude?

  doc
end

Parse XML input from a String or IO object, and return a new XML::Document.

🛡 By default, Nokogiri treats documents as untrusted, and so does not attempt to load DTDs or access the network. See Nokogiri::XML::ParseOptions for a complete list of options; and that module’s DEFAULT_XML constant for what’s set (and not set) by default.

Required Parameters

• input (String | IO) The content to be parsed.

Optional Keyword Arguments

• url: (String) The base URI for this document.

• 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_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::Document

# File lib/nokogiri/xml/document.rb, line 104
      

⚠ This method is only available when running JRuby.

Create a Document using an existing Java DOM document object.

The returned Document shares the same underlying data structure as the Java object, so changes in one are reflected in the other.

Parameters

• ‘java_document` (Java::OrgW3cDom::Document) (The class `Java::OrgW3cDom::Document` is also accessible as `org.w3c.dom.Document`.)

Returns

Nokogiri::XML::Document

See also #to_java

# File lib/nokogiri/xml/document.rb, line 223
def clone(level = 1)
  copy = OBJECT_CLONE_METHOD.bind_call(self)
  copy.initialize_copy_with_args(self, level)
end

Clone this node.

Parameters

• level (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.

Returns

The new Nokogiri::XML::Document

# File lib/nokogiri/xml/document.rb, line 361
def collect_namespaces
  xpath("//namespace::*").each_with_object({}) do |ns, hash|
    hash[["xmlns", ns.prefix].compact.join(":")] = ns.href if ns.prefix != "xml"
  end
end

Recursively get all namespaces from this node and its subtree and return them as a hash.

⚠ This method will not handle duplicate namespace prefixes, since the return value is a hash.

Note that this method does an xpath lookup for nodes with namespaces, and as a result the order (and which duplicate prefix “wins”) may be dependent on the implementation of the underlying XML library.

Example: Basic usage

Given this document:

<root xmlns="default" xmlns:foo="bar">
  <bar xmlns:hello="world" />
</root>

This method will return:

{"xmlns:foo"=>"bar", "xmlns"=>"default", "xmlns:hello"=>"world"}

Example: Duplicate prefixes

Given this document:

<root xmlns:foo="bar">
  <bar xmlns:foo="baz" />
</root>

The hash returned will be something like:

{"xmlns:foo" => "baz"}

# File lib/nokogiri/xml/document.rb, line 306
def create_cdata(string, &block)
  Nokogiri::XML::CDATA.new(self, string.to_s, &block)
end

Create a CDATA Node containing string

# File lib/nokogiri/xml/document.rb, line 311
def create_comment(string, &block)
  Nokogiri::XML::Comment.new(self, string.to_s, &block)
end

Create a Comment Node containing string

# File lib/nokogiri/xml/document.rb, line 276
def create_element(name, *contents_or_attrs, &block)
  elm = Nokogiri::XML::Element.new(name, self, &block)
  contents_or_attrs.each do |arg|
    case arg
    when Hash
      arg.each do |k, v|
        key = k.to_s
        if key =~ NCNAME_RE
          ns_name = Regexp.last_match(1)
          elm.add_namespace_definition(ns_name, v)
        else
          elm[k.to_s] = v.to_s
        end
      end
    else
      elm.content = arg
    end
  end
  if (ns = elm.namespace_definitions.find { |n| n.prefix.nil? || (n.prefix == "") })
    elm.namespace = ns
  end
  elm
end

Create a new Element with ‘name` belonging to this document, optionally setting contents or attributes.

This method is not the most user-friendly option if your intention is to add a node to the document tree. Prefer one of the Nokogiri::XML::Node methods like Node#add_child, Node#add_next_sibling, Node#replace, etc. which will both create an element (or subtree) and place it in the document tree.

Arguments may be passed to initialize the element:

• a Hash argument will be used to set attributes

• a non-Hash object that responds to #to_s will be used to set the new node’s contents

A block may be passed to mutate the node.

Parameters

• ‘name` (String)

• ‘contents_or_attrs` (#to_s, Hash)

Yields

‘node` (Nokogiri::XML::Element)

Returns

Nokogiri::XML::Element

Example: An empty element without attributes

doc.create_element("div")
# => <div></div>

Example: An element with contents

doc.create_element("div", "contents")
# => <div>contents</div>

Example: An element with attributes

doc.create_element("div", {"class" => "container"})
# => <div class='container'></div>

Example: An element with contents and attributes

doc.create_element("div", "contents", {"class" => "container"})
# => <div class='container'>contents</div>

Example: Passing a block to mutate the element

doc.create_element("div") { |node| node["class"] = "blue" if before_noon? }

# File lib/nokogiri/xml/document.rb, line 301
def create_text_node(string, &block)
  Nokogiri::XML::Text.new(string.to_s, self, &block)
end

Create a Text Node with string

# File lib/nokogiri/xml/document.rb, line 501
def deconstruct_keys(keys)
  { root: root }
end

Returns a hash describing the Document, to use in pattern matching.

Valid keys and their values:

• root → (Node, nil) The root node of the Document, or nil if the document is empty.

In the future, other keys may allow accessing things like doctype and processing instructions. If you have a use case and would like this functionality, please let us know by opening an issue or a discussion on the github project.

Example

doc = Nokogiri::XML.parse(<<~XML)
  <?xml version="1.0"?>
  <root>
    <child>
  </root>
XML

doc.deconstruct_keys([:root])
# => {:root=>
#      #(Element:0x35c {
#        name = "root",
#        children = [
#          #(Text "\n" + "  "),
#          #(Element:0x370 { name = "child", children = [ #(Text "\n")] }),
#          #(Text "\n")]
#        })}

Example of an empty document

doc = Nokogiri::XML::Document.new

doc.deconstruct_keys([:root])
# => {:root=>nil}

Since v1.14.0

# File lib/nokogiri/xml/document.rb, line 409
def decorate(node)
  return unless @decorators

  @decorators.each do |klass, list|
    next unless node.is_a?(klass)

    list.each { |mod| node.extend(mod) }
  end
end

Apply any decorators to node

# File lib/nokogiri/xml/document.rb, line 368
def decorators(key)
  @decorators ||= {}
  @decorators[key] ||= []
end

Get the list of decorators given key

# File lib/nokogiri/xml/document.rb, line 321
def document
  self
end

A reference to self

# File lib/nokogiri/xml/document.rb, line 207
def dup(level = 1)
  copy = OBJECT_DUP_METHOD.bind_call(self)
  copy.initialize_copy_with_args(self, level)
end

Duplicate this node.

Parameters

• level (optional Integer). 0 is a shallow copy, 1 (the default) is a deep copy.

Returns

The new Nokogiri::XML::Document

# File lib/nokogiri/xml/document.rb, line 429
def fragment(tags = nil)
  DocumentFragment.new(self, tags, root)
end

Create a Nokogiri::XML::DocumentFragment from tags Returns an empty fragment if tags is nil.

# File lib/nokogiri/xml/document.rb, line 316
def name
  "document"
end

The name of this document. Always returns “document”

# File lib/nokogiri/xml/document.rb, line 422
def namespaces
  root ? root.namespaces : {}
end

Get the hash of namespaces on the root Nokogiri::XML::Node

# File lib/nokogiri/xml/document.rb, line 398
def slop!
  unless decorators(XML::Node).include?(Nokogiri::Decorators::Slop)
    decorators(XML::Node) << Nokogiri::Decorators::Slop
    decorate!
  end

  self
end

Explore a document with shortcut methods. See Nokogiri::Slop for details.

Note that any nodes that have been instantiated before slop! is called will not be decorated with sloppy behavior. So, if you’re in irb, the preferred idiom is:

irb> doc = Nokogiri::Slop my_markup

and not

irb> doc = Nokogiri::HTML my_markup
... followed by irb's implicit inspect (and therefore instantiation of every node) ...
irb> doc.slop!
... which does absolutely nothing.

# File lib/nokogiri/xml/document.rb, line 122
      

⚠ This method is only available when running JRuby.

Returns the underlying Java DOM document object for this document.

The returned Java object shares the same underlying data structure as this document, so changes in one are reflected in the other.

Returns

Java::OrgW3cDom::Document (The class ‘Java::OrgW3cDom::Document` is also accessible as `org.w3c.dom.Document`.)

See also Document.wrap

# File lib/nokogiri/xml/document.rb, line 376
def validate
  return unless internal_subset

  internal_subset.validate(self)
end

Validate this Document against its DTD. Returns a list of errors on the document or nil when there is no DTD.

# File lib/nokogiri/xml/document.rb, line 457
def xpath_doctype
  Nokogiri::CSS::XPathVisitor::DoctypeConfig::XML
end

Returns

The document type which determines CSS-to-XPath translation.

See XPathVisitor for more information.