local-lib5/man/man3/XML::Simple.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "XML::Simple 3"
 127 .TH XML::Simple 3 "2007-08-15" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XML::Simple \- Easy API to maintain XML (esp config files)
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use XML::Simple;
 138 \&
 139 \&    my $ref = XMLin([<xml file or string>] [, <options>]);
 140 \&
 141 \&    my $xml = XMLout($hashref [, <options>]);
 142 .Ve
 143 .PP
 144 Or the object oriented way:
 145 .PP
 146 .Vb 1
 147 \&    require XML::Simple;
 148 \&
 149 \&    my $xs = XML::Simple\->new(options);
 150 \&
 151 \&    my $ref = $xs\->XMLin([<xml file or string>] [, <options>]);
 152 \&
 153 \&    my $xml = $xs\->XMLout($hashref [, <options>]);
 154 .Ve
 155 .PP
 156 (or see \*(L"\s-1SAX\s0 \s-1SUPPORT\s0\*(R" for 'the \s-1SAX\s0 way').
 157 .PP
 158 To catch common errors:
 159 .PP
 160 .Vb 1
 161 \&    use XML::Simple qw(:strict);
 162 .Ve
 163 .PP
 164 (see \*(L"\s-1STRICT\s0 \s-1MODE\s0\*(R" for more details).
 165 .SH "QUICK START"
 166 .IX Header "QUICK START"
 167 Say you have a script called \fBfoo\fR and a file of configuration options
 168 called \fBfoo.xml\fR containing this:
 169 .PP
 170 .Vb 10
 171 \&  <config logdir="/var/log/foo/" debugfile="/tmp/foo.debug">
 172 \&    <server name="sahara" osname="solaris" osversion="2.6">
 173 \&      <address>10.0.0.101</address>
 174 \&      <address>10.0.1.101</address>
 175 \&    </server>
 176 \&    <server name="gobi" osname="irix" osversion="6.5">
 177 \&      <address>10.0.0.102</address>
 178 \&    </server>
 179 \&    <server name="kalahari" osname="linux" osversion="2.0.34">
 180 \&      <address>10.0.0.103</address>
 181 \&      <address>10.0.1.103</address>
 182 \&    </server>
 183 \&  </config>
 184 .Ve
 185 .PP
 186 The following lines of code in \fBfoo\fR:
 187 .PP
 188 .Vb 1
 189 \&  use XML::Simple;
 190 \&
 191 \&  my $config = XMLin();
 192 .Ve
 193 .PP
 194 will 'slurp' the configuration options into the hashref \f(CW$config\fR (because no
 195 arguments are passed to \f(CW\*(C`XMLin()\*(C'\fR the name and location of the \s-1XML\s0 file will
 196 be inferred from name and location of the script).  You can dump out the
 197 contents of the hashref using Data::Dumper:
 198 .PP
 199 .Vb 1
 200 \&  use Data::Dumper;
 201 \&
 202 \&  print Dumper($config);
 203 .Ve
 204 .PP
 205 which will produce something like this (formatting has been adjusted for
 206 brevity):
 207 .PP
 208 .Vb 10
 209 \&  {
 210 \&      \*(Aqlogdir\*(Aq        => \*(Aq/var/log/foo/\*(Aq,
 211 \&      \*(Aqdebugfile\*(Aq     => \*(Aq/tmp/foo.debug\*(Aq,
 212 \&      \*(Aqserver\*(Aq        => {
 213 \&          \*(Aqsahara\*(Aq        => {
 214 \&              \*(Aqosversion\*(Aq     => \*(Aq2.6\*(Aq,
 215 \&              \*(Aqosname\*(Aq        => \*(Aqsolaris\*(Aq,
 216 \&              \*(Aqaddress\*(Aq       => [ \*(Aq10.0.0.101\*(Aq, \*(Aq10.0.1.101\*(Aq ]
 217 \&          },
 218 \&          \*(Aqgobi\*(Aq          => {
 219 \&              \*(Aqosversion\*(Aq     => \*(Aq6.5\*(Aq,
 220 \&              \*(Aqosname\*(Aq        => \*(Aqirix\*(Aq,
 221 \&              \*(Aqaddress\*(Aq       => \*(Aq10.0.0.102\*(Aq
 222 \&          },
 223 \&          \*(Aqkalahari\*(Aq      => {
 224 \&              \*(Aqosversion\*(Aq     => \*(Aq2.0.34\*(Aq,
 225 \&              \*(Aqosname\*(Aq        => \*(Aqlinux\*(Aq,
 226 \&              \*(Aqaddress\*(Aq       => [ \*(Aq10.0.0.103\*(Aq, \*(Aq10.0.1.103\*(Aq ]
 227 \&          }
 228 \&      }
 229 \&  }
 230 .Ve
 231 .PP
 232 Your script could then access the name of the log directory like this:
 233 .PP
 234 .Vb 1
 235 \&  print $config\->{logdir};
 236 .Ve
 237 .PP
 238 similarly, the second address on the server 'kalahari' could be referenced as:
 239 .PP
 240 .Vb 1
 241 \&  print $config\->{server}\->{kalahari}\->{address}\->[1];
 242 .Ve
 243 .PP
 244 What could be simpler?  (Rhetorical).
 245 .PP
 246 For simple requirements, that's really all there is to it.  If you want to
 247 store your \s-1XML\s0 in a different directory or file, or pass it in as a string or
 248 even pass it in via some derivative of an IO::Handle, you'll need to check out
 249 \&\*(L"\s-1OPTIONS\s0\*(R".  If you want to turn off or tweak the array folding feature (that
 250 neat little transformation that produced \f(CW$config\fR\->{server}) you'll find options
 251 for that as well.
 252 .PP
 253 If you want to generate \s-1XML\s0 (for example to write a modified version of
 254 \&\f(CW$config\fR back out as \s-1XML\s0), check out \f(CW\*(C`XMLout()\*(C'\fR.
 255 .PP
 256 If your needs are not so simple, this may not be the module for you.  In that
 257 case, you might want to read \*(L"\s-1WHERE\s0 \s-1TO\s0 \s-1FROM\s0 \s-1HERE\s0?\*(R".
 258 .SH "DESCRIPTION"
 259 .IX Header "DESCRIPTION"
 260 The XML::Simple module provides a simple \s-1API\s0 layer on top of an underlying \s-1XML\s0
 261 parsing module (either XML::Parser or one of the \s-1SAX2\s0 parser modules).  Two
 262 functions are exported: \f(CW\*(C`XMLin()\*(C'\fR and \f(CW\*(C`XMLout()\*(C'\fR.  Note: you can explicity
 263 request the lower case versions of the function names: \f(CW\*(C`xml_in()\*(C'\fR and
 264 \&\f(CW\*(C`xml_out()\*(C'\fR.
 265 .PP
 266 The simplest approach is to call these two functions directly, but an
 267 optional object oriented interface (see \*(L"\s-1OPTIONAL\s0 \s-1OO\s0 \s-1INTERFACE\s0\*(R" below)
 268 allows them to be called as methods of an \fBXML::Simple\fR object.  The object
 269 interface can also be used at either end of a \s-1SAX\s0 pipeline.
 270 .SS "\fIXMLin()\fP"
 271 .IX Subsection "XMLin()"
 272 Parses \s-1XML\s0 formatted data and returns a reference to a data structure which
 273 contains the same information in a more readily accessible form.  (Skip
 274 down to \*(L"\s-1EXAMPLES\s0\*(R" below, for more sample code).
 275 .PP
 276 \&\f(CW\*(C`XMLin()\*(C'\fR accepts an optional \s-1XML\s0 specifier followed by zero or more 'name =>
 277 value' option pairs.  The \s-1XML\s0 specifier can be one of the following:
 278 .IP "A filename" 4
 279 .IX Item "A filename"
 280 If the filename contains no directory components \f(CW\*(C`XMLin()\*(C'\fR will look for the
 281 file in each directory in the SearchPath (see \*(L"\s-1OPTIONS\s0\*(R" below) or in the
 282 current directory if the SearchPath option is not defined.  eg:
 283 .Sp
 284 .Vb 1
 285 \&  $ref = XMLin(\*(Aq/etc/params.xml\*(Aq);
 286 .Ve
 287 .Sp
 288 Note, the filename '\-' can be used to parse from \s-1STDIN\s0.
 289 .IP "undef" 4
 290 .IX Item "undef"
 291 If there is no \s-1XML\s0 specifier, \f(CW\*(C`XMLin()\*(C'\fR will check the script directory and
 292 each of the SearchPath directories for a file with the same name as the script
 293 but with the extension '.xml'.  Note: if you wish to specify options, you
 294 must specify the value 'undef'.  eg:
 295 .Sp
 296 .Vb 1
 297 \&  $ref = XMLin(undef, ForceArray => 1);
 298 .Ve
 299 .IP "A string of \s-1XML\s0" 4
 300 .IX Item "A string of XML"
 301 A string containing \s-1XML\s0 (recognised by the presence of '<' and '>' characters)
 302 will be parsed directly.  eg:
 303 .Sp
 304 .Vb 1
 305 \&  $ref = XMLin(\*(Aq<opt username="bob" password="flurp" />\*(Aq);
 306 .Ve
 307 .IP "An IO::Handle object" 4
 308 .IX Item "An IO::Handle object"
 309 An IO::Handle object will be read to \s-1EOF\s0 and its contents parsed. eg:
 310 .Sp
 311 .Vb 2
 312 \&  $fh = IO::File\->new(\*(Aq/etc/params.xml\*(Aq);
 313 \&  $ref = XMLin($fh);
 314 .Ve
 315 .SS "\fIXMLout()\fP"
 316 .IX Subsection "XMLout()"
 317 Takes a data structure (generally a hashref) and returns an \s-1XML\s0 encoding of
 318 that structure.  If the resulting \s-1XML\s0 is parsed using \f(CW\*(C`XMLin()\*(C'\fR, it should
 319 return a data structure equivalent to the original (see caveats below).
 320 .PP
 321 The \f(CW\*(C`XMLout()\*(C'\fR function can also be used to output the \s-1XML\s0 as \s-1SAX\s0 events
 322 see the \f(CW\*(C`Handler\*(C'\fR option and \*(L"\s-1SAX\s0 \s-1SUPPORT\s0\*(R" for more details).
 323 .PP
 324 When translating hashes to \s-1XML\s0, hash keys which have a leading '\-' will be
 325 silently skipped.  This is the approved method for marking elements of a
 326 data structure which should be ignored by \f(CW\*(C`XMLout\*(C'\fR.  (Note: If these items
 327 were not skipped the key names would be emitted as element or attribute names
 328 with a leading '\-' which would not be valid \s-1XML\s0).
 329 .SS "Caveats"
 330 .IX Subsection "Caveats"
 331 Some care is required in creating data structures which will be passed to
 332 \&\f(CW\*(C`XMLout()\*(C'\fR.  Hash keys from the data structure will be encoded as either \s-1XML\s0
 333 element names or attribute names.  Therefore, you should use hash key names
 334 which conform to the relatively strict \s-1XML\s0 naming rules:
 335 .PP
 336 Names in \s-1XML\s0 must begin with a letter.  The remaining characters may be
 337 letters, digits, hyphens (\-), underscores (_) or full stops (.).  It is also
 338 allowable to include one colon (:) in an element name but this should only be
 339 used when working with namespaces (\fBXML::Simple\fR can only usefully work with
 340 namespaces when teamed with a \s-1SAX\s0 Parser).
 341 .PP
 342 You can use other punctuation characters in hash values (just not in hash
 343 keys) however \fBXML::Simple\fR does not support dumping binary data.
 344 .PP
 345 If you break these rules, the current implementation of \f(CW\*(C`XMLout()\*(C'\fR will
 346 simply emit non-compliant \s-1XML\s0 which will be rejected if you try to read it
 347 back in.  (A later version of \fBXML::Simple\fR might take a more proactive
 348 approach).
 349 .PP
 350 Note also that although you can nest hashes and arrays to arbitrary levels,
 351 circular data structures are not supported and will cause \f(CW\*(C`XMLout()\*(C'\fR to die.
 352 .PP
 353 If you wish to 'round\-trip' arbitrary data structures from Perl to \s-1XML\s0 and back
 354 to Perl, then you should probably disable array folding (using the KeyAttr
 355 option) both with \f(CW\*(C`XMLout()\*(C'\fR and with \f(CW\*(C`XMLin()\*(C'\fR.  If you still don't get the
 356 expected results, you may prefer to use XML::Dumper which is designed for
 357 exactly that purpose.
 358 .PP
 359 Refer to \*(L"\s-1WHERE\s0 \s-1TO\s0 \s-1FROM\s0 \s-1HERE\s0?\*(R" if \f(CW\*(C`XMLout()\*(C'\fR is too simple for your needs.
 360 .SH "OPTIONS"
 361 .IX Header "OPTIONS"
 362 \&\fBXML::Simple\fR supports a number of options (in fact as each release of
 363 \&\fBXML::Simple\fR adds more options, the module's claim to the name 'Simple'
 364 becomes increasingly tenuous).  If you find yourself repeatedly having to
 365 specify the same options, you might like to investigate \*(L"\s-1OPTIONAL\s0 \s-1OO\s0
 366 \&\s-1INTERFACE\s0\*(R" below.
 367 .PP
 368 If you can't be bothered reading the documentation, refer to
 369 \&\*(L"\s-1STRICT\s0 \s-1MODE\s0\*(R" to automatically catch common mistakes.
 370 .PP
 371 Because there are so many options, it's hard for new users to know which ones
 372 are important, so here are the two you really need to know about:
 373 .IP "\(bu" 4
 374 check out \f(CW\*(C`ForceArray\*(C'\fR because you'll almost certainly want to turn it on
 375 .IP "\(bu" 4
 376 make sure you know what the \f(CW\*(C`KeyAttr\*(C'\fR option does and what its default value is
 377 because it may surprise you otherwise (note in particular that 'KeyAttr'
 378 affects both \f(CW\*(C`XMLin\*(C'\fR and \f(CW\*(C`XMLout\*(C'\fR)
 379 .PP
 380 The option name headings below have a trailing 'comment' \- a hash followed by
 381 two pieces of metadata:
 382 .IP "\(bu" 4
 383 Options are marked with '\fIin\fR' if they are recognised by \f(CW\*(C`XMLin()\*(C'\fR and
 384 \&'\fIout\fR' if they are recognised by \f(CW\*(C`XMLout()\*(C'\fR.
 385 .IP "\(bu" 4
 386 Each option is also flagged to indicate whether it is:
 387 .Sp
 388 .Vb 7
 389 \& \*(Aqimportant\*(Aq   \- don\*(Aqt use the module until you understand this one
 390 \& \*(Aqhandy\*(Aq       \- you can skip this on the first time through
 391 \& \*(Aqadvanced\*(Aq    \- you can skip this on the second time through
 392 \& \*(AqSAX only\*(Aq    \- don\*(Aqt worry about this unless you\*(Aqre using SAX (or
 393 \&                 alternatively if you need this, you also need SAX)
 394 \& \*(Aqseldom used\*(Aq \- you\*(Aqll probably never use this unless you were the
 395 \&                 person that requested the feature
 396 .Ve
 397 .PP
 398 The options are listed alphabetically:
 399 .PP
 400 Note: option names are no longer case sensitive so you can use the mixed case
 401 versions shown here; all lower case as required by versions 2.03 and earlier;
 402 or you can add underscores between the words (eg: key_attr).
 403 .SS "AttrIndent => 1 \fI# out \- handy\fP"
 404 .IX Subsection "AttrIndent => 1 # out - handy"
 405 When you are using \f(CW\*(C`XMLout()\*(C'\fR, enable this option to have attributes printed
 406 one-per-line with sensible indentation rather than all on one line.
 407 .SS "Cache => [ cache schemes ] \fI# in \- advanced\fP"
 408 .IX Subsection "Cache => [ cache schemes ] # in - advanced"
 409 Because loading the \fBXML::Parser\fR module and parsing an \s-1XML\s0 file can consume a
 410 significant number of \s-1CPU\s0 cycles, it is often desirable to cache the output of
 411 \&\f(CW\*(C`XMLin()\*(C'\fR for later reuse.
 412 .PP
 413 When parsing from a named file, \fBXML::Simple\fR supports a number of caching
 414 schemes.  The 'Cache' option may be used to specify one or more schemes (using
 415 an anonymous array).  Each scheme will be tried in turn in the hope of finding
 416 a cached pre-parsed representation of the \s-1XML\s0 file.  If no cached copy is
 417 found, the file will be parsed and the first cache scheme in the list will be
 418 used to save a copy of the results.  The following cache schemes have been
 419 implemented:
 420 .IP "storable" 4
 421 .IX Item "storable"
 422 Utilises \fBStorable.pm\fR to read/write a cache file with the same name as the
 423 \&\s-1XML\s0 file but with the extension .stor
 424 .IP "memshare" 4
 425 .IX Item "memshare"
 426 When a file is first parsed, a copy of the resulting data structure is retained
 427 in memory in the \fBXML::Simple\fR module's namespace.  Subsequent calls to parse
 428 the same file will return a reference to this structure.  This cached version
 429 will persist only for the life of the Perl interpreter (which in the case of
 430 mod_perl for example, may be some significant time).
 431 .Sp
 432 Because each caller receives a reference to the same data structure, a change
 433 made by one caller will be visible to all.  For this reason, the reference
 434 returned should be treated as read-only.
 435 .IP "memcopy" 4
 436 .IX Item "memcopy"
 437 This scheme works identically to 'memshare' (above) except that each caller
 438 receives a reference to a new data structure which is a copy of the cached
 439 version.  Copying the data structure will add a little processing overhead,
 440 therefore this scheme should only be used where the caller intends to modify
 441 the data structure (or wishes to protect itself from others who might).  This
 442 scheme uses \fBStorable.pm\fR to perform the copy.
 443 .PP
 444 Warning! The memory-based caching schemes compare the timestamp on the file to
 445 the time when it was last parsed.  If the file is stored on an \s-1NFS\s0 filesystem
 446 (or other network share) and the clock on the file server is not exactly
 447 synchronised with the clock where your script is run, updates to the source \s-1XML\s0
 448 file may appear to be ignored.
 449 .SS "ContentKey => 'keyname' \fI# in+out \- seldom used\fP"
 450 .IX Subsection "ContentKey => 'keyname' # in+out - seldom used"
 451 When text content is parsed to a hash value, this option let's you specify a
 452 name for the hash key to override the default 'content'.  So for example:
 453 .PP
 454 .Vb 1
 455 \&  XMLin(\*(Aq<opt one="1">Text</opt>\*(Aq, ContentKey => \*(Aqtext\*(Aq)
 456 .Ve
 457 .PP
 458 will parse to:
 459 .PP
 460 .Vb 1
 461 \&  { \*(Aqone\*(Aq => 1, \*(Aqtext\*(Aq => \*(AqText\*(Aq }
 462 .Ve
 463 .PP
 464 instead of:
 465 .PP
 466 .Vb 1
 467 \&  { \*(Aqone\*(Aq => 1, \*(Aqcontent\*(Aq => \*(AqText\*(Aq }
 468 .Ve
 469 .PP
 470 \&\f(CW\*(C`XMLout()\*(C'\fR will also honour the value of this option when converting a hashref
 471 to \s-1XML\s0.
 472 .PP
 473 You can also prefix your selected key name with a '\-' character to have
 474 \&\f(CW\*(C`XMLin()\*(C'\fR try a little harder to eliminate unnecessary 'content' keys after
 475 array folding.  For example:
 476 .PP
 477 .Vb 6
 478 \&  XMLin(
 479 \&    \*(Aq<opt><item name="one">First</item><item name="two">Second</item></opt>\*(Aq,
 480 \&    KeyAttr => {item => \*(Aqname\*(Aq},
 481 \&    ForceArray => [ \*(Aqitem\*(Aq ],
 482 \&    ContentKey => \*(Aq\-content\*(Aq
 483 \&  )
 484 .Ve
 485 .PP
 486 will parse to:
 487 .PP
 488 .Vb 6
 489 \&  {
 490 \&    \*(Aqitem\*(Aq => {
 491 \&      \*(Aqone\*(Aq =>  \*(AqFirst\*(Aq
 492 \&      \*(Aqtwo\*(Aq =>  \*(AqSecond\*(Aq
 493 \&    }
 494 \&  }
 495 .Ve
 496 .PP
 497 rather than this (without the '\-'):
 498 .PP
 499 .Vb 6
 500 \&  {
 501 \&    \*(Aqitem\*(Aq => {
 502 \&      \*(Aqone\*(Aq => { \*(Aqcontent\*(Aq => \*(AqFirst\*(Aq }
 503 \&      \*(Aqtwo\*(Aq => { \*(Aqcontent\*(Aq => \*(AqSecond\*(Aq }
 504 \&    }
 505 \&  }
 506 .Ve
 507 .SS "DataHandler => code_ref \fI# in \- \s-1SAX\s0 only\fP"
 508 .IX Subsection "DataHandler => code_ref # in - SAX only"
 509 When you use an \fBXML::Simple\fR object as a \s-1SAX\s0 handler, it will return a
 510 \&'simple tree' data structure in the same format as \f(CW\*(C`XMLin()\*(C'\fR would return.  If
 511 this option is set (to a subroutine reference), then when the tree is built the
 512 subroutine will be called and passed two arguments: a reference to the
 513 \&\fBXML::Simple\fR object and a reference to the data tree.  The return value from
 514 the subroutine will be returned to the \s-1SAX\s0 driver.  (See \*(L"\s-1SAX\s0 \s-1SUPPORT\s0\*(R" for
 515 more details).
 516 .SS "ForceArray => 1 \fI# in \- important\fP"
 517 .IX Subsection "ForceArray => 1 # in - important"
 518 This option should be set to '1' to force nested elements to be represented
 519 as arrays even when there is only one.  Eg, with ForceArray enabled, this
 520 \&\s-1XML:\s0
 521 .PP
 522 .Vb 3
 523 \&    <opt>
 524 \&      <name>value</name>
 525 \&    </opt>
 526 .Ve
 527 .PP
 528 would parse to this:
 529 .PP
 530 .Vb 5
 531 \&    {
 532 \&      \*(Aqname\*(Aq => [
 533 \&                  \*(Aqvalue\*(Aq
 534 \&                ]
 535 \&    }
 536 .Ve
 537 .PP
 538 instead of this (the default):
 539 .PP
 540 .Vb 3
 541 \&    {
 542 \&      \*(Aqname\*(Aq => \*(Aqvalue\*(Aq
 543 \&    }
 544 .Ve
 545 .PP
 546 This option is especially useful if the data structure is likely to be written
 547 back out as \s-1XML\s0 and the default behaviour of rolling single nested elements up
 548 into attributes is not desirable.
 549 .PP
 550 If you are using the array folding feature, you should almost certainly enable
 551 this option.  If you do not, single nested elements will not be parsed to
 552 arrays and therefore will not be candidates for folding to a hash.  (Given that
 553 the default value of 'KeyAttr' enables array folding, the default value of this
 554 option should probably also have been enabled too \- sorry).
 555 .SS "ForceArray => [ names ] \fI# in \- important\fP"
 556 .IX Subsection "ForceArray => [ names ] # in - important"
 557 This alternative (and preferred) form of the 'ForceArray' option allows you to
 558 specify a list of element names which should always be forced into an array
 559 representation, rather than the 'all or nothing' approach above.
 560 .PP
 561 It is also possible (since version 2.05) to include compiled regular
 562 expressions in the list \- any element names which match the pattern will be
 563 forced to arrays.  If the list contains only a single regex, then it is not
 564 necessary to enclose it in an arrayref.  Eg:
 565 .PP
 566 .Vb 1
 567 \&  ForceArray => qr/_list$/
 568 .Ve
 569 .SS "ForceContent => 1 \fI# in \- seldom used\fP"
 570 .IX Subsection "ForceContent => 1 # in - seldom used"
 571 When \f(CW\*(C`XMLin()\*(C'\fR parses elements which have text content as well as attributes,
 572 the text content must be represented as a hash value rather than a simple
 573 scalar.  This option allows you to force text content to always parse to
 574 a hash value even when there are no attributes.  So for example:
 575 .PP
 576 .Vb 1
 577 \&  XMLin(\*(Aq<opt><x>text1</x><y a="2">text2</y></opt>\*(Aq, ForceContent => 1)
 578 .Ve
 579 .PP
 580 will parse to:
 581 .PP
 582 .Vb 4
 583 \&  {
 584 \&    \*(Aqx\*(Aq => {           \*(Aqcontent\*(Aq => \*(Aqtext1\*(Aq },
 585 \&    \*(Aqy\*(Aq => { \*(Aqa\*(Aq => 2, \*(Aqcontent\*(Aq => \*(Aqtext2\*(Aq }
 586 \&  }
 587 .Ve
 588 .PP
 589 instead of:
 590 .PP
 591 .Vb 4
 592 \&  {
 593 \&    \*(Aqx\*(Aq => \*(Aqtext1\*(Aq,
 594 \&    \*(Aqy\*(Aq => { \*(Aqa\*(Aq => 2, \*(Aqcontent\*(Aq => \*(Aqtext2\*(Aq }
 595 \&  }
 596 .Ve
 597 .SS "GroupTags => { grouping tag => grouped tag } \fI# in+out \- handy\fP"
 598 .IX Subsection "GroupTags => { grouping tag => grouped tag } # in+out - handy"
 599 You can use this option to eliminate extra levels of indirection in your Perl
 600 data structure.  For example this \s-1XML:\s0
 601 .PP
 602 .Vb 7
 603 \&  <opt>
 604 \&   <searchpath>
 605 \&     <dir>/usr/bin</dir>
 606 \&     <dir>/usr/local/bin</dir>
 607 \&     <dir>/usr/X11/bin</dir>
 608 \&   </searchpath>
 609 \& </opt>
 610 .Ve
 611 .PP
 612 Would normally be read into a structure like this:
 613 .PP
 614 .Vb 5
 615 \&  {
 616 \&    searchpath => {
 617 \&                    dir => [ \*(Aq/usr/bin\*(Aq, \*(Aq/usr/local/bin\*(Aq, \*(Aq/usr/X11/bin\*(Aq ]
 618 \&                  }
 619 \&  }
 620 .Ve
 621 .PP
 622 But when read in with the appropriate value for 'GroupTags':
 623 .PP
 624 .Vb 1
 625 \&  my $opt = XMLin($xml, GroupTags => { searchpath => \*(Aqdir\*(Aq });
 626 .Ve
 627 .PP
 628 It will return this simpler structure:
 629 .PP
 630 .Vb 3
 631 \&  {
 632 \&    searchpath => [ \*(Aq/usr/bin\*(Aq, \*(Aq/usr/local/bin\*(Aq, \*(Aq/usr/X11/bin\*(Aq ]
 633 \&  }
 634 .Ve
 635 .PP
 636 The grouping element (\f(CW\*(C`<searchpath>\*(C'\fR in the example) must not contain any
 637 attributes or elements other than the grouped element.
 638 .PP
 639 You can specify multiple 'grouping element' to 'grouped element' mappings in
 640 the same hashref.  If this option is combined with \f(CW\*(C`KeyAttr\*(C'\fR, the array
 641 folding will occur first and then the grouped element names will be eliminated.
 642 .PP
 643 \&\f(CW\*(C`XMLout\*(C'\fR will also use the grouptag mappings to re-introduce the tags around
 644 the grouped elements.  Beware though that this will occur in all places that
 645 the 'grouping tag' name occurs \- you probably don't want to use the same name
 646 for elements as well as attributes.
 647 .SS "Handler => object_ref \fI# out \- \s-1SAX\s0 only\fP"
 648 .IX Subsection "Handler => object_ref # out - SAX only"
 649 Use the 'Handler' option to have \f(CW\*(C`XMLout()\*(C'\fR generate \s-1SAX\s0 events rather than
 650 returning a string of \s-1XML\s0.  For more details see \*(L"\s-1SAX\s0 \s-1SUPPORT\s0\*(R" below.
 651 .PP
 652 Note: the current implementation of this option generates a string of \s-1XML\s0
 653 and uses a \s-1SAX\s0 parser to translate it into \s-1SAX\s0 events.  The normal encoding
 654 rules apply here \- your data must be \s-1UTF8\s0 encoded unless you specify an
 655 alternative encoding via the 'XMLDecl' option; and by the time the data reaches
 656 the handler object, it will be in \s-1UTF8\s0 form regardless of the encoding you
 657 supply.  A future implementation of this option may generate the events
 658 directly.
 659 .SS "KeepRoot => 1 \fI# in+out \- handy\fP"
 660 .IX Subsection "KeepRoot => 1 # in+out - handy"
 661 In its attempt to return a data structure free of superfluous detail and
 662 unnecessary levels of indirection, \f(CW\*(C`XMLin()\*(C'\fR normally discards the root
 663 element name.  Setting the 'KeepRoot' option to '1' will cause the root element
 664 name to be retained.  So after executing this code:
 665 .PP
 666 .Vb 1
 667 \&  $config = XMLin(\*(Aq<config tempdir="/tmp" />\*(Aq, KeepRoot => 1)
 668 .Ve
 669 .PP
 670 You'll be able to reference the tempdir as
 671 \&\f(CW\*(C`$config\->{config}\->{tempdir}\*(C'\fR instead of the default
 672 \&\f(CW\*(C`$config\->{tempdir}\*(C'\fR.
 673 .PP
 674 Similarly, setting the 'KeepRoot' option to '1' will tell \f(CW\*(C`XMLout()\*(C'\fR that the
 675 data structure already contains a root element name and it is not necessary to
 676 add another.
 677 .SS "KeyAttr => [ list ] \fI# in+out \- important\fP"
 678 .IX Subsection "KeyAttr => [ list ] # in+out - important"
 679 This option controls the 'array folding' feature which translates nested
 680 elements from an array to a hash.  It also controls the 'unfolding' of hashes
 681 to arrays.
 682 .PP
 683 For example, this \s-1XML:\s0
 684 .PP
 685 .Vb 4
 686 \&    <opt>
 687 \&      <user login="grep" fullname="Gary R Epstein" />
 688 \&      <user login="stty" fullname="Simon T Tyson" />
 689 \&    </opt>
 690 .Ve
 691 .PP
 692 would, by default, parse to this:
 693 .PP
 694 .Vb 12
 695 \&    {
 696 \&      \*(Aquser\*(Aq => [
 697 \&                  {
 698 \&                    \*(Aqlogin\*(Aq => \*(Aqgrep\*(Aq,
 699 \&                    \*(Aqfullname\*(Aq => \*(AqGary R Epstein\*(Aq
 700 \&                  },
 701 \&                  {
 702 \&                    \*(Aqlogin\*(Aq => \*(Aqstty\*(Aq,
 703 \&                    \*(Aqfullname\*(Aq => \*(AqSimon T Tyson\*(Aq
 704 \&                  }
 705 \&                ]
 706 \&    }
 707 .Ve
 708 .PP
 709 If the option 'KeyAttr => \*(L"login\*(R"' were used to specify that the 'login'
 710 attribute is a key, the same \s-1XML\s0 would parse to:
 711 .PP
 712 .Vb 10
 713 \&    {
 714 \&      \*(Aquser\*(Aq => {
 715 \&                  \*(Aqstty\*(Aq => {
 716 \&                              \*(Aqfullname\*(Aq => \*(AqSimon T Tyson\*(Aq
 717 \&                            },
 718 \&                  \*(Aqgrep\*(Aq => {
 719 \&                              \*(Aqfullname\*(Aq => \*(AqGary R Epstein\*(Aq
 720 \&                            }
 721 \&                }
 722 \&    }
 723 .Ve
 724 .PP
 725 The key attribute names should be supplied in an arrayref if there is more
 726 than one.  \f(CW\*(C`XMLin()\*(C'\fR will attempt to match attribute names in the order
 727 supplied.  \f(CW\*(C`XMLout()\*(C'\fR will use the first attribute name supplied when
 728 \&'unfolding' a hash into an array.
 729 .PP
 730 Note 1: The default value for 'KeyAttr' is ['name', 'key', 'id'].  If you do
 731 not want folding on input or unfolding on output you must setting this option
 732 to an empty list to disable the feature.
 733 .PP
 734 Note 2: If you wish to use this option, you should also enable the
 735 \&\f(CW\*(C`ForceArray\*(C'\fR option.  Without 'ForceArray', a single nested element will be
 736 rolled up into a scalar rather than an array and therefore will not be folded
 737 (since only arrays get folded).
 738 .SS "KeyAttr => { list } \fI# in+out \- important\fP"
 739 .IX Subsection "KeyAttr => { list } # in+out - important"
 740 This alternative (and preferred) method of specifiying the key attributes
 741 allows more fine grained control over which elements are folded and on which
 742 attributes.  For example the option 'KeyAttr => { package => 'id' } will cause
 743 any package elements to be folded on the 'id' attribute.  No other elements
 744 which have an 'id' attribute will be folded at all.
 745 .PP
 746 Note: \f(CW\*(C`XMLin()\*(C'\fR will generate a warning (or a fatal error in \*(L"\s-1STRICT\s0 \s-1MODE\s0\*(R")
 747 if this syntax is used and an element which does not have the specified key
 748 attribute is encountered (eg: a 'package' element without an 'id' attribute, to
 749 use the example above).  Warnings will only be generated if \fB\-w\fR is in force.
 750 .PP
 751 Two further variations are made possible by prefixing a '+' or a '\-' character
 752 to the attribute name:
 753 .PP
 754 The option 'KeyAttr => { user => \*(L"+login\*(R" }' will cause this \s-1XML:\s0
 755 .PP
 756 .Vb 4
 757 \&    <opt>
 758 \&      <user login="grep" fullname="Gary R Epstein" />
 759 \&      <user login="stty" fullname="Simon T Tyson" />
 760 \&    </opt>
 761 .Ve
 762 .PP
 763 to parse to this data structure:
 764 .PP
 765 .Vb 12
 766 \&    {
 767 \&      \*(Aquser\*(Aq => {
 768 \&                  \*(Aqstty\*(Aq => {
 769 \&                              \*(Aqfullname\*(Aq => \*(AqSimon T Tyson\*(Aq,
 770 \&                              \*(Aqlogin\*(Aq    => \*(Aqstty\*(Aq
 771 \&                            },
 772 \&                  \*(Aqgrep\*(Aq => {
 773 \&                              \*(Aqfullname\*(Aq => \*(AqGary R Epstein\*(Aq,
 774 \&                              \*(Aqlogin\*(Aq    => \*(Aqgrep\*(Aq
 775 \&                            }
 776 \&                }
 777 \&    }
 778 .Ve
 779 .PP
 780 The '+' indicates that the value of the key attribute should be copied rather
 781 than moved to the folded hash key.
 782 .PP
 783 A '\-' prefix would produce this result:
 784 .PP
 785 .Vb 12
 786 \&    {
 787 \&      \*(Aquser\*(Aq => {
 788 \&                  \*(Aqstty\*(Aq => {
 789 \&                              \*(Aqfullname\*(Aq => \*(AqSimon T Tyson\*(Aq,
 790 \&                              \*(Aq\-login\*(Aq    => \*(Aqstty\*(Aq
 791 \&                            },
 792 \&                  \*(Aqgrep\*(Aq => {
 793 \&                              \*(Aqfullname\*(Aq => \*(AqGary R Epstein\*(Aq,
 794 \&                              \*(Aq\-login\*(Aq    => \*(Aqgrep\*(Aq
 795 \&                            }
 796 \&                }
 797 \&    }
 798 .Ve
 799 .PP
 800 As described earlier, \f(CW\*(C`XMLout\*(C'\fR will ignore hash keys starting with a '\-'.
 801 .SS "NoAttr => 1 \fI# in+out \- handy\fP"
 802 .IX Subsection "NoAttr => 1 # in+out - handy"
 803 When used with \f(CW\*(C`XMLout()\*(C'\fR, the generated \s-1XML\s0 will contain no attributes.
 804 All hash key/values will be represented as nested elements instead.
 805 .PP
 806 When used with \f(CW\*(C`XMLin()\*(C'\fR, any attributes in the \s-1XML\s0 will be ignored.
 807 .SS "NoEscape => 1 \fI# out \- seldom used\fP"
 808 .IX Subsection "NoEscape => 1 # out - seldom used"
 809 By default, \f(CW\*(C`XMLout()\*(C'\fR will translate the characters '<', '>', '&' and
 810 \&'"' to '&lt;', '&gt;', '&amp;' and '&quot' respectively.  Use this option to
 811 suppress escaping (presumably because you've already escaped the data in some
 812 more sophisticated manner).
 813 .SS "NoIndent => 1 \fI# out \- seldom used\fP"
 814 .IX Subsection "NoIndent => 1 # out - seldom used"
 815 Set this option to 1 to disable \f(CW\*(C`XMLout()\*(C'\fR's default 'pretty printing' mode.
 816 With this option enabled, the \s-1XML\s0 output will all be on one line (unless there
 817 are newlines in the data) \- this may be easier for downstream processing.
 818 .SS "NoSort => 1 \fI# out \- seldom used\fP"
 819 .IX Subsection "NoSort => 1 # out - seldom used"
 820 Newer versions of XML::Simple sort elements and attributes alphabetically (*),
 821 by default.  Enable this option to suppress the sorting \- possibly for
 822 backwards compatibility.
 823 .PP
 824 * Actually, sorting is alphabetical but 'key' attribute or element names (as in
 825 \&'KeyAttr') sort first.  Also, when a hash of hashes is 'unfolded', the elements
 826 are sorted alphabetically by the value of the key field.
 827 .SS "NormaliseSpace => 0 | 1 | 2 \fI# in \- handy\fP"
 828 .IX Subsection "NormaliseSpace => 0 | 1 | 2 # in - handy"
 829 This option controls how whitespace in text content is handled.  Recognised
 830 values for the option are:
 831 .IP "\(bu" 4
 832 0 = (default) whitespace is passed through unaltered (except of course for the
 833 normalisation of whitespace in attribute values which is mandated by the \s-1XML\s0
 834 recommendation)
 835 .IP "\(bu" 4
 836 1 = whitespace is normalised in any value used as a hash key (normalising means
 837 removing leading and trailing whitespace and collapsing sequences of whitespace
 838 characters to a single space)
 839 .IP "\(bu" 4
 840 2 = whitespace is normalised in all text content
 841 .PP
 842 Note: you can spell this option with a 'z' if that is more natural for you.
 843 .SS "NSExpand => 1 \fI# in+out handy \- \s-1SAX\s0 only\fP"
 844 .IX Subsection "NSExpand => 1 # in+out handy - SAX only"
 845 This option controls namespace expansion \- the translation of element and
 846 attribute names of the form 'prefix:name' to '{uri}name'.  For example the
 847 element name 'xsl:template' might be expanded to:
 848 \&'{http://www.w3.org/1999/XSL/Transform}template'.
 849 .PP
 850 By default, \f(CW\*(C`XMLin()\*(C'\fR will return element names and attribute names exactly as
 851 they appear in the \s-1XML\s0.  Setting this option to 1 will cause all element and
 852 attribute names to be expanded to include their namespace prefix.
 853 .PP
 854 \&\fINote: You must be using a \s-1SAX\s0 parser for this option to work (ie: it does not
 855 work with XML::Parser)\fR.
 856 .PP
 857 This option also controls whether \f(CW\*(C`XMLout()\*(C'\fR performs the reverse translation
 858 from '{uri}name' back to 'prefix:name'.  The default is no translation.  If
 859 your data contains expanded names, you should set this option to 1 otherwise
 860 \&\f(CW\*(C`XMLout\*(C'\fR will emit \s-1XML\s0 which is not well formed.
 861 .PP
 862 \&\fINote: You must have the XML::NamespaceSupport module installed if you want
 863 \&\f(CI\*(C`XMLout()\*(C'\fI to translate URIs back to prefixes\fR.
 864 .SS "NumericEscape => 0 | 1 | 2 \fI# out \- handy\fP"
 865 .IX Subsection "NumericEscape => 0 | 1 | 2 # out - handy"
 866 Use this option to have 'high' (non-ASCII) characters in your Perl data
 867 structure converted to numeric entities (eg: &#8364;) in the \s-1XML\s0 output.  Three
 868 levels are possible:
 869 .PP
 870 0 \- default: no numeric escaping (\s-1OK\s0 if you're writing out \s-1UTF8\s0)
 871 .PP
 872 1 \- only characters above 0xFF are escaped (ie: characters in the 0x80\-FF range are not escaped), possibly useful with \s-1ISO8859\-1\s0 output
 873 .PP
 874 2 \- all characters above 0x7F are escaped (good for plain \s-1ASCII\s0 output)
 875 .SS "OutputFile => <file specifier> \fI# out \- handy\fP"
 876 .IX Subsection "OutputFile => <file specifier> # out - handy"
 877 The default behaviour of \f(CW\*(C`XMLout()\*(C'\fR is to return the \s-1XML\s0 as a string.  If you
 878 wish to write the \s-1XML\s0 to a file, simply supply the filename using the
 879 \&'OutputFile' option.
 880 .PP
 881 This option also accepts an \s-1IO\s0 handle object \- especially useful in Perl 5.8.0
 882 and later for output using an encoding other than \s-1UTF\-8\s0, eg:
 883 .PP
 884 .Vb 2
 885 \&  open my $fh, \*(Aq>:encoding(iso\-8859\-1)\*(Aq, $path or die "open($path): $!";
 886 \&  XMLout($ref, OutputFile => $fh);
 887 .Ve
 888 .PP
 889 Note, XML::Simple does not require that the object you pass in to the
 890 OutputFile option inherits from IO::Handle \- it simply assumes the object
 891 supports a \f(CW\*(C`print\*(C'\fR method.
 892 .SS "ParserOpts => [ XML::Parser Options ] \fI# in \- don't use this\fP"
 893 .IX Subsection "ParserOpts => [ XML::Parser Options ] # in - don't use this"
 894 \&\fINote: This option is now officially deprecated.  If you find it useful, email
 895 the author with an example of what you use it for.  Do not use this option to
 896 set the ProtocolEncoding, that's just plain wrong \- fix the \s-1XML\s0\fR.
 897 .PP
 898 This option allows you to pass parameters to the constructor of the underlying
 899 XML::Parser object (which of course assumes you're not using \s-1SAX\s0).
 900 .SS "RootName => 'string' \fI# out \- handy\fP"
 901 .IX Subsection "RootName => 'string' # out - handy"
 902 By default, when \f(CW\*(C`XMLout()\*(C'\fR generates \s-1XML\s0, the root element will be named
 903 \&'opt'.  This option allows you to specify an alternative name.
 904 .PP
 905 Specifying either undef or the empty string for the RootName option will
 906 produce \s-1XML\s0 with no root elements.  In most cases the resulting \s-1XML\s0 fragment
 907 will not be 'well formed' and therefore could not be read back in by \f(CW\*(C`XMLin()\*(C'\fR.
 908 Nevertheless, the option has been found to be useful in certain circumstances.
 909 .SS "SearchPath => [ list ] \fI# in \- handy\fP"
 910 .IX Subsection "SearchPath => [ list ] # in - handy"
 911 If you pass \f(CW\*(C`XMLin()\*(C'\fR a filename, but the filename include no directory
 912 component, you can use this option to specify which directories should be
 913 searched to locate the file.  You might use this option to search first in the
 914 user's home directory, then in a global directory such as /etc.
 915 .PP
 916 If a filename is provided to \f(CW\*(C`XMLin()\*(C'\fR but SearchPath is not defined, the
 917 file is assumed to be in the current directory.
 918 .PP
 919 If the first parameter to \f(CW\*(C`XMLin()\*(C'\fR is undefined, the default SearchPath
 920 will contain only the directory in which the script itself is located.
 921 Otherwise the default SearchPath will be empty.
 922 .SS "SuppressEmpty => 1 | '' | undef \fI# in+out \- handy\fP"
 923 .IX Subsection "SuppressEmpty => 1 | '' | undef # in+out - handy"
 924 This option controls what \f(CW\*(C`XMLin()\*(C'\fR should do with empty elements (no
 925 attributes and no content).  The default behaviour is to represent them as
 926 empty hashes.  Setting this option to a true value (eg: 1) will cause empty
 927 elements to be skipped altogether.  Setting the option to 'undef' or the empty
 928 string will cause empty elements to be represented as the undefined value or
 929 the empty string respectively.  The latter two alternatives are a little
 930 easier to test for in your code than a hash with no keys.
 931 .PP
 932 The option also controls what \f(CW\*(C`XMLout()\*(C'\fR does with undefined values.  Setting
 933 the option to undef causes undefined values to be output as empty elements
 934 (rather than empty attributes), it also suppresses the generation of warnings
 935 about undefined values.  Setting the option to a true value (eg: 1) causes
 936 undefined values to be skipped altogether on output.
 937 .SS "ValueAttr => [ names ] \fI# in \- handy\fP"
 938 .IX Subsection "ValueAttr => [ names ] # in - handy"
 939 Use this option to deal elements which always have a single attribute and no
 940 content.  Eg:
 941 .PP
 942 .Vb 4
 943 \&  <opt>
 944 \&    <colour value="red" />
 945 \&    <size   value="XXL" />
 946 \&  </opt>
 947 .Ve
 948 .PP
 949 Setting \f(CW\*(C`ValueAttr => [ \*(Aqvalue\*(Aq ]\*(C'\fR will cause the above \s-1XML\s0 to parse to:
 950 .PP
 951 .Vb 4
 952 \&  {
 953 \&    colour => \*(Aqred\*(Aq,
 954 \&    size   => \*(AqXXL\*(Aq
 955 \&  }
 956 .Ve
 957 .PP
 958 instead of this (the default):
 959 .PP
 960 .Vb 4
 961 \&  {
 962 \&    colour => { value => \*(Aqred\*(Aq },
 963 \&    size   => { value => \*(AqXXL\*(Aq }
 964 \&  }
 965 .Ve
 966 .PP
 967 Note: This form of the ValueAttr option is not compatible with \f(CW\*(C`XMLout()\*(C'\fR \-
 968 since the attribute name is discarded at parse time, the original \s-1XML\s0 cannot be
 969 reconstructed.
 970 .SS "ValueAttr => { element => attribute, ... } \fI# in+out \- handy\fP"
 971 .IX Subsection "ValueAttr => { element => attribute, ... } # in+out - handy"
 972 This (preferred) form of the ValueAttr option requires you to specify both
 973 the element and the attribute names.  This is not only safer, it also allows
 974 the original \s-1XML\s0 to be reconstructed by \f(CW\*(C`XMLout()\*(C'\fR.
 975 .PP
 976 Note: You probably don't want to use this option and the NoAttr option at the
 977 same time.
 978 .SS "Variables => { name => value } \fI# in \- handy\fP"
 979 .IX Subsection "Variables => { name => value } # in - handy"
 980 This option allows variables in the \s-1XML\s0 to be expanded when the file is read.
 981 (there is no facility for putting the variable names back if you regenerate
 982 \&\s-1XML\s0 using \f(CW\*(C`XMLout\*(C'\fR).
 983 .PP
 984 A 'variable' is any text of the form \f(CW\*(C`${name}\*(C'\fR which occurs in an attribute
 985 value or in the text content of an element.  If 'name' matches a key in the
 986 supplied hashref, \f(CW\*(C`${name}\*(C'\fR will be replaced with the corresponding value from
 987 the hashref.  If no matching key is found, the variable will not be replaced.
 988 Names must match the regex: \f(CW\*(C`[\ew.]+\*(C'\fR (ie: only 'word' characters and dots are
 989 allowed).
 990 .SS "VarAttr => 'attr_name' \fI# in \- handy\fP"
 991 .IX Subsection "VarAttr => 'attr_name' # in - handy"
 992 In addition to the variables defined using \f(CW\*(C`Variables\*(C'\fR, this option allows
 993 variables to be defined in the \s-1XML\s0.  A variable definition consists of an
 994 element with an attribute called 'attr_name' (the value of the \f(CW\*(C`VarAttr\*(C'\fR
 995 option).  The value of the attribute will be used as the variable name and the
 996 text content of the element will be used as the value.  A variable defined in
 997 this way will override a variable defined using the \f(CW\*(C`Variables\*(C'\fR option.  For
 998 example:
 999 .PP
1000 .Vb 7
1001 \&  XMLin( \*(Aq<opt>
1002 \&            <dir name="prefix">/usr/local/apache</dir>
1003 \&            <dir name="exec_prefix">${prefix}</dir>
1004 \&            <dir name="bindir">${exec_prefix}/bin</dir>
1005 \&          </opt>\*(Aq,
1006 \&         VarAttr => \*(Aqname\*(Aq, ContentKey => \*(Aq\-content\*(Aq
1007 \&        );
1008 .Ve
1009 .PP
1010 produces the following data structure:
1011 .PP
1012 .Vb 7
1013 \&  {
1014 \&    dir => {
1015 \&             prefix      => \*(Aq/usr/local/apache\*(Aq,
1016 \&             exec_prefix => \*(Aq/usr/local/apache\*(Aq,
1017 \&             bindir      => \*(Aq/usr/local/apache/bin\*(Aq,
1018 \&           }
1019 \&  }
1020 .Ve
1021 .SS "XMLDecl => 1  or  XMLDecl => 'string'  \fI# out \- handy\fP"
1022 .IX Subsection "XMLDecl => 1  or  XMLDecl => 'string'  # out - handy"
1023 If you want the output from \f(CW\*(C`XMLout()\*(C'\fR to start with the optional \s-1XML\s0
1024 declaration, simply set the option to '1'.  The default \s-1XML\s0 declaration is:
1025 .PP
1026 .Vb 1
1027 \&        <?xml version=\*(Aq1.0\*(Aq standalone=\*(Aqyes\*(Aq?>
1028 .Ve
1029 .PP
1030 If you want some other string (for example to declare an encoding value), set
1031 the value of this option to the complete string you require.
1032 .SH "OPTIONAL OO INTERFACE"
1033 .IX Header "OPTIONAL OO INTERFACE"
1034 The procedural interface is both simple and convenient however there are a
1035 couple of reasons why you might prefer to use the object oriented (\s-1OO\s0)
1036 interface:
1037 .IP "\(bu" 4
1038 to define a set of default values which should be used on all subsequent calls
1039 to \f(CW\*(C`XMLin()\*(C'\fR or \f(CW\*(C`XMLout()\*(C'\fR
1040 .IP "\(bu" 4
1041 to override methods in \fBXML::Simple\fR to provide customised behaviour
1042 .PP
1043 The default values for the options described above are unlikely to suit
1044 everyone.  The \s-1OO\s0 interface allows you to effectively override \fBXML::Simple\fR's
1045 defaults with your preferred values.  It works like this:
1046 .PP
1047 First create an XML::Simple parser object with your preferred defaults:
1048 .PP
1049 .Vb 1
1050 \&  my $xs = XML::Simple\->new(ForceArray => 1, KeepRoot => 1);
1051 .Ve
1052 .PP
1053 then call \f(CW\*(C`XMLin()\*(C'\fR or \f(CW\*(C`XMLout()\*(C'\fR as a method of that object:
1054 .PP
1055 .Vb 2
1056 \&  my $ref = $xs\->XMLin($xml);
1057 \&  my $xml = $xs\->XMLout($ref);
1058 .Ve
1059 .PP
1060 You can also specify options when you make the method calls and these values
1061 will be merged with the values specified when the object was created.  Values
1062 specified in a method call take precedence.
1063 .PP
1064 Note: when called as methods, the \f(CW\*(C`XMLin()\*(C'\fR and \f(CW\*(C`XMLout()\*(C'\fR routines may be
1065 called as \f(CW\*(C`xml_in()\*(C'\fR or \f(CW\*(C`xml_out()\*(C'\fR.  The method names are aliased so the
1066 only difference is the aesthetics.
1067 .SS "Parsing Methods"
1068 .IX Subsection "Parsing Methods"
1069 You can explicitly call one of the following methods rather than rely on the
1070 \&\f(CW\*(C`xml_in()\*(C'\fR method automatically determining whether the target to be parsed is
1071 a string, a file or a filehandle:
1072 .IP "parse_string(text)" 4
1073 .IX Item "parse_string(text)"
1074 Works exactly like the \f(CW\*(C`xml_in()\*(C'\fR method but assumes the first argument is
1075 a string of \s-1XML\s0 (or a reference to a scalar containing a string of \s-1XML\s0).
1076 .IP "parse_file(filename)" 4
1077 .IX Item "parse_file(filename)"
1078 Works exactly like the \f(CW\*(C`xml_in()\*(C'\fR method but assumes the first argument is
1079 the name of a file containing \s-1XML\s0.
1080 .IP "parse_fh(file_handle)" 4
1081 .IX Item "parse_fh(file_handle)"
1082 Works exactly like the \f(CW\*(C`xml_in()\*(C'\fR method but assumes the first argument is
1083 a filehandle which can be read to get \s-1XML\s0.
1084 .SS "Hook Methods"
1085 .IX Subsection "Hook Methods"
1086 You can make your own class which inherits from XML::Simple and overrides
1087 certain behaviours.  The following methods may provide useful 'hooks' upon
1088 which to hang your modified behaviour.  You may find other undocumented methods
1089 by examining the source, but those may be subject to change in future releases.
1090 .IP "handle_options(direction, name => value ...)" 4
1091 .IX Item "handle_options(direction, name => value ...)"
1092 This method will be called when one of the parsing methods or the \f(CW\*(C`XMLout()\*(C'\fR
1093 method is called.  The initial argument will be a string (either 'in' or 'out')
1094 and the remaining arguments will be name value pairs.
1095 .IP "\fIdefault_config_file()\fR" 4
1096 .IX Item "default_config_file()"
1097 Calculates and returns the name of the file which should be parsed if no
1098 filename is passed to \f(CW\*(C`XMLin()\*(C'\fR (default: \f(CW\*(C`$0.xml\*(C'\fR).
1099 .IP "build_simple_tree(filename, string)" 4
1100 .IX Item "build_simple_tree(filename, string)"
1101 Called from \f(CW\*(C`XMLin()\*(C'\fR or any of the parsing methods.  Takes either a file name
1102 as the first argument or \f(CW\*(C`undef\*(C'\fR followed by a 'string' as the second
1103 argument.  Returns a simple tree data structure.  You could override this
1104 method to apply your own transformations before the data structure is returned
1105 to the caller.
1106 .IP "\fInew_hashref()\fR" 4
1107 .IX Item "new_hashref()"
1108 When the 'simple tree' data structure is being built, this method will be
1109 called to create any required anonymous hashrefs.
1110 .IP "sorted_keys(name, hashref)" 4
1111 .IX Item "sorted_keys(name, hashref)"
1112 Called when \f(CW\*(C`XMLout()\*(C'\fR is translating a hashref to \s-1XML\s0.  This routine returns
1113 a list of hash keys in the order that the corresponding attributes/elements
1114 should appear in the output.
1115 .IP "escape_value(string)" 4
1116 .IX Item "escape_value(string)"
1117 Called from \f(CW\*(C`XMLout()\*(C'\fR, takes a string and returns a copy of the string with
1118 \&\s-1XML\s0 character escaping rules applied.
1119 .IP "numeric_escape(string)" 4
1120 .IX Item "numeric_escape(string)"
1121 Called from \f(CW\*(C`escape_value()\*(C'\fR, to handle non-ASCII characters (depending on the
1122 value of the NumericEscape option).
1123 .IP "copy_hash(hashref, extra_key => value, ...)" 4
1124 .IX Item "copy_hash(hashref, extra_key => value, ...)"
1125 Called from \f(CW\*(C`XMLout()\*(C'\fR, when 'unfolding' a hash of hashes into an array of
1126 hashes.  You might wish to override this method if you're using tied hashes and
1127 don't want them to get untied.
1128 .SS "Cache Methods"
1129 .IX Subsection "Cache Methods"
1130 XML::Simple implements three caching schemes ('storable', 'memshare' and
1131 \&'memcopy').  You can implement a custom caching scheme by implementing
1132 two methods \- one for reading from the cache and one for writing to it.
1133 .PP
1134 For example, you might implement a new 'dbm' scheme that stores cached data
1135 structures using the \s-1MLDBM\s0 module.  First, you would add a
1136 \&\f(CW\*(C`cache_read_dbm()\*(C'\fR method which accepted a filename for use as a lookup key
1137 and returned a data structure on success, or undef on failure.  Then, you would
1138 implement a \f(CW\*(C`cache_read_dbm()\*(C'\fR method which accepted a data structure and a
1139 filename.
1140 .PP
1141 You would use this caching scheme by specifying the option:
1142 .PP
1143 .Vb 1
1144 \&  Cache => [ \*(Aqdbm\*(Aq ]
1145 .Ve
1146 .SH "STRICT MODE"
1147 .IX Header "STRICT MODE"
1148 If you import the \fBXML::Simple\fR routines like this:
1149 .PP
1150 .Vb 1
1151 \&  use XML::Simple qw(:strict);
1152 .Ve
1153 .PP
1154 the following common mistakes will be detected and treated as fatal errors
1155 .IP "\(bu" 4
1156 Failing to explicitly set the \f(CW\*(C`KeyAttr\*(C'\fR option \- if you can't be bothered
1157 reading about this option, turn it off with: KeyAttr => [ ]
1158 .IP "\(bu" 4
1159 Failing to explicitly set the \f(CW\*(C`ForceArray\*(C'\fR option \- if you can't be bothered
1160 reading about this option, set it to the safest mode with: ForceArray => 1
1161 .IP "\(bu" 4
1162 Setting ForceArray to an array, but failing to list all the elements from the
1163 KeyAttr hash.
1164 .IP "\(bu" 4
1165 Data error \- KeyAttr is set to say { part => 'partnum' } but the \s-1XML\s0 contains
1166 one or more <part> elements without a 'partnum' attribute (or nested
1167 element).  Note: if strict mode is not set but \-w is, this condition triggers a
1168 warning.
1169 .IP "\(bu" 4
1170 Data error \- as above, but non-unique values are present in the key attribute
1171 (eg: more than one <part> element with the same partnum).  This will
1172 also trigger a warning if strict mode is not enabled.
1173 .IP "\(bu" 4
1174 Data error \- as above, but value of key attribute (eg: partnum) is not a
1175 scalar string (due to nested elements etc).  This will also trigger a warning
1176 if strict mode is not enabled.
1177 .SH "SAX SUPPORT"
1178 .IX Header "SAX SUPPORT"
1179 From version 1.08_01, \fBXML::Simple\fR includes support for \s-1SAX\s0 (the Simple \s-1API\s0
1180 for \s-1XML\s0) \- specifically \s-1SAX2\s0.
1181 .PP
1182 In a typical \s-1SAX\s0 application, an \s-1XML\s0 parser (or \s-1SAX\s0 'driver') module generates
1183 \&\s-1SAX\s0 events (start of element, character data, end of element, etc) as it parses
1184 an \s-1XML\s0 document and a 'handler' module processes the events to extract the
1185 required data.  This simple model allows for some interesting and powerful
1186 possibilities:
1187 .IP "\(bu" 4
1188 Applications written to the \s-1SAX\s0 \s-1API\s0 can extract data from huge \s-1XML\s0 documents
1189 without the memory overheads of a \s-1DOM\s0 or tree \s-1API\s0.
1190 .IP "\(bu" 4
1191 The \s-1SAX\s0 \s-1API\s0 allows for plug and play interchange of parser modules without
1192 having to change your code to fit a new module's \s-1API\s0.  A number of \s-1SAX\s0 parsers
1193 are available with capabilities ranging from extreme portability to blazing
1194 performance.
1195 .IP "\(bu" 4
1196 A \s-1SAX\s0 'filter' module can implement both a handler interface for receiving
1197 data and a generator interface for passing modified data on to a downstream
1198 handler.  Filters can be chained together in 'pipelines'.
1199 .IP "\(bu" 4
1200 One filter module might split a data stream to direct data to two or more
1201 downstream handlers.
1202 .IP "\(bu" 4
1203 Generating \s-1SAX\s0 events is not the exclusive preserve of \s-1XML\s0 parsing modules.
1204 For example, a module might extract data from a relational database using \s-1DBI\s0
1205 and pass it on to a \s-1SAX\s0 pipeline for filtering and formatting.
1206 .PP
1207 \&\fBXML::Simple\fR can operate at either end of a \s-1SAX\s0 pipeline.  For example,
1208 you can take a data structure in the form of a hashref and pass it into a
1209 \&\s-1SAX\s0 pipeline using the 'Handler' option on \f(CW\*(C`XMLout()\*(C'\fR:
1210 .PP
1211 .Vb 3
1212 \&  use XML::Simple;
1213 \&  use Some::SAX::Filter;
1214 \&  use XML::SAX::Writer;
1215 \&
1216 \&  my $ref = {
1217 \&               ....   # your data here
1218 \&            };
1219 \&
1220 \&  my $writer = XML::SAX::Writer\->new();
1221 \&  my $filter = Some::SAX::Filter\->new(Handler => $writer);
1222 \&  my $simple = XML::Simple\->new(Handler => $filter);
1223 \&  $simple\->XMLout($ref);
1224 .Ve
1225 .PP
1226 You can also put \fBXML::Simple\fR at the opposite end of the pipeline to take
1227 advantage of the simple 'tree' data structure once the relevant data has been
1228 isolated through filtering:
1229 .PP
1230 .Vb 3
1231 \&  use XML::SAX;
1232 \&  use Some::SAX::Filter;
1233 \&  use XML::Simple;
1234 \&
1235 \&  my $simple = XML::Simple\->new(ForceArray => 1, KeyAttr => [\*(Aqpartnum\*(Aq]);
1236 \&  my $filter = Some::SAX::Filter\->new(Handler => $simple);
1237 \&  my $parser = XML::SAX::ParserFactory\->parser(Handler => $filter);
1238 \&
1239 \&  my $ref = $parser\->parse_uri(\*(Aqsome_huge_file.xml\*(Aq);
1240 \&
1241 \&  print $ref\->{part}\->{\*(Aq555\-1234\*(Aq};
1242 .Ve
1243 .PP
1244 You can build a filter by using an XML::Simple object as a handler and setting
1245 its DataHandler option to point to a routine which takes the resulting tree,
1246 modifies it and sends it off as \s-1SAX\s0 events to a downstream handler:
1247 .PP
1248 .Vb 5
1249 \&  my $writer = XML::SAX::Writer\->new();
1250 \&  my $filter = XML::Simple\->new(
1251 \&                 DataHandler => sub {
1252 \&                                  my $simple = shift;
1253 \&                                  my $data = shift;
1254 \&
1255 \&                                  # Modify $data here
1256 \&
1257 \&                                  $simple\->XMLout($data, Handler => $writer);
1258 \&                                }
1259 \&               );
1260 \&  my $parser = XML::SAX::ParserFactory\->parser(Handler => $filter);
1261 \&
1262 \&  $parser\->parse_uri($filename);
1263 .Ve
1264 .PP
1265 \&\fINote: In this last example, the 'Handler' option was specified in the call to
1266 \&\f(CI\*(C`XMLout()\*(C'\fI but it could also have been specified in the constructor\fR.
1267 .SH "ENVIRONMENT"
1268 .IX Header "ENVIRONMENT"
1269 If you don't care which parser module \fBXML::Simple\fR uses then skip this
1270 section entirely (it looks more complicated than it really is).
1271 .PP
1272 \&\fBXML::Simple\fR will default to using a \fB\s-1SAX\s0\fR parser if one is available or
1273 \&\fBXML::Parser\fR if \s-1SAX\s0 is not available.
1274 .PP
1275 You can dictate which parser module is used by setting either the environment
1276 variable '\s-1XML_SIMPLE_PREFERRED_PARSER\s0' or the package variable
1277 \&\f(CW$XML::Simple::PREFERRED_PARSER\fR to contain the module name.  The following rules
1278 are used:
1279 .IP "\(bu" 4
1280 The package variable takes precedence over the environment variable if both are defined.  To force \fBXML::Simple\fR to ignore the environment settings and use
1281 its default rules, you can set the package variable to an empty string.
1282 .IP "\(bu" 4
1283 If the 'preferred parser' is set to the string 'XML::Parser', then
1284 XML::Parser will be used (or \f(CW\*(C`XMLin()\*(C'\fR will die if XML::Parser is not
1285 installed).
1286 .IP "\(bu" 4
1287 If the 'preferred parser' is set to some other value, then it is assumed to be
1288 the name of a \s-1SAX\s0 parser module and is passed to XML::SAX::ParserFactory.
1289 If \s-1XML::SAX\s0 is not installed, or the requested parser module is not
1290 installed, then \f(CW\*(C`XMLin()\*(C'\fR will die.
1291 .IP "\(bu" 4
1292 If the 'preferred parser' is not defined at all (the normal default
1293 state), an attempt will be made to load \s-1XML::SAX\s0.  If \s-1XML::SAX\s0 is
1294 installed, then a parser module will be selected according to
1295 XML::SAX::ParserFactory's normal rules (which typically means the last \s-1SAX\s0
1296 parser installed).
1297 .IP "\(bu" 4
1298 if the 'preferred parser' is not defined and \fB\s-1XML::SAX\s0\fR is not
1299 installed, then \fBXML::Parser\fR will be used.  \f(CW\*(C`XMLin()\*(C'\fR will die if
1300 XML::Parser is not installed.
1301 .PP
1302 Note: The \fB\s-1XML::SAX\s0\fR distribution includes an \s-1XML\s0 parser written entirely in
1303 Perl.  It is very portable but it is not very fast.  You should consider
1304 installing XML::LibXML or XML::SAX::Expat if they are available for your
1305 platform.
1306 .SH "ERROR HANDLING"
1307 .IX Header "ERROR HANDLING"
1308 The \s-1XML\s0 standard is very clear on the issue of non-compliant documents.  An
1309 error in parsing any single element (for example a missing end tag) must cause
1310 the whole document to be rejected.  \fBXML::Simple\fR will die with an appropriate
1311 message if it encounters a parsing error.
1312 .PP
1313 If dying is not appropriate for your application, you should arrange to call
1314 \&\f(CW\*(C`XMLin()\*(C'\fR in an eval block and look for errors in $@.  eg:
1315 .PP
1316 .Vb 2
1317 \&    my $config = eval { XMLin() };
1318 \&    PopUpMessage($@) if($@);
1319 .Ve
1320 .PP
1321 Note, there is a common misconception that use of \fBeval\fR will significantly
1322 slow down a script.  While that may be true when the code being eval'd is in a
1323 string, it is not true of code like the sample above.
1324 .SH "EXAMPLES"
1325 .IX Header "EXAMPLES"
1326 When \f(CW\*(C`XMLin()\*(C'\fR reads the following very simple piece of \s-1XML:\s0
1327 .PP
1328 .Vb 1
1329 \&    <opt username="testuser" password="frodo"></opt>
1330 .Ve
1331 .PP
1332 it returns the following data structure:
1333 .PP
1334 .Vb 4
1335 \&    {
1336 \&      \*(Aqusername\*(Aq => \*(Aqtestuser\*(Aq,
1337 \&      \*(Aqpassword\*(Aq => \*(Aqfrodo\*(Aq
1338 \&    }
1339 .Ve
1340 .PP
1341 The identical result could have been produced with this alternative \s-1XML:\s0
1342 .PP
1343 .Vb 1
1344 \&    <opt username="testuser" password="frodo" />
1345 .Ve
1346 .PP
1347 Or this (although see 'ForceArray' option for variations):
1348 .PP
1349 .Vb 4
1350 \&    <opt>
1351 \&      <username>testuser</username>
1352 \&      <password>frodo</password>
1353 \&    </opt>
1354 .Ve
1355 .PP
1356 Repeated nested elements are represented as anonymous arrays:
1357 .PP
1358 .Vb 9
1359 \&    <opt>
1360 \&      <person firstname="Joe" lastname="Smith">
1361 \&        <email>joe@smith.com</email>
1362 \&        <email>jsmith@yahoo.com</email>
1363 \&      </person>
1364 \&      <person firstname="Bob" lastname="Smith">
1365 \&        <email>bob@smith.com</email>
1366 \&      </person>
1367 \&    </opt>
1368 \&
1369 \&    {
1370 \&      \*(Aqperson\*(Aq => [
1371 \&                    {
1372 \&                      \*(Aqemail\*(Aq => [
1373 \&                                   \*(Aqjoe@smith.com\*(Aq,
1374 \&                                   \*(Aqjsmith@yahoo.com\*(Aq
1375 \&                                 ],
1376 \&                      \*(Aqfirstname\*(Aq => \*(AqJoe\*(Aq,
1377 \&                      \*(Aqlastname\*(Aq => \*(AqSmith\*(Aq
1378 \&                    },
1379 \&                    {
1380 \&                      \*(Aqemail\*(Aq => \*(Aqbob@smith.com\*(Aq,
1381 \&                      \*(Aqfirstname\*(Aq => \*(AqBob\*(Aq,
1382 \&                      \*(Aqlastname\*(Aq => \*(AqSmith\*(Aq
1383 \&                    }
1384 \&                  ]
1385 \&    }
1386 .Ve
1387 .PP
1388 Nested elements with a recognised key attribute are transformed (folded) from
1389 an array into a hash keyed on the value of that attribute (see the \f(CW\*(C`KeyAttr\*(C'\fR
1390 option):
1391 .PP
1392 .Vb 5
1393 \&    <opt>
1394 \&      <person key="jsmith" firstname="Joe" lastname="Smith" />
1395 \&      <person key="tsmith" firstname="Tom" lastname="Smith" />
1396 \&      <person key="jbloggs" firstname="Joe" lastname="Bloggs" />
1397 \&    </opt>
1398 \&
1399 \&    {
1400 \&      \*(Aqperson\*(Aq => {
1401 \&                    \*(Aqjbloggs\*(Aq => {
1402 \&                                   \*(Aqfirstname\*(Aq => \*(AqJoe\*(Aq,
1403 \&                                   \*(Aqlastname\*(Aq => \*(AqBloggs\*(Aq
1404 \&                                 },
1405 \&                    \*(Aqtsmith\*(Aq => {
1406 \&                                  \*(Aqfirstname\*(Aq => \*(AqTom\*(Aq,
1407 \&                                  \*(Aqlastname\*(Aq => \*(AqSmith\*(Aq
1408 \&                                },
1409 \&                    \*(Aqjsmith\*(Aq => {
1410 \&                                  \*(Aqfirstname\*(Aq => \*(AqJoe\*(Aq,
1411 \&                                  \*(Aqlastname\*(Aq => \*(AqSmith\*(Aq
1412 \&                                }
1413 \&                  }
1414 \&    }
1415 .Ve
1416 .PP
1417 The <anon> tag can be used to form anonymous arrays:
1418 .PP
1419 .Vb 6
1420 \&    <opt>
1421 \&      <head><anon>Col 1</anon><anon>Col 2</anon><anon>Col 3</anon></head>
1422 \&      <data><anon>R1C1</anon><anon>R1C2</anon><anon>R1C3</anon></data>
1423 \&      <data><anon>R2C1</anon><anon>R2C2</anon><anon>R2C3</anon></data>
1424 \&      <data><anon>R3C1</anon><anon>R3C2</anon><anon>R3C3</anon></data>
1425 \&    </opt>
1426 \&
1427 \&    {
1428 \&      \*(Aqhead\*(Aq => [
1429 \&                  [ \*(AqCol 1\*(Aq, \*(AqCol 2\*(Aq, \*(AqCol 3\*(Aq ]
1430 \&                ],
1431 \&      \*(Aqdata\*(Aq => [
1432 \&                  [ \*(AqR1C1\*(Aq, \*(AqR1C2\*(Aq, \*(AqR1C3\*(Aq ],
1433 \&                  [ \*(AqR2C1\*(Aq, \*(AqR2C2\*(Aq, \*(AqR2C3\*(Aq ],
1434 \&                  [ \*(AqR3C1\*(Aq, \*(AqR3C2\*(Aq, \*(AqR3C3\*(Aq ]
1435 \&                ]
1436 \&    }
1437 .Ve
1438 .PP
1439 Anonymous arrays can be nested to arbirtrary levels and as a special case, if
1440 the surrounding tags for an \s-1XML\s0 document contain only an anonymous array the
1441 arrayref will be returned directly rather than the usual hashref:
1442 .PP
1443 .Vb 5
1444 \&    <opt>
1445 \&      <anon><anon>Col 1</anon><anon>Col 2</anon></anon>
1446 \&      <anon><anon>R1C1</anon><anon>R1C2</anon></anon>
1447 \&      <anon><anon>R2C1</anon><anon>R2C2</anon></anon>
1448 \&    </opt>
1449 \&
1450 \&    [
1451 \&      [ \*(AqCol 1\*(Aq, \*(AqCol 2\*(Aq ],
1452 \&      [ \*(AqR1C1\*(Aq, \*(AqR1C2\*(Aq ],
1453 \&      [ \*(AqR2C1\*(Aq, \*(AqR2C2\*(Aq ]
1454 \&    ]
1455 .Ve
1456 .PP
1457 Elements which only contain text content will simply be represented as a
1458 scalar.  Where an element has both attributes and text content, the element
1459 will be represented as a hashref with the text content in the 'content' key
1460 (see the \f(CW\*(C`ContentKey\*(C'\fR option):
1461 .PP
1462 .Vb 4
1463 \&  <opt>
1464 \&    <one>first</one>
1465 \&    <two attr="value">second</two>
1466 \&  </opt>
1467 \&
1468 \&  {
1469 \&    \*(Aqone\*(Aq => \*(Aqfirst\*(Aq,
1470 \&    \*(Aqtwo\*(Aq => { \*(Aqattr\*(Aq => \*(Aqvalue\*(Aq, \*(Aqcontent\*(Aq => \*(Aqsecond\*(Aq }
1471 \&  }
1472 .Ve
1473 .PP
1474 Mixed content (elements which contain both text content and nested elements)
1475 will be not be represented in a useful way \- element order and significant
1476 whitespace will be lost.  If you need to work with mixed content, then
1477 XML::Simple is not the right tool for your job \- check out the next section.
1478 .SH "WHERE TO FROM HERE?"
1479 .IX Header "WHERE TO FROM HERE?"
1480 \&\fBXML::Simple\fR is able to present a simple \s-1API\s0 because it makes some
1481 assumptions on your behalf.  These include:
1482 .IP "\(bu" 4
1483 You're not interested in text content consisting only of whitespace
1484 .IP "\(bu" 4
1485 You don't mind that when things get slurped into a hash the order is lost
1486 .IP "\(bu" 4
1487 You don't want fine-grained control of the formatting of generated \s-1XML\s0
1488 .IP "\(bu" 4
1489 You would never use a hash key that was not a legal \s-1XML\s0 element name
1490 .IP "\(bu" 4
1491 You don't need help converting between different encodings
1492 .PP
1493 In a serious \s-1XML\s0 project, you'll probably outgrow these assumptions fairly
1494 quickly.  This section of the document used to offer some advice on chosing a
1495 more powerful option.  That advice has now grown into the 'Perl\-XML \s-1FAQ\s0'
1496 document which you can find at: <http://perl\-xml.sourceforge.net/faq/>
1497 .PP
1498 The advice in the \s-1FAQ\s0 boils down to a quick explanation of tree versus
1499 event based parsers and then recommends:
1500 .PP
1501 For event based parsing, use \s-1SAX\s0 (do not set out to write any new code for
1502 XML::Parser's handler \s-1API\s0 \- it is obselete).
1503 .PP
1504 For tree-based parsing, you could choose between the 'Perlish' approach of
1505 XML::Twig and more standards based \s-1DOM\s0 implementations \- preferably one with
1506 XPath support.
1507 .SH "SEE ALSO"
1508 .IX Header "SEE ALSO"
1509 \&\fBXML::Simple\fR requires either XML::Parser or \s-1XML::SAX\s0.
1510 .PP
1511 To generate documents with namespaces, XML::NamespaceSupport is required.
1512 .PP
1513 The optional caching functions require Storable.
1514 .PP
1515 Answers to Frequently Asked Questions about XML::Simple are bundled with this
1516 distribution as: XML::Simple::FAQ
1517 .SH "COPYRIGHT"
1518 .IX Header "COPYRIGHT"
1519 Copyright 1999\-2004 Grant McLean <grantm@cpan.org>
1520 .PP
1521 This library is free software; you can redistribute it and/or modify it
1522 under the same terms as Perl itself.