<html><head><metacharset="UTF-8"><linkhref="css/default.css"rel="stylesheet"type="text/css"><scriptsrc="js/jquery.min.js"type="text/javascript"></script><scriptsrc="js/page_effects.js"type="text/javascript"></script><title>taoensso.nippy documentation</title></head><body><divid="header"><h2>Generated by <ahref="https://github.com/weavejester/codox">Codox</a></h2><h1><ahref="index.html">Nippy 2.7.0-alpha1 API documentation</a></h1></div><divclass="sidebar"id="namespaces"><h3><ahref="index.html"><spanclass="inner">Namespaces</span></a></h3><ul><liclass="depth-1"><divclass="no-link"><divclass="inner"><spanclass="tree"><spanclass="top"></span><spanclass="bottom"></span></span><span>taoensso</span></div></div></li><liclass="depth-2 current"><ahref="taoensso.nippy.html"><divclass="inner"><spanclass="tree"><spanclass="top"></span><spanclass="bottom"></span></span><span>nippy</span></div></a></li><liclass="depth-3 branch"><ahref="taoensso.nippy.benchmarks.html"><divclass="inner"><spanclass="tree"><spanclass="top"></span><spanclass="bottom"></span></span><span>benchmarks</span></div></a></li><liclass="depth-3 branch"><ahref="taoensso.nippy.compression.html"><divclass="inner"><spanclass="tree"><spanclass="top"></span><spanclass="bottom"></span></span><span>compression</span></div></a></li><liclass="depth-3 branch"><ahref="taoensso.nippy.encryption.html"><divclass="inner"><spanclass="tree"><spanclass="top"></span><spanclass="bottom"></span></span><span>encryption</span></div></a></li><liclass="depth-3 branch"><ahref="taoensso.nippy.tools.html"><divclass="inner"><spanclass="tree"><spanclass="top"></span><spanclass="bottom"></span></span><span>tools</span></div></a></li><liclass="depth-3"><ahref="taoensso.nippy.utils.html"><divclass="inner"><spanclass="tree"><spanclass="top"></span><spanclass="bottom"></span></span><span>utils</span></div></a></li></ul></div><divclass="sidebar"id="vars"><h3><ahref="#top"><spanclass="inner">Public Vars</span></a></h3><ul><liclass="depth-1"><ahref="taoensso.nippy.html#var-*final-freeze-fallback*"><divclass="inner"><span>*final-freeze-fallback*</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var--.3ECompressable-LZMA2"><divclass="inner"><span>->Compressable-LZMA2</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var--.3EStressRecord"><divclass="inner"><span>->StressRecord</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-aes128-encryptor"><divclass="inner"><span>aes128-encryptor</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-coerce-custom-type-id"><divclass="inner"><span>coerce-custom-type-id</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-custom-readers"><divclass="inner"><span>custom-readers</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-extend-freeze"><divclass="inner"><span>extend-freeze</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-extend-thaw"><divclass="inner"><span>extend-thaw</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-Freezable"><divclass="inner"><span>Freezable</span></div></a></li><liclass="depth-2"><ahref="taoensso.nippy.html#var-freeze-to-out*"><divclass="inner"><spanclass="tree"><spanclass="top"></span><spanclass="bottom"></span></span><span>freeze-to-out*</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-freezable.3F"><divclass="inner"><span>freezable?</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-freeze"><divclass="inner"><span>freeze</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-freeze-fallback-as-str"><divclass="inner"><span>freeze-fallback-as-str</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-freeze-to-out.21"><divclass="inner"><span>freeze-to-out!</span></div></a></li><liclass="depth-1"><ahref="taoensso.nippy.html#var-freeze-to-stream.21"><divclass="inner"><span>freeze-to-stream!</span><
from Deep-Freeze.</pre></div><divclass="public anchor"id="var-*final-freeze-fallback*"><h3>*final-freeze-fallback*</h3><h4class="dynamic">dynamic</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Alpha - subject to change.
</pre></div></div><divclass="public anchor"id="var--.3ECompressable-LZMA2"><h3>->Compressable-LZMA2</h3><divclass="usage"><code>(->Compressable-LZMA2 value)</code></div><divclass="doc"><preclass="plaintext">Positional factory function for class taoensso.nippy.Compressable-LZMA2.
</pre></div></div><divclass="public anchor"id="var--.3EStressRecord"><h3>->StressRecord</h3><divclass="usage"><code>(->StressRecord data)</code></div><divclass="doc"><preclass="plaintext">Positional factory function for class taoensso.nippy.StressRecord.
</pre></div></div><divclass="public anchor"id="var-aes128-encryptor"><h3>aes128-encryptor</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext">Default 128bit AES encryptor with multi-round SHA-512 key-gen.
Password form [:salted "my-password"]
---------------------------------------
USE CASE: You want more than a small, finite number of passwords (e.g. each
item encrypted will use a unique user-provided password).
IMPLEMENTATION: Uses a relatively cheap key hash, but automatically salts
every key.
PROS: Each key is independent so would need to be attacked independently.
CONS: Key caching impossible, so there's an inherent trade-off between
encryption/decryption speed and the difficulty of attacking any
particular key.
Slower than `aes128-cached`, and easier to attack any particular key - but
keys are independent.
Password form [:cached "my-password"]
---------------------------------------
USE CASE: You want only a small, finite number of passwords (e.g. a limited
number of staff/admins, or you'll be using a single password to
encrypt many items).
IMPLEMENTATION: Uses a _very_ expensive (but cached) key hash, and no salt.
PROS: Great amortized encryption/decryption speed. Expensive key hash makes
attacking any particular key very difficult.
CONS: Using a small number of keys for many encrypted items means that if any
key _is_ somehow compromised, _all_ items encrypted with that key are
compromised.
Faster than `aes128-salted`, and harder to attack any particular key - but
increased danger if a key is somehow compromised.</pre></div></div><divclass="public anchor"id="var-coerce-custom-type-id"><h3>coerce-custom-type-id</h3><divclass="usage"><code>(coerce-custom-type-id custom-type-id)</code></div><divclass="doc"><preclass="plaintext">* +ive byte id -> -ive byte id (for unprefixed custom types).
* Keyword id -> Short hash id (for prefixed custom types).</pre></div></div><divclass="public anchor"id="var-custom-readers"><h3>custom-readers</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-extend-freeze"><h3>extend-freeze</h3><h4class="type">macro</h4><divclass="usage"><code>(extend-freeze type custom-type-id [x out] & body)</code></div><divclass="doc"><preclass="plaintext">Extends Nippy to support freezing of a custom type (ideally concrete) with
given id of form:
* Keyword - 2 byte overhead, resistent to id collisions.
* Byte ∈[1, 128] - no overhead, subject to id collisions.
(extend-freeze MyType :foo/my-type [x data-output] ; Keyword id
(.writeUTF [data-output] (:data x)))
;; or
(extend-freeze MyType 1 [x data-output] ; Byte id
(.writeUTF [data-output] (:data x)))</pre></div></div><divclass="public anchor"id="var-extend-thaw"><h3>extend-thaw</h3><h4class="type">macro</h4><divclass="usage"><code>(extend-thaw custom-type-id [in] & body)</code></div><divclass="doc"><preclass="plaintext">Extends Nippy to support thawing of a custom type with given id:
(extend-thaw :foo/my-type [data-input] ; Keyword id
(->MyType (.readUTF data-input)))
;; or
(extend-thaw 1 [data-input] ; Byte id
(->MyType (.readUTF data-input)))</pre></div></div><divclass="public anchor"id="var-Freezable"><h3>Freezable</h3><h4class="type">protocol</h4><divclass="usage"></div><divclass="doc"><preclass="plaintext">Be careful about extending to interfaces, Ref. <ahref="http://goo.gl/6gGRlU">http://goo.gl/6gGRlU</a>.
</pre></div><divclass="members"><h4>members</h4><divclass="inner"><divclass="public anchor"id="var-freeze-to-out*"><h3>freeze-to-out*</h3><divclass="usage"><code>(freeze-to-out* this out)</code></div><divclass="doc"><preclass="plaintext"></pre></div></div></div></div></div><divclass="public anchor"id="var-freezable.3F"><h3>freezable?</h3><divclass="usage"><code>(freezable? x & [{:keys [allow-clojure-reader? allow-java-serializable?]}])</code></div><divclass="doc"><preclass="plaintext">Alpha - subject to change, may be buggy!
**moderately reliable** since they're cached by arg type and don't test for
pre/post serialization equality (there's no good general way of doing so).</pre></div></div><divclass="public anchor"id="var-freeze"><h3>freeze</h3><divclass="usage"><code>(freeze x & [{:keys [compressor encryptor password skip-header?], :or {compressor lz4-compressor, encryptor aes128-encryptor}, :as opts}])</code></div><divclass="doc"><preclass="plaintext">Serializes arg (any Clojure data type) to a byte array. To freeze custom
types, extend the Clojure reader or see `extend-freeze`.</pre></div></div><divclass="public anchor"id="var-freeze-fallback-as-str"><h3>freeze-fallback-as-str</h3><divclass="usage"><code>(freeze-fallback-as-str x out)</code></div><divclass="doc"><preclass="plaintext">Alpha-subject to change.
</pre></div></div><divclass="public anchor"id="var-freeze-to-out.21"><h3>freeze-to-out!</h3><divclass="usage"><code>(freeze-to-out! data-output x & _)</code></div><divclass="doc"><preclass="plaintext">Low-level API. Serializes arg (any Clojure data type) to a DataOutput.
</pre></div></div><divclass="public anchor"id="var-freeze-to-stream.21"><h3>freeze-to-stream!</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext">DEPRECATED: Use `freeze-to-out!` instead.
A good general-purpose compressor, competitive with Snappy.
Thanks to Max Penet (@mpenet) for our first implementation,
Ref. <ahref="https://github.com/mpenet/nippy-lz4">https://github.com/mpenet/nippy-lz4</a></pre></div></div><divclass="public anchor"id="var-lz4hc-compressor"><h3>lz4hc-compressor</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext">Like `lz4-compressor` but trades some write speed for ratio.
Write speed: _very_ slow (also currently single-threaded).
Read speed: slow.
A specialized compressor for large, low-write data in space-sensitive
environments.</pre></div></div><divclass="public anchor"id="var-map-.3ECompressable-LZMA2"><h3>map->Compressable-LZMA2</h3><divclass="usage"><code>(map->Compressable-LZMA2 m__5869__auto__)</code></div><divclass="doc"><preclass="plaintext">Factory function for class taoensso.nippy.Compressable-LZMA2, taking a map of keywords to field values.
</pre></div></div><divclass="public anchor"id="var-map-.3EStressRecord"><h3>map->StressRecord</h3><divclass="usage"><code>(map->StressRecord m__5869__auto__)</code></div><divclass="doc"><preclass="plaintext">Factory function for class taoensso.nippy.StressRecord, taking a map of keywords to field values.
</pre></div></div><divclass="public anchor"id="var-read-biginteger"><h3>read-biginteger</h3><h4class="type">macro</h4><divclass="usage"><code>(read-biginteger in)</code></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-read-bytes"><h3>read-bytes</h3><h4class="type">macro</h4><divclass="usage"><code>(read-bytes in & [small?])</code></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-read-compact-long"><h3>read-compact-long</h3><h4class="type">macro</h4><divclass="usage"><code>(read-compact-long in)</code></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-read-utf8"><h3>read-utf8</h3><h4class="type">macro</h4><divclass="usage"><code>(read-utf8 in & [small?])</code></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-snappy-compressor"><h3>snappy-compressor</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext">Default org.iq80.snappy.Snappy compressor:
Ratio: low.
Write speed: very high.
Read speed: very high.
A good general-purpose compressor.</pre></div></div><divclass="public anchor"id="var-stress-data"><h3>stress-data</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext">Reference data used for tests & benchmarks.
</pre></div></div><divclass="public anchor"id="var-stress-data-benchable"><h3>stress-data-benchable</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext">Reference data with stuff removed that breaks reader or other utils we'll
be benching against.</pre></div></div><divclass="public anchor"id="var-stress-data-comparable"><h3>stress-data-comparable</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext">Reference data with stuff removed that breaks roundtrip equality.
</pre></div></div><divclass="public anchor"id="var-thaw"><h3>thaw</h3><divclass="usage"><code>(thaw ba & [{:keys [compressor encryptor password], :or {compressor :auto, encryptor :auto}, :as opts}])</code></div><divclass="doc"><preclass="plaintext">Deserializes a frozen object from given byte array to its original Clojure
data type. Supports data frozen with current and all previous versions of
Nippy. To thaw custom types, extend the Clojure reader or see `extend-thaw`.
Options include:
:compressor - An ICompressor, :auto (requires Nippy header), or nil.
:encryptor - An IEncryptor, :auto (requires Nippy header), or nil.</pre></div></div><divclass="public anchor"id="var-thaw-from-in.21"><h3>thaw-from-in!</h3><divclass="usage"><code>(thaw-from-in! data-input & _)</code></div><divclass="doc"><preclass="plaintext">Low-level API. Deserializes a frozen object from given DataInput to its
original Clojure data type.</pre></div></div><divclass="public anchor"id="var-thaw-from-stream.21"><h3>thaw-from-stream!</h3><divclass="usage"></div><divclass="doc"><preclass="plaintext">DEPRECATED: Use `thaw-from-in!` instead.
</pre></div></div><divclass="public anchor"id="var-when-debug-mode"><h3>when-debug-mode</h3><h4class="type">macro</h4><divclass="usage"><code>(when-debug-mode & body)</code></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-write-biginteger"><h3>write-biginteger</h3><h4class="type">macro</h4><divclass="usage"><code>(write-biginteger out x)</code></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-write-bytes"><h3>write-bytes</h3><h4class="type">macro</h4><divclass="usage"><code>(write-bytes out ba & [small?])</code></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-write-compact-long"><h3>write-compact-long</h3><h4class="type">macro</h4><divclass="usage"><code>(write-compact-long out x)</code></div><divclass="doc"><preclass="plaintext">Uses 2->9 bytes.
</pre></div></div><divclass="public anchor"id="var-write-id"><h3>write-id</h3><h4class="type">macro</h4><divclass="usage"><code>(write-id out id)</code></div><divclass="doc"><preclass="plaintext"></pre></div></div><divclass="public anchor"id="var-write-utf8"><h3>write-utf8</h3><h4class="type">macro</h4><divclass="usage"><code>(write-utf8 out x & [small?])</code></div><divclass="doc"><preclass="plaintext"></pre></div></div></div></body></html>
