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.