document - rexml: Ruby Standard Library Documentation

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

Tasks on this page:

- New Document

  - Task: Create an Empty Document

  - Task: Parse a String into a New Document

  - Task: Parse an IO Stream into a New Document

  - Task: Create a Document from an Existing Document

  - Task: Clone a Document

- Document Type

  - Task: Get the Document Type

  - Task: Set the Document Type

- XML Declaration

  - Task: Get the XML Declaration

  - Task: Set the XML Declaration

- Children

  - Task: Add an Element Child

  - Task: Add a Non-Element Child

- Writing

  - Task: Write to $stdout

  - Task: Write to IO Stream

  - Task: Write with No Indentation

  - Task: Write with Specified Indentation

- Querying

  - Task: Get the Document

  - Task: Get the Encoding

  - Task: Get the Node Type

  - Task: Get the Root Element

  - Task: Determine Whether Stand-Alone

  - Task: Get the Version

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