lib/MooseX/Storage.pm

   1
   2 package MooseX::Storage;
   3 use Moose qw(confess);
   4
   5 use MooseX::Storage::Meta::Attribute::DoNotSerialize;
   6
   7 our $VERSION   = '0.20';
   8 our $AUTHORITY = 'cpan:STEVAN';
   9
  10 sub import {
  11     my $pkg = caller();
  12
  13     return if $pkg eq 'main';
  14
  15     ($pkg->can('meta'))
  16         || confess "This package can only be used in Moose based classes";
  17
  18     $pkg->meta->add_method('Storage' => __PACKAGE__->meta->find_method_by_name('_injected_storage_role_generator'));
  19 }
  20
  21 sub _injected_storage_role_generator {
  22     my %params = @_;
  23
  24     if (exists $params{'base'}) {
  25         $params{'base'} = ('Base::' . $params{'base'});
  26     }
  27     else {
  28         $params{'base'} = 'Basic';
  29     }
  30
  31     my @roles = (
  32         ('MooseX::Storage::' . $params{'base'}),
  33     );
  34
  35     # NOTE:
  36     # you don't have to have a format
  37     # role, this just means you dont
  38     # get anything other than pack/unpack
  39     push @roles => 'MooseX::Storage::Format::' . $params{'format'}
  40         if exists $params{'format'};
  41
  42     # NOTE:
  43     # many IO roles don't make sense unless
  44     # you have also have a format role chosen
  45     # too, the exception being StorableFile
  46     if (exists $params{'io'}) {
  47         # NOTE:
  48         # we dont need this code anymore, cause
  49         # the role composition will catch it for
  50         # us. This allows the StorableFile to work
  51         #(exists $params{'format'})
  52         #    || confess "You must specify a format role in order to use an IO role";
  53         push @roles => 'MooseX::Storage::IO::' . $params{'io'};
  54     }
  55
  56     # Note:
  57     # These traits alter the behaviour of the engine, the user can
  58     # specify these per role-usage
  59     for my $trait ( @{ $params{'traits'} ||= [] } ) {
  60         push @roles, 'MooseX::Storage::Traits::'.$trait;
  61     }
  62
  63     for my $role ( @roles ) {
  64         Class::MOP::load_class($role) or die "Could not load role ($role)";
  65     }
  66
  67     return @roles;
  68 }
  69
  70 1;
  71
  72 __END__
  73
  74 =pod
  75
  76 =head1 NAME
  77
  78 MooseX::Storage - A serialization framework for Moose classes
  79
  80 =head1 SYNOPSIS
  81
  82   package Point;
  83   use Moose;
  84   use MooseX::Storage;
  85
  86   our $VERSION = '0.01';
  87
  88   with Storage('format' => 'JSON', 'io' => 'File');
  89
  90   has 'x' => (is => 'rw', isa => 'Int');
  91   has 'y' => (is => 'rw', isa => 'Int');
  92
  93   1;
  94
  95   my $p = Point->new(x => 10, y => 10);
  96
  97   ## methods to pack/unpack an
  98   ## object in perl data structures
  99
 100   # pack the class into a hash
 101   $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
 102
 103   # unpack the hash into a class
 104   my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
 105
 106   ## methods to freeze/thaw into
 107   ## a specified serialization format
 108   ## (in this case JSON)
 109
 110   # pack the class into a JSON string
 111   $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
 112
 113   # unpack the JSON string into a class
 114   my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
 115
 116   ## methods to load/store a class
 117   ## on the file system
 118
 119   $p->store('my_point.json');
 120
 121   my $p2 = Point->load('my_point.json');
 122
 123 =head1 DESCRIPTION
 124
 125 MooseX::Storage is a serialization framework for Moose, it provides
 126 a very flexible and highly pluggable way to serialize Moose classes
 127 to a number of different formats and styles.
 128
 129 =head2 Important Note
 130
 131 This is still an early release of this module, so use with caution.
 132 It's outward facing serialization API should be considered stable,
 133 but I still reserve the right to make tweaks if I need too. Anything
 134 beyond the basic pack/unpack, freeze/thaw and load/store should not
 135 be relied on.
 136
 137 =head2 Levels of Serialization
 138
 139 There are 3 levels to the serialization, each of which builds upon
 140 the other and each of which can be customized to the specific needs
 141 of your class.
 142
 143 =over 4
 144
 145 =item B<base>
 146
 147 The first (base) level is C<pack> and C<unpack>. In this level the
 148 class is serialized into a Perl HASH reference, it is tagged with the
 149 class name and each instance attribute is stored. Very simple.
 150
 151 This level is not optional, it is the bare minumum that
 152 MooseX::Storage provides and all other levels build on top of this.
 153
 154 See L<Moosex::Storage::Basic> for the fundamental implementation and
 155 options to C<pack> and C<unpack>
 156
 157 =item B<format>
 158
 159 The second (format) level is C<freeze> and C<thaw>. In this level the
 160 output of C<pack> is sent to C<freeze> or the output of C<thaw> is sent
 161 to C<unpack>. This levels primary role is to convert to and from the
 162 specific serialization format and Perl land.
 163
 164 This level is optional, if you don't want/need it, you don't have to
 165 have it. You can just use C<pack>/C<unpack> instead.
 166
 167 =item B<io>
 168
 169 The third (io) level is C<load> and C<store>. In this level we are reading
 170 and writing data to file/network/database/etc.
 171
 172 This level is also optional, in most cases it does require a C<format> role
 173 to also be used, the expection being the C<StorableFile> role.
 174
 175 =back
 176
 177 =head2 Behaviour modifiers
 178
 179 The serialization behaviour can be changed by supplying C<traits>.
 180 This can be done as follows:
 181
 182   use MooseX::Storage;
 183   with Storage( traits => [Trait1, Trait2,...] );
 184
 185 The following traits are currently bundled with C<MooseX::Storage>:
 186
 187 =over 4
 188
 189 =item OnlyWhenBuilt
 190
 191 Only attributes that have been built (ie, where the predicate returns
 192 'true') will be serialized. This avoids any potentially expensive computations.
 193
 194 See L<MooseX::Storage::Traits::OnlyWhenBuilt> for details.
 195
 196 =back
 197
 198 =head2 How we serialize
 199
 200 There are always limits to any serialization framework, there are just
 201 some things which are really difficult to serialize properly and some
 202 things which cannot be serialized at all.
 203
 204 =head2 What can be serialized?
 205
 206 Currently only numbers, string, ARRAY refs, HASH refs and other
 207 MooseX::Storage enabled objects are supported.
 208
 209 With Array and Hash references the first level down is inspected and
 210 any objects found are serialized/deserialized for you. We do not do
 211 this recusively by default, however this feature may become an
 212 option eventually.
 213
 214 The specific serialize/deserialize routine is determined by the
 215 Moose type constraint a specific attribute has. In most cases subtypes
 216 of the supported types are handled correctly, and there is a facility
 217 for adding handlers for custom types as well. This will get documented
 218 eventually, but it is currently still in development.
 219
 220 =head2 What can not be serialized?
 221
 222 We do not support CODE references yet, but this support might be added
 223 in using B::Deparse or some other deep magic.
 224
 225 Scalar refs are not supported, mostly because there is no way to know
 226 if the value being referenced will be there when the object is inflated.
 227 I highly doubt will be ever support this in a general sense, but it
 228 would be possible to add this yourself for a small specific case.
 229
 230 Circular references are specifically disallowed, however if you break
 231 the cycles yourself then re-assemble them later you can get around this.
 232 The reason we disallow circular refs is because they are not always supported
 233 in all formats we use, and they tend to be very tricky to do for all
 234 possible cases. It is almost always something you want to have tight control
 235 over anyway.
 236
 237 =head1 CAVEAT
 238
 239 This is B<not> a persistence framework, changes to your object after
 240 you load or store it will not be reflected in the stored class.
 241
 242 =head1 EXPORTS
 243
 244 =over 4
 245
 246 =item B<Storage (%options)>
 247
 248 This module will export the C<Storage> method will can be used to
 249 load a specific set of MooseX::Storage roles to implement a specific
 250 combination of features. It is meant to make things easier, but it
 251 is by no means the only way. You can still compose your roles by
 252 hand if you like.
 253
 254 =back
 255
 256 =head1 METHODS
 257
 258 =over 4
 259
 260 =item B<import>
 261
 262 =back
 263
 264 =head2 Introspection
 265
 266 =over 4
 267
 268 =item B<meta>
 269
 270 =back
 271
 272 =head1 TODO
 273
 274 This module needs docs and probably a Cookbook of some kind as well.
 275 This is an early release, so that is my excuse for now :)
 276
 277 For the time being, please read the tests and feel free to email me
 278 if you have any questions. This module can also be discussed on IRC
 279 in the #moose channel on irc.perl.org.
 280
 281 =head1 BUGS
 282
 283 All complex software has bugs lurking in it, and this module is no
 284 exception. If you find a bug please either email me, or add the bug
 285 to cpan-RT.
 286
 287 =head1 AUTHOR
 288
 289 Chris Prather E<lt>chris.prather@iinteractive.comE<gt>
 290
 291 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
 292
 293 Yuval Kogman E<lt>yuval.kogman@iinteractive.comE<gt>
 294
 295 =head1 COPYRIGHT AND LICENSE
 296
 297 Copyright 2007-2008 by Infinity Interactive, Inc.
 298
 299 L<http://www.iinteractive.com>
 300
 301 This library is free software; you can redistribute it and/or modify
 302 it under the same terms as Perl itself.
 303
 304 =cut