Bio::R...torable(3pm)

💾 NAME 💾

Bio::Root::Storable — safely store your objects on disk and pull them back out again. It's giving persistence, bestie. ✨

(This one's from the User Contributed Perl Documentation pages, and it's a 3pm module page, iykyk.)

---

✨ 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 🌸

Okay so. This is a generic module that lets objects get safely stored to disk and retrieved back off disk. Any BioPerl object can inherit from it. 💅

One lil thing though: it usually won't be the first class in the inheritance list, so you should call _initialise_storable() while the object is being instantiated. Don't skip that part, fr fr.

Object storage here is recursive. The way that works: if the object you're storing contains other storable objects, those get stored separately, and in the parent hierarchy they get swapped out for a skeleton object. Later, when the parent gets retrieved, its children stay in that skeleton state until the parent explicitly retrieves them. This lazy-retrieve thing is highkey iconic for memory efficiency in certain applications. 👑

By default, objects are stored in binary format — that's the Perl Storable module doing the heavy lifting. But heads up: earlier versions of Perl5 don't ship Storable as a core module. If you're on one of those, ASCII object storage kicks in instead, using the Perl Data::Dumper module.

You can also make ASCII storage the default on purpose: just set the value of $Bio::Root::Storable::BINARY to false. 🎀

---

👑 AUTHOR 👑

Will Spooner

---

🔧 METHODS 🔧

new

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

_initialise_storable

• Arg [1]: See 'new' method
• Function: Initialises storable-specific attributes
• Returntype: boolean
• Exceptions: (none listed)
• Caller: (none listed)
• Example: (none listed)

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: (none listed)
• 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: (none listed)
• Caller: (none listed)
• Example: $obj->workdir('/tmp/foo');

template

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

suffix

• Arg [1]: string (optional)
• Function: Accessor for the statefile template.
• Returntype: string
• Exceptions: (none listed)
• Caller: (none listed)
• 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 inheriting object
• Exceptions: (none listed)
• Caller: (none listed)
• 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: (none listed)
• Caller: (none listed)
• 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: (none listed)
• Caller: (none listed)
• 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: (none listed)
• Caller: (none listed)
• 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: (none listed)
• Caller: (none listed)
• 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 inheriting object
• Exceptions: (none listed)
• Caller: (none listed)
• Example: my $obj = Bio::Root::Storable->retrieve( $token );

Not me pointing out that the original sentence literally stops at "and not the" 💀 — I'm keeping it exactly as written because I am not about to invent the ending for you. Facts stay facts, bestie.

clone

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

remove

• Arg [1]: none
• Function: Clears the stored object from disk
• Returntype: boolean
• Exceptions: (none listed)
• Caller: (none listed)
• 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: (none listed)
• Exceptions: (none listed)
• Caller: (none listed)
• Example: (none listed)

_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! Like, genuinely. Do not freestyle this one. 🙈

• Returntype: variable
• Exceptions: (none listed)
• Caller: (none listed)
• Example: (none listed)

---

And that's the whole page, no notes. This was perl v5.32.1, dated 2021-08-15, from the User Contributed Perl Documentation — so if you're reading this way later than that, iykyk and go check for a newer one. Byee, go store some objects safely 🦋💖