Commit | Line | Data |
4d941613 |
1 | # NAME |
2 | |
3 | MooseX::Storage - A serialization framework for Moose classes |
4 | |
5 | # SYNOPSIS |
6 | |
7 | package Point; |
8 | use Moose; |
9 | use MooseX::Storage; |
10 | |
11 | with Storage('format' => 'JSON', 'io' => 'File'); |
12 | |
13 | has 'x' => (is => 'rw', isa => 'Int'); |
14 | has 'y' => (is => 'rw', isa => 'Int'); |
15 | |
16 | 1; |
17 | |
18 | my $p = Point->new(x => 10, y => 10); |
19 | |
20 | ## methods to pack/unpack an |
21 | ## object in perl data structures |
22 | |
23 | # pack the class into a hash |
24 | $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 } |
25 | |
26 | # unpack the hash into a class |
27 | my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 }); |
28 | |
29 | ## methods to freeze/thaw into |
30 | ## a specified serialization format |
31 | ## (in this case JSON) |
32 | |
33 | # pack the class into a JSON string |
34 | $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 } |
35 | |
36 | # unpack the JSON string into a class |
37 | my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }'); |
38 | |
39 | ## methods to load/store a class |
40 | ## on the file system |
41 | |
42 | $p->store('my_point.json'); |
43 | |
44 | my $p2 = Point->load('my_point.json'); |
45 | |
46 | # DESCRIPTION |
47 | |
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. |
51 | |
52 | ## Important Note |
53 | |
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 |
58 | be relied on. |
59 | |
60 | ## Levels of Serialization |
61 | |
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 |
64 | of your class. |
65 | |
66 | - __base__ |
67 | |
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. |
71 | |
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. |
74 | |
75 | See [MooseX::Storage::Basic](http://search.cpan.org/perldoc?MooseX::Storage::Basic) for the fundamental implementation and |
76 | options to `pack` and `unpack` |
77 | |
78 | - __format__ |
79 | |
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. |
84 | |
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. |
87 | |
88 | - __io__ |
89 | |
90 | The third (io) level is `load` and `store`. In this level we are reading |
91 | and writing data to file/network/database/etc. |
92 | |
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. |
95 | |
96 | ## Behaviour modifiers |
97 | |
98 | The serialization behaviour can be changed by supplying `traits`. |
99 | This can be done as follows: |
100 | |
101 | use MooseX::Storage; |
102 | with Storage( traits => [Trait1, Trait2,...] ); |
103 | |
104 | The following traits are currently bundled with `MooseX::Storage`: |
105 | |
106 | - OnlyWhenBuilt |
107 | |
108 | Only attributes that have been built (i.e., where the predicate returns |
109 | 'true') will be serialized. This avoids any potentially expensive computations. |
110 | |
111 | See [MooseX::Storage::Traits::OnlyWhenBuilt](http://search.cpan.org/perldoc?MooseX::Storage::Traits::OnlyWhenBuilt) for details. |
112 | |
113 | ## How we serialize |
114 | |
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. |
118 | |
119 | ## What can be serialized? |
120 | |
121 | Currently only numbers, string, ARRAY refs, HASH refs and other |
122 | MooseX::Storage enabled objects are supported. |
123 | |
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 |
127 | option eventually. |
128 | |
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. |
134 | |
135 | ## What can not be serialized? |
136 | |
137 | We do not support CODE references yet, but this support might be added |
138 | in using B::Deparse or some other deep magic. |
139 | |
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. |
144 | |
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 |
150 | over anyway. |
151 | |
152 | # CAVEAT |
153 | |
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. |
156 | |
157 | # EXPORTS |
158 | |
159 | - __Storage (%options)__ |
160 | |
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 |
165 | hand if you like. |
166 | |
167 | By default, options are assumed to be short forms. For example, this: |
168 | |
169 | Storage(format => 'JSON'); |
170 | |
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: |
173 | |
174 | Storage(format => '=My::Private::JSONFormat'); |
175 | |
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 |
178 | parameters: |
179 | |
180 | Storage(format => [ JSONpm => { json_opts => { pretty => 1 } } ]); |
181 | |
182 | # METHODS |
183 | |
184 | - __import__ |
185 | |
186 | ## Introspection |
187 | |
188 | - __meta__ |
189 | |
190 | # TODO |
191 | |
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 :) |
194 | |
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. |
198 | |
199 | # BUGS |
200 | |
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 |
203 | to cpan-RT. |
204 | |
205 | # AUTHOR |
206 | |
207 | Chris Prather <chris.prather@iinteractive.com> |
208 | |
209 | Stevan Little <stevan.little@iinteractive.com> |
210 | |
211 | Yuval Kogman <yuval.kogman@iinteractive.com> |
212 | |
213 | # COPYRIGHT AND LICENSE |
214 | |
215 | Copyright 2007-2008 by Infinity Interactive, Inc. |
216 | |
217 | [http://www.iinteractive.com](http://www.iinteractive.com) |
218 | |
219 | This library is free software; you can redistribute it and/or modify |
220 | it under the same terms as Perl itself. |