XML::Dumper(3pm)

1Dumper(3)             User Contributed Perl Documentation            Dumper(3)
2
3
4

NAME

6       XML::Dumper - Perl module for dumping Perl objects from/to XML
7

SYNOPSIS

9         # ===== Using an object
10         use XML::Dumper;
11         $dump = new XML::Dumper;
12
13         $xml  = $dump->pl2xml( $perl );
14         $perl = $dump->xml2pl( $xml );
15         $dump->pl2xml( $perl, "my_perl_data.xml.gz" );
16
17         # ===== Using function calls
18         use XML::Dumper;
19
20         $xml  = pl2xml( $perl );
21         $perl = xml2pl( $xml );
22

EXTENDED SYNOPSIS

24         use XML::Dumper;
25         my $dump = new XML::Dumper;
26
27         my $perl  = '';
28         my $xml   = '';
29
30         # ===== Convert Perl code to XML
31         $perl = [
32           {
33                       fname       => 'Fred',
34                       lname       => 'Flintstone',
35                       residence   => 'Bedrock'
36           },
37           {
38                       fname       => 'Barney',
39                       lname       => 'Rubble',
40                       residence   => 'Bedrock'
41           }
42         ];
43         $xml = $dump->pl2xml( $perl );
44
45         # ===== Dump to a file
46         my $file = "dump.xml";
47         $dump->pl2xml( $perl, $file );
48
49         # ===== Convert XML to Perl code
50         $xml = q|
51         <perldata>
52          <arrayref>
53           <item key="0">
54            <hashref>
55               <item key="fname">Fred</item>
56               <item key="lname">Flintstone</item>
57               <item key="residence">Bedrock</item>
58            </hashref>
59           </item>
60           <item key="1">
61            <hashref>
62               <item key="fname">Barney</item>
63               <item key="lname">Rubble</item>
64               <item key="residence">Bedrock</item>
65            </hashref>
66           </item>
67          </arrayref>
68         </perldata>
69         |;
70
71         my $perl = $dump->xml2pl( $xml );
72
73         # ===== Convert an XML file to Perl code
74         my $perl = $dump->xml2pl( $file );
75
76         # ===== And serialize Perl code to an XML file
77         $dump->pl2xml( $perl, $file );
78
79         # ===== USE COMPRESSION
80         $dump->pl2xml( $perl, $file.".gz" );
81
82         # ===== INCLUDE AN IN-DOCUMENT DTD
83         $dump->dtd;
84         my $xml_with_dtd = $dump->pl2xml( $perl );
85
86         # ===== USE EXTERNAL DTD
87         $dump->dtd( $file, $url );
88         my $xml_with_link_to_dtd = $dump->pl2xml( $perl );
89

DESCRIPTION

