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

FreeBSD Manual Pages

  
 
  

home | help
Bio::Root::Storable(3)User Contributed Perl DocumentatioBio::Root::Storable(3)

NAME
       Bio::Root::Storable - Safely store/retrieve objects from	disk

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

AUTHOR Will Spooner
   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	normally 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   :

perl v5.32.1			  2019-12-07		Bio::Root::Storable(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR Will Spooner

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

home | help