The Storable package brings persistence to your Perl data structures
containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be
conveniently stored to disk and retrieved at a later time.

It can be used in the regular procedural way by calling 'store' with a
reference to the object to be stored, along with the file name where the
image should be written.

The routine returns 'undef' for I/O problems or other internal error, a
true value otherwise. Serious errors are propagated as a 'die' exception.

To retrieve data stored to disk, use 'retrieve' with a file name. The
objects stored into that file are recreated into memory for you, and a
_reference_ to the root object is returned. In case an I/O error occurs
while reading, 'undef' is returned instead. Other serious errors are
propagated via 'die'.

Since storage is performed recursively, you might want to stuff references
to objects that share a lot of common data into a single array or hash
table, and then store that object. That way, when you retrieve back the
whole thing, the objects will continue to share what they originally
shared.

At the cost of a slight header overhead, you may store to an already opened
file descriptor using the 'store_fd' routine, and retrieve from a file via
'fd_retrieve'. Those names aren't imported by default, so you will have to
do that explicitly if you need those routines. The file descriptor you
supply must be already opened, for read if you're going to retrieve and for
write if you wish to store.

store_fd(\%table, *STDOUT) || die "can't store to stdout\n";
$hashref = fd_retrieve(*STDIN);

You can also store data in network order to allow easy sharing across
multiple platforms, or when storing on a socket known to be remotely
connected. The routines to call have an initial 'n' prefix for _network_,
as in 'nstore' and 'nstore_fd'. At retrieval time, your data will be
correctly restored so you don't have to know whether you're restoring from
native or network ordered data. Double values are stored stringified to
ensure portability as well, at the slight risk of loosing some precision in
the last decimals.

When using 'fd_retrieve', objects are retrieved in sequence, one object
(i.e. one recursive tree) per associated 'store_fd'.

If you're more from the object-oriented camp, you can inherit from Storable
and directly store your objects by invoking 'store' as a method. The fact
that the root of the to-be-stored tree is a blessed reference (i.e. an
object) is special-cased so that the retrieve does not provide a reference
to that object but rather the blessed object reference itself. (Otherwise,
you'd get a reference to that blessed object).