From: Stevan Little Date: Mon, 30 Apr 2007 00:02:01 +0000 (+0000) Subject: docs X-Git-Tag: 0_02~19 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=gitmo%2FMooseX-Storage.git;a=commitdiff_plain;h=1390c23dd40f71e312351625cf8b5d2d9a9eefa4 docs --- diff --git a/lib/MooseX/Storage.pm b/lib/MooseX/Storage.pm index 07bc85f..ccf48f4 100644 --- a/lib/MooseX/Storage.pm +++ b/lib/MooseX/Storage.pm @@ -58,8 +58,146 @@ MooseX::Storage - An serialization framework for Moose classes =head1 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', x => 10, y => 10 } + + # unpack the hash into a class + my $p2 = Point->unpack({ __CLASS__ => 'Point', 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", "x" : 10, "y" : 10 } + + # unpack the JSON string into a class + my $p2 = Point->thaw('{ "__CLASS__" : "Point", "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'); + =head1 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. + +=head2 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. + +=over 4 + +=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 +class name and each instance attribute is stored. Very simple. + +This level is not optional, it is the bare minumum that +MooseX::Storage provides and all other levels build on top of this. + +=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. + +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. + +This level is also optional, it does however require the C level +to be present (at least the current state does). + +=back + +=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 +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. + +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 +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. + +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. + +=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. + +=head1 EXPORTS + +=over 4 + +=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 +hand if you like. + +=back + =head1 METHODS =over 4 @@ -76,6 +214,15 @@ MooseX::Storage - An serialization framework for Moose classes =back +=head1 TODO + +This module needs docs and probably a couple 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. + =head1 BUGS All complex software has bugs lurking in it, and this module is no diff --git a/lib/MooseX/Storage/Basic.pm b/lib/MooseX/Storage/Basic.pm index 24a39ac..38622ff 100644 --- a/lib/MooseX/Storage/Basic.pm +++ b/lib/MooseX/Storage/Basic.pm @@ -24,12 +24,37 @@ __END__ =head1 NAME -MooseX::Storage::Basic +MooseX::Storage::Basic - The simplest level of serialization =head1 SYNOPSIS + package Point; + use Moose; + use MooseX::Storage; + + with Storage; + + 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', x => 10, y => 10 } + + # unpack the hash into a class + my $p2 = Point->unpack({ __CLASS__ => 'Point', x => 10, y => 10 }); + =head1 DESCRIPTION +This is the most basic form of serialization. This is used by default +but the exported C function. + =head1 METHODS =over 4 diff --git a/lib/MooseX/Storage/Engine.pm b/lib/MooseX/Storage/Engine.pm index dd47f8c..50294c2 100644 --- a/lib/MooseX/Storage/Engine.pm +++ b/lib/MooseX/Storage/Engine.pm @@ -287,12 +287,12 @@ __END__ =head1 NAME -MooseX::Storage::Engine - -=head1 SYNOPSIS +MooseX::Storage::Engine - The meta-engine to handle collapsing and expanding objects =head1 DESCRIPTION +No user serviceable parts inside. If you really want to know, read the source :) + =head1 METHODS =head2 Accessors diff --git a/lib/MooseX/Storage/Format/JSON.pm b/lib/MooseX/Storage/Format/JSON.pm index 47d59ec..cc5544a 100644 --- a/lib/MooseX/Storage/Format/JSON.pm +++ b/lib/MooseX/Storage/Format/JSON.pm @@ -29,6 +29,29 @@ MooseX::Storage::Format::JSON =head1 SYNOPSIS + package Point; + use Moose; + use MooseX::Storage; + + with Storage('format' => 'JSON'); + + has 'x' => (is => 'rw', isa => 'Int'); + has 'y' => (is => 'rw', isa => 'Int'); + + 1; + + my $p = Point->new(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", "x" : 10, "y" : 10 } + + # unpack the JSON string into a class + my $p2 = Point->thaw('{ "__CLASS__" : "Point", "x" : 10, "y" : 10 }'); + =head1 DESCRIPTION =head1 METHODS diff --git a/lib/MooseX/Storage/Format/YAML.pm b/lib/MooseX/Storage/Format/YAML.pm index 08525e9..d7ccb06 100644 --- a/lib/MooseX/Storage/Format/YAML.pm +++ b/lib/MooseX/Storage/Format/YAML.pm @@ -32,6 +32,39 @@ MooseX::Storage::Format::YAML =head1 SYNOPSIS + package Point; + use Moose; + use MooseX::Storage; + + with Storage('format' => 'YAML'); + + has 'x' => (is => 'rw', isa => 'Int'); + has 'y' => (is => 'rw', isa => 'Int'); + + 1; + + my $p = Point->new(x => 10, y => 10); + + ## methods to freeze/thaw into + ## a specified serialization format + ## (in this case YAML) + + # pack the class into a YAML string + $p->freeze(); + + # ---- + # __CLASS__: "Point" + # x: 10 + # y: 10 + + # unpack the JSON string into a class + my $p2 = Point->thaw(< -=item B +=item B =back