X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.md;h=20d85bf1e8033c43b5cd66be76fab2663b4a288d;hb=fdc71a7a0725af3c3f955ce57ebdee29deb41afa;hp=e69de29bb2d1d6434b8b29ae775ad8c2e48c5391;hpb=d3671a48f9673b8f5e74f9105b56406e4bfe5a6b;p=gitmo%2FMooseX-Storage.git diff --git a/README.md b/README.md index e69de29..20d85bf 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,220 @@ +# NAME + +MooseX::Storage - A serialization framework for Moose classes + +# SYNOPSIS + + package Point; + use Moose; + use MooseX::Storage; + + 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 + ## 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 + ## 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 }'); + + ## methods to load/store a class + ## on the file system + + $p->store('my_point.json'); + + my $p2 = Point->load('my_point.json'); + +# DESCRIPTION + +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. + +## 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, +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 +be relied on. + +## Levels of Serialization + +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. + +- __base__ + + The first (base) level is `pack` and `unpack`. 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 minimum that + MooseX::Storage provides and all other levels build on top of this. + + See [MooseX::Storage::Basic](http://search.cpan.org/perldoc?MooseX::Storage::Basic) for the fundamental implementation and + options to `pack` and `unpack` + +- __format__ + + The second (format) level is `freeze` and `thaw`. In this level the + output of `pack` is sent to `freeze` or the output of `thaw` is sent + to `unpack`. 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 + have it. You can just use `pack`/`unpack` instead. + +- __io__ + + The third (io) level is `load` and `store`. 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 `format` role + to also be used, the exception being the `StorableFile` role. + +## Behaviour modifiers + +The serialization behaviour can be changed by supplying `traits`. +This can be done as follows: + + use MooseX::Storage; + with Storage( traits => [Trait1, Trait2,...] ); + +The following traits are currently bundled with `MooseX::Storage`: + +- OnlyWhenBuilt + + Only attributes that have been built (i.e., where the predicate returns + 'true') will be serialized. This avoids any potentially expensive computations. + + See [MooseX::Storage::Traits::OnlyWhenBuilt](http://search.cpan.org/perldoc?MooseX::Storage::Traits::OnlyWhenBuilt) for details. + +## 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 +things which cannot be serialized at all. + +## What can be serialized? + +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 recursively 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 +for adding handlers for custom types as well. This will get documented +eventually, but it is currently still in development. + +## 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. + +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 +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 +over anyway. + +# CAVEAT + +This is __not__ a persistence framework; changes to your object after +you load or store it will not be reflected in the stored class. + +# EXPORTS + +- __Storage (%options)__ + + This module will export the `Storage` method and 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. + + By default, options are assumed to be short forms. For example, this: + + Storage(format => 'JSON'); + + ...will result in looking for MooseX::Storage::Format::JSON. To use a role + that is not under the default namespace prefix, start with an equal sign: + + Storage(format => '=My::Private::JSONFormat'); + + To use a parameterized role (for which, see [MooseX::Role::Parameterized](http://search.cpan.org/perldoc?MooseX::Role::Parameterized)) you + can pass an arrayref of the role name (in short or long form, as above) and its + parameters: + + Storage(format => [ JSONpm => { json_opts => { pretty => 1 } } ]); + +# METHODS + +- __import__ + +## Introspection + +- __meta__ + +# TODO + +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 +in the \#moose channel on irc.perl.org. + +# BUGS + +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. + +# AUTHOR + +Chris Prather + +Stevan Little + +Yuval Kogman + +# COPYRIGHT AND LICENSE + +Copyright 2007-2008 by Infinity Interactive, Inc. + +[http://www.iinteractive.com](http://www.iinteractive.com) + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself.