NAME

       WebKDC::XmlDoc - Manipulate a document of WebKDC::XmlElement objects

SYNOPSIS

           use WebKDC::XmlDoc;

           my $doc = WebKDC::XmlDoc->new;
           $doc->start ('root');
           $doc->start ('child', { key => 'value' }, 'some content');
           $doc->add ('subchild, 'more content');
           print $doc->current->name, "\n";
           $doc->end;
           $doc->end;
           print $doc->root->name, "\n";

DESCRIPTION

       A WebKDC::XmlDoc represents an XML document as a tree of WebKDC::XmlElement objects.  It
       is used internally by the WebKDC module to create and parse XML documents when talking to
       a WebAuth WebKDC.

       A (non-empty) document has a root element and a stack of open elements.  It is assembled
       by starting an element (with start(), possibly including attributes and content),
       manipulating that element if necessary, and then ending the element, done recursively.
       Once an element has been ended, there is no way using this interface to further change it,
       although it can be retrieved by getting the root of the tree with root() and then walking
       the tree.  add() is an optimization that combines start() and end() and is more efficient
       if an element has no child elements.

       Most manipulation of this document is done via the WebKDC::XmlElement methods, which allow
       parsing an XML document into this format, finding children of a particular element, and
       converting a document to its XML representation.  This module only defines the top-level
       structure and the methods that have to be called on the document as a whole rather than on
       an individual element.

CLASS METHODS

       new ()
           Create a new, empty document.  This document will have no root.  The first element
           added with start() or add() will become the root of the document.

INSTANCE METHODS

       add (NAME[, ATTRS[, CONTENT]])
           Add a new element with name NAME as a child of the current element and immediately
           close it, equivalent to start() followed immediately by end().  Optional attributes
           (which should be an anonymous hash of names and values) and content (which should be a
           string) may be provided.  To provide CONTENT without ATTRS, pass "{}" as ATTRS.
           Returns the WebKDC::XmlDoc object.

           If the document is empty, the new element becomes the root.

       current ()
           Returns the current element as a WebKDC::XmlElement object.  The current element is
           the most recent element opened by start() and not yet closed with end().

       end ([NAME])
           End the current element.  If the optional NAME parameter is given, throw an exception
           and take no action if the current open element is not named NAME.  Returns the
           WebKDC::XmlDoc object.

       root ()
           Returns the root WebKDC::XmlElement object of the document or undef if the document is
           empty.  To convert the entire document to XML, use:

               my $xml = $doc->root->to_string;

           (which uses the to_string() method of WebKDC::XmlElement).

       start (NAME[, ATTRS[, CONTENT]])
           Add a new element with name NAME as a child of the current element and make the new
           element the current element (so subsequent elements added by start() or add() will be
           children of it) until the next end().  Optional attributes (which should be an
           anonymous hash of names and values) and content (which should be a string) may be
           provided.  To provide CONTENT without ATTRS, pass "{}" as ATTRS.  Returns the
           WebKDC::XmlDoc object.

           If the document is empty, the new element becomes the root.

AUTHOR

       Roland Schemers and Russ Allbery <eagle@eyrie.org>

SEE ALSO

       WebKDC(3), WebKDC::XmlElement(3)

       This module is part of WebAuth.  The current version is available from
       <http://webauth.stanford.edu/>.