simple(3)

NAME

XML::Simple - Easy API to read/write XML (esp config
files)

SYNOPSIS

use XML::Simple;
my $ref = XMLin([<xml file or string>] [, <options>]);
my $xml = XMLout($hashref [, <options>]);
Or the object oriented way:
require XML::Simple;
my $xs = new XML::Simple(options);
my  $ref  =  $xs->XMLin([<xml file or string>] [, <options>]);
my $xml = $xs->XMLout($hashref [, <options>]);

QUICK START

Say you have a script called foo and a file of configura
tion options called foo.xml containing this:

<config logdir="/var/log/foo/" debugfile="/tmp/foo.de

bug">

<server name="sahara" osname="solaris" osver

sion="2.6">

<address>10.0.0.101</address>
<address>10.0.1.101</address>

</server>
<server name="gobi" osname="irix" osversion="6.5">

<address>10.0.0.102</address>

</server>
<server name="kalahari" osname="linux" osver

sion="2.0.34">

<address>10.0.0.103</address>
<address>10.0.1.103</address>

</server>

</config>

The following lines of code in foo:

use XML::Simple;

my $config = XMLin();

will 'slurp' the configuration options into the hashref
$config (because no arguments are passed to "XMLin()" the
name and location of the XML file will be inferred from
name and location of the script). You can dump out the
contents of the hashref using Data::Dumper:

use Data::Dumper;

print Dumper($config);

which will produce something like this (formatting has
been adjusted for brevity):

{

'logdir' => '/var/log/foo/',
'debugfile' => '/tmp/foo.debug',
'server' => {

'sahara' => {

'osversion' => '2.6',
'osname' => 'solaris',
'address' => [ '10.0.0.101',

'10.0.1.101' ]

},
'gobi' => {

'osversion' => '6.5',
'osname' => 'irix',
'address' => '10.0.0.102'

},
'kalahari' => {

'osversion' => '2.0.34',
'osname' => 'linux',
'address' => [ '10.0.0.103',

'10.0.1.103' ]

}

}

}

Your script could then access the name of the log direc
tory like this:

print $config->{logdir};

similarly, the second address on the server 'kalahari'
could be referenced as:

print $config->{server}->{kalahari}->{address}->[1];

What could be simpler? (Rhetorical).

For simple requirements, that's really all there is to it.
If you want to store your XML in a different directory or
file, or pass it in as a string or even pass it in via
some derivative of an IO::Handle, you'll need to check out
"OPTIONS". If you want to turn off or tweak the array
folding feature (that neat little transformation that pro
duced $config->{server}) you'll find options for that as
well.

If you want to generate XML (for example to write a modi
fied version of $config back out as XML), check out
"XMLout()".

If your needs are not so simple, this may not be the mod
ule for you. In that case, you might want to read "WHERE
TO FROM HERE?".

DESCRIPTION

The XML::Simple module provides a simple API layer on top
of the XML::Parser module. Two functions are exported:
"XMLin()" and "XMLout()".

The most common approach is to simply call these two func
tions directly, but an optional object oriented interface
(see "OPTIONAL OO INTERFACE" below) allows them to be
called as methods of an XML::Simple object.

XMLin()

Parses XML formatted data and returns a reference to a
data structure which contains the same information in a
more readily accessible form. (Skip down to "EXAMPLES"
below, for more sample code).

"XMLin()" accepts an optional XML specifier followed by
zero or more 'name => value' option pairs. The XML speci
fier can be one of the following:

A filename

If the filename contains no directory components
"XMLin()" will look for the file in each directory in
the searchpath (see "OPTIONS" below). eg:

$ref = XMLin('/etc/params.xml');

Note, the filename '-' can be used to parse from
STDIN.

undef

If there is no XML specifier, "XMLin()" will check the
script directory and each of the searchpath directo
ries for a file with the same name as the script but
with the extension '.xml'. Note: if you wish to spec
ify options, you must specify the value 'undef'. eg:

$ref = XMLin(undef, forcearray => 1);

A string of XML

A string containing XML (recognised by the presence of
'<' and '>' characters) will be parsed directly. eg:

