.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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 "XML::AutoWriter 3pm"
.TH XML::AutoWriter 3pm "2014-09-17" "perl v5.20.0" "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"
XML::AutoWriter \- DOCTYPE based XML output
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&   use XML::Doctype         NAME => a, SYSTEM_ID => \*(Aqa.dtd\*(Aq ;
\&   use XML::AutoWriter qw( :all :dtd_tags ) ;
\&   #
\&   # a.dtd contains:
\&   #
\&   #   <!ELEMENT a ( b1, b2?, b3* ) >
\&   #      <!ATTLIST   a aa1 CDATA       #REQUIRED >
\&   #   <!ELEMENT b1 ( c1 ) >
\&   #   <!ELEMENT b2 ( c2 ) >
\&   #
\&   b1 ;                # Emits <a><b1>
\&   c2( attr=>"val" ) ; # Emits </b1><b2><c2 attr="val">
\&   endAllTags ;        # Emits </c2></b2></a>
\&
\&   ## If you\*(Aqve got an XML::Doctype object handy:
\&   use XML::AutoWriter qw( :dtd_tags ), DOCTYPE => $doctype ;
\&
\&   ## If you\*(Aqve saved a preparsed DTD as a perl module
\&   use FooML::Doctype::v1_0001 ;
\&   use XML::AutoWriter qw( :dtd_tags ) ;
\&
\&   ## Or as a normal perl object:
\&   $writer = XML::AutoWriter\->new( ... ) ;
\&   $writer\->startTag( \*(Aqb1\*(Aq ) ;
\&   $writer\->startTag( \*(Aqc2\*(Aq ) ;
\&   $writer\->end ;
.Ve
.SH "STATUS"
.IX Header "STATUS"
Alpha.  Use and patch, don't depend on things not changing drastically.
.PP
Many methods supplied by XML::Writer are not yet supplied here.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module subclasses XML::ValidWriter and provides automatic
start and end tag generation, allowing you to emit only the 'important'
tags.
.PP
See XML::ValidWriter for the details on all functions not documented
here.
.SS "XML::Writer \s-1API\s0 compatibility"
.IX Subsection "XML::Writer API compatibility"
Much of the interface is patterned
after XML::Writer so that it can possibly be used as a drop-in
replacement.  It will take awhile before this module emulates enough
of XML::Writer to be a drop-in replacement in situations where the
more advanced XML::Writer methods are used.
.SS "Automatic start tags"
.IX Subsection "Automatic start tags"
Automatic start tag creation is done when emitting a start tag that is
not allowed to be a child of the currently open tag
but is allowed to be contained in the currently open tag's subset.  In
this case, the minimal number of start tags necessary to allow
All start tags between the current tag and the desired tag are automatically
emitted with no attributes.
.SS "Automatic end tags"
.IX Subsection "Automatic end tags"
If start tag autogeneration fails, then end tag autogeneration is attempted.
\&\fIstartTag()\fR scans the stack of currently open tags trying to close as few as
possible before start tag autogeneration suceeds.
.PP
Explicit end tags may be emitted to prevent unwanted automatic start
tags, and, in the future, warnings or errors will be available in place
of automatic start and end tag creation.
.SH "METHODS AND FUNCTIONS"
.IX Header "METHODS AND FUNCTIONS"
All of the routines in this module can be called as either functions
or methods unless otherwise noted.
.PP
To call these routines as functions use either the \s-1DOCTYPE\s0 or
:dtd_tags options in the parameters to the use statement:
.PP
.Vb 2
\&   use XML::AutoWriter DOCTYPE => XML::Doctype\->new( ... ) ;
\&   use XML::AutoWriter qw( :dtd_tags ) ;
.Ve
.PP
This associates an XML::AutoWriter and an XML::Doctype with the
package.  These are used by the routines when called as functions.
.IP "new" 4
.IX Item "new"
.Vb 1
\&   $writer = XML::AutoWriter\->new( DTD => $dtd, OUTPUT => \e*FH ) ;
.Ve
.Sp
Creates an XML::AutoWriter.
.Sp
All other parameters are passed to
the XML::ValidWriter base class constructor.
.IP "characters" 4
.IX Item "characters"
.Vb 2
\&   characters( \*(Aqyabba dabba dooo\*(Aq ) ;
\&   $writer\->characters( \*(Aqyabba dabba dooo\*(Aq ) ;
.Ve
.Sp
If the currently open tag cannot contain #PCDATA, then start tag autogeneration
will be attempted, followed by end tag autogeneration.
.Sp
Start tag autogeneration takes place even if you pass in only '', or even (),
the empty list.
.IP "endTag" 4
.IX Item "endTag"
.Vb 4
\&   endTag ;
\&   endTag( \*(Aqa\*(Aq ) ;
\&   $writer\->endTag ;
\&   $writer\->endTag( \*(Aqa\*(Aq ) ;
.Ve
.Sp
Prints one or more end tags.  The tag name is optional and defaults to the
most recently emitted start tag if not present.
.Sp
This will emit as many close tags as necessary to close the supplied tag
name, or will emit an error if the tag name specified is not open in the
output document.
.IP "startTag" 4
.IX Item "startTag"
.Vb 3
\&   startTag( \*(Aqa\*(Aq, attr => val ) ;  # use default XML::AutoWriter for
\&                                   # current package.
\&   $writer\->startTag( \*(Aqa\*(Aq, attr => val ) ;
.Ve
.Sp
Emits a named start tag with optional attributes.  If the named tag
cannot be a child of the most recently started tag, then any tags
that need to be opened between that one and the named tag are opened.
.Sp
If the named tag cannot be enclosed within the most recently opened
tag, no matter how deep, then \fIstartTag()\fR tries to end as few started tags
as necessary to allow the named tag to be emitted within a tag already on the
stack.
.Sp
This warns (once) if no <?xml?> declaration has been emitted.  It does not
check to see if a <!DOCTYPE...> has been emitted.  It dies if an attempt
is made to emit a second root element.
.SH "AUTHOR"
.IX Header "AUTHOR"
Barrie Slaymaker <barries@slaysys.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is Copyright 2000, 2005, 2009 Barrie Slaymaker.  Some rights reserved.
.PP
This module is licensed under your choice of the Artistic, \s-1BSD\s0 or
General Public License.