X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMooseX%2FStorage.pm;h=6812dcffcc9be03b8cec9624fc9e2d723e519f00;hb=14e5132ad4def507c424a56dfb30b935b1ab3b44;hp=a6e4c25910114181b2143f420ab00bf087535471;hpb=76b60811edb8232e205ef3ca18427edf2efbde4a;p=gitmo%2FMooseX-Storage.git diff --git a/lib/MooseX/Storage.pm b/lib/MooseX/Storage.pm index a6e4c25..6812dcf 100644 --- a/lib/MooseX/Storage.pm +++ b/lib/MooseX/Storage.pm @@ -4,55 +4,55 @@ use Moose qw(confess); use MooseX::Storage::Meta::Attribute::DoNotSerialize; -our $VERSION = '0.18'; +our $VERSION = '0.21'; our $AUTHORITY = 'cpan:STEVAN'; sub import { my $pkg = caller(); - + return if $pkg eq 'main'; - + ($pkg->can('meta')) || confess "This package can only be used in Moose based classes"; - - $pkg->meta->add_method('Storage' => __PACKAGE__->meta->find_method_by_name('_injected_storage_role_generator')); + + $pkg->meta->add_method('Storage' => __PACKAGE__->meta->find_method_by_name('_injected_storage_role_generator')); } sub _injected_storage_role_generator { my %params = @_; - + if (exists $params{'base'}) { - $params{'base'} = ('Base::' . $params{'base'}); + $params{'base'} = ('Base::' . $params{'base'}); } else { - $params{'base'} = 'Basic'; + $params{'base'} = 'Basic'; } - + my @roles = ( ('MooseX::Storage::' . $params{'base'}), ); - + # NOTE: - # you don't have to have a format - # role, this just means you dont + # you don't have to have a format + # role, this just means you dont # get anything other than pack/unpack push @roles => 'MooseX::Storage::Format::' . $params{'format'} if exists $params{'format'}; - + # NOTE: - # many IO roles don't make sense unless + # many IO roles don't make sense unless # you have also have a format role chosen # too, the exception being StorableFile if (exists $params{'io'}) { # NOTE: - # we dont need this code anymore, cause - # the role composition will catch it for + # we dont need this code anymore, cause + # the role composition will catch it for # us. This allows the StorableFile to work #(exists $params{'format'}) # || confess "You must specify a format role in order to use an IO role"; push @roles => 'MooseX::Storage::IO::' . $params{'io'}; } - + # Note: # These traits alter the behaviour of the engine, the user can # specify these per role-usage @@ -60,10 +60,10 @@ sub _injected_storage_role_generator { push @roles, 'MooseX::Storage::Traits::'.$trait; } - for my $role ( @roles ) { + for my $role ( @roles ) { Class::MOP::load_class($role) or die "Could not load role ($role)"; } - + return @roles; } @@ -82,61 +82,61 @@ MooseX::Storage - A serialization framework for Moose classes package Point; use Moose; use MooseX::Storage; - + our $VERSION = '0.01'; - + with Storage('format' => 'JSON', 'io' => 'File'); - + has 'x' => (is => 'rw', isa => 'Int'); has 'y' => (is => 'rw', isa => 'Int'); - + 1; - + my $p = Point->new(x => 10, y => 10); - - ## methods to pack/unpack an + + ## methods to pack/unpack an ## object in perl data structures - + # pack the class into a hash $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 } - + # unpack the hash into a class my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 }); - ## methods to freeze/thaw into + ## methods to freeze/thaw into ## a specified serialization format ## (in this case JSON) - + # pack the class into a JSON string $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 } - + # unpack the JSON string into a class - my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }'); + my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }'); - ## methods to load/store a class + ## methods to load/store a class ## on the file system - + $p->store('my_point.json'); - + my $p2 = Point->load('my_point.json'); =head1 DESCRIPTION -MooseX::Storage is a serialization framework for Moose, it provides +MooseX::Storage is a serialization framework for Moose, it provides a very flexible and highly pluggable way to serialize Moose classes to a number of different formats and styles. =head2 Important Note -This is still an early release of this module, so use with caution. -It's outward facing serialization API should be considered stable, +This is still an early release of this module, so use with caution. +It's outward facing serialization API should be considered stable, but I still reserve the right to make tweaks if I need too. Anything -beyond the basic pack/unpack, freeze/thaw and load/store should not +beyond the basic pack/unpack, freeze/thaw and load/store should not be relied on. =head2 Levels of Serialization -There are 3 levels to the serialization, each of which builds upon +There are 3 levels to the serialization, each of which builds upon the other and each of which can be customized to the specific needs of your class. @@ -144,27 +144,30 @@ of your class. =item B -The first (base) level is C and C. In this level the -class is serialized into a Perl HASH reference, it is tagged with the +The first (base) level is C and C. In this level the +class is serialized into a Perl HASH reference, it is tagged with the class name and each instance attribute is stored. Very simple. -This level is not optional, it is the bare minumum that +This level is not optional, it is the bare minumum that MooseX::Storage provides and all other levels build on top of this. +See L for the fundamental implementation and +options to C and C + =item B -The second (format) level is C and C. In this level the -output of C is sent to C or the output of C is sent -to C. This levels primary role is to convert to and from the -specific serialization format and Perl land. +The second (format) level is C and C. In this level the +output of C is sent to C or the output of C is sent +to C. This levels primary role is to convert to and from the +specific serialization format and Perl land. -This level is optional, if you don't want/need it, you don't have to +This level is optional, if you don't want/need it, you don't have to have it. You can just use C/C instead. =item B -The third (io) level is C and C. In this level we are reading -and writing data to file/network/database/etc. +The third (io) level is C and C. In this level we are reading +and writing data to file/network/database/etc. This level is also optional, in most cases it does require a C role to also be used, the expection being the C role. @@ -178,14 +181,14 @@ This can be done as follows: use MooseX::Storage; with Storage( traits => [Trait1, Trait2,...] ); - + The following traits are currently bundled with C: =over 4 =item OnlyWhenBuilt -Only attributes that have been built (ie, where the predicate returns +Only attributes that have been built (ie, where the predicate returns 'true') will be serialized. This avoids any potentially expensive computations. See L for details. @@ -194,47 +197,47 @@ See L for details. =head2 How we serialize -There are always limits to any serialization framework, there are just -some things which are really difficult to serialize properly and some +There are always limits to any serialization framework, there are just +some things which are really difficult to serialize properly and some things which cannot be serialized at all. =head2 What can be serialized? -Currently only numbers, string, ARRAY refs, HASH refs and other -MooseX::Storage enabled objects are supported. +Currently only numbers, string, ARRAY refs, HASH refs and other +MooseX::Storage enabled objects are supported. -With Array and Hash references the first level down is inspected and -any objects found are serialized/deserialized for you. We do not do -this recusively by default, however this feature may become an +With Array and Hash references the first level down is inspected and +any objects found are serialized/deserialized for you. We do not do +this recusively by default, however this feature may become an option eventually. -The specific serialize/deserialize routine is determined by the -Moose type constraint a specific attribute has. In most cases subtypes -of the supported types are handled correctly, and there is a facility +The specific serialize/deserialize routine is determined by the +Moose type constraint a specific attribute has. In most cases subtypes +of the supported types are handled correctly, and there is a facility for adding handlers for custom types as well. This will get documented eventually, but it is currently still in development. =head2 What can not be serialized? -We do not support CODE references yet, but this support might be added -in using B::Deparse or some other deep magic. +We do not support CODE references yet, but this support might be added +in using B::Deparse or some other deep magic. -Scalar refs are not supported, mostly because there is no way to know -if the value being referenced will be there when the object is inflated. -I highly doubt will be ever support this in a general sense, but it +Scalar refs are not supported, mostly because there is no way to know +if the value being referenced will be there when the object is inflated. +I highly doubt will be ever support this in a general sense, but it would be possible to add this yourself for a small specific case. -Circular references are specifically disallowed, however if you break +Circular references are specifically disallowed, however if you break the cycles yourself then re-assemble them later you can get around this. -The reason we disallow circular refs is because they are not always supported -in all formats we use, and they tend to be very tricky to do for all -possible cases. It is almost always something you want to have tight control +The reason we disallow circular refs is because they are not always supported +in all formats we use, and they tend to be very tricky to do for all +possible cases. It is almost always something you want to have tight control over anyway. =head1 CAVEAT This is B a persistence framework, changes to your object after -you load or store it will not be reflected in the stored class. +you load or store it will not be reflected in the stored class. =head1 EXPORTS @@ -242,10 +245,10 @@ you load or store it will not be reflected in the stored class. =item B -This module will export the C method will can be used to -load a specific set of MooseX::Storage roles to implement a specific -combination of features. It is meant to make things easier, but it -is by no means the only way. You can still compose your roles by +This module will export the C method will can be used to +load a specific set of MooseX::Storage roles to implement a specific +combination of features. It is meant to make things easier, but it +is by no means the only way. You can still compose your roles by hand if you like. =back @@ -268,16 +271,16 @@ hand if you like. =head1 TODO -This module needs docs and probably a Cookbook of some kind as well. +This module needs docs and probably a Cookbook of some kind as well. This is an early release, so that is my excuse for now :) -For the time being, please read the tests and feel free to email me -if you have any questions. This module can also be discussed on IRC +For the time being, please read the tests and feel free to email me +if you have any questions. This module can also be discussed on IRC in the #moose channel on irc.perl.org. =head1 BUGS -All complex software has bugs lurking in it, and this module is no +All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.