.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "WebKDC::XmlDoc 3pm" .TH WebKDC::XmlDoc 3pm "2019-01-05" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" WebKDC::XmlDoc \- Manipulate a document of WebKDC::XmlElement objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use WebKDC::XmlDoc; \& \& my $doc = WebKDC::XmlDoc\->new; \& $doc\->start (\*(Aqroot\*(Aq); \& $doc\->start (\*(Aqchild\*(Aq, { key => \*(Aqvalue\*(Aq }, \*(Aqsome content\*(Aq); \& $doc\->add (\*(Aqsubchild, \*(Aqmore content\*(Aq); \& print $doc\->current\->name, "\en"; \& $doc\->end; \& $doc\->end; \& print $doc\->root\->name, "\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A WebKDC::XmlDoc represents an \s-1XML\s0 document as a tree of WebKDC::XmlElement objects. It is used internally by the WebKDC module to create and parse \s-1XML\s0 documents when talking to a WebAuth WebKDC. .PP A (non-empty) document has a root element and a stack of open elements. It is assembled by starting an element (with \fBstart()\fR, 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 \fBroot()\fR and then walking the tree. \fBadd()\fR is an optimization that combines \fBstart()\fR and \fBend()\fR and is more efficient if an element has no child elements. .PP Most manipulation of this document is done via the WebKDC::XmlElement methods, which allow parsing an \s-1XML\s0 document into this format, finding children of a particular element, and converting a document to its \s-1XML\s0 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. .SH "CLASS METHODS" .IX Header "CLASS METHODS" .IP "new ()" 4 .IX Item "new ()" Create a new, empty document. This document will have no root. The first element added with \fBstart()\fR or \fBadd()\fR will become the root of the document. .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" .IP "add (NAME[, ATTRS[, \s-1CONTENT\s0]])" 4 .IX Item "add (NAME[, ATTRS[, CONTENT]])" Add a new element with name \s-1NAME\s0 as a child of the current element and immediately close it, equivalent to \fBstart()\fR followed immediately by \fBend()\fR. Optional attributes (which should be an anonymous hash of names and values) and content (which should be a string) may be provided. To provide \s-1CONTENT\s0 without \s-1ATTRS,\s0 pass \f(CW\*(C`{}\*(C'\fR as \s-1ATTRS.\s0 Returns the WebKDC::XmlDoc object. .Sp If the document is empty, the new element becomes the root. .IP "current ()" 4 .IX Item "current ()" Returns the current element as a WebKDC::XmlElement object. The current element is the most recent element opened by \fBstart()\fR and not yet closed with \fBend()\fR. .IP "end ([\s-1NAME\s0])" 4 .IX Item "end ([NAME])" End the current element. If the optional \s-1NAME\s0 parameter is given, throw an exception and take no action if the current open element is not named \&\s-1NAME.\s0 Returns the WebKDC::XmlDoc object. .IP "root ()" 4 .IX Item "root ()" Returns the root WebKDC::XmlElement object of the document or undef if the document is empty. To convert the entire document to \s-1XML,\s0 use: .Sp .Vb 1 \& my $xml = $doc\->root\->to_string; .Ve .Sp (which uses the \fBto_string()\fR method of WebKDC::XmlElement). .IP "start (NAME[, ATTRS[, \s-1CONTENT\s0]])" 4 .IX Item "start (NAME[, ATTRS[, CONTENT]])" Add a new element with name \s-1NAME\s0 as a child of the current element and make the new element the current element (so subsequent elements added by \&\fBstart()\fR or \fBadd()\fR will be children of it) until the next \fBend()\fR. Optional attributes (which should be an anonymous hash of names and values) and content (which should be a string) may be provided. To provide \s-1CONTENT\s0 without \s-1ATTRS,\s0 pass \f(CW\*(C`{}\*(C'\fR as \s-1ATTRS.\s0 Returns the WebKDC::XmlDoc object. .Sp If the document is empty, the new element becomes the root. .SH "AUTHOR" .IX Header "AUTHOR" Roland Schemers and Russ Allbery .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBWebKDC\fR\|(3), \fBWebKDC::XmlElement\fR\|(3) .PP This module is part of WebAuth. The current version is available from .