Class Document

Class Document has methods from its superclasses and included modules; see:

• Tasks for Element.

• Tasks for Parent.

• Tasks for Child.

• Tasks for Node.

• Module Enumerable.

:include: ../tocs/document_toc.rdoc

New Document

Task: Create an Empty Document

Use method Document::new to create an empty document.

d = REXML::Document.new

Task: Parse a String into a New Document

Use method Document::new to parse an XML string into a new document:

xml_string = '<root><a/>text<b/>more<c/></root>'
d = REXML::Document.new(xml_string)
d.root # => <root> ... </>

Task: Parse an IO Stream into a New Document

Use method Document::new to parse an XML IO stream into a new document:

xml_string = '<root><a/>text<b/>more<c/></root>'
File.write('t.xml', xml_string)
d = File.open('t.xml', 'r') do |file|
  REXML::Document.new(file)
end
d.root # => <root> ... </>

Task: Create a Document from an Existing Document

Use method Document::new to create a document from an existing document. The context and attributes are copied to the new document, but not the children:

xml_string = '<root><a/>text<b/>more<c/></root>'
d = REXML::Document.new(xml_string)
d.children    # => [<root> ... </>]
d.context = {raw: :all, compress_whitespace: :all}
d.add_attributes({'bar' => 0, 'baz' => 1})
d1 = REXML::Document.new(d)
d1.context    # => {:raw=>:all, :compress_whitespace=>:all}
d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
d1.children   # => []

Task: Clone a Document

Use method Document#clone to clone a document. The context and attributes are copied to the new document, but not the children:

xml_string = '<root><a/>text<b/>more<c/></root>'
d = REXML::Document.new(xml_string)
d.children    # => [<root> ... </>]
d.context = {raw: :all, compress_whitespace: :all}
d.add_attributes({'bar' => 0, 'baz' => 1})
d1 = d.clone  # => < bar='0' baz='1'/>
d1.context    # => {:raw=>:all, :compress_whitespace=>:all}
d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
d1.children   # => []

Document Type

Task: Get the Document Type

Use method Document#doctype to get the document type:

d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
d.doctype.class # => REXML::DocType
d = REXML::Document.new('')
d.doctype.class # => nil

Task: Set the Document Type

Use method document#add to add or replace the document type:

d = REXML::Document.new('')
d.doctype.class # => nil
d.add(REXML::DocType.new('foo'))
d.doctype.class # => REXML::DocType

XML Declaration

Task: Get the XML Declaration

Use method document#xml_decl to get the XML declaration:

d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
d.xml_decl.class # => REXML::XMLDecl
d.xml_decl       # => <?xml ... ?>
d = REXML::Document.new('')
d.xml_decl.class # => REXML::XMLDecl
d.xml_decl       # => <?xml ... ?>

Task: Set the XML Declaration

Use method document#add to replace the XML declaration:

d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
d.add(REXML::XMLDecl.new)

Children

Task: Add an Element Child

Use method document#add_element to add an element to the document:

d = REXML::Document.new('')
d.add_element(REXML::Element.new('root'))
d.children # => [<root/>]

Task: Add a Non-Element Child

Use method document#add to add a non-element to the document:

xml_string = '<root><a/>text<b/>more<c/></root>'
d = REXML::Document.new(xml_string)
d.add(REXML::Text.new('foo'))
d.children # => [<root> ... </>, "foo"]

Writing

Task: Write to $stdout

Use method document#write to write the document to $stdout:

xml_string = '<root><a/>text<b/>more<c/></root>'
d = REXML::Document.new(xml_string)
d.write

Output:

<root><a/>text<b/>more<c/></root>

Task: Write to IO Stream

Use method document#write to write the document to $stdout:

xml_string = '<root><a/>text<b/>more<c/></root>'
d = REXML::Document.new(xml_string)
File.open('t.xml', 'w') do |file|
  d.write(file)
end
p File.read('t.xml')

Output:

"<root><a/>text<b/>more<c/></root>"

Task: Write with No Indentation

Use method document#write to write the document with no indentation:

xml_string = '<root><a><b><c></c></b></a></root>'
d = REXML::Document.new(xml_string)
d.write({indent: 0})

Output:

<root>
<a>
<b>
<c/>
</b>
</a>
</root>

Task: Write with Specified Indentation

Use method document#write to write the document with a specified indentation:

xml_string = '<root><a><b><c></c></b></a></root>'
d = REXML::Document.new(xml_string)
d.write({indent: 2})

Output:

<root>
  <a>
    <b>
      <c/>
    </b>
  </a>
</root>

Querying

Task: Get the Document

Use method document#document to get the document (self); overrides Element#document:

xml_string = '<root><a><b><c></c></b></a></root>'
d = REXML::Document.new(xml_string)
d.document == d # => true

Task: Get the Encoding

Use method document#document to get the document (self); overrides Element#document:

xml_string = '<root><a><b><c></c></b></a></root>'
d = REXML::Document.new(xml_string)
d.encoding # => "UTF-8"

Task: Get the Node Type

Use method document#node_type to get the node type (:document); overrides Element#node_type:

xml_string = '<root><a><b><c></c></b></a></root>'
d = REXML::Document.new(xml_string)
d.node_type # => :document

Task: Get the Root Element

Use method document#root to get the root element:

xml_string = '<root><a><b><c></c></b></a></root>'
d = REXML::Document.new(xml_string)
d.root # => <root> ... </>

Task: Determine Whether Stand-Alone

Use method document#stand_alone? to get the stand-alone value:

d = REXML::Document.new('<?xml standalone="yes"?>')
d.stand_alone? # => "yes"

Task: Get the Version

Use method document#version to get the version:

d = REXML::Document.new('<?xml version="2.0" encoding="UTF-8"?>')
d.version # => "2.0"