NAME

       Class::Std::Storable - Support for creating serializable "inside-out" classes

VERSION

       This document describes Class::Std::Storable version 0.0.1

SYNOPSIS

       In general, use this class exactly as you would Class::Std.

           package Ice::Cream;
           use Class::Std::Storable;
           {
               my %name_of :ATTR( :get<name> :set<name> );
               my %flavor_of :ATTR( :get<flavor> :set<flavor> );
           }

           package main;
           my $object = Ice::Cream->new;
           $object->set_name("Vanilla Bean");
           $object->set_flavor("vanilla");

       But now, you may also serialize the object with Storable.

           use Storable;
           my $serialized = Storable::freeze($object);
           #store to a file, database, or wherever, and retrieve later.
           my $clone = Storable::thaw($serialized);

DESCRIPTION

       Class::Std introduced the "inside-out" model for classes (perldoc Class::Std for details).
       Among its salient features is complete encapsulation; that is, an object's data may only
       be accessed via its methods, unlike the usual hashref model that permits direct access by
       any code whatsoever.  However, the drawback of complete encapsulation is that normal
       mechanisms for serialization won't work, as they rely on direct access to an object's
       attributes.

       This class provides the class-building functionality from Class::Std, and in addition
       provides an interface to allow Storable to freeze and thaw any declared attributes of this
       class and any superclasses that were built via Class::Std::Storable.

       However, in order to let Storable save attributes and construct the object, it is
       necessary to expose the attributes of the class to the world.  Thus, any code could use
       the same interface that Storable does to get a copy of object attributes and create new
       objects with arbitrary attributes without going through the constructor.  While the
       interface CAN'T be used to replace the existing attributes of an object, it COULD be used
       to create an arbitrarily mutated clone of an object without going through its methods.
       Also, if attributes are themselves references, then the objects to which they refer can be
       obtained and modified.

       As true encapsulation is one of the major features of Class::Std, this would be a good
       reason NOT to use this class.  But this sacrifice is required to provide serialization.
       You must choose which is more important for your purposes, serialization or complete
       encapsulation.  Consider also that while bypassing the class methods is possible to a
       limited degree with Class::Std::Storable, doing so is much more complicated than just
       using the methods, so use of this class still discourages casual violations of
       encapsulation.

INTERFACE

       See Class::Std

       This package provides object methods STORABLE_freeze and STORABLE_thaw which are not
       intended to be used directly or overridden.

       A class generated using Class::Std::Storable may provide hooks to be called when a freeze
       or a thaw is performed.  These methods will be called if provided:

       $obj->STORABLE_freeze_pre($cloning)
           Called against the object at the very beginning of a freeze.  First parameter is
           Storable's "cloning" flag -- see Storable.  This method could be used, for example, to
           adjust or remove non-serializable attributes.

       $obj->STORABLE_freeze_post($cloning, $param_ref)
           Called against the object after the parameters for the freeze have been determined,
           but before actual serialization.  First parameter is Storable's "cloning" flag -- see
           Storable.  Second parameter is a reference to a hash of hashes of parameters to be
           frozen, where the first level hash is keyed on the package name of the class, and the
           second level is keyed on the declared parameters of that class.  E.g.:

               $param_ref = {
                   'Base::Class' => {
                       flavor  => "vanilla",
                       name  => "Vanilla Bean",
                   },
                   'Sub::Class' => {
                       name => "Shiny Wax",
                       price => '$0.02',
                   },
               };

           This hook could be used to adjust the attributes that are about to be frozen for its
           class.  It is probably unwise to adjust the attributes of other classes or to add new
           top-level hash entries.  This hook could also be used to undo any changes that were
           necessary in STORABLE_freeze_pre.

       $obj->STORABLE_thaw_pre($cloning, $param_ref)
           Called against the object at the very beginning of a thaw.  First parameter is
           Storable's "cloning" flag -- see Storable.  Second parameter is the same parameter
           hash described for the previous method, which will be used to reconstruct the object.

           This method could be used for validation, or to reconstruct attributes that couldn't
           be serialized.

       $obj->STORABLE_thaw_post($cloning)
           Called against the object when a thaw is otherwise complete.  First parameter is
           Storable's "cloning" flag -- see Storable.  This method could be used for validation,
           to reconstruct attributes that couldn't be serialized, or to adjust class data.

       It would undoubtedly be a good idea to mark these methods :CUMULATIVE if provided, so that
       base classes can perform their own hooks.  Also, these methods can not be provided via
       AUTOLOAD.

