lib/MooseX/Storage.pm

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