91       XML::Dumper dumps Perl data to XML format. XML::Dumper can also read
92       XML data that was previously dumped by the module and convert it back
93       to Perl. You can use the module read the XML from a file and write the
94       XML to a file. Perl objects are blessed back to their original
95       packaging; if the modules are installed on the system where the perl
96       objects are reconstituted from xml, they will behave as expected.
97       Intuitively, if the perl objects are converted and reconstituted in the
98       same environment, all should be well. And it is.
99
100       Additionally, because XML benefits so nicely from compression,
101       XML::Dumper understands gzipped XML files. It does so with an optional
102       dependency on Compress::Zlib. So, if you dump a Perl variable with a
103       file that has an extension of '.xml.gz', it will store and compress the
104       file in gzipped format.  Likewise, if you read a file with the
105       extension '.xml.gz', it will uncompress the file in memory before
106       parsing the XML back into a Perl variable.
107
108       Another fine challenge that this module rises to meet is that it
109       understands circular definitions and multiple references to a single
110       object. This includes doubly-linked lists, circular references, and the
111       so-called 'Flyweight' pattern of Object Oriented programming. So it can
112       take the gnarliest of your perl data, and should do just fine.
113
114       One caveat; XML::Dumper does not handle binary data. There have been
115       discussions in the expat mailing list archives discussing the
116       challenges associated with encoding binary data with XML. I chose the
117       cowardly path of making the problem a non-issue by not addressing it.
118       To store binary data, one could encode the data into ASCII before
119       encapsulating the data as XML, and then reverse the process to restore
120       the data. There are several Perl modules that one can use for this,
121       Convert::UU, for example.
122
123   FUNCTIONS AND METHODS
124       •   new() - XML::Dumper constructor.
125
126           Creates a lean, mean, XML dumping machine. It's also completely at
127           your disposal.
128
129       •   dtd -
130
131           Generates a Document Type Dictionary for the 'perldata' data type.
132           The default behaviour is to embed the DTD in the XML, thereby
133           creating valid XML. Given a filename, the DTD will be written out
134           to that file and the XML document for your Perl data will link to
135           the file. Given a filename and an URL, the DTD will be written out
136           the file and the XML document will link to the URL.  XML::Dumper
137           doesn't try really hard to determine where your DTD's ought to go
138           or relative paths or anything, so be careful with what arguments
139           you supply this method, or just go with the default with the
140           embedded DTD. Between DTD's and Schemas, the potential for more
141           free-form data to be imported and exported becomes feasible.
142
143           Usage:
144
145             dtd();                                # Causes XML to include embedded DTD
146             dtd( $file );                 # DTD saved to $file; XML will link to $file
147             dtd( $file, $url );   # DTD saved to $file; XML will link to $url
148             dtd( 0 );                             # Prevents XML from including embedded DTD
149
150       •   pl2xml( $xml, [ $file ] ) -
151
152           (Also perl2xml(), for those who enjoy readability over brevity).
153
154           Converts Perl data to XML. If a second argument is given, then the
155           Perl data will be stored to disk as XML, using the second argument
156           as a filename.
157
158           Usage: See Synopsis
159
160       •   xml2pl( $xml_or_filename, [ $callback ] ) -
161
162           (Also xml2perl(), for those who enjoy readability over brevity.)
163
164           Converts XML to a Perl datatype. If this method is given a second
165           argument, XML::Dumper will use the second argument as a callback
166           (if possible). If the first argument isn't XML and exists as a
167           file, that file will be read and its contents will be used as the
168           input XML.
169
170           Currently, the only supported invocation of callbacks is through
171           soft references. That is to say, the callback argument ought to be
172           a string that matches the name of a callable method for your
173           classes. If you have a congruent interface, this should work like a
174           peach. If your class interface doesn't have such a named method, it
175           won't be called.
176
177       •   xml_compare( $xml1, $xml2 ) - Compares xml for content
178
179           Compares two dumped Perl data structures (that is, compares the
180           xml) for identity in content. Use this function rather than perl's
181           built-in string comparison. This function will return true for any
182           two perl data that are either deep clones of each other, or
183           identical. This method is exported by default.
184
185       •   xml_identity( $xml1, $xml2 ) - Compares xml for identity
186
187           Compares two dumped Perl data structures (that is, compares the
188           xml) for identity in instantiation. This function will return true
189           for any two perl data that are identical, but not for deep clones
190           of each other. This method is also exported by default.
191

EXPORTS

193       By default, the following methods are exported:
194
195         xml2pl, pl2xml, xml_compare, xml_identity
196

BUGS AND DEPENDENCIES

198       XML::Dumper has changed API since 0.4, as a response to a bug report
199       from PerlMonks. I felt it was necessary, as the functions simply didn't
200       work as advertised. That is, xml2pl really didnt accept xml as an
201       argument; what it wanted was an XML Parse tree. To correct for the API
202       change, simply don't parse the XML before feeding it to XML::Dumper.
203
204       XML::Dumper also has no understanding of typeglobs (references or not),
205       references to regular expressions, or references to Perl subroutines.
206       Turns out that Data::Dumper doesn't do references to Perl subroutines,
207       either, so at least I'm in somewhat good company.
208
209       XML::Dumper requires one perl module, available from CPAN
210
211               XML::Parser
212
213       XML::Parser itself relies on Clark Cooper's Expat implementation in
214       Perl, which in turn requires James Clark's expat package itself. See
215       the documentation for XML::Parser for more information.
216

REVISIONS AND CREDITS

218       The list of credits got so long that I had to move it to the Changes
219       file. Thanks to all those who've contributed with bug reports and
220       suggested features! Keep 'em coming!
221
222       I've had ownership of the module since June of 2002, and very much
223       appreciate requests on how to make the module better. It has served me
224       well, both as a learning tool on how I can repay my debt to the Perl
225       Community, and as a practical module that is useful. I'm thrilled to be
226       able to offer this bit of code. So, if you have suggestions, bug
227       reports, or feature requests, please let me know and I'll do my best to
228       make this a better module.
229

CURRENT MAINTAINER

231       Mike Wong <mike_w3@pacbell.net>
232
233       XML::Dumper is free software. You can redistribute it and/or modify it
234       under the same terms as Perl itself.
235

ORIGINAL AUTHOR

237       Jonathan Eisenzopf <eisen@pobox.com>
238