DIAGNOSTICS

       See Class::Std for its diagnostics.  Only the following are particular to
       Class::Std::Storable.  All are exceptions thrown with Carp::croak.

       "unknown attribute(s) seen while thawing"
           This indicates that when STORABLE_thaw tried to thaw an object, it found that the
           frozen object had an attribute that is not declared in the class.

           This could mean the class definition changed, removing or renaming attributes, between
           the freezing and thawing of the object.

           It could also mean that the STORABLE_freeze_post hook was used to insert an unknown
           key into the freezing hash for this class.  Remove such additions in the
           STORABLE_thaw_pre hook (before the thawing gets under way).

       "unknown base class '$package' seen while thawing"
           This means that when thawing an object, its frozen hash representation included an
           entry that is neither the class or a base class.  While this could mean that class
           names changed between freezing and thawing the object (don't do that), a more likely
           explanation is that a STORABLE_freeze_post hook inserted an unknown key into the top
           level of the freezing hash (don't do that either).

       "trying to modify existing attributes for $package"
           This probably means that some code is calling STORABLE_thaw directly on an existing
           object in an attempt to fiddle with its attributes.  Don't even think about doing
           that.

           The other explanation would be that the STORABLE_thaw_pre hook set an attribute for
           the object but left that attribute in the frozen hash to be thawed later.
           STORABLE_thaw_pre should delete from the frozen hash any attributes that it sets
           itself.

CONFIGURATION AND ENVIRONMENT

       Class::Std::Storable requires no configuration files or environment variables.

DEPENDENCIES

       Class::Std version 0.0.4 or newer, which is not at this time part of the Perl core
       modules.  This module depends on a small set of Class::Std internals staying largely the
       same and could break if that assumption proves false.

INCOMPATIBILITIES

       None reported.

LIMITATIONS

       Vanilla Class::Std objects are not themselves serializable.  Any base classes that are not
       built using Class::Std::Storable will probably not serialize correctly without special
       tricks.  This is a feature, as it means no one can just subclass a Class::Std class and
       break its encapsulation.

       Class::Std::Storable works fine with nested structures and correctly persists multiple
       references to the same object, as long as all references are contained in a single
       serialization.

       Class::Std::Storable has never been tested for thread safety, so no guarantees there.

       Class::Std::Storable attempts to identify attributes by their declaration, that is,
       according to how :ATTR declares their getters/setters/initializers.  If none of these are
       declared for an attribute, it can only be identified by its position, that is, the order
       of its appearance in the source code.  This scheme will break if you change the position
       of these nameless attributes, or change the names of the named ones, between the freezing
       and the thawing of an object.

       Serialization of inside-out objects naturally maintains the same caveats as for any other
       object.  Only declared (:ATTR) object attributes identified with the object will be
       serialized with the object.  In particular, "class data" won't be serialized with the
       object.  Also, an object can't be serialized if any of its attributes cannot themselves be
       serialized, e.g. if one is a closure.

BUGS

       No bugs have been reported.

       Please report any bugs or feature requests to "bug-class-std-storable@rt.cpan.org", or
       through the web interface at <http://rt.cpan.org>.

AUTHOR

       Luke Meyer  "<luke@daeron.com>"

LICENCE AND COPYRIGHT

       Copyright (c) 2005, Luke Meyer. All rights reserved.

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

DISCLAIMER OF WARRANTY

       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE,
       TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
       COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF
       ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
       THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE
       DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT
       HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY
       THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
       INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
       LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY
       OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
       SUCH DAMAGES.