=pod
=encoding UTF-8
=head1 NAME
MooseX::Storage - A serialization framework for Moose classes
=head1 VERSION
version 0.53
=head1 SYNOPSIS
package Point; use Moose; use MooseX::Storage;
with Storage('format' => 'JSON', 'io' => 'File');
has 'x' => (is => 'rw', isa => 'Int'); has 'y' => (is => 'rw', isa => 'Int');
1;
my $p = Point->new(x => 10, y => 10);
$p->pack(); # { CLASS => 'Point-0.01', x => 10, y => 10 }
my $p2 = Point->unpack({ CLASS => 'Point-0.01', x => 10, y => 10 });
$p->freeze(); # { "CLASS" : "Point-0.01", "x" : 10, "y" : 10 }
my $p2 = Point->thaw('{ "CLASS" : "Point-0.01", "x" : 10, "y" : 10 }');
$p->store('my_point.json');
my $p2 = Point->load('my_point.json');
=head1 DESCRIPTION
MooseX::Storage is a serialization framework for Moose, it provides a very flexible and highly pluggable way to serialize Moose classes to a number of different formats and styles.
=head2 Levels of Serialization
There are three levels to the serialization, each of which builds upon the other and each of which can be customized to the specific needs of your class.
=over 4
=item B
The first (base) level is C
This level is not optional, it is the bare minimum that MooseX::Storage provides and all other levels build on top of this.
See L
=item B
The second (format) level is C
This level is optional, if you don't want/need it, you don't have to
have it. You can just use C
=for stopwords io
=item B
The third (io) level is C
This level is also optional, in most cases it does require a C
=back
=head2 Behaviour modifiers
The serialization behaviour can be changed by supplying C
This can be done as follows:
use MooseX::Storage;
with Storage( traits => [Trait1, Trait2,...] );
has my_attr => ( traits => [Trait1, Trait2, ...], ... );
The following B
=over 4
=item OnlyWhenBuilt
Only attributes that have been built (i.e., where the predicate returns 'true') will be serialized. This avoids any potentially expensive computations.
See L
=item DisableCycleDetection
=for stopwords serialisable
Disables the default checks for circular references, which is necessary if you use such references in your serialisable objects.
See L
=back
The following B
=over 4
=item DoNotSerialize
Skip serialization entirely for this attribute.
See L
=back
=head2 How we serialize
There are always limits to any serialization framework -- there are just some things which are really difficult to serialize properly and some things which cannot be serialized at all.
=head2 What can be serialized?
Currently only numbers, string, ARRAY refs, HASH refs and other MooseX::Storage-enabled objects are supported.
With Array and Hash references the first level down is inspected and any objects found are serialized/deserialized for you. We do not do this recursively by default, however this feature may become an option eventually.
=for stopwords subtypes
The specific serialize/deserialize routine is determined by the
L
=head2 What can not be serialized?
We do not support CODE references yet, but this support might be added
in using L
Scalar refs are not supported, mostly because there is no way to know if the value being referenced will be there when the object is inflated. I highly doubt will be ever support this in a general sense, but it would be possible to add this yourself for a small specific case.
Circular references are specifically disallowed, however if you break the cycles yourself then re-assemble them later you can get around this. The reason we disallow circular refs is because they are not always supported in all formats we use, and they tend to be very tricky to do for all possible cases. It is almost always something you want to have tight control over anyway.
=head1 CAVEAT
This is B
=head1 EXPORTS
=over 4
=item B<Storage (%options)>
This module will export the C
By default, options are assumed to be short forms. For example, this:
Storage(format => 'JSON');
...will result in looking for MooseX::Storage::Format::JSON. To use a role that is not under the default namespace prefix, start with an equal sign:
Storage(format => '=My::Private::JSONFormat');
=for stopwords parameterized
To use a parameterized role (for which, see L
Storage(format => [ JSONpm => { json_opts => { pretty => 1 } } ]);
=back
=head1 METHODS
=over 4
=item B
=back
=head2 Introspection
=over 4
=item B
=back
=for stopwords TODO
=head1 TODO
This module needs docs and probably a Cookbook of some kind as well. This is an early release, so that is my excuse for now :)
For the time being, please read the tests and feel free to email me if you have any questions. This module can also be discussed on IRC in the #moose channel on irc.perl.org.
=head1 SUPPORT
Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=MooseX-Storage> (or Lbug-MooseX-Storage@rt.cpan.org|mailto:bug-MooseX-Storage@rt.cpan.org).
There is also a mailing list available for users of this distribution, at Lhttp://lists.perl.org/list/moose.html.
There is also an irc channel available for users of this distribution, at
L<C<#moose> on C
=head1 AUTHORS
=over 4
=item *
Chris Prather chris.prather@iinteractive.com
=item *
Stevan Little stevan.little@iinteractive.com
=item *
יובל קוג'מן (Yuval Kogman) nothingmuch@woobling.org
=back
=head1 CONTRIBUTORS
=for stopwords Karen Etheridge Tomas Doran Ricardo Signes Chris Prather Jos Boumans Shawn M Moore Jonathan Yu Dmitry Latin Robert Boone Dagfinn Ilmari Mannsåker Cory Watson sillitoe Dan Brook David Golden Steinbrunner Florian Ragwitz Graham Knop Jason Pope Johannes Plunien Rockway Yanick Champoux
=over 4
=item *
Karen Etheridge ether@cpan.org
=item *
Tomas Doran bobtfish@bobtfish.net
=item *
Ricardo Signes rjbs@cpan.org
=item *
Chris Prather chris@prather.org
=item *
Jos Boumans jos@dwim.org
=item *
Shawn M Moore sartak@gmail.com
=item *
Jonathan Yu frequency@cpan.org
=item *
Dmitry Latin dim0xff@gmail.com
=item *
Robert Boone robo4288@gmail.com
=item *
Dagfinn Ilmari Mannsåker ilmari@ilmari.org
=item *
Cory Watson gphat@Crankwizzah.local
=item *
sillitoe ian@sillit.com
=item *
Dan Brook dan@broquaint.com
=item *
David Golden dagolden@cpan.org
=item *
David Steinbrunner dsteinbrunner@pobox.com
=item *
Florian Ragwitz rafl@debian.org
=item *
Graham Knop haarg@haarg.org
=item *
Jason Pope cowholio4@gmail.com
=item *
Johannes Plunien plu@pqpq.de
=item *
Jonathan Rockway jon@jrock.us
=item *
Yanick Champoux yanick@babyl.dyndns.org
=back
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2007 by Infinity Interactive, Inc.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
=cut