1MooseX::Storage(3)    User Contributed Perl Documentation   MooseX::Storage(3)
2
3
4

NAME

6       MooseX::Storage - A serialization framework for Moose classes
7

VERSION

9       version 0.53
10

SYNOPSIS

12         package Point;
13         use Moose;
14         use MooseX::Storage;
15
16         with Storage('format' => 'JSON', 'io' => 'File');
17
18         has 'x' => (is => 'rw', isa => 'Int');
19         has 'y' => (is => 'rw', isa => 'Int');
20
21         1;
22
23         my $p = Point->new(x => 10, y => 10);
24
25         ## methods to pack/unpack an
26         ## object in perl data structures
27
28         # pack the class into a hash
29         $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
30
31         # unpack the hash into a class
32         my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
33
34         ## methods to freeze/thaw into
35         ## a specified serialization format
36         ## (in this case JSON)
37
38         # pack the class into a JSON string
39         $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
40
41         # unpack the JSON string into a class
42         my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
43
44         ## methods to load/store a class
45         ## on the file system
46
47         $p->store('my_point.json');
48
49         my $p2 = Point->load('my_point.json');
50

DESCRIPTION

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
56   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
61       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
66           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
69           See MooseX::Storage::Basic for the fundamental implementation and
70           options to "pack" and "unpack"
71
72       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
78           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
81       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
84           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
88   Behaviour modifiers
89       The serialization behaviour can be changed by supplying "traits" to
90       either the class or an individual attribute.
91
92       This can be done as follows:
93
94         use MooseX::Storage;
95
96         # adjust behaviour for the entire class
97         with Storage( traits => [Trait1, Trait2,...] );
98
99         # adjust behaviour for an attribute
100         has my_attr => (
101           traits => [Trait1, Trait2, ...],
102           ...
103         );
104
105       The following class traits are currently bundled with MooseX::Storage:
106
107       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
112           See MooseX::Storage::Traits::OnlyWhenBuilt for details.
113
114       DisableCycleDetection
115           Disables the default checks for circular references, which is
116           necessary if you use such references in your serialisable objects.
117
118           See MooseX::Storage::Traits::DisableCycleDetection for details.
119
120       The following attribute traits are currently bundled with
121       MooseX::Storage:
122
123       DoNotSerialize
124           Skip serialization entirely for this attribute.
125
126           See MooseX::Storage::Meta::Attribute::Trait::DoNotSerialize for
127           details.
128
129   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
134   What can be serialized?
135       Currently only numbers, string, ARRAY refs, HASH refs and other
136       MooseX::Storage-enabled objects are supported.
137
138       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
143       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
149   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
153       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
159       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

CAVEAT

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

EXPORTS

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
178           By default, options are assumed to be short forms.  For example,
179           this:
180
181             Storage(format => 'JSON');
182
183           ...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
187             Storage(format => '=My::Private::JSONFormat');
188
189           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
193             Storage(format => [ JSONpm => { json_opts => { pretty => 1 } } ]);
194

METHODS

196       import
197
198   Introspection
199       meta
200

TODO

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
205       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

SUPPORT

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
215       There is also a mailing list available for users of this distribution,
216       at <http://lists.perl.org/list/moose.html>.
217
218       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

AUTHORS

222       •   Chris Prather <chris.prather@iinteractive.com>
223
224       •   Stevan Little <stevan.little@iinteractive.com>
225
226       •   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
227

CONTRIBUTORS

229       •   Karen Etheridge <ether@cpan.org>
230
231       •   Tomas Doran <bobtfish@bobtfish.net>
232
233       •   Ricardo Signes <rjbs@cpan.org>
234
235       •   Chris Prather <chris@prather.org>
236
237       •   Jos Boumans <jos@dwim.org>
238
239       •   Shawn M Moore <sartak@gmail.com>
240
241       •   Jonathan Yu <frequency@cpan.org>
242
243       •   Dmitry Latin <dim0xff@gmail.com>
244
245       •   Robert Boone <robo4288@gmail.com>
246
247       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
248
249       •   Cory Watson <gphat@Crankwizzah.local>
250
251       •   sillitoe <ian@sillit.com>
252
253       •   Dan Brook <dan@broquaint.com>
254
255       •   David Golden <dagolden@cpan.org>
256
257       •   David Steinbrunner <dsteinbrunner@pobox.com>
258
259       •   Florian Ragwitz <rafl@debian.org>
260
261       •   Graham Knop <haarg@haarg.org>
262
263       •   Jason Pope <cowholio4@gmail.com>
264
265       •   Johannes Plunien <plu@pqpq.de>
266
267       •   Jonathan Rockway <jon@jrock.us>
268
269       •   Yanick Champoux <yanick@babyl.dyndns.org>
270
272       This software is copyright (c) 2007 by Infinity Interactive, Inc.
273
274       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.
276
277
278
279perl v5.36.0                      2023-01-20                MooseX::Storage(3)
Impressum