Class: REXML::Document (Ruby 2.7.5)
Description: Class : REXML::Document - Ruby 2.7.5

### Home Classes Methods

### In Files

- rexml/document.rb

### Parent

Element

### Methods

- ::entity_expansion_limit
- ::entity_expansion_limit=
- ::entity_expansion_text_limit
- ::entity_expansion_text_limit=
- ::new
- ::parse_stream
- #<<
- #add
- #add_element
- #clone
- #doctype
- #document
- #encoding
- #expanded_name
- #name
- #node_type
- #record_entity_expansion
- #root
- #stand_alone?
- #version
- #write
- #xml_decl

### Class/Module Index

Quicksearch

- Array
- Float
- Integer
- Object
- REXML
- REXML::AttlistDecl
- REXML::Attribute
- REXML::Attributes
- REXML::CData
- REXML::Child
- REXML::Comment
- REXML::DTD
- REXML::DTD::AttlistDecl
- REXML::DTD::ElementDecl
- REXML::DTD::EntityDecl
- REXML::DTD::NotationDecl
- REXML::DTD::Parser
- REXML::Declaration
- REXML::DocType
- REXML::Document
- REXML::Element
- REXML::ElementDecl
- REXML::Elements
- REXML::Encoding
- REXML::Entity
- REXML::EntityConst
- REXML::ExternalEntity
- REXML::Formatters
- REXML::Formatters::Default
- REXML::Formatters::Pretty
- REXML::Formatters::Transitive
- REXML::Functions
- REXML::IOSource
- REXML::Instruction
- REXML::Light
- REXML::Light::Node
- REXML::Namespace
- REXML::Node
- REXML::NotationDecl
- REXML::Output
- REXML::Parent
- REXML::ParseException
- REXML::Parsers
- REXML::Parsers::BaseParser
- REXML::Parsers::LightParser
- REXML::Parsers::PullEvent
- REXML::Parsers::PullParser
- REXML::Parsers::SAX2Parser
- REXML::Parsers::StreamParser
- REXML::Parsers::TreeParser
- REXML::Parsers::UltraLightParser
- REXML::Parsers::XPathParser
- REXML::QuickPath
- REXML::ReferenceWriter
- REXML::SAX2Listener
- REXML::Security
- REXML::Source
- REXML::SourceFactory
- REXML::StreamListener
- REXML::Text
- REXML::UndefinedNamespaceException
- REXML::Validation
- REXML::Validation::Choice
- REXML::Validation::Event
- REXML::Validation::Interleave
- REXML::Validation::OneOrMore
- REXML::Validation::Optional
- REXML::Validation::Ref
- REXML::Validation::RelaxNG
- REXML::Validation::Sequence
- REXML::Validation::State
- REXML::Validation::ValidationException
- REXML::Validation::Validator
- REXML::Validation::ZeroOrMore
- REXML::XMLDecl
- REXML::XMLTokens
- REXML::XPath
- REXML::XPathNode
- REXML::XPathParser
- Symbol

No matching classes.

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

Deprecated. Use `REXML::Security.entity_expansion_limit=` instead.

                   # File rexml/document.rb, line 255
    def Document::entity_expansion_limit
      return Security.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.

Deprecated. Use `REXML::Security.entity_expansion_limit=` instead.

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

entity_expansion_text_limit() click to toggle source

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

Deprecated. Use `REXML::Security.entity_expansion_text_limit` instead.

                   # File rexml/document.rb, line 269
    def Document::entity_expansion_text_limit
      return Security.entity_expansion_text_limit
    end

entity_expansion_text_limit=( val ) click to toggle source

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

Deprecated. Use `REXML::Security.entity_expansion_text_limit=` instead.

                   # File rexml/document.rb, line 262
    def Document::entity_expansion_text_limit=( val )
      Security.entity_expansion_text_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 36
    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 241
    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 69
    def add( child )
      if child.kind_of? XMLDecl
        if @children[0].kind_of? XMLDecl
          @children[0] = child
        else
          @children.unshift child
        end
        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 = @children.find_index { |x|
          x.kind_of?(Element) || x.kind_of?(DocType)
        }
        if insert_before_index # Not null = not end of list
          if @children[ insert_before_index ].kind_of? DocType
            @children[ insert_before_index ] = child
          else
            @children[ insert_before_index-1, 0 ] = child
          end
        else  # Insert at end of list
          @children << 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 102
    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 54
    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 118
    def doctype
      @children.find { |item| item.kind_of? DocType }
    end

document() click to toggle source

                   # File rexml/document.rb, line 282
    def document
      self
    end

encoding() click to toggle source

@return the `XMLDecl` encoding of this document as an `Encoding` object. If no `XMLDecl` has been set, returns the default encoding.

                   # File rexml/document.rb, line 139
    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 59
    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 49
    def node_type
      :document
    end

record_entity_expansion() click to toggle source

                   # File rexml/document.rb, line 275
    def record_entity_expansion
      @entity_expansion_count += 1
      if @entity_expansion_count > Security.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 110
    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 145
    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 132
    def version
      xml_decl().version
    end

write(output=$stdout, indent=-1, transtive=false, ie_hack=false, encoding=nil) click to toggle source
write(options={:output => $stdout, :indent => -1, :transtive => false, :ie_hack => false, :encoding => nil})

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 unnecessary bandwidth to applications such as XML-RPC.

Accept Nth argument style and options Hash style as argument. The recommended style is options Hash style for one or more arguments case.

Examples

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

    output = ""
    Document.new("<a><b/></a>").write(output)

    output = ""
    Document.new("<a><b/></a>").write(:output => output, :indent => 2)

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

Examples

    output = ""
    tr = Transitive.new
    tr.write(Document.new("<a><b/></a>"), output)

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

transitive

  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

  This hack inserts a space before the /> on empty tags to address a limitation of Internet Explorer. Defaults to false

encoding

  `Encoding` name as String. Change output encoding to specified encoding instead of encoding in XML declaration. Defaults to nil. It means encoding in XML declaration is used.

                   # File rexml/document.rb, line 205
    def write(*arguments)
      if arguments.size == 1 and arguments[0].class == Hash
        options = arguments[0]

        output     = options[:output]
        indent     = options[:indent]
        transitive = options[:transitive]
        ie_hack    = options[:ie_hack]
        encoding   = options[:encoding]
      else
        output, indent, transitive, ie_hack, encoding, = *arguments
      end

      output   ||= $stdout
      indent   ||= -1
      transitive = false if transitive.nil?
      ie_hack    = false if ie_hack.nil?
      encoding ||= xml_decl.encoding

      if encoding != 'UTF-8' && !output.kind_of?(Output)
        output = Output.new( output, encoding )
      end
      formatter = if indent > -1
          if transitive
            require_relative "formatters/transitive"
            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 124
    def xml_decl
      rv = @children[0]
      return rv if rv.kind_of? XMLDecl
      @children.unshift(XMLDecl.default)[0]
    end