22 Persistent Values: Pickle

The Pickle module provides procedures to store and retrieve stateless values on persistent storage.

save

{Pickle.save +X +PathV}

Stores X in a file named PathV.

Note that X can be any stateless value. So it is possible to save for example records, procedures or classes. However an exception is raised if for example X contains an object or a logic variable.

saveCompressed

{Pickle.saveCompressed X +PathV +LevelI}

Works like save but additionally compresses its output. LevelI is an integer between 0 and 9 specifying the compression level: the higher the value the better the compression factor, but the longer compression takes. A value of 0 gives no compression, so {Pickle.save X Value} is equivalent to {Pickle.saveCompressed X Value 0}.

Compression time and ratio depend on the type of input. The compression ratio might vary between 20 and 80 percent, while compression at level 9 is usually less than 2 times slower than using no compression.

saveWithHeader

{Pickle.saveWithHeader X +PathV +HeaderV +LevelI}

This procedure is a generalization of the above builtins. It saves X in file +PathV with compression level +LevelI and additionally prepends the virtual string HeaderV at the beginning. So HeaderV can be used for example to prepend a comment in front of the pickle or to prepend a shell startup script to load and execute the pickle.

loadWithHeader

{Pickle.loadWithHeader +UrlV ?Pair}

This procedure retrieves a value from URL UrlV that has been previously saved with one of the above procedures. It returns a pair HeaderV#Value, where HeaderV is the (possibly empty) header and Value the value that was retrieved.

load

{Pickle.load +UrlV ?Value}

This is just a shortcut for

{Pickle.loadWithHeader UrlV _#Value}

pack

{Pickle.pack +X ?ByteString}

Takes a value X and pickles it to a bytestring.

unpack

{Pickle.unpack +PickleV ?Value}

Unpacks a virtual string PickleV that has created by pickling (e.g., by Pickle.pack).

Pickle.unpack may crash the Oz Engine if given a corrupt pickle.