1=head1 NAME
2
3XML::Compile::Dumper - Remember precompiled XML processors
4
5=head1 SYNOPSIS
6
7 # create readers and writers or soap things
8 my $reader = $schema->compile(READER => '{myns}mytype');
9 my $writer = $schema->compile(WRITER => ...);
10
11 # then dump them into a package
12 my $dumper = XML::Compile::Dumper->new
13   (package => 'My::Package', filename => 'My/Package.pm');
14 $dumper->freeze(foo => $reader, bar => $writer);
15 $dumper->close;
16
17 # later, they can get recalled using
18 use My::Package;
19 my $hash = foo($xml);
20 my $doc  = bar($doc, $xml);
21
22=head1 DESCRIPTION
23
24This module simplifies the task of saving and loading pre-compiled
25translators.  Schema's can get huge, and when you are not creating a
26daemon to do the XML communication, you may end-up compiling and
27interpreting these large schemas often, just to be able to process
28simple data-structures.
29
30Based on the excellent module Data::Dump::Streamer, this module
31helps you create standard Perl packages which contain the reader
32and writer code references.
33
34WARNING: this feature was introduced in release 0.17.  Using perl
355.8.8, libxml 2.6.26, XML::LibXML 2.60, and Data::Dump::Streamer
362.03, Perl complains about C<"PmmREFCNT_dec: REFCNT decremented below
370! during global destruction."> when the tests are run.  This bug
38can be anywhere. Therefore, these tests are disabled by default in
39t/TestTools.pm.  If you have time, could you please run the tests with
40C<$skip_dumper = 0;> and report the results to the author?
41
42=head1 METHODS
43
44=head2 Constructors
45
46$obj-E<gt>B<close>
47
48=over 4
49
50Finalize the produced file.  This will be called automatically
51if the objects goes out-of-scope.
52
53=back
54
55XML::Compile::Dumper-E<gt>B<new>(OPTIONS)
56
57=over 4
58
59Create an object which will collect the information for the output
60file.  You have to specify either a C<filehandle> or a C<filename>.
61A filehandle will be closed after processing.
62
63 Option    --Default
64 filehandle  undef
65 filename    undef
66 package     <required>
67
68. filehandle => C<IO::Handle>
69
70. filename => FILENAME
71
72=over 4
73
74The file will be written using utf8 encoding, using IO::File.  If
75you want something else, open your filehandle first, and provide that
76as argument.
77
78=back
79
80. package => PACKAGE
81
82=over 4
83
84The name-space which will be used: it will produce a C<package>
85line in the output.
86
87=back
88
89=back
90
91=head2 Accessors
92
93$obj-E<gt>B<file>
94
95=over 4
96
97Returns the output file-handle, which you may use to add extensions to
98the module.
99
100=back
101
102=head2 Producers
103
104$obj-E<gt>B<footer>(FILEHANDLE)
105
106=over 4
107
108=back
109
110$obj-E<gt>B<freeze>(PAIRS|HASH)
111
112=over 4
113
114Produce the dump for a group of code references, which will be
115made available under a normal subroutine name.  This method
116can only be called once.
117
118=back
119
120$obj-E<gt>B<header>(FILEHANDLE, PACKAGE)
121
122=over 4
123
124Prints the header text to the file.
125
126=back
127
128=head1 DIAGNOSTICS
129
130Error: either filename or filehandle required
131
132=over 4
133
134=back
135
136Error: freeze can only be called once
137
138=over 4
139
140The various closures may have related variables, and therefore
141need to be dumped in one go.
142
143=back
144
145Error: freeze needs PAIRS or a HASH
146
147=over 4
148
149=back
150
151Error: package name required
152
153=over 4
154
155The perl module which is produced is cleanly encapsulating the
156produced program text in a perl package name-space.  The name
157has to be provided.
158
159=back
160
161Error: value with $name is not a code reference
162
163=over 4
164
165=back
166
167=head1 SEE ALSO
168
169This module is part of XML-Compile-Dumper distribution version 0.13,
170built on March 26, 2010. Website: F<http://perl.overmeer.net/xml-compile/>
171
172All modules in this suite:
173L<XML::Compile>,
174L<XML::Compile::SOAP>,
175L<XML::Compile::SOAP12>,
176L<XML::Compile::SOAP::Daemon>,
177L<XML::Compile::Tester>,
178L<XML::Compile::Cache>,
179L<XML::Compile::Dumper>,
180L<XML::Compile::RPC>,
181and
182L<XML::Rewrite>,
183L<XML::ExistDB>,
184L<XML::LibXML::Simple>.
185
186Please post questions or ideas to the mailinglist at
187F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile>
188For life contact with other developers, visit the C<#xml-compile> channel
189on C<irc.perl.org>.
190
191=head1 LICENSE
192
193Copyrights 2007-2010 by Mark Overmeer. For other contributors see ChangeLog.
194
195This program is free software; you can redistribute it and/or modify it
196under the same terms as Perl itself.
197See F<http://www.perl.com/perl/misc/Artistic.html>
198
199