Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

MooseX::Storage(3)                   User Contributed Perl Documentation                  MooseX::Storage(3)



NAME
       MooseX::Storage - A serialization framework for Moose classes

SYNOPSIS
         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
         ## 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 minumum that MooseX::Storage provides and all other
           levels build on top of this.

           See 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 (ie, where the predicate returns 'true') will be serialized.
           This avoids any potentially expensive computations.

           See 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 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.

   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 reassemble
       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) 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 <chris.prather@iinteractive.com>

       Stevan Little <stevan.little@iinteractive.com>

       Yuval Kogman <yuval.kogman@iinteractive.com>

COPYRIGHT AND LICENSE
       Copyright 2007-2008 by Infinity Interactive, Inc.

       <http://www.iinteractive.com>

       This library is free software; you can redistribute it and/or modify it under the same terms as Perl
       itself.



perl v5.16.2                                     2012-02-28                               MooseX::Storage(3)