REXML::Document

Represents a full XML document, including PIs, a doctype, etc. A Document has a single child that can be accessed by root(). Note that if you want to have an XML declaration written for a document you create, you must add one; REXML documents do not write a default declaration for you. See |DECLARATION| and |write|.

Constants

DECLARATION: A convenient default XML declaration. If you want an XML declaration, the easiest way to add one is mydoc << Document::DECLARATION DEPRECATED Use: mydoc << REXML::XMLDecl.default

Attributes

entity_expansion_count[R]

Public Class Methods

entity_expansion_limit() click to toggle source

Get the entity expansion limit. By default the limit is set to 10000.

 
               # File rexml/document.rb, line 212
def Document::entity_expansion_limit
  return @@entity_expansion_limit
end

entity_expansion_limit=( val ) click to toggle source

Set the entity expansion limit. By default the limit is set to 10000.

 
               # File rexml/document.rb, line 207
def Document::entity_expansion_limit=( val )
  @@entity_expansion_limit = val
end

new( source = nil, context = {} ) click to toggle source

Constructor @param source if supplied, must be a Document, String, or IO. Documents have their context and Element attributes cloned. Strings are expected to be valid XML documents. IOs are expected to be sources of valid XML documents. @param context if supplied, contains the context of the document; this should be a Hash.

 
               # File rexml/document.rb, line 34
          def initialize( source = nil, context = {} )
@entity_expansion_count = 0
                  super()
                  @context = context
                  return if source.nil?
                  if source.kind_of? Document
                          @context = source.context
                          super source
                  else
                          build(  source )
                  end
          end

parse_stream( source, listener ) click to toggle source

 
               # File rexml/document.rb, line 200
def Document::parse_stream( source, listener )
        Parsers::StreamParser.new( source, listener ).parse
end

Public Instance Methods

<<( child ) click to toggle source

Alias for: add

add( child ) click to toggle source

We override this, because XMLDecls and DocTypes must go at the start of the document

 
               # File rexml/document.rb, line 67
        def add( child )
                if child.kind_of? XMLDecl
                        @children.unshift child
child.parent = self
                elsif child.kind_of? DocType
# Find first Element or DocType node and insert the decl right
# before it.  If there is no such node, just insert the child at the
# end.  If there is a child and it is an DocType, then replace it.
insert_before_index = 0
@children.find { |x| 
  insert_before_index += 1
  x.kind_of?(Element) || x.kind_of?(DocType)
}
if @children[ insert_before_index ] # Not null = not end of list
  if @children[ insert_before_index ].kind_of DocType
    @children[ insert_before_index ] = child
  else
    @children[ index_before_index-1, 0 ] = child
  end
else  # Insert at end of list
  @children[insert_before_index] = child
end
                        child.parent = self
                else
                        rv = super
                        raise "attempted adding second root element to document" if @elements.size > 1
                        rv
                end
        end

Also aliased as: <<

add_element(arg=nil, arg2=nil) click to toggle source

 
               # File rexml/document.rb, line 98
def add_element(arg=nil, arg2=nil)
        rv = super
        raise "attempted adding second root element to document" if @elements.size > 1
        rv
end

clone() click to toggle source

Should be obvious

 
               # File rexml/document.rb, line 52
def clone
        Document.new self
end

doctype() click to toggle source

@return the DocType child of the document, if one exists, and nil otherwise.

 
               # File rexml/document.rb, line 114
def doctype
        @children.find { |item| item.kind_of? DocType }
end

encoding() click to toggle source

@return the XMLDecl encoding of this document as a String. If no XMLDecl has been set, returns the default encoding.

 
               # File rexml/document.rb, line 134
def encoding
        xml_decl().encoding
end

expanded_name() click to toggle source

According to the XML spec, a root node has no expanded name

 
               # File rexml/document.rb, line 57
def expanded_name
        ''
        #d = doc_type
        #d ? d.name : "UNDEFINED"
end

Also aliased as: name

name() click to toggle source

Alias for: expanded_name

node_type() click to toggle source

 
               # File rexml/document.rb, line 47
def node_type
  :document
end

record_entity_expansion() click to toggle source

 
               # File rexml/document.rb, line 218
def record_entity_expansion
  @entity_expansion_count += 1
  if @entity_expansion_count > @@entity_expansion_limit
    raise "number of entity expansions exceeded, processing aborted."
  end
end

root() click to toggle source

@return the root Element of the document, or nil if this document has no children.

 
               # File rexml/document.rb, line 106
          def root
elements[1]
#self
#@children.find { |item| item.kind_of? Element }
          end

stand_alone?() click to toggle source

@return the XMLDecl standalone value of this document as a String. If no XMLDecl has been set, returns the default setting.

 
               # File rexml/document.rb, line 140
def stand_alone?
        xml_decl().stand_alone?
end

version() click to toggle source

@return the XMLDecl version of this document as a String. If no XMLDecl has been set, returns the default version.

 
               # File rexml/document.rb, line 128
def version
        xml_decl().version
end

write( output=$stdout, indent=-1, trans=false, ie_hack=false ) click to toggle source

Write the XML tree out, optionally with indent. This writes out the entire XML document, including XML declarations, doctype declarations, and processing instructions (if any are given).

A controversial point is whether Document should always write the XML declaration (<?xml version='1.0'?>) whether or not one is given by the user (or source document). REXML does not write one if one was not specified, because it adds unneccessary bandwidth to applications such as XML-RPC.

See also the classes in the rexml/formatters package for the proper way to change the default formatting of XML output

Examples

Document.new("<a><b/></a>").serialize

output_string = ""
tr = Transitive.new( output_string )
Document.new("<a><b/></a>").serialize( tr )

output: output an object which supports '<< string'; this is where the

document will be written.

indent: An integer. If -1, no indenting will be used; otherwise, the indentation will be twice this number of spaces, and children will be indented an additional amount. For a value of 3, every item will be indented 3 more levels, or 6 more spaces (2 * 3). Defaults to -1
trans: If transitive is true and indent is >= 0, then the output will be pretty-printed in such a way that the added whitespace does not affect the absolute value of the document – that is, it leaves the value and number of Text nodes in the document unchanged.
ie_hack: Internet Explorer is the worst piece of crap to have ever been written, with the possible exception of Windows itself. Since IE is unable to parse proper XML, we have to provide a hack to generate XML that IE's limited abilities can handle. This hack inserts a space before the /> on empty tags. Defaults to false

 
               # File rexml/document.rb, line 183
          def write( output=$stdout, indent=-1, trans=false, ie_hack=false )
if xml_decl.encoding != "UTF-8" && !output.kind_of?(Output)
  output = Output.new( output, xml_decl.encoding )
end
formatter = if indent > -1
    if trans
      REXML::Formatters::Transitive.new( indent, ie_hack )
    else
      REXML::Formatters::Pretty.new( indent, ie_hack )
    end
  else
    REXML::Formatters::Default.new( ie_hack )
  end
formatter.write( self, output )
          end

xml_decl() click to toggle source

@return the XMLDecl of this document; if no XMLDecl has been set, the default declaration is returned.

 
               # File rexml/document.rb, line 120
          def xml_decl
                  rv = @children[0]
return rv if rv.kind_of? XMLDecl
rv = @children.unshift(XMLDecl.default)[0]
          end

Home Classes Methods

In Files

Parent

Methods

Class/Module Index

REXML::Document

Constants

Attributes

Public Class Methods

Public Instance Methods