1MooseX::Storage(3) User Contributed Perl Documentation MooseX::Storage(3)
2
6 MooseX::Storage - A serialization framework for Moose classes
7
9 package Point;
10 use Moose;
11 use MooseX::Storage;
12 our $VERSION = '0.01';
14 with Storage('format' => 'JSON', 'io' => 'File');
16 has 'x' => (is => 'rw', isa => 'Int');
18 has 'y' => (is => 'rw', isa => 'Int');
19 1;
21 my $p = Point->new(x => 10, y => 10);
23 ## methods to pack/unpack an
25 ## object in perl data structures
26 # pack the class into a hash
28 $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
29 # unpack the hash into a class
31 my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
32 ## methods to freeze/thaw into
34 ## a specified serialization format
35 ## (in this case JSON)
36 # pack the class into a JSON string
38 $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
39 # unpack the JSON string into a class
41 my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
42 ## methods to load/store a class
44 ## on the file system
45 $p->store('my_point.json');
47 my $p2 = Point->load('my_point.json');
49
51 MooseX::Storage is a serialization framework for Moose, it provides a
52 very flexible and highly pluggable way to serialize Moose classes to a
53 number of different formats and styles.
54 Important Note
56 This is still an early release of this module, so use with caution.
57 It's outward facing serialization API should be considered stable, but
58 I still reserve the right to make tweaks if I need too. Anything beyond
59 the basic pack/unpack, freeze/thaw and load/store should not be relied
60 on.
61 Levels of Serialization
63 There are 3 levels to the serialization, each of which builds upon the
64 other and each of which can be customized to the specific needs of your
65 class.
66 base
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
70 the class name and each instance attribute is stored. Very simple.
71 This level is not optional, it is the bare minumum that
73 MooseX::Storage provides and all other levels build on top of this.
74 See Moosex::Storage::Basic for the fundamental implementation and
76 options to "pack" and "unpack"
77 format
79 The second (format) level is "freeze" and "thaw". In this level the
80 output of "pack" is sent to "freeze" or the output of "thaw" is
81 sent to "unpack". This levels primary role is to convert to and
82 from the specific serialization format and Perl land.
83 This level is optional, if you don't want/need it, you don't have
85 to have it. You can just use "pack"/"unpack" instead.
86 io The third (io) level is "load" and "store". In this level we are
88 reading and writing data to file/network/database/etc.
89 This level is also optional, in most cases it does require a
91 "format" role to also be used, the expection being the
92 "StorableFile" role.
93 Behaviour modifiers
95 The serialization behaviour can be changed by supplying "traits". This
96 can be done as follows:
97 use MooseX::Storage;
99 with Storage( traits => [Trait1, Trait2,...] );
100 The following traits are currently bundled with "MooseX::Storage":
102 OnlyWhenBuilt
104 Only attributes that have been built (ie, where the predicate
105 returns 'true') will be serialized. This avoids any potentially
106 expensive computations.
107 See MooseX::Storage::Traits::OnlyWhenBuilt for details.
109 How we serialize
111 There are always limits to any serialization framework, there are just
112 some things which are really difficult to serialize properly and some
113 things which cannot be serialized at all.
114 What can be serialized?
116 Currently only numbers, string, ARRAY refs, HASH refs and other
117 MooseX::Storage enabled objects are supported.
118 With Array and Hash references the first level down is inspected and
120 any objects found are serialized/deserialized for you. We do not do
121 this recusively by default, however this feature may become an option
122 eventually.
123 The specific serialize/deserialize routine is determined by the Moose
125 type constraint a specific attribute has. In most cases subtypes of the
126 supported types are handled correctly, and there is a facility for
127 adding handlers for custom types as well. This will get documented
128 eventually, but it is currently still in development.
129 What can not be serialized?
131 We do not support CODE references yet, but this support might be added
132 in using B::Deparse or some other deep magic.
133 Scalar refs are not supported, mostly because there is no way to know
135 if the value being referenced will be there when the object is
136 inflated. I highly doubt will be ever support this in a general sense,
137 but it would be possible to add this yourself for a small specific
138 case.
139 Circular references are specifically disallowed, however if you break
141 the cycles yourself then re-assemble them later you can get around
142 this. The reason we disallow circular refs is because they are not
143 always supported in all formats we use, and they tend to be very tricky
144 to do for all possible cases. It is almost always something you want to
145 have tight control over anyway.
146
148 This is not a persistence framework, changes to your object after you
149 load or store it will not be reflected in the stored class.
150
152 Storage (%options)
153 This module will export the "Storage" method will can be used to
154 load a specific set of MooseX::Storage roles to implement a
155 specific combination of features. It is meant to make things
156 easier, but it is by no means the only way. You can still compose
157 your roles by hand if you like.
158
160 import
161 Introspection
163 meta
164
166 This module needs docs and probably a Cookbook of some kind as well.
167 This is an early release, so that is my excuse for now :)
168 For the time being, please read the tests and feel free to email me if
170 you have any questions. This module can also be discussed on IRC in the
171 #moose channel on irc.perl.org.
172
174 All complex software has bugs lurking in it, and this module is no
175 exception. If you find a bug please either email me, or add the bug to
176 cpan-RT.
177
179 Chris Prather <chris.prather@iinteractive.com>
180 Stevan Little <stevan.little@iinteractive.com>
182 Yuval Kogman <yuval.kogman@iinteractive.com>
184
186 Copyright 2007-2008 by Infinity Interactive, Inc.
187 <http://www.iinteractive.com>
189 This library is free software; you can redistribute it and/or modify it
191 under the same terms as Perl itself.
192perl v5.12.0 2009-07-14 MooseX::Storage(3)