3 MooseX::Storage - A serialization framework for Moose classes
11 with Storage('format' => 'JSON', 'io' => 'File');
13 has 'x' => (is => 'rw', isa => 'Int');
14 has 'y' => (is => 'rw', isa => 'Int');
18 my $p = Point->new(x => 10, y => 10);
20 ## methods to pack/unpack an
21 ## object in perl data structures
23 # pack the class into a hash
24 $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
26 # unpack the hash into a class
27 my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
29 ## methods to freeze/thaw into
30 ## a specified serialization format
31 ## (in this case JSON)
33 # pack the class into a JSON string
34 $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
36 # unpack the JSON string into a class
37 my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
39 ## methods to load/store a class
42 $p->store('my_point.json');
44 my $p2 = Point->load('my_point.json');
48 MooseX::Storage is a serialization framework for Moose, it provides
49 a very flexible and highly pluggable way to serialize Moose classes
50 to a number of different formats and styles.
54 This is still an early release of this module, so use with caution.
55 It's outward facing serialization API should be considered stable,
56 but I still reserve the right to make tweaks if I need too. Anything
57 beyond the basic pack/unpack, freeze/thaw and load/store should not
60 ## Levels of Serialization
62 There are 3 levels to the serialization, each of which builds upon
63 the other and each of which can be customized to the specific needs
68 The first (base) level is `pack` and `unpack`. In this level the
69 class is serialized into a Perl HASH reference, it is tagged with the
70 class name and each instance attribute is stored. Very simple.
72 This level is not optional, it is the bare minimum that
73 MooseX::Storage provides and all other levels build on top of this.
75 See [MooseX::Storage::Basic](http://search.cpan.org/perldoc?MooseX::Storage::Basic) for the fundamental implementation and
76 options to `pack` and `unpack`
80 The second (format) level is `freeze` and `thaw`. In this level the
81 output of `pack` is sent to `freeze` or the output of `thaw` is sent
82 to `unpack`. This levels primary role is to convert to and from the
83 specific serialization format and Perl land.
85 This level is optional, if you don't want/need it, you don't have to
86 have it. You can just use `pack`/`unpack` instead.
90 The third (io) level is `load` and `store`. In this level we are reading
91 and writing data to file/network/database/etc.
93 This level is also optional, in most cases it does require a `format` role
94 to also be used, the exception being the `StorableFile` role.
96 ## Behaviour modifiers
98 The serialization behaviour can be changed by supplying `traits`.
99 This can be done as follows:
102 with Storage( traits => [Trait1, Trait2,...] );
104 The following traits are currently bundled with `MooseX::Storage`:
108 Only attributes that have been built (i.e., where the predicate returns
109 'true') will be serialized. This avoids any potentially expensive computations.
111 See [MooseX::Storage::Traits::OnlyWhenBuilt](http://search.cpan.org/perldoc?MooseX::Storage::Traits::OnlyWhenBuilt) for details.
115 There are always limits to any serialization framework, there are just
116 some things which are really difficult to serialize properly and some
117 things which cannot be serialized at all.
119 ## What can be serialized?
121 Currently only numbers, string, ARRAY refs, HASH refs and other
122 MooseX::Storage enabled objects are supported.
124 With Array and Hash references the first level down is inspected and
125 any objects found are serialized/deserialized for you. We do not do
126 this recursively by default, however this feature may become an
129 The specific serialize/deserialize routine is determined by the
130 Moose type constraint a specific attribute has. In most cases subtypes
131 of the supported types are handled correctly, and there is a facility
132 for adding handlers for custom types as well. This will get documented
133 eventually, but it is currently still in development.
135 ## What can not be serialized?
137 We do not support CODE references yet, but this support might be added
138 in using B::Deparse or some other deep magic.
140 Scalar refs are not supported, mostly because there is no way to know
141 if the value being referenced will be there when the object is inflated.
142 I highly doubt will be ever support this in a general sense, but it
143 would be possible to add this yourself for a small specific case.
145 Circular references are specifically disallowed, however if you break
146 the cycles yourself then re-assemble them later you can get around this.
147 The reason we disallow circular refs is because they are not always supported
148 in all formats we use, and they tend to be very tricky to do for all
149 possible cases. It is almost always something you want to have tight control
154 This is __not__ a persistence framework; changes to your object after
155 you load or store it will not be reflected in the stored class.
159 - __Storage (%options)__
161 This module will export the `Storage` method and can be used to
162 load a specific set of MooseX::Storage roles to implement a specific
163 combination of features. It is meant to make things easier, but it
164 is by no means the only way. You can still compose your roles by
167 By default, options are assumed to be short forms. For example, this:
169 Storage(format => 'JSON');
171 ...will result in looking for MooseX::Storage::Format::JSON. To use a role
172 that is not under the default namespace prefix, start with an equal sign:
174 Storage(format => '=My::Private::JSONFormat');
176 To use a parameterized role (for which, see [MooseX::Role::Parameterized](http://search.cpan.org/perldoc?MooseX::Role::Parameterized)) you
177 can pass an arrayref of the role name (in short or long form, as above) and its
180 Storage(format => [ JSONpm => { json_opts => { pretty => 1 } } ]);
192 This module needs docs and probably a Cookbook of some kind as well.
193 This is an early release, so that is my excuse for now :)
195 For the time being, please read the tests and feel free to email me
196 if you have any questions. This module can also be discussed on IRC
197 in the \#moose channel on irc.perl.org.
201 All complex software has bugs lurking in it, and this module is no
202 exception. If you find a bug please either email me, or add the bug
207 Chris Prather <chris.prather@iinteractive.com>
209 Stevan Little <stevan.little@iinteractive.com>
211 Yuval Kogman <yuval.kogman@iinteractive.com>
213 # COPYRIGHT AND LICENSE
215 Copyright 2007-2008 by Infinity Interactive, Inc.
217 [http://www.iinteractive.com](http://www.iinteractive.com)
219 This library is free software; you can redistribute it and/or modify
220 it under the same terms as Perl itself.