The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
ETHER / MooseX-Storage-0.46 / README.md

NAME

MooseX::Storage - A serialization framework for Moose classes

VERSION

version 0.46

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.

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.

Behaviour modifiers

The serialization behaviour can be changed by supplying traits to either the class or an individual attribute.

This can be done as follows:

use MooseX::Storage;

# adjust behaviour for the entire class
with Storage( traits => [Trait1, Trait2,...] );

# adjust behaviour for an attribute
has my_attr => (
  traits => [Trait1, Trait2, ...],
  ...
);

The following class traits are currently bundled with MooseX::Storage:

The following attribute traits are currently bundled with MooseX::Storage:

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

METHODS

Introspection

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.

AUTHORS

COPYRIGHT AND LICENSE

This software is copyright (c) 2007 by Infinity Interactive, Inc..

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

CONTRIBUTORS