1MooseX::Storage(3) User Contributed Perl Documentation MooseX::Storage(3)
2
6 MooseX::Storage - A serialization framework for Moose classes
7
9 version 0.53
10
12 package Point;
13 use Moose;
14 use MooseX::Storage;
15 with Storage('format' => 'JSON', 'io' => 'File');
17 has 'x' => (is => 'rw', isa => 'Int');
19 has 'y' => (is => 'rw', isa => 'Int');
20 1;
22 my $p = Point->new(x => 10, y => 10);
24 ## methods to pack/unpack an
26 ## object in perl data structures
27 # pack the class into a hash
29 $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
30 # unpack the hash into a class
32 my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
33 ## methods to freeze/thaw into
35 ## a specified serialization format
36 ## (in this case JSON)
37 # pack the class into a JSON string
39 $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
40 # unpack the JSON string into a class
42 my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
43 ## methods to load/store a class
45 ## on the file system
46 $p->store('my_point.json');
48 my $p2 = Point->load('my_point.json');
50
52 MooseX::Storage is a serialization framework for Moose, it provides a
53 very flexible and highly pluggable way to serialize Moose classes to a
54 number of different formats and styles.
55 Levels of Serialization
57 There are three levels to the serialization, each of which builds upon
58 the other and each of which can be customized to the specific needs of
59 your class.
60 base
62 The first (base) level is "pack" and "unpack". In this level the
63 class is serialized into a Perl HASH reference, it is tagged with
64 the class name and each instance attribute is stored. Very simple.
65 This level is not optional, it is the bare minimum that
67 MooseX::Storage provides and all other levels build on top of this.
68 See MooseX::Storage::Basic for the fundamental implementation and
70 options to "pack" and "unpack"
71 format
73 The second (format) level is "freeze" and "thaw". In this level the
74 output of "pack" is sent to "freeze" or the output of "thaw" is
75 sent to "unpack". This levels primary role is to convert to and
76 from the specific serialization format and Perl land.
77 This level is optional, if you don't want/need it, you don't have
79 to have it. You can just use "pack"/"unpack" instead.
80 io The third (io) level is "load" and "store". In this level we are
82 reading and writing data to file/network/database/etc.
83 This level is also optional, in most cases it does require a
85 "format" role to also be used, the exception being the
86 "StorableFile" role.
87 Behaviour modifiers
89 The serialization behaviour can be changed by supplying "traits" to
90 either the class or an individual attribute.
91 This can be done as follows:
93 use MooseX::Storage;
95 # adjust behaviour for the entire class
97 with Storage( traits => [Trait1, Trait2,...] );
98 # adjust behaviour for an attribute
100 has my_attr => (
101 traits => [Trait1, Trait2, ...],
102 ...
103 );
104 The following class traits are currently bundled with MooseX::Storage:
106 OnlyWhenBuilt
108 Only attributes that have been built (i.e., where the predicate
109 returns 'true') will be serialized. This avoids any potentially
110 expensive computations.
111 See MooseX::Storage::Traits::OnlyWhenBuilt for details.
113 DisableCycleDetection
115 Disables the default checks for circular references, which is
116 necessary if you use such references in your serialisable objects.
117 See MooseX::Storage::Traits::DisableCycleDetection for details.
119 The following attribute traits are currently bundled with
121 MooseX::Storage:
122 DoNotSerialize
124 Skip serialization entirely for this attribute.
125 See MooseX::Storage::Meta::Attribute::Trait::DoNotSerialize for
127 details.
128 How we serialize
130 There are always limits to any serialization framework -- there are
131 just some things which are really difficult to serialize properly and
132 some things which cannot be serialized at all.
133 What can be serialized?
135 Currently only numbers, string, ARRAY refs, HASH refs and other
136 MooseX::Storage-enabled objects are supported.
137 With Array and Hash references the first level down is inspected and
139 any objects found are serialized/deserialized for you. We do not do
140 this recursively by default, however this feature may become an option
141 eventually.
142 The specific serialize/deserialize routine is determined by the Moose
144 type constraint a specific attribute has. In most cases subtypes of the
145 supported types are handled correctly, and there is a facility for
146 adding handlers for custom types as well. This will get documented
147 eventually, but it is currently still in development.
148 What can not be serialized?
150 We do not support CODE references yet, but this support might be added
151 in using B::Deparse or some other deep magic.
152 Scalar refs are not supported, mostly because there is no way to know
154 if the value being referenced will be there when the object is
155 inflated. I highly doubt will be ever support this in a general sense,
156 but it would be possible to add this yourself for a small specific
157 case.
158 Circular references are specifically disallowed, however if you break
160 the cycles yourself then re-assemble them later you can get around
161 this. The reason we disallow circular refs is because they are not
162 always supported in all formats we use, and they tend to be very tricky
163 to do for all possible cases. It is almost always something you want to
164 have tight control over anyway.
165
167 This is not a persistence framework; changes to your object after you
168 load or store it will not be reflected in the stored class.
169
171 Storage (%options)
172 This module will export the "Storage" method and can be used to
173 load a specific set of MooseX::Storage roles to implement a
174 specific combination of features. It is meant to make things
175 easier, but it is by no means the only way. You can still compose
176 your roles by hand if you like.
177 By default, options are assumed to be short forms. For example,
179 this:
180 Storage(format => 'JSON');
182 ...will result in looking for MooseX::Storage::Format::JSON. To
184 use a role that is not under the default namespace prefix, start
185 with an equal sign:
186 Storage(format => '=My::Private::JSONFormat');
188 To use a parameterized role (for which, see
190 MooseX::Role::Parameterized) you can pass an arrayref of the role
191 name (in short or long form, as above) and its parameters:
192 Storage(format => [ JSONpm => { json_opts => { pretty => 1 } } ]);
194
196 import
197 Introspection
199 meta
200
202 This module needs docs and probably a Cookbook of some kind as well.
203 This is an early release, so that is my excuse for now :)
204 For the time being, please read the tests and feel free to email me if
206 you have any questions. This module can also be discussed on IRC in the
207 #moose channel on irc.perl.org.
208
210 Bugs may be submitted through the RT bug tracker
211 <https://rt.cpan.org/Public/Dist/Display.html?Name=MooseX-Storage> (or
212 bug-MooseX-Storage@rt.cpan.org <mailto:bug-MooseX-
213 Storage@rt.cpan.org>).
214 There is also a mailing list available for users of this distribution,
216 at <http://lists.perl.org/list/moose.html>.
217 There is also an irc channel available for users of this distribution,
219 at "#moose" on "irc.perl.org" <irc://irc.perl.org/#moose>.
220
222 • Chris Prather <chris.prather@iinteractive.com>
223 • Stevan Little <stevan.little@iinteractive.com>
225 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
227
229 • Karen Etheridge <ether@cpan.org>
230 • Tomas Doran <bobtfish@bobtfish.net>
232 • Ricardo Signes <rjbs@cpan.org>
234 • Chris Prather <chris@prather.org>
236 • Jos Boumans <jos@dwim.org>
238 • Shawn M Moore <sartak@gmail.com>
240 • Jonathan Yu <frequency@cpan.org>
242 • Dmitry Latin <dim0xff@gmail.com>
244 • Robert Boone <robo4288@gmail.com>
246 • Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
248 • Cory Watson <gphat@Crankwizzah.local>
250 • sillitoe <ian@sillit.com>
252 • Dan Brook <dan@broquaint.com>
254 • David Golden <dagolden@cpan.org>
256 • David Steinbrunner <dsteinbrunner@pobox.com>
258 • Florian Ragwitz <rafl@debian.org>
260 • Graham Knop <haarg@haarg.org>
262 • Jason Pope <cowholio4@gmail.com>
264 • Johannes Plunien <plu@pqpq.de>
266 • Jonathan Rockway <jon@jrock.us>
268 • Yanick Champoux <yanick@babyl.dyndns.org>
270
272 This software is copyright (c) 2007 by Infinity Interactive, Inc.
273 This is free software; you can redistribute it and/or modify it under
275 the same terms as the Perl 5 programming language system itself.
276perl v5.36.0 2023-01-20 MooseX::Storage(3)