PApp::Storable 1.2

Storable module is a persistence for Perl data structures.

SYNOPSIS

use Storable;
store %table, file;
$hashref = retrieve(file);

use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);

# Network order
nstore %table, file;
$hashref = retrieve(file); # There is NO nretrieve()

# Storing to and retrieving from an already opened file
store_fd @array, *STDOUT;
nstore_fd %table, *STDOUT;
$aryref = fd_retrieve(*SOCKET);
$hashref = fd_retrieve(*SOCKET);

# Serializing to memory
$serialized = freeze %table;
%table_clone = %{ thaw($serialized) };

# Deep (recursive) cloning
$cloneref = dclone($ref);

# Advisory locking
use Storable qw(lock_store lock_nstore lock_retrieve)
lock_store %table, file;
lock_nstore %table, file;
$hashref = lock_retrieve(file);

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 arent 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 youre going to retrieve and for write if you wish to store.

store_fd(%table, *STDOUT) || die "cant store to stdoutn";
$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 dont have to know whether youre 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 youre 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, youd get a reference to that blessed object).