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