2 package MooseX::Storage;
5 use MooseX::Storage::Meta::Attribute::DoNotSerialize;
12 return if $pkg eq 'main';
15 || confess "This package can only be used in Moose based classes";
17 $pkg->meta->alias_method('Storage' => sub {
20 if (exists $params{'base'}) {
21 $params{'base'} = ('Base::' . $params{'base'});
24 $params{'base'} = 'Basic';
28 ('MooseX::Storage::' . $params{'base'}),
32 # you don't have to have a format
33 # role, this just means you dont
34 # get anything other than pack/unpack
35 push @roles => 'MooseX::Storage::Format::' . $params{'format'}
36 if exists $params{'format'};
39 # if you do choose an IO role, then
40 # you *must* have a format role chosen
41 # since load/store require freeze/thaw
42 if (exists $params{'io'}) {
43 (exists $params{'format'})
44 || confess "You must specify a format role in order to use an IO role";
45 push @roles => 'MooseX::Storage::IO::' . $params{'io'};
48 Class::MOP::load_class($_)
49 || die "Could not load role (" . $_ . ") for package ($pkg)"
64 MooseX::Storage - An serialization framework for Moose classes
72 our $VERSION = '0.01';
74 with Storage('format' => 'JSON', 'io' => 'File');
76 has 'x' => (is => 'rw', isa => 'Int');
77 has 'y' => (is => 'rw', isa => 'Int');
81 my $p = Point->new(x => 10, y => 10);
83 ## methods to pack/unpack an
84 ## object in perl data structures
86 # pack the class into a hash
87 $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
89 # unpack the hash into a class
90 my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
92 ## methods to freeze/thaw into
93 ## a specified serialization format
94 ## (in this case JSON)
96 # pack the class into a JSON string
97 $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
99 # unpack the JSON string into a class
100 my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
102 ## methods to load/store a class
103 ## on the file system
105 $p->store('my_point.json');
107 my $p2 = Point->load('my_point.json');
111 MooseX::Storage is a serialization framework for Moose, it provides
112 a very flexible and highly pluggable way to serialize Moose classes
113 to a number of different formats and styles.
115 =head2 Important Note
117 This is still an early release of this module, so use with caution.
118 It's outward facing serialization API should be considered stable,
119 but I still reserve the right to make tweaks if I need too. Anything
120 beyond the basic pack/unpack, freeze/thaw and load/store should not
123 =head2 Levels of Serialization
125 There are 3 levels to the serialization, each of which builds upon
126 the other and each of which can be customized to the specific needs
133 The first (base) level is C<pack> and C<unpack>. In this level the
134 class is serialized into a Perl HASH reference, it is tagged with the
135 class name and each instance attribute is stored. Very simple.
137 This level is not optional, it is the bare minumum that
138 MooseX::Storage provides and all other levels build on top of this.
142 The second (format) level is C<freeze> and C<thaw>. In this level the
143 output of C<pack> is sent to C<freeze> or the output of C<thaw> is sent
144 to C<unpack>. This levels primary role is to convert to and from the
145 specific serialization format and Perl land.
147 This level is optional, if you don't want/need it, you don't have to
148 have it. You can just use C<pack>/C<unpack> instead.
152 The third (io) level is C<load> and C<store>. In this level we are reading
153 and writing data to file/network/database/etc.
155 This level is also optional, it does however require the C<format> level
156 to be present (at least the current state does).
160 =head2 How we serialize
162 There are always limits to any serialization framework, there are just
163 some things which are really difficult to serialize properly and some
164 things which cannot be serialized at all.
166 =head2 What can be serialized?
168 Currently only numbers, string, ARRAY refs, HASH refs and other
169 MooseX::Storage enabled objects are supported.
171 With Array and Hash references the first level down is inspected and
172 any objects found are serialized/deserialized for you. We do not do
173 this recusively by default, however this feature may become an
176 The specific serialize/deserialize routine is determined by the
177 Moose type constraint a specific attribute has. In most cases subtypes
178 of the supported types are handled correctly, and there is a facility
179 for adding handlers for custom types as well. This will get documented
180 eventually, but it is currently still in development.
182 =head2 What can not be serialized?
184 We do not support CODE references yet, but this support might be added
185 in using B::Deparse or some other deep magic.
187 Scalar refs are not supported, mostly because there is no way to know
188 if the value being referenced will be there when the object is inflated.
189 I highly doubt will be ever support this in a general sense, but it
190 would be possible to add this yourself for a small specific case.
192 Circular references are specifically disallowed, however if you break
193 the cycles yourself then re-assemble them later you can get around this.
194 The reason we disallow circular refs is because they are not always supported
195 in all formats we use, and they tend to be very tricky to do for all
196 possible cases. It is almost always something you want to have tight control
201 This is B<not> a persistence framework, changes to your object after
202 you load or store it will not be reflected in the stored class.
208 =item B<Storage (%options)>
210 This module will export the C<Storage> method will can be used to
211 load a specific set of MooseX::Storage roles to implement a specific
212 combination of features. It is meant to make things easier, but it
213 is by no means the only way. You can still compose your roles by
236 This module needs docs and probably a Cookbook of some kind as well.
237 This is an early release, so that is my excuse for now :)
239 For the time being, please read the tests and feel free to email me
240 if you have any questions. This module can also be discussed on IRC
241 in the #moose channel on irc.perl.org.
245 All complex software has bugs lurking in it, and this module is no
246 exception. If you find a bug please either email me, or add the bug
251 Chris Prather E<lt>chris.prather@iinteractive.comE<gt>
253 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
255 =head1 COPYRIGHT AND LICENSE
257 Copyright 2007 by Infinity Interactive, Inc.
259 L<http://www.iinteractive.com>
261 This library is free software; you can redistribute it and/or modify
262 it under the same terms as Perl itself.