21 Persistent Values: Pickle

# 21 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.