File Content: document.rdoc == Class Document Class Document has methods from its superclasses and included modules; see: - {Tasks for Element}[element_rdoc.html]. - {Tasks for Parent}[parent_rdoc.html]. - {Tasks for Child}[child_rdoc.html]. - {Tasks for Node}[node_rdoc.html]. - {Module Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html]. :include: ../tocs/document_toc.rdoc === New Document ==== Task: Create an Empty Document Use method {Document::new}[../../../../REXML/Document.html#method-c-new] to create an empty document. d = REXML::Document.new ==== Task: Parse a \String into a New Document Use method {Document::new}[../../../../REXML/Document.html#method-c-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}[../../../../REXML/Document.html#method-c-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}[../../../../REXML/Document.html#method-c-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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-write] to write the document to <tt>$stdout</tt>: 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}[../../../../REXML/Document.html#method-i-write] to write the document to <tt>$stdout</tt>: 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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-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}[../../../../REXML/Document.html#method-i-document] to get the document (+self+); overrides <tt>Element#document</tt>: 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}[../../../../REXML/Document.html#method-i-document] to get the document (+self+); overrides <tt>Element#document</tt>: 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}[../../../../REXML/Document.html#method-i-node_type] to get the node type (+:document+); overrides <tt>Element#node_type</tt>: 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}[../../../../REXML/Document.html#method-i-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?}[../../../../REXML/Document.html#method-i-stand_alone-3F] 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}[../../../../REXML/Document.html#method-i-version] to get the version: d = REXML::Document.new('<?xml version="2.0" encoding="UTF-8"?>') d.version # => "2.0" Submit