NAME¶
Data::DumpXML - Dump arbitrary data structures as XML
SYNOPSIS¶
use Data::DumpXML qw(dump_xml);
$xml = dump_xml(@list)
DESCRIPTION¶
This module provides a single function called
dump_xml() that takes a
list of Perl values as its argument and produces a string as its result. The
string returned is an XML document that represents any Perl data structures
passed to the function. Reference loops are handled correctly.
The following data model is used:
data : scalar*
scalar = undef | str | ref | alias
ref : scalar | array | hash | glob | code
array: scalar*
hash: (key scalar)*
The distribution comes with an XML schema and a DTD that more formally describe
this structure.
As an example of the XML documents produced, the following call:
$a = bless [1,2], "Foo";
dump_xml($a);
produces:
<?xml version="1.0" encoding="US-ASCII"?>
<data xmlns="http://www.cpan.org/.../Data-DumpXML.xsd">
<ref>
<array class="Foo">
<str>1</str>
<str>2</str>
</array>
</ref>
</data>
If
dump_xml() is called in a void context, then the dump is printed on
STDERR automatically. For compatibility with "Data::Dump", there is
also an alias for
dump_xml() called simply
dump().
"Data::DumpXML::Parser" is a class that can restore data structures
dumped by
dump_xml().
Configuration variables
The generated XML is influenced by a set of configuration variables. If you
modify them, then it is a good idea to localize the effect. For example:
sub my_dump_xml {
local $Data::DumpXML::INDENT = "";
local $Data::DumpXML::XML_DECL = 0;
local $Data::DumpXML::DTD_LOCATION = "";
local $Data::DumpXML::NS_PREFIX = "dumpxml";
return dump_xml(@_);
}
The variables are:
- $Data::DumpXML::INDENT
- You can set the variable $Data::DumpXML::INDENT to control
the amount of indenting. The variable contains the whitespace you want to
be used for each level of indenting. The default is a single space. To
suppress indenting, set it to "".
- $Data::DumpXML::INDENT_STYLE
- This variable controls where end element are placed. If you
set this variable to the value "Lisp" then end tags are not
prefixed by NL. This give a more compact output.
- $Data::DumpXML::XML_DECL
- This boolean variable controls whether an XML declaration
should be prefixed to the output. The XML declaration is the <?xml
...?> thingy. The default is 1. Set this value to 0 to suppress the
declaration.
- $Data::DumpXML::NAMESPACE
- This variable contains the namespace used for the XML
elements. The default is to let this be a URI that actually resolve to the
XML schema on CPAN. Set it to "" to disable use of
namespaces.
- $Data::DumpXML::NS_PREFIX
- This variable contains the namespace prefix to use on the
elements. The default is "", which means that a default
namespace will be declared.
- $Data::DumpXML::SCHEMA_LOCATION
- This variable contains the location of the XML schema. If
this variable is non-empty, then an "xsi:schemaLocation"
attribute is added to the top level "data" element. The default
is not to include this, as the location can be inferred from the default
XML namespace used.
- $Data::DumpXML::DTD_LOCATION
- This variable contains the location of the DTD. If this
variable is non-empty, then a <!DOCTYPE ...> is included in the
output. The default is to point to the DTD on CPAN. Set it to ""
to suppress the <!DOCTYPE ...> line.
BUGS¶
Class names with 8-bit characters are dumped as Latin-1, but converted to UTF-8
when restored by the Data::DumpXML::Parser.
The content of globs and subroutines are not dumped. They are restored as the
strings "** glob **" and "** code **".
LVALUE and IO objects are not dumped at all. They simply disappear from the
restored data structure.
SEE ALSO¶
Data::DumpXML::Parser, XML::Parser, XML::Dumper, Data::Dump
AUTHORS¶
The "Data::DumpXML" module is written by Gisle Aas
<gisle@aas.no>, based on "Data::Dump".
The "Data::Dump" module was written by Gisle Aas, based on
"Data::Dumper" by Gurusamy Sarathy <gsar@umich.edu>.
Copyright 1998-2003 Gisle Aas.
Copyright 1996-1998 Gurusamy Sarathy.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.