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