# 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`](Storable/freeze.md) Serialise a referenced Perl structure into an opaque byte string using the host’s native byte order. #### [`nfreeze`](Storable/nfreeze.md) Serialise a referenced Perl structure to bytes in network (big-endian) byte order for portable transport. #### [`thaw`](Storable/thaw.md) Reconstruct a Perl structure from a byte string produced by `freeze` or `nfreeze`. ### File persistence #### [`store`](Storable/store.md) Serialise a referenced structure and write it to a named file, overwriting any previous contents. #### [`nstore`](Storable/nstore.md) Serialise a referenced structure in network byte order and write it to a named file. #### [`retrieve`](Storable/retrieve.md) Read a frozen structure from a named file and reconstruct it. ### File-descriptor persistence #### [`store_fd`](Storable/store_fd.md) Serialise a referenced structure in native byte order and write it to an open filehandle. #### [`nstore_fd`](Storable/nstore_fd.md) Serialise a referenced structure in network byte order and write it to an open filehandle. #### [`fd_retrieve`](Storable/fd_retrieve.md) Read one frozen structure from an open filehandle and reconstruct it. ### Deep cloning #### [`dclone`](Storable/dclone.md) Produce a structurally independent deep copy of a Perl structure by round-tripping it through the serialiser. ### Magic inspection #### [`file_magic`](Storable/file_magic.md) Inspect a file’s Storable header without thawing, returning metadata as a hash reference. #### [`read_magic`](Storable/read_magic.md) Inspect an in-memory frozen buffer’s header, returning metadata as a hash reference. ### Tuning #### [`stack_depth`](Storable/stack_depth.md) Return the current scalar recursion limit used while freezing and thawing. #### [`stack_depth_hash`](Storable/stack_depth_hash.md) Return the current hash-specific recursion limit used while freezing and thawing.