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