2 package MooseX::Storage;
5 use MooseX::Storage::Meta::Attribute::DoNotSerialize;
8 our $AUTHORITY = 'cpan:STEVAN';
13 return if $pkg eq 'main';
16 || confess "This package can only be used in Moose based classes";
18 $pkg->meta->add_method('Storage' => __PACKAGE__->meta->find_method_by_name('_injected_storage_role_generator'));
21 sub _injected_storage_role_generator {
24 if (exists $params{'base'}) {
25 $params{'base'} = ('Base::' . $params{'base'});
28 $params{'base'} = 'Basic';
32 ('MooseX::Storage::' . $params{'base'}),
36 # you don't have to have a format
37 # role, this just means you dont
38 # get anything other than pack/unpack
39 push @roles => 'MooseX::Storage::Format::' . $params{'format'}
40 if exists $params{'format'};
43 # many IO roles don't make sense unless
44 # you have also have a format role chosen
45 # too, the exception being StorableFile
46 if (exists $params{'io'}) {
48 # we dont need this code anymore, cause
49 # the role composition will catch it for
50 # us. This allows the StorableFile to work
51 #(exists $params{'format'})
52 # || confess "You must specify a format role in order to use an IO role";
53 push @roles => 'MooseX::Storage::IO::' . $params{'io'};
56 Class::MOP::load_class($_)
57 || die "Could not load role (" . $_ . ")"
71 MooseX::Storage - An serialization framework for Moose classes
79 our $VERSION = '0.01';
81 with Storage('format' => 'JSON', 'io' => 'File');
83 has 'x' => (is => 'rw', isa => 'Int');
84 has 'y' => (is => 'rw', isa => 'Int');
88 my $p = Point->new(x => 10, y => 10);
90 ## methods to pack/unpack an
91 ## object in perl data structures
93 # pack the class into a hash
94 $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
96 # unpack the hash into a class
97 my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
99 ## methods to freeze/thaw into
100 ## a specified serialization format
101 ## (in this case JSON)
103 # pack the class into a JSON string
104 $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
106 # unpack the JSON string into a class
107 my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
109 ## methods to load/store a class
110 ## on the file system
112 $p->store('my_point.json');
114 my $p2 = Point->load('my_point.json');
118 MooseX::Storage is a serialization framework for Moose, it provides
119 a very flexible and highly pluggable way to serialize Moose classes
120 to a number of different formats and styles.
122 =head2 Important Note
124 This is still an early release of this module, so use with caution.
125 It's outward facing serialization API should be considered stable,
126 but I still reserve the right to make tweaks if I need too. Anything
127 beyond the basic pack/unpack, freeze/thaw and load/store should not
130 =head2 Levels of Serialization
132 There are 3 levels to the serialization, each of which builds upon
133 the other and each of which can be customized to the specific needs
140 The first (base) level is C<pack> and C<unpack>. In this level the
141 class is serialized into a Perl HASH reference, it is tagged with the
142 class name and each instance attribute is stored. Very simple.
144 This level is not optional, it is the bare minumum that
145 MooseX::Storage provides and all other levels build on top of this.
149 The second (format) level is C<freeze> and C<thaw>. In this level the
150 output of C<pack> is sent to C<freeze> or the output of C<thaw> is sent
151 to C<unpack>. This levels primary role is to convert to and from the
152 specific serialization format and Perl land.
154 This level is optional, if you don't want/need it, you don't have to
155 have it. You can just use C<pack>/C<unpack> instead.
159 The third (io) level is C<load> and C<store>. In this level we are reading
160 and writing data to file/network/database/etc.
162 This level is also optional, in most cases it does require a C<format> role
163 to also be used, the expection being the C<StorableFile> role.
167 =head2 How we serialize
169 There are always limits to any serialization framework, there are just
170 some things which are really difficult to serialize properly and some
171 things which cannot be serialized at all.
173 =head2 What can be serialized?
175 Currently only numbers, string, ARRAY refs, HASH refs and other
176 MooseX::Storage enabled objects are supported.
178 With Array and Hash references the first level down is inspected and
179 any objects found are serialized/deserialized for you. We do not do
180 this recusively by default, however this feature may become an
183 The specific serialize/deserialize routine is determined by the
184 Moose type constraint a specific attribute has. In most cases subtypes
185 of the supported types are handled correctly, and there is a facility
186 for adding handlers for custom types as well. This will get documented
187 eventually, but it is currently still in development.
189 =head2 What can not be serialized?
191 We do not support CODE references yet, but this support might be added
192 in using B::Deparse or some other deep magic.
194 Scalar refs are not supported, mostly because there is no way to know
195 if the value being referenced will be there when the object is inflated.
196 I highly doubt will be ever support this in a general sense, but it
197 would be possible to add this yourself for a small specific case.
199 Circular references are specifically disallowed, however if you break
200 the cycles yourself then re-assemble them later you can get around this.
201 The reason we disallow circular refs is because they are not always supported
202 in all formats we use, and they tend to be very tricky to do for all
203 possible cases. It is almost always something you want to have tight control
208 This is B<not> a persistence framework, changes to your object after
209 you load or store it will not be reflected in the stored class.
215 =item B<Storage (%options)>
217 This module will export the C<Storage> method will can be used to
218 load a specific set of MooseX::Storage roles to implement a specific
219 combination of features. It is meant to make things easier, but it
220 is by no means the only way. You can still compose your roles by
243 This module needs docs and probably a Cookbook of some kind as well.
244 This is an early release, so that is my excuse for now :)
246 For the time being, please read the tests and feel free to email me
247 if you have any questions. This module can also be discussed on IRC
248 in the #moose channel on irc.perl.org.
252 All complex software has bugs lurking in it, and this module is no
253 exception. If you find a bug please either email me, or add the bug
258 Chris Prather E<lt>chris.prather@iinteractive.comE<gt>
260 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
262 Yuval Kogman E<lt>yuval.kogman@iinteractive.comE<gt>
264 =head1 COPYRIGHT AND LICENSE
266 Copyright 2007-2008 by Infinity Interactive, Inc.
268 L<http://www.iinteractive.com>
270 This library is free software; you can redistribute it and/or modify
271 it under the same terms as Perl itself.