Storable

📦 std

Serialise arbitrary Perl data structures to bytes, reconstruct them later, or deep-clone them in memory.

Storable turns a reference — to a scalar, array, hash, blessed object, or any tree built from them — into an opaque byte string that can be written to disk, sent over a socket, or fed back into the module to reproduce the original structure. The round trip preserves shared references, circular references, weak references, tied variables, regexp objects, and blessed classes (with STORABLE_freeze / STORABLE_thaw hooks honoured).

Two axes of choice cover every use:

• Where the bytes go. freeze returns them as a string, store writes them to a named file, store_fd writes them to an open filehandle. thaw, retrieve, and fd_retrieve are the matching readers.

• Byte order on the wire. freeze / store / store_fd use the host’s native byte order — fastest, but only portable between machines of the same endianness and integer size. The n-prefixed variants nfreeze, nstore, nstore_fd use network (big-endian) order and are portable across architectures. The reader side auto-detects which was used.

dclone is the in-memory shortcut for “I want a structurally independent copy of this data.” It serialises and immediately deserialises, so every element is freshly allocated and every STORABLE_freeze / STORABLE_thaw hook runs — which is the only safe way to clone objects that wrap non-SV resources (a PDL’s engine pointer, a tied variable’s backing state, a file handle).

file_magic and read_magic inspect a frozen payload without thawing it, returning a hash describing byte order, header size, and version metadata. Use them to validate untrusted input or to pick a reader before committing to a thaw.

Functions

Freeze and thaw

freeze

Serialise a referenced Perl structure into an opaque byte string using the host’s native byte order.

nfreeze

Serialise a referenced Perl structure to bytes in network (big-endian) byte order for portable transport.

thaw

Reconstruct a Perl structure from a byte string produced by freeze or nfreeze.

File persistence

store

Serialise a referenced structure and write it to a named file, overwriting any previous contents.

nstore

Serialise a referenced structure in network byte order and write it to a named file.

retrieve

Read a frozen structure from a named file and reconstruct it.

File-descriptor persistence

store_fd

Serialise a referenced structure in native byte order and write it to an open filehandle.

nstore_fd

Serialise a referenced structure in network byte order and write it to an open filehandle.

fd_retrieve

Read one frozen structure from an open filehandle and reconstruct it.

Deep cloning

dclone

Produce a structurally independent deep copy of a Perl structure by round-tripping it through the serialiser.

Magic inspection

file_magic

Inspect a file’s Storable header without thawing, returning metadata as a hash reference.

read_magic

Inspect an in-memory frozen buffer’s header, returning metadata as a hash reference.

Tuning

stack_depth

Return the current scalar recursion limit used while freezing and thawing.

stack_depth_hash

Return the current hash-specific recursion limit used while freezing and thawing.