Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MooseX::Storage(3)    User Contributed Perl Documentation   MooseX::Storage(3)

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

VERSION
       version 0.53

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 three 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 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"	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:

       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 for details.

       DisableCycleDetection
	   Disables the	default	checks for circular references,	which is
	   necessary if	you use	such references	in your	serialisable objects.

	   See MooseX::Storage::Traits::DisableCycleDetection for details.

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

       DoNotSerialize
	   Skip	serialization entirely for this	attribute.

	   See MooseX::Storage::Meta::Attribute::Trait::DoNotSerialize 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)	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.

SUPPORT
       Bugs may	be submitted through the RT bug	tracker
       <https://rt.cpan.org/Public/Dist/Display.html?Name=MooseX-Storage> (or
       bug-MooseX-Storage@rt.cpan.org <mailto:bug-MooseX-
       Storage@rt.cpan.org>).

       There is	also a mailing list available for users	of this	distribution,
       at <http://lists.perl.org/list/moose.html>.

       There is	also an	irc channel available for users	of this	distribution,
       at "#moose" on "irc.perl.org" <irc://irc.perl.org/#moose>.

AUTHORS
       o   Chris Prather <chris.prather@iinteractive.com>

       o   Stevan Little <stevan.little@iinteractive.com>

       o   xxxx	x<section>xx'xx	(Yuval Kogman) <nothingmuch@woobling.org>

CONTRIBUTORS
       o   Karen Etheridge <ether@cpan.org>

       o   Tomas Doran <bobtfish@bobtfish.net>

       o   Ricardo Signes <rjbs@cpan.org>

       o   Chris Prather <chris@prather.org>

       o   Jos Boumans <jos@dwim.org>

       o   Shawn M Moore <sartak@gmail.com>

       o   Jonathan Yu <frequency@cpan.org>

       o   Dmitry Latin	<dim0xff@gmail.com>

       o   Robert Boone	<robo4288@gmail.com>

       o   Dagfinn Ilmari MannsAYker <ilmari@ilmari.org>

       o   Cory	Watson <gphat@Crankwizzah.local>

       o   sillitoe <ian@sillit.com>

       o   Dan Brook <dan@broquaint.com>

       o   David Golden	<dagolden@cpan.org>

       o   David Steinbrunner <dsteinbrunner@pobox.com>

       o   Florian Ragwitz <rafl@debian.org>

       o   Graham Knop <haarg@haarg.org>

       o   Jason Pope <cowholio4@gmail.com>

       o   Johannes Plunien <plu@pqpq.de>

       o   Jonathan Rockway <jon@jrock.us>

       o   Yanick Champoux <yanick@babyl.dyndns.org>

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.

perl v5.32.1			  2020-04-18		    MooseX::Storage(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CAVEAT | EXPORTS | METHODS | TODO | SUPPORT | AUTHORS | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MooseX::Storage&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help