.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "Composer 3pm"
.TH Composer 3pm "2008-02-07" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
XML::Handler::Composer \- Another XML printer/writer/generator
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use XML::Handler::Composer;
.PP
my \f(CW$composer\fR = new XML::Handler::Composer ( [\s-1OPTIONS\s0] );
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
XML::Handler::Composer is similar to XML::Writer, XML::Handler::XMLWriter,
XML::Handler::YAWriter etc. in that it generates \s-1XML\s0 output.
.PP
This implementation may not be fast and it may not be the best solution for
your particular problem, but it has some features that may be missing in the
other implementations:
.IP "* Supports every output encoding that \s-1XML::UM\s0 supports" 4
.IX Item "Supports every output encoding that XML::UM supports"
\&\s-1XML::UM\s0 supports every encoding for which there is a mapping file 
in the XML::Encoding distribution.
.IP "* Pretty printing" 4
.IX Item "Pretty printing"
When used with XML::Filter::Reindent.
.IP "* Fine control over which kind of quotes are used" 4
.IX Item "Fine control over which kind of quotes are used"
See options below.
.IP "* Supports PerlSAX interface" 4
.IX Item "Supports PerlSAX interface"
.SH "Constructor Options"
.IX Header "Constructor Options"
.PD 0
.IP "* EndWithNewline (Default: 1)" 4
.IX Item "EndWithNewline (Default: 1)"
.PD
Whether to print a newline at the end of the file (i.e. after the root element)
.IP "* Newline (Default: undef)" 4
.IX Item "Newline (Default: undef)"
If defined, which newline to use for printing.
(Note that XML::Parser etc. convert newlines into \*(L"\ex0A\*(R".)
.Sp
If undef, newlines will not be converted and XML::Handler::Composer will
use \*(L"\ex0A\*(R" when printing.
.Sp
A value of \*(L"\en\*(R" will convert the internal newlines into the platform
specific line separator.
.Sp
See the PreserveWS option in the characters event (below) for finer control
over when newline conversion is active.
.IP "* DocTypeIndent (Default: a Newline and 2 spaces)" 4
.IX Item "DocTypeIndent (Default: a Newline and 2 spaces)"
Newline plus indent that is used to separate lines inside the \s-1DTD\s0.
.IP "* IndentAttList (Default: 8 spaces)" 4
.IX Item "IndentAttList (Default: 8 spaces)"
Indent used when printing an <!ATTLIST> declaration that has more than one
attribute definition, e.g.
.Sp
.Vb 4
\& <!ATTLIST my_elem
\&        attr1 CDATA "foo"
\&        attr2 CDATA "bar"
\& >
.Ve
.ie n .IP "* Quote (Default: { XMLDecl => '""', Attr => '""', Entity => '""', SystemLiteral => '""' })" 4
.el .IP "* Quote (Default: { XMLDecl => '``', Attr => '''', Entity => '``', SystemLiteral => '''' })" 4
.IX Item "Quote (Default: { XMLDecl => '', Attr => '', Entity => '', SystemLiteral => '' })"
Quote contains a reference to a hash that defines which quoting characters 
to use when printing \s-1XML\s0 declarations (XMLDecl), attribute values (Attr), 
<!ENTITY> values (Entity) and system/public literals (SystemLiteral) 
as found in <!DOCTYPE>, <!ENTITY> declarations etc.
.IP "* PrintDefaultAttr (Default: 0)" 4
.IX Item "PrintDefaultAttr (Default: 0)"
If 1, prints attribute values regardless of whether they are default 
attribute values (as defined in <!ATTLIST> declarations.)
Normally, default attributes are not printed.
.IP "* Encoding (Default: undef)" 4
.IX Item "Encoding (Default: undef)"
Defines the output encoding (if specified.) 
Note that future calls to the \fIxml_decl()\fR handler may override this setting
(if they contain an Encoding definition.)
.IP "* EncodeUnmapped (Default: \e&XML::UM::encode_unmapped_dec)" 4
.IX Item "EncodeUnmapped (Default: &XML::UM::encode_unmapped_dec)"
Defines how Unicode characters not found in the mapping file (of the 
specified encoding) are printed. 
By default, they are converted to decimal entity references, like '&#123;'
.Sp
Use \e&XML::UM::encode_unmapped_hex for hexadecimal constants, like '&#xAB;'
.ie n .IP "* Print (Default: sub { print @_ }, which prints to stdout)" 4
.el .IP "* Print (Default: sub { print \f(CW@_\fR }, which prints to stdout)" 4
.IX Item "Print (Default: sub { print @_ }, which prints to stdout)"
The subroutine that is used to print the encoded \s-1XML\s0 output.
The default prints the string to stdout.
.SH "Method: get_compressed_element_suffix ($event)"
.IX Header "Method: get_compressed_element_suffix ($event)"
Override this method to support the different styles for printing
empty elements in compressed notation, e.g. <p/>, <p></p>, <p />, <p>.
.PP
The default returns \*(L"/>\*(R", which results in <p/>.
Use \*(L" />\*(R" for \s-1XHTML\s0 style elements or \*(L">\*(R" for certain \s-1HTML\s0 style elements.
.PP
The \f(CW$event\fR parameter is the hash reference that was received from the
\&\fIstart_element()\fR handler.
.SH "Extra PerlSAX event information"
.IX Header "Extra PerlSAX event information"
XML::Handler::Composer relies on hints from previous \s-1SAX\s0 filters to
format certain parts of the \s-1XML\s0. 
These \s-1SAX\s0 filters (e.g. XML::Filter::Reindent) pass extra information by adding
name/value pairs to the appropriate PerlSAX events (the events themselves are 
hash references.)
.IP "* entity_reference: Parameter => 1" 4
.IX Item "entity_reference: Parameter => 1"
If Parameter is 1, it means that it is a parameter entity reference. 
A parameter entity is referenced with \f(CW%ent\fR; instead of &ent; and the
entity declaration starts with <!ENTITY % ent ...> instead of <!ENTITY ent ...>
.Sp
\&\s-1NOTE:\s0 This should be added to the PerlSAX interface!
.IP "* start_element/end_element: Compress => 1" 4
.IX Item "start_element/end_element: Compress => 1"
If Compress is 1 in both the start_element and end_element event, the element
will be printed in compressed form, e.g. <a/> instead of <a></a>.
.IP "* start_element: PreserveWS => 1" 4
.IX Item "start_element: PreserveWS => 1"
If newline conversion is active (i.e. Newline was defined in the constructor),
then newlines will *NOT* be converted in text (character events) within this
element.
.IP "* attlist_decl: First, MoreFollow" 4
.IX Item "attlist_decl: First, MoreFollow"
The First and MoreFollow options can be used to force successive <!ATTLIST>
declarations for the same element to be merged, e.g.
.Sp
.Vb 5
\& <!ATTLIST my_elem
\&        attr1 CDATA "foo"
\&        attr2 CDATA "bar"
\&        attr3 CDATA "quux"
\& >
.Ve
.Sp
In this example, the attlist_decl event for foo should contain
(First => 1, MoreFollow => 1) and the event for bar should contain 
(MoreFollow => 1). The quux event should have no extra info.
.Sp
\&'First' indicates that the event is the first of a sequence.
\&'MoreFollow' indicates that more events will follow in this sequence.
.Sp
If neither option is set by the preceding PerlSAX filter, each attribute
definition will be printed as a separate <!ATTLIST> line.
.SH "CAVEATS"
.IX Header "CAVEATS"
This code is highly experimental! 
It has not been tested well and the \s-1API\s0 may change.
.SH "AUTHOR"
.IX Header "AUTHOR"
Enno Derksen is the original author.
.PP
Send bug reports, hints, tips, suggestions to T.J. Mather at
<\fItjmather@tjmather.com\fR>.