=head1 NAME

XML::Compile::Dumper - Remember precompiled XML processors

=head1 SYNOPSIS

 # create readers and writers or soap things
 my $reader = $schema->compile(READER => '{myns}mytype');
 my $writer = $schema->compile(WRITER => ...);

 # then dump them into a package
 my $dumper = XML::Compile::Dumper->new
   (package => 'My::Package', filename => 'My/Package.pm');
 $dumper->freeze(foo => $reader, bar => $writer);
 $dumper->close;

 # later, they can get recalled using
 use My::Package;
 my $hash = foo($xml);
 my $doc  = bar($doc, $xml);

=head1 DESCRIPTION

This module simplifies the task of saving and loading pre-compiled
translators.  Schema's can get huge, and when you are not creating a
daemon to do the XML communication, you may end-up compiling and
interpreting these large schemas often, just to be able to process
simple data-structures.

Based on the excellent module Data::Dump::Streamer, this module
helps you create standard Perl packages which contain the reader
and writer code references.

WARNING: this feature was introduced in release 0.17.  Using perl
5.8.8, libxml 2.6.26, XML::LibXML 2.60, and Data::Dump::Streamer
2.03, Perl complains about C<"PmmREFCNT_dec: REFCNT decremented below
0! during global destruction."> when the tests are run.  This bug
can be anywhere. Therefore, these tests are disabled by default in
t/TestTools.pm.  If you have time, could you please run the tests with
C<$skip_dumper = 0;> and report the results to the author?

=head1 METHODS

=head2 Constructors

$obj-E<gt>B<close>

=over 4

Finalize the produced file.  This will be called automatically
if the objects goes out-of-scope.

=back

XML::Compile::Dumper-E<gt>B<new>(OPTIONS)

=over 4

Create an object which will collect the information for the output
file.  You have to specify either a C<filehandle> or a C<filename>.
A filehandle will be closed after processing.

 Option    --Default
 filehandle  undef
 filename    undef
 package     <required>

. filehandle => C<IO::Handle>

. filename => FILENAME

=over 4

The file will be written using utf8 encoding, using IO::File.  If
you want something else, open your filehandle first, and provide that
as argument.

=back

. package => PACKAGE

=over 4

The name-space which will be used: it will produce a C<package>
line in the output.

=back

=back

=head2 Accessors

$obj-E<gt>B<file>

=over 4

Returns the output file-handle, which you may use to add extensions to
the module.

=back

=head2 Producers

$obj-E<gt>B<footer>(FILEHANDLE)

=over 4

=back

$obj-E<gt>B<freeze>(PAIRS|HASH)

=over 4

Produce the dump for a group of code references, which will be
made available under a normal subroutine name.  This method
can only be called once.

=back

$obj-E<gt>B<header>(FILEHANDLE, PACKAGE)

=over 4

Prints the header text to the file.

=back

=head1 DIAGNOSTICS

Error: either filename or filehandle required

=over 4

=back

Error: freeze can only be called once

=over 4

The various closures may have related variables, and therefore
need to be dumped in one go.

=back

Error: freeze needs PAIRS or a HASH

=over 4

=back

Error: package name required

=over 4

The perl module which is produced is cleanly encapsulating the
produced program text in a perl package name-space.  The name
has to be provided.

=back

Error: value with $name is not a code reference

=over 4

=back

=head1 SEE ALSO

This module is part of XML-Compile-Dumper distribution version 0.13,
built on March 26, 2010. Website: F<http://perl.overmeer.net/xml-compile/>

All modules in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP12>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
and
L<XML::Rewrite>,
L<XML::ExistDB>,
L<XML::LibXML::Simple>.

Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile>
For life contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.

=head1 LICENSE

Copyrights 2007-2010 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>