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