Ruby » Ruby 1.8

require "rexml/element"

require "rexml/xmldecl"

require "rexml/source"

require "rexml/comment"

require "rexml/doctype"

require "rexml/instruction"

require "rexml/rexml"

require "rexml/parseexception"

require "rexml/output"

require "rexml/parsers/baseparser"

require "rexml/parsers/streamparser"

require "rexml/parsers/treeparser"

module REXML

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

        class Document < Element

                # 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

                DECLARATION = XMLDecl.default

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

                def initialize( source = nil, context = {} )

                        super()

                        @context = context

                        return if source.nil?

                        if source.kind_of? Document

                                @context = source.context

                                super source

                        else

                                build(  source )

                        end

                end

    def node_type

      :document

    end

                # Should be obvious

                def clone

                        Document.new self

                end

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

                def expanded_name

                        ''

                        #d = doc_type

                        #d ? d.name : "UNDEFINED"

                end

                alias :name :expanded_name

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

                # of the document

                def add( child )

                        if child.kind_of? XMLDecl

                                @children.unshift child

                        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

                alias :<< :add

                def add_element(arg=nil, arg2=nil)

                        rv = super

                        raise "attempted adding second root element to document" if @elements.size > 1

                        rv

                end

                # @return the root Element of the document, or nil if this document

                # has no children.

                def root

      elements[1]

      #self

      #@children.find { |item| item.kind_of? Element }

                end

                # @return the DocType child of the document, if one exists,

                # and nil otherwise.

                def doctype

                        @children.find { |item| item.kind_of? DocType }

                end

                # @return the XMLDecl of this document; if no XMLDecl has been

                # set, the default declaration is returned.

                def xml_decl

                        rv = @children[0]

      return rv if rv.kind_of? XMLDecl

      rv = @children.unshift(XMLDecl.default)[0]

                end

                # @return the XMLDecl version of this document as a String.

                # If no XMLDecl has been set, returns the default version.

                def version

                        xml_decl().version

                end

                # @return the XMLDecl encoding of this document as a String.

                # If no XMLDecl has been set, returns the default encoding.

                def encoding

                        xml_decl().encoding

                end

                # @return the XMLDecl standalone value of this document as a String.

                # If no XMLDecl has been set, returns the default setting.

                def stand_alone?

                        xml_decl().stand_alone?

                end

    # 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

                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 transitive

          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

                def Document::parse_stream( source, listener )

                        Parsers::StreamParser.new( source, listener ).parse

                end

                private

                def build( source )

      Parsers::TreeParser.new( source, self ).parse

                end

        end

end