Provided by: libbio-perl-perl_1.6.923-1_all bug

NAME

       Bio::Root::Storable - object serialisation methods

SYNOPSIS

         my $storable = Bio::Root::Storable->new();

         # Store/retrieve using class retriever
         my $token     = $storable->store();
         my $storable2 = Bio::Root::Storable->retrieve( $token );

         # Store/retrieve using object retriever
         my $storable2 = $storable->new_retrievable();
         $storable2->retrieve();

DESCRIPTION

       Generic module that allows objects to be safely stored/retrieved from disk.  Can be
       inhereted by any BioPerl object. As it will not usually be the first class in the
       inheretence list, _initialise_storable() should be called during object instantiation.

       Object storage is recursive; If the object being stored contains other storable objects,
       these will be stored separately, and replaced by a skeleton object in the parent
       heirarchy. When the parent is later retrieved, its children remain in the skeleton state
       until explicitly retrieved by the parent. This lazy-retrieve approach has obvious memory
       efficiency benefits for certain applications.

       By default, objects are stored in binary format (using the Perl Storable module). Earlier
       versions of Perl5 do not include Storable as a core module. If this is the case, ASCII
       object storage (using the Perl Data::Dumper module) is used instead.

       ASCII storage can be enabled by default by setting the value of
       $Bio::Root::Storable::BINARY to false.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists.  Your
       participation is much appreciated.

         bioperl-l@bio.perl.org

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Will Spooner

       Email whs@sanger.ac.uk

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   new
         Arg [1]   : -workdir  => filesystem path,
                     -template => tmpfile template,
                     -suffix   => tmpfile suffix,
         Function  : Builds a new Bio::Root::Storable inhereting object
         Returntype: Bio::Root::Storable inhereting object
         Exceptions:
         Caller    :
         Example   : $storable = Bio::Root::Storable->new()

   _initialise_storable
         Arg [1]   : See 'new' method
         Function  : Initialises storable-specific attributes
         Returntype: boolean
         Exceptions:
         Caller    :
         Example   :

   statefile
         Arg [1]   : string (optional)
         Function  : Accessor for the file to write state into.
                     Should not normaly use as a setter - let Root::IO
                     do this for you.
         Returntype: string
         Exceptions:
         Caller    : Bio::Root::Storable->store
         Example   : my $statefile = $obj->statefile();

   workdir
         Arg [1]   : string (optional) (TODO - convert to array for x-platform)
         Function  : Accessor for the statefile directory. Defaults to File::Spec->tmpdir
         Returntype: string
         Exceptions:
         Caller    :
         Example   : $obj->workdir('/tmp/foo');

   template
         Arg [1]   : string (optional)
         Function  : Accessor for the statefile template. Defaults to XXXXXXXX
         Returntype: string
         Exceptions:
         Caller    :
         Example   : $obj->workdir('RES_XXXXXXXX');

   suffix
         Arg [1]   : string (optional)
         Function  : Accessor for the statefile template.
         Returntype: string
         Exceptions:
         Caller    :
         Example   : $obj->suffix('.state');

   new_retrievable
         Arg [1]   : Same as for 'new'
         Function  : Similar to store, except returns a 'skeleton' of the calling
                     object, rather than the statefile.
                     The skeleton can be repopulated by calling 'retrieve'. This
                     will be a clone of the original object.
         Returntype: Bio::Root::Storable inhereting object
         Exceptions:
         Caller    :
         Example   : my $skel = $obj->new_retrievable(); # skeleton
                     $skel->retrieve();                  # clone

   retrievable
         Arg [1]   : none
         Function  : Reports whether the object is in 'skeleton' state, and the
                     'retrieve' method can be called.
         Returntype: boolean
         Exceptions:
         Caller    :
         Example   : if( $obj->retrievable ){ $obj->retrieve }

   token
         Arg [1]   : None
         Function  : Accessor for token attribute
         Returntype: string. Whatever retrieve needs to retrieve.
                     This base implementation returns the statefile
         Exceptions:
         Caller    :
         Example   : my $token = $obj->token();

   store
         Arg [1]   : none
         Function  : Saves a serialised representation of the object structure
                     to disk. Returns the name of the file that the object was
                     saved to.
         Returntype: string

         Exceptions:
         Caller    :
         Example   : my $token = $obj->store();

   serialise
         Arg [1]   : none
         Function  : Prepares the the serialised representation of the object.
                     Object attribute names starting with '__' are skipped.
                     This is useful for those that do not serialise too well
                     (e.g. filehandles).
                     Attributes are examined for other storable objects. If these
                     are found they are serialised separately using 'new_retrievable'
         Returntype: string
         Exceptions:
         Caller    :
         Example   : my $serialised = $obj->serialise();

   retrieve
         Arg [1]   : string; filesystem location of the state file to be retrieved
         Function  : Retrieves a stored object from disk.
                     Note that the retrieved object will be blessed into its original
                     class, and not the
         Returntype: Bio::Root::Storable inhereting object
         Exceptions:
         Caller    :
         Example   : my $obj = Bio::Root::Storable->retrieve( $token );

   clone
         Arg [1]   : none
         Function  : Returns a clone of the calling object
         Returntype: Bio::Root::Storable inhereting object
         Exceptions:
         Caller    :
         Example   : my $clone = $obj->clone();

   remove
         Arg [1]   : none
         Function  : Clears the stored object from disk
         Returntype: boolean
         Exceptions:
         Caller    :
         Example   : $obj->remove();

   _freeze
         Arg [1]   : variable
         Function  : Converts whatever is in the the arg into a string.
                     Uses either Storable::freeze or Data::Dumper::Dump
                     depending on the value of $Bio::Root::BINARY
         Returntype:
         Exceptions:
         Caller    :
         Example   :

   _thaw
         Arg [1]   : string
         Function  : Converts the string into a perl 'whatever'.
                     Uses either Storable::thaw or eval depending on the
                     value of $Bio::Root::BINARY.
                     Note; the string arg should have been created with
                     the _freeze method, or strange things may occur!
         Returntype: variable
         Exceptions:
         Caller    :
         Example   :