$ref = XMLin('<opt username="bob" password="flurp"

/>');

An IO::Handle object

An IO::Handle object will be read to EOF and its con
tents parsed. eg:

$fh = new IO::File('/etc/params.xml');
$ref = XMLin($fh);

XMLout()

Takes a data structure (generally a hashref) and returns
an XML encoding of that structure. If the resulting XML
is parsed using "XMLin()", it will return a data structure
equivalent to the original.

When translating hashes to XML, hash keys which have a
leading '-' will be silently skipped. This is the
approved method for marking elements of a data structure
which should be ignored by "XMLout". (Note: If these
items were not skipped the key names would be emitted as
element or attribute names with a leading '-' which would
not be valid XML).

Caveats

Some care is required in creating data structures which
will be passed to "XMLout()". Hash keys from the data
structure will be encoded as either XML element names or
attribute names. Therefore, you should use hash key names
which conform to the relatively strict XML naming rules:

Names in XML must begin with a letter. The remaining
characters may be letters, digits, hyphens (-), under
scores (_) or full stops (.). It is also allowable to
include one colon (:) in an element name but this should
only be used when working with namespaces - a facility
well beyond the scope of XML::Simple.

You can use other punctuation characters in hash values
(just not in hash keys) however XML::Simple does not sup port dumping binary data.

If you break these rules, the current implementation of
"XMLout()" will simply emit non-compliant XML which will
be rejected if you try to read it back in. (A later ver
sion of XML::Simple might take a more proactive approach).

Note also that although you can nest hashes and arrays to
arbitrary levels, recursive data structures are not sup
ported and will cause "XMLout()" to die.

Refer to "WHERE TO FROM HERE?" if "XMLout()" is too simple
for your needs.

OPTIONS

XML::Simple supports a number of options (in fact as each release of XML::Simple adds more options, the module's claim to the name 'Simple' becomes more tenuous). If you
find yourself repeatedly having to specify the same
options, you might like to investigate "OPTIONAL OO INTER
FACE" below.

Because there are so many options, it's hard for new users
to know which ones are important, so here are the two you
really need to know about:

· check out 'forcearray' because you'll almost certainly

want to turn it on

· make sure you know what the 'keyattr' option does and

what its default value is because it may surprise you
otherwise

Both "XMLin()" and "XMLout()" expect a single argument
followed by a list of options. An option takes the form
of a 'name => value' pair. The options listed below are
marked with 'in' if they are recognised by "XMLin()" and
'out' if they are recognised by "XMLout()".

keyattr => [ list ] (in+out)

This option controls the 'array folding' feature which
translates nested elements from an array to a hash.
For example, this XML:

<opt>

<user login="grep" fullname="Gary R Epstein" />
<user login="stty" fullname="Simon T Tyson" />

</opt>

would, by default, parse to this:

{

'user' => [

{

'login' => 'grep',
'fullname' => 'Gary R Epstein'

},
{

'login' => 'stty',
'fullname' => 'Simon T Tyson'

}

]

}

If the option 'keyattr => "login"' were used to spec
ify that the 'login' attribute is a key, the same XML
would parse to:

{

'user' => {

'stty' => {

'fullname' => 'Simon T

Tyson'

},

'grep' => {

'fullname' => 'Gary R

Epstein'

}

}

}

The key attribute names should be supplied in an
arrayref if there is more than one. "XMLin()" will
attempt to match attribute names in the order sup
plied. "XMLout()" will use the first attribute name
supplied when 'unfolding' a hash into an array.

Note: the keyattr option controls the folding of
arrays. By default a single nested element will be
rolled up into a scalar rather than an array and
therefore will not be folded. Use the 'forcearray'
option (below) to force nested elements to be parsed
into arrays and therefore candidates for folding into
hashes.

The default value for 'keyattr' is ['name', 'key',
'id']. Setting this option to an empty list will dis
able the array folding feature.

keyattr => { list } (in+out)

This alternative method of specifiying the key
attributes allows more fine grained control over which
elements are folded and on which attributes. For
example the option 'keyattr => { package => 'id' }
will cause any package elements to be folded on the
'id' attribute. No other elements which have an 'id'
attribute will be folded at all.

Note: "XMLin()" will generate a warning if this syntax
is used and an element which does not have the speci
fied key attribute is encountered (eg: a 'package'
element without an 'id' attribute, to use the example
above). Warnings will only be generated if -w is in
force.

Two further variations are made possible by prefixing
a '+' or a '-' character to the attribute name:

The option 'keyattr => { user => "+login" }' will
cause this XML:

<opt>

<user login="grep" fullname="Gary R Epstein" />
<user login="stty" fullname="Simon T Tyson" />

</opt>

to parse to this data structure:

{

'user' => {

'stty' => {

'fullname' => 'Simon T

Tyson',
'login' => 'stty'

},

'grep' => {

'fullname' => 'Gary R

Epstein',
'login' => 'grep'

}

}

}

The '+' indicates that the value of the key attribute
should be copied rather than moved to the folded hash
key.

A '-' prefix would produce this result:

{

'user' => {

'stty' => {

'fullname' => 'Simon T

Tyson',
'-login' => 'stty'

},

'grep' => {

'fullname' => 'Gary R

Epstein',
'-login' => 'grep'

}

}

}

As described earlier, "XMLout" will ignore hash keys
starting with a '-'.

searchpath => [ list ] (in)

Where the XML is being read from a file, and no path
to the file is specified, this attribute allows you to
specify which directories should be searched.

If the first parameter to "XMLin()" is undefined, the
default searchpath will contain only the directory in
which the script itself is located. Otherwise the
default searchpath will be empty.

Note: the current directory ('.') is not searched
unless it is the directory containing the script.

forcearray => 1 (in)

This option should be set to '1' to force nested ele
ments to be represented as arrays even when there is
only one. Eg, with forcearray enabled, this XML:

<opt>

<name>value</name>

</opt>

would parse to this:

{

'name' => [

'value'

]

}

instead of this (the default):

{

'name' => 'value'

}

This option is especially useful if the data structure
is likely to be written back out as XML and the
default behaviour of rolling single nested elements up
into attributes is not desirable.

If you are using the array folding feature, you should
almost certainly enable this option. If you do not,
single nested elements will not be parsed to arrays
and therefore will not be candidates for folding to a
hash. (Given that the default value of 'keyattr'
enables array folding, the default value of this
option should probably also have been enabled too sorry).

forcearray => [ name(s) ] (in)

This alternative form of the 'forcearray' option
allows you to specify a list of element names which
should always be forced into an array representation,
rather than the 'all or nothing' approach above.

noattr => 1 (in+out)

When used with "XMLout()", the generated XML will con
tain no attributes. All hash key/values will be rep
resented as nested elements instead.

When used with "XMLin()", any attributes in the XML
will be ignored.

suppressempty => 1 | '' | undef (in)

This option controls what "XMLin()" should do with
empty elements (no attributes and no content). The
default behaviour is to represent them as empty
hashes. Setting this option to a true value (eg: 1)
will cause empty elements to be skipped altogether.
Setting the option to 'undef' or the empty string will
cause empty elements to be represented as the unde
fined value or the empty string respectively. The
latter two alternatives are a little easier to test
for in your code than a hash with no keys.

cache => [ cache scheme(s) ] (in)

Because loading the XML::Parser module and parsing an XML file can consume a significant number of CPU
cycles, it is often desirable to cache the output of
"XMLin()" for later reuse.

When parsing from a named file, XML::Simple supports a number of caching schemes. The 'cache' option may be
used to specify one or more schemes (using an anony
mous array). Each scheme will be tried in turn in the
hope of finding a cached pre-parsed representation of
the XML file. If no cached copy is found, the file
will be parsed and the first cache scheme in the list
will be used to save a copy of the results. The fol
lowing cache schemes have been implemented:

storable

Utilises Storable.pm to read/write a cache file with the same name as the XML file but with the
extension .stor

memshare

When a file is first parsed, a copy of the result
ing data structure is retained in memory in the
XML::Simple module's namespace. Subsequent calls to parse the same file will return a reference to
this structure. This cached version will persist
only for the life of the Perl interpreter (which
in the case of mod_perl for example, may be some
significant time).

Because each caller receives a reference to the
same data structure, a change made by one caller
will be visible to all. For this reason, the ref
erence returned should be treated as read-only.

memcopy

This scheme works identically to 'memshare'
(above) except that each caller receives a refer
ence to a new data structure which is a copy of
the cached version. Copying the data structure
will add a little processing overhead, therefore
this scheme should only be used where the caller
intends to modify the data structure (or wishes to
protect itself from others who might). This
scheme uses Storable.pm to perform the copy.

keeproot => 1 (in+out)

In its attempt to return a data structure free of
superfluous detail and unnecessary levels of indirec
tion, "XMLin()" normally discards the root element
name. Setting the 'keeproot' option to '1' will cause
the root element name to be retained. So after exe
cuting this code:

$config = XMLin('<config tempdir="/tmp" />', keep

root => 1)

You'll be able to reference the tempdir as "$con
fig->{config}->{tempdir}" instead of the default
"$config->{tempdir}".

Similarly, setting the 'keeproot' option to '1' will
tell "XMLout()" that the data structure already con
tains a root element name and it is not necessary to
add another.

rootname => 'string' (out)

By default, when "XMLout()" generates XML, the root
element will be named 'opt'. This option allows you
to specify an alternative name.

Specifying either undef or the empty string for the
rootname option will produce XML with no root ele
ments. In most cases the resulting XML fragment will
not be 'well formed' and therefore could not be read
back in by "XMLin()". Nevertheless, the option has
been found to be useful in certain circumstances.

forcecontent (in)

When "XMLin()" parses elements which have text content
as well as attributes, the text content must be repre
sented as a hash value rather than a simple scalar.
This option allows you to force text content to always
parse to a hash value even when there are no
attributes. So for example:

XMLin('<opt><x>text1</x><y a="2">text2</y></opt>',

forcecontent => 1)

will parse to:

{

'x' => { 'content' => 'text1' },
'y' => { 'a' => 2, 'content' => 'text2' }

}

instead of:

{

'x' => 'text1',
'y' => { 'a' => 2, 'content' => 'text2' }

}

contentkey => 'keyname' (in+out)

When text content is parsed to a hash value, this
option let's you specify a name for the hash key to
override the default 'content'. So for example:

XMLin('<opt one="1">Text</opt>', contentkey =>

'text')

will parse to:

{ 'one' => 1, 'text' => 'Text' }

instead of:

{ 'one' => 1, 'content' => 'Text' }

"XMLout()" will also honour the value of this option
when converting a hashref to XML.

xmldecl => 1 or xmldecl => 'string' (out)

If you want the output from "XMLout()" to start with
the optional XML declaration, simply set the option to
'1'. The default XML declaration is:

<?xml version='1.0' standalone='yes'?>

If you want some other string (for example to declare
an encoding value), set the value of this option to
the complete string you require.

outputfile => <file specifier> (out)

The default behaviour of "XMLout()" is to return the
XML as a string. If you wish to write the XML to a
file, simply supply the filename using the 'output
file' option. Alternatively, you can supply an IO
handle object instead of a filename.

noescape => 1 (out)

By default, "XMLout()" will translate the characters
'<', '>', '&' and '"' to '&lt;', '&gt;', '&amp;' and
'&quot' respectively. Use this option to suppress
escaping (presumably because you've already escaped
the data in some more sophisticated manner).

parseropts => [ XML::Parser Options ] (in)

Use this option to specify parameters that should be
passed to the constructor of the underlying
XML::Parser object. For example to turn on the names
pace processing mode, you could say:

XMLin($xml, parseropts => [ Namespaces => 1 ])

OPTIONAL OO INTERFACE

The procedural interface is both simple and convenient
however there are a couple of reasons why you might prefer
to use the object oriented (OO) interface:

· to define a set of default values which should be used

on all subsequent calls to "XMLin()" or "XMLout()"

· to override methods in XML::Simple to provide cus

tomised behaviour

The default values for the options described above are
unlikely to suit everyone. The OO interface allows you to
effectively override XML::Simple's defaults with your pre ferred values. It works like this:

First create an XML::Simple parser object with your pre
ferred defaults:

my $xs = new XML::Simple(forcearray => 1, keeproot =>

1);

then call "XMLin()" or "XMLout()" as a method of that
object:

my $ref = $xs->XMLin($xml);
my $xml = $xs->XMLout($ref);

You can also specify options when you make the method
calls and these values will be merged with the values
specified when the object was created. Values specified
in a method call take precedence.

Overriding methods is a more advanced topic but might be
useful if for example you wished to provide an alternative
routine for escaping character data (the escape_value
method) or for building the initial parse tree (the
build_tree method).

ERROR HANDLING

The XML standard is very clear on the issue of non-compli
ant documents. An error in parsing any single element
(for example a missing end tag) must cause the whole docu
ment to be rejected. XML::Simple will die with an appro priate message if it encounters a parsing error.

If dying is not appropriate for your application, you
should arrange to call "XMLin()" in an eval block and look
for errors in $@. eg:

my $config = eval { XMLin() };
PopUpMessage($@) if($@);

Note, there is a common misconception that use of eval
will significantly slow down a script. While that may be
true when the code being eval'd is in a string, it is not
true of code like the sample above.

EXAMPLES

When "XMLin()" reads the following very simple piece of
XML:

<opt username="testuser" password="frodo"></opt>

it returns the following data structure:

{

'username' => 'testuser',
'password' => 'frodo'

}

The identical result could have been produced with this
alternative XML:

<opt username="testuser" password="frodo" />

Or this (although see 'forcearray' option for variations):

<opt>

<username>testuser</username>
<password>frodo</password>

</opt>

Repeated nested elements are represented as anonymous
arrays:

<opt>

<person firstname="Joe" lastname="Smith">

<email>joe@smith.com</email>
<email>jsmith@yahoo.com</email>

</person>
<person firstname="Bob" lastname="Smith">

<email>bob@smith.com</email>

</person>

</opt>

{

'person' => [

{

'email' => [

'joe@smith.com',
'jsmith@yahoo.com'

],

'firstname' => 'Joe',
'lastname' => 'Smith'

},
{

'email' => 'bob@smith.com',
'firstname' => 'Bob',
'lastname' => 'Smith'

}

]

}

Nested elements with a recognised key attribute are trans
formed (folded) from an array into a hash keyed on the
value of that attribute:

<opt>

<person key="jsmith" firstname="Joe" last

name="Smith" />
<person key="tsmith" firstname="Tom" last

name="Smith" />
<person key="jbloggs" firstname="Joe" last

name="Bloggs" />

</opt>

{

'person' => {

'jbloggs' => {

'firstname' => 'Joe',
'lastname' => 'Bloggs'

},

'tsmith' => {

'firstname' => 'Tom',
'lastname' => 'Smith'

},

'jsmith' => {

'firstname' => 'Joe',
'lastname' => 'Smith'

}

}

}

The <anon> tag can be used to form anonymous arrays:

<opt>

<head><anon>Col 1</anon><anon>Col 2</anon><anon>Col

3</anon></head>
<da

ta><anon>R1C1</anon><anon>R1C2</anon><anon>R1C3</anon></data>
<da

ta><anon>R2C1</anon><anon>R2C2</anon><anon>R2C3</anon></data>
<da

ta><anon>R3C1</anon><anon>R3C2</anon><anon>R3C3</anon></data>

</opt>

{

'head' => [

[ 'Col 1', 'Col 2', 'Col 3' ]

],

'data' => [

[ 'R1C1', 'R1C2', 'R1C3' ],
[ 'R2C1', 'R2C2', 'R2C3' ],
[ 'R3C1', 'R3C2', 'R3C3' ]

]

}

Anonymous arrays can be nested to arbirtrary levels and as
a special case, if the surrounding tags for an XML docu
ment contain only an anonymous array the arrayref will be
returned directly rather than the usual hashref:

<opt>

<anon><anon>Col 1</anon><anon>Col 2</anon></anon>
<anon><anon>R1C1</anon><anon>R1C2</anon></anon>
<anon><anon>R2C1</anon><anon>R2C2</anon></anon>

</opt>

[

[ 'Col 1', 'Col 2' ],
[ 'R1C1', 'R1C2' ],
[ 'R2C1', 'R2C2' ]

]

Elements which only contain text content will simply be
represented as a scalar. Where an element has both
attributes and text content, the element will be repre
sented as a hashref with the text content in the 'content'
key:

<opt>

<one>first</one>
<two attr="value">second</two>

</opt>

{

'one' => 'first',
'two' => { 'attr' => 'value', 'content' => 'second' }

}

Mixed content (elements which contain both text content
and nested elements) will be not be represented in a use
ful way - element order and significant whitespace will be
lost. If you need to work with mixed content, then
XML::Simple is not the right tool for your job - check out
the next section.

WHERE TO FROM HERE?

XML::Simple is by nature very simple.

· The parsing process liberally disposes of 'surplus'

whitespace - some applications will be sensitive to
this.

· Slurping data into a hash will implicitly discard

information about attribute order. Normally this
would not be a problem because any items for which
order is important would typically be encoded as ele
ments rather than attributes. However XML::Simple's aggressive slurping and folding algorithms can defeat
even these techniques.

· The API offers little control over the output of

"XMLout()". In particular, it is not especially
likely that feeding the output from "XMLin()" into
"XMLout()" will reproduce the original XML (although
passing the output from "XMLout()" into "XMLin()"
should reproduce the original data structure).

· "XMLout()" cannot produce well formed HTML unless you

feed it with care - hash keys must conform to XML ele
ment naming rules and undefined values should be
avoided.

· "XMLout()" does not currently support encodings

(although it shouldn't stand in your way if you feed
it encoded data).

· If you're attempting to get the output from "XMLout()"

to conform to a specific DTD, you're almost certainly
using the wrong tool for the job.

If any of these points are a problem for you, then
XML::Simple is probably not the right module for your application. The following section is intended to give
pointers which might help you select a more powerful tool
- it's a bit sketchy right now but submissions are wel
come.

XML::Parser

XML::Simple is built on top of XML::Parser, so if you have XML::Simple working you already have XML::Parser installed. This is a comprehensive, fast, industrial
strength (non-validating) parsing tool built on top of
James Clark's 'expat' library. It does support con
verting XML into a Perl tree structure (with full sup
port for mixed content) but for arbritrarily large
documents you're probably better off defining handler
routines for XML::Parser to call as each element is parsed. The distribution includes a number of sample
applications.

XML::DOM

The data structure returned by XML::Simple was designed for convenience rather than standards compli
ance. XML::DOM is a parser built on top of
XML::Parser, which returns a 'Document' object con forming to the API of the Document Object Model as
described at http://www.w3.org/TR/REC-DOM-Level-1 .
This Document object can then be examined, modified
and written back out to a file or converted to a
string.

XML::Grove

Compliance with the Document Object Model might be
particularly useful when porting code to or from
another language. However, if you're looking for a
simpler, 'perlish' object interface, take a look at
XML::Grove.

XML::Twig

XML::Twig offers a tree-oriented interface to a docu
ment while still allowing the processing of documents
of any size. It allows processing chunks of documents
in tree-mode which can then be flushed or purged from
the memory. The XML::Twig page is at http://stan
dards.ieee.org/resources/spasystem/twig/

libxml-perl

libxml-perl is a collection of Perl modules, scripts, and documents for working with XML in Perl. The dis
tribution includes PerlSAX - a Perl implementation of
the SAX API. It also include XML::PatAct modules for processing XML by defining patterns and associating
them with actions. For more details see http://bit
sko.slc.ut.us/libxml-perl/ .

XML::PYX

XML::PYX allows you to apply Unix command pipelines (using grep, sed etc) to filter or transform XML
files. Ideally suited for tasks such as extracting
all text content or stripping out all occurrences of a
particular tag without having to write a Perl script
at all. It can also be used for transforming HTML to
XHTML.

XML::RAX

If you wish to process XML files containing a series
of 'records', XML::RAX provides a simple purposedesigned interface. If it still hasn't made it to
CPAN, try: http://www.dancentury.com/robh/

XML::Writer

XML::Writer is a helper module for Perl programs that write XML documents.

XML::Dumper

XML::Dumper dumps Perl data to a structured XML for mat. XML::Dumper can also read XML data that was pre viously dumped by the module and convert it back to
Perl.

Don't forget to check out the Perl XML FAQ at:
http://www.perlxml.com/faq/perl-xml-faq.html

STATUS

This version (1.08) is the current stable version.

SEE ALSO

XML::Simple requires XML::Parser and File::Spec. The optional caching functions require Storable.

COPYRIGHT

Copyright 1999-2001 Grant McLean <grantm@cpan.org>

This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

perl v5.8.0 2002-02-09 Simple(3)