lib/MooseX/Storage.pm

   1 package MooseX::Storage;
   2 use Moose qw(confess);
   3
   4 use MooseX::Storage::Meta::Attribute::DoNotSerialize;
   5 use String::RewritePrefix ();
   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->add_method('Storage' => __PACKAGE__->meta->find_method_by_name('_injected_storage_role_generator'));
  16 }
  17
  18 my %HORRIBLE_GC_AVOIDANCE_HACK;
  19
  20 sub _rewrite_role_name {
  21     my ($self, $base, $string) = @_;
  22
  23     my $role_name = scalar String::RewritePrefix->rewrite(
  24         {
  25             ''  => "MooseX::Storage::$base\::",
  26             '=' => '',
  27         },
  28         $string,
  29     );
  30 }
  31
  32 sub _expand_role {
  33     my ($self, $base, $value) = @_;
  34
  35     return unless defined $value;
  36
  37     if (ref $value) {
  38         confess "too many args in arrayref role declaration" if @$value > 2;
  39         my ($class, $param) = @$value;
  40
  41         $class = $self->_rewrite_role_name($base => $class);
  42         Class::MOP::load_class($class);
  43
  44         my $role = $class->meta->generate_role(parameters => $param);
  45
  46         $HORRIBLE_GC_AVOIDANCE_HACK{ $role->name } = $role;
  47         return $role->name;
  48     } else {
  49         my $class = $self->_rewrite_role_name($base, $value);
  50         Class::MOP::load_class($class);
  51
  52         my $role = $class;
  53
  54         if ($class->meta->isa(
  55             'MooseX::Role::Parameterized::Meta::Role::Parameterizable'
  56         )) {
  57             $role = $class->meta->generate_role(parameters => undef);
  58             $HORRIBLE_GC_AVOIDANCE_HACK{ $role->name } = $role;
  59             return $role->name;
  60         }
  61
  62         return $class;
  63     }
  64 }
  65
  66 sub _injected_storage_role_generator {
  67     my %params = @_;
  68
  69     $params{base} = '=MooseX::Storage::Basic' unless defined $params{base};
  70
  71     my @roles = __PACKAGE__->_expand_role(Base => $params{base});
  72
  73     # NOTE:
  74     # you don't have to have a format
  75     # role, this just means you dont
  76     # get anything other than pack/unpack
  77     push @roles, __PACKAGE__->_expand_role(Format => $params{format});
  78
  79     # NOTE:
  80     # many IO roles don't make sense unless
  81     # you have also have a format role chosen
  82     # too, the exception being StorableFile
  83     #
  84     # NOTE:
  85     # we dont need this code anymore, cause
  86     # the role composition will catch it for
  87     # us. This allows the StorableFile to work
  88     #(exists $params{'format'})
  89     #    || confess "You must specify a format role in order to use an IO role";
  90     push @roles, __PACKAGE__->_expand_role(IO => $params{io});
  91
  92     # Note:
  93     # These traits alter the behaviour of the engine, the user can
  94     # specify these per role-usage
  95     for my $trait ( @{ $params{'traits'} ||= [] } ) {
  96         push @roles, __PACKAGE__->_expand_role(Traits => $trait);
  97     }
  98
  99     return @roles;
 100 }
 101
 102 1;
 103
 104 __END__
 105
 106 =pod
 107
 108 =head1 NAME
 109
 110 MooseX::Storage - A serialization framework for Moose classes
 111
 112 =head1 SYNOPSIS
 113
 114   package Point;
 115   use Moose;
 116   use MooseX::Storage;
 117
 118   with Storage('format' => 'JSON', 'io' => 'File');
 119
 120   has 'x' => (is => 'rw', isa => 'Int');
 121   has 'y' => (is => 'rw', isa => 'Int');
 122
 123   1;
 124
 125   my $p = Point->new(x => 10, y => 10);
 126
 127   ## methods to pack/unpack an
 128   ## object in perl data structures
 129
 130   # pack the class into a hash
 131   $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
 132
 133   # unpack the hash into a class
 134   my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
 135
 136   ## methods to freeze/thaw into
 137   ## a specified serialization format
 138   ## (in this case JSON)
 139
 140   # pack the class into a JSON string
 141   $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
 142
 143   # unpack the JSON string into a class
 144   my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
 145
 146   ## methods to load/store a class
 147   ## on the file system
 148
 149   $p->store('my_point.json');
 150
 151   my $p2 = Point->load('my_point.json');
 152
 153 =head1 DESCRIPTION
 154
 155 MooseX::Storage is a serialization framework for Moose, it provides
 156 a very flexible and highly pluggable way to serialize Moose classes
 157 to a number of different formats and styles.
 158
 159 =head2 Important Note
 160
 161 This is still an early release of this module, so use with caution.
 162 It's outward facing serialization API should be considered stable,
 163 but I still reserve the right to make tweaks if I need too. Anything
 164 beyond the basic pack/unpack, freeze/thaw and load/store should not
 165 be relied on.
 166
 167 =head2 Levels of Serialization
 168
 169 There are 3 levels to the serialization, each of which builds upon
 170 the other and each of which can be customized to the specific needs
 171 of your class.
 172
 173 =over 4
 174
 175 =item B<base>
 176
 177 The first (base) level is C<pack> and C<unpack>. In this level the
 178 class is serialized into a Perl HASH reference, it is tagged with the
 179 class name and each instance attribute is stored. Very simple.
 180
 181 This level is not optional, it is the bare minumum that
 182 MooseX::Storage provides and all other levels build on top of this.
 183
 184 See L<MooseX::Storage::Basic> for the fundamental implementation and
 185 options to C<pack> and C<unpack>
 186
 187 =item B<format>
 188
 189 The second (format) level is C<freeze> and C<thaw>. In this level the
 190 output of C<pack> is sent to C<freeze> or the output of C<thaw> is sent
 191 to C<unpack>. This levels primary role is to convert to and from the
 192 specific serialization format and Perl land.
 193
 194 This level is optional, if you don't want/need it, you don't have to
 195 have it. You can just use C<pack>/C<unpack> instead.
 196
 197 =item B<io>
 198
 199 The third (io) level is C<load> and C<store>. In this level we are reading
 200 and writing data to file/network/database/etc.
 201
 202 This level is also optional, in most cases it does require a C<format> role
 203 to also be used, the exception being the C<StorableFile> role.
 204
 205 =back
 206
 207 =head2 Behaviour modifiers
 208
 209 The serialization behaviour can be changed by supplying C<traits>.
 210 This can be done as follows:
 211
 212   use MooseX::Storage;
 213   with Storage( traits => [Trait1, Trait2,...] );
 214
 215 The following traits are currently bundled with C<MooseX::Storage>:
 216
 217 =over 4
 218
 219 =item OnlyWhenBuilt
 220
 221 Only attributes that have been built (ie, where the predicate returns
 222 'true') will be serialized. This avoids any potentially expensive computations.
 223
 224 See L<MooseX::Storage::Traits::OnlyWhenBuilt> for details.
 225
 226 =back
 227
 228 =head2 How we serialize
 229
 230 There are always limits to any serialization framework, there are just
 231 some things which are really difficult to serialize properly and some
 232 things which cannot be serialized at all.
 233
 234 =head2 What can be serialized?
 235
 236 Currently only numbers, string, ARRAY refs, HASH refs and other
 237 MooseX::Storage enabled objects are supported.
 238
 239 With Array and Hash references the first level down is inspected and
 240 any objects found are serialized/deserialized for you. We do not do
 241 this recusively by default, however this feature may become an
 242 option eventually.
 243
 244 The specific serialize/deserialize routine is determined by the
 245 Moose type constraint a specific attribute has. In most cases subtypes
 246 of the supported types are handled correctly, and there is a facility
 247 for adding handlers for custom types as well. This will get documented
 248 eventually, but it is currently still in development.
 249
 250 =head2 What can not be serialized?
 251
 252 We do not support CODE references yet, but this support might be added
 253 in using B::Deparse or some other deep magic.
 254
 255 Scalar refs are not supported, mostly because there is no way to know
 256 if the value being referenced will be there when the object is inflated.
 257 I highly doubt will be ever support this in a general sense, but it
 258 would be possible to add this yourself for a small specific case.
 259
 260 Circular references are specifically disallowed, however if you break
 261 the cycles yourself then re-assemble them later you can get around this.
 262 The reason we disallow circular refs is because they are not always supported
 263 in all formats we use, and they tend to be very tricky to do for all
 264 possible cases. It is almost always something you want to have tight control
 265 over anyway.
 266
 267 =head1 CAVEAT
 268
 269 This is B<not> a persistence framework; changes to your object after
 270 you load or store it will not be reflected in the stored class.
 271
 272 =head1 EXPORTS
 273
 274 =over 4
 275
 276 =item B<Storage (%options)>
 277
 278 This module will export the C<Storage> method and can be used to
 279 load a specific set of MooseX::Storage roles to implement a specific
 280 combination of features. It is meant to make things easier, but it
 281 is by no means the only way. You can still compose your roles by
 282 hand if you like.
 283
 284 By default, options are assumed to be short forms.  For example, this:
 285
 286   Storage(format => 'JSON');
 287
 288 ...will result in looking for MooseX::Storage::Format::JSON.  To use a role
 289 that is not under the default namespace prefix, start with an equal sign:
 290
 291   Storage(format => '=My::Private::JSONFormat');
 292
 293 To use a parameterized role (for which, see L<MooseX::Role::Parameterized>) you
 294 can pass an arrayref of the role name (in short or long form, as above) and its
 295 parameters:
 296
 297   Storage(format => [ JSONpm => { json_opts => { pretty => 1 } } ]);
 298
 299 =back
 300
 301 =head1 METHODS
 302
 303 =over 4
 304
 305 =item B<import>
 306
 307 =back
 308
 309 =head2 Introspection
 310
 311 =over 4
 312
 313 =item B<meta>
 314
 315 =back
 316
 317 =head1 TODO
 318
 319 This module needs docs and probably a Cookbook of some kind as well.
 320 This is an early release, so that is my excuse for now :)
 321
 322 For the time being, please read the tests and feel free to email me
 323 if you have any questions. This module can also be discussed on IRC
 324 in the #moose channel on irc.perl.org.
 325
 326 =head1 BUGS
 327
 328 All complex software has bugs lurking in it, and this module is no
 329 exception. If you find a bug please either email me, or add the bug
 330 to cpan-RT.
 331
 332 =head1 AUTHOR
 333
 334 Chris Prather E<lt>chris.prather@iinteractive.comE<gt>
 335
 336 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
 337
 338 Yuval Kogman E<lt>yuval.kogman@iinteractive.comE<gt>
 339
 340 =head1 COPYRIGHT AND LICENSE
 341
 342 Copyright 2007-2008 by Infinity Interactive, Inc.
 343
 344 L<http://www.iinteractive.com>
 345
 346 This library is free software; you can redistribute it and/or modify
 347 it under the same terms as Perl itself.
 348
 349 =cut