luciano/nippy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'dev'

Browse source
This commit is contained in:
Peter Taoussanis 2016-01-23 11:46:56 +07:00
commit b7dd32b3d2
4 changed files with 80 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
CHANGELOG.md
View file

@ -1,5 +1,14 @@
> This project uses [Break Versioning](https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md) as of **Aug 16, 2014**. > This project uses [Break Versioning](https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md) as of **Aug 16, 2014**.
## v2.11.0-RC1 / 2016 Jan 23
> Identical to v2.11.0-beta1 (published December 13 2015)
```clojure
[com.taoensso/nippy "2.11.0-RC1"]
```
## v2.11.0-beta1 / 2015 Dec 13 ## v2.11.0-beta1 / 2015 Dec 13
> This is a major performance release that **drops default support for thawing Nippy v1 archives** but is otherwise non-breaking > This is a major performance release that **drops default support for thawing Nippy v1 archives** but is otherwise non-breaking

108
README.md
View file

@ -1,42 +1,50 @@
**[API docs][]** | **[CHANGELOG][]** | [other Clojure libs][] | [Twitter][] | [contact/contrib](#contact--contributing) | current [Break Version][]: <a href="https://www.taoensso.com" title="More stuff by @ptaoussanis at www.taoensso.com">
<img src="https://www.taoensso.com/taoensso-open-source.png" alt="Taoensso open-source" width="400"/></a>
**[CHANGELOG]** | [API] | current [Break Version]:
```clojure ```clojure
[com.taoensso/nippy "2.10.0"] ; Stable [com.taoensso/nippy "2.10.0"] ; Stable
[com.taoensso/nippy "2.11.0-beta1"] ; Dev, see CHANGELOG for details [com.taoensso/nippy "2.11.0-RC1"] ; See CHANGELOG for details
``` ```
# Nippy, a Clojure serialization library # Nippy
Clojure's [rich data types](http://clojure.org/datatypes) are *awesome*. And its [reader](http://clojure.org/reader) allows you to take your data just about anywhere. But the reader can be painfully slow when you've got a lot of data to crunch (like when you're serializing to a database). ## The fastest serialization library for Clojure
Nippy is an attempt to provide a reliable, high-performance **drop-in alternative to the reader**. It's used as the serializer for the [Carmine Redis client](https://github.com/ptaoussanis/carmine), the [Faraday DynamoDB client](https://github.com/ptaoussanis/faraday), and a number of other projects. Clojure's [rich data types] are *awesome*. And its [reader] allows you to take your data just about anywhere. But the reader can be painfully slow when you've got a lot of data to crunch (like when you're serializing to a database).
## What's in the box™? Nippy is an attempt to provide a reliable, high-performance **drop-in alternative to the reader**. Used by the [Carmine Redis client], the [Faraday DynamoDB client], [PigPen], [Onyx] and others.
* Small, uncomplicated **all-Clojure** library
* **Terrific performance** (the fastest for Clojure that I'm aware of) ## Features
* Comprehesive **support for all standard data types** * Small, uncomplicated **all-Clojure** library
* **Easily extendable to custom data types** (v2.1+) * **Terrific performance** (the fastest for Clojure that I'm aware of)
* Java's **Serializable** fallback when available (v2.5+) * Comprehesive **support for all standard data types**
* **Reader-fallback** for all other types (including Clojure 1.4+ tagged literals) * **Easily extendable to custom data types** (v2.1+)
* **Full test coverage** for every supported type * Java's **Serializable** fallback when available (v2.5+)
* Fully pluggable **compression**, including built-in high-performance [LZ4](https://code.google.com/p/lz4/) compressor * **Reader-fallback** for all other types (including Clojure 1.4+ tagged literals)
* Fully pluggable **encryption**, including built-in high-strength AES128 enabled with a single `:password [:salted "my-password"]` option (v2+) * **Full test coverage** for every supported type
* Utils for **easy integration into 3rd-party tools/libraries** (v2+) * Fully pluggable **compression**, including built-in high-performance [LZ4] compressor
* Fully pluggable **encryption**, including built-in high-strength AES128 enabled with a single `:password [:salted "my-password"]` option (v2+)
* Utils for **easy integration into 3rd-party tools/libraries** (v2+)
## Getting started ## Getting started
### Dependencies Add the necessary dependency to your project:
Add the necessary dependency to your [Leiningen][] `project.clj` and `require` the library in your ns:
```clojure ```clojure
[com.taoensso/nippy "2.10.0"] ; project.clj [com.taoensso/nippy "2.10.0"]
(ns my-app (:require [taoensso.nippy :as nippy])) ; ns ```
And setup your namespace imports:
```clojure
(ns my-ns (:require [taoensso.nippy :as nippy]))
``` ```
### De/serializing ### De/serializing
As an example of what Nippy can do, let's take a look at its own reference stress data: As an example of what it can do, let's take a look at Nippy's own reference stress data:
```clojure ```clojure
nippy/stress-data nippy/stress-data
@ -120,7 +128,7 @@ Nippy also gives you **dead simple data encryption**. Add a single option to you
(nippy/thaw <encrypted-data> {:password [:salted "my-password"]}) ; Decrypt (nippy/thaw <encrypted-data> {:password [:salted "my-password"]}) ; Decrypt
``` ```
There's two default forms of encryption on offer: `:salted` and `:cached`. Each of these makes carefully-chosen trade-offs and is suited to one of two common use cases. See the `aes128-encryptor` [docstring](http://ptaoussanis.github.io/nippy/taoensso.nippy.encryption.html) for a detailed explanation of why/when you'd want one or the other. There's two default forms of encryption on offer: `:salted` and `:cached`. Each of these makes carefully-chosen trade-offs and is suited to one of two common use cases. See the `aes128-encryptor` [API] docs for a detailed explanation of why/when you'd want one or the other.
### Custom types (v2.1+) ### Custom types (v2.1+)
@ -140,33 +148,45 @@ There's two default forms of encryption on offer: `:salted` and `:cached`. Each
## Performance ## Performance
![Comparison chart](https://github.com/ptaoussanis/nippy/raw/master/benchmarks.png) ![benchmarks-png]
[Detailed benchmark information](https://docs.google.com/spreadsheet/ccc?key=0AuSXb68FH4uhdE5kTTlocGZKSXppWG9sRzA5Y2pMVkE) is available on Google Docs. [Detailed benchmark info] is available on Google Docs.
## Contact & contributing ## Contacting me / contributions
`lein start-dev` to get a (headless) development repl that you can connect to with [Cider][] (Emacs) or your IDE. Please use the project's [GitHub issues page] for all questions, ideas, etc. **Pull requests welcome**. See the project's [GitHub contributors page] for a list of contributors.
Please use the project's GitHub [issues page][] for project questions/comments/suggestions/whatever **(pull requests welcome!)**. Am very open to ideas if you have any! Otherwise, you can reach me at [Taoensso.com]. Happy hacking!
Otherwise reach me (Peter Taoussanis) at [taoensso.com][] or on [Twitter][]. Cheers! \- [Peter Taoussanis]
## License ## License
Copyright &copy; 2012-2015 Peter Taoussanis. Distributed under the [Eclipse Public License][], the same as Clojure. Distributed under the [EPL v1.0] \(same as Clojure).
Copyright &copy; 2012-2016 [Peter Taoussanis].
<!--- Standard links -->
[API docs]: http://ptaoussanis.github.io/nippy/ [Taoensso.com]: https://www.taoensso.com
[CHANGELOG]: https://github.com/ptaoussanis/nippy/releases [Peter Taoussanis]: https://www.taoensso.com
[other Clojure libs]: https://www.taoensso.com/clojure [@ptaoussanis]: https://www.taoensso.com
[taoensso.com]: https://www.taoensso.com [More by @ptaoussanis]: https://www.taoensso.com
[Twitter]: https://twitter.com/ptaoussanis
[issues page]: https://github.com/ptaoussanis/nippy/issues
[commit history]: https://github.com/ptaoussanis/nippy/commits/master
[Break Version]: https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md [Break Version]: https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md
[Leiningen]: http://leiningen.org/
[Cider]: https://github.com/clojure-emacs/cider <!--- Standard links (repo specific) -->
[CDS]: http://clojure-doc.org/ [CHANGELOG]: https://github.com/ptaoussanis/nippy/releases
[ClojureWerkz]: http://clojurewerkz.org/ [API]: http://ptaoussanis.github.io/nippy/
[Eclipse Public License]: https://raw2.github.com/ptaoussanis/nippy/master/LICENSE [GitHub issues page]: https://github.com/ptaoussanis/nippy/issues
[GitHub contributors page]: https://github.com/ptaoussanis/nippy/graphs/contributors
[EPL v1.0]: https://raw.githubusercontent.com/ptaoussanis/nippy/master/LICENSE
[Hero]: https://raw.githubusercontent.com/ptaoussanis/nippy/master/hero.png "Title"
<!--- Unique links -->
[rich data types]: http://clojure.org/reference/datatypes
[reader]: http://clojure.org/reference/reader
[Carmine Redis client]: https://github.com/ptaoussanis/carmine
[Faraday DynamoDB client]: https://github.com/ptaoussanis/faraday
[PigPen]: https://github.com/Netflix/PigPen
[Onyx]: https://github.com/onyx-platform/onyx
[LZ4]: https://code.google.com/p/lz4/
[benchmarks-png]: https://github.com/ptaoussanis/nippy/raw/master/benchmarks.png
[Detailed benchmark info]: https://docs.google.com/spreadsheet/ccc?key=0AuSXb68FH4uhdE5kTTlocGZKSXppWG9sRzA5Y2pMVkE

10
project.clj
View file

@ -1,6 +1,6 @@
(defproject com.taoensso/nippy "2.11.0-beta1" (defproject com.taoensso/nippy "2.11.0-RC1"
:author "Peter Taoussanis <https://www.taoensso.com>" :author "Peter Taoussanis <https://www.taoensso.com>"
:description "Clojure serialization library" :description "High-performance serialization library for Clojure"
:url "https://github.com/ptaoussanis/nippy" :url "https://github.com/ptaoussanis/nippy"
:license {:name "Eclipse Public License" :license {:name "Eclipse Public License"
:url "http://www.eclipse.org/legal/epl-v10.html" :url "http://www.eclipse.org/legal/epl-v10.html"
@ -15,7 +15,7 @@
:dependencies :dependencies
[[org.clojure/clojure "1.5.1"] [[org.clojure/clojure "1.5.1"]
[org.clojure/tools.reader "0.10.0"] [org.clojure/tools.reader "0.10.0"]
[com.taoensso/encore "2.28.0"] [com.taoensso/encore "2.32.0"]
[org.iq80.snappy/snappy "0.4"] [org.iq80.snappy/snappy "0.4"]
[org.tukaani/xz "1.5"] [org.tukaani/xz "1.5"]
[net.jpountz.lz4/lz4 "1.3"]] [net.jpountz.lz4/lz4 "1.3"]]
@ -30,12 +30,12 @@
:test {:jvm-opts ["-Xms1024m" "-Xmx2048m"] :test {:jvm-opts ["-Xms1024m" "-Xmx2048m"]
:dependencies [[org.clojure/test.check "0.9.0"] :dependencies [[org.clojure/test.check "0.9.0"]
[org.clojure/data.fressian "0.2.1"] [org.clojure/data.fressian "0.2.1"]
[org.xerial.snappy/snappy-java "1.1.2"]]} [org.xerial.snappy/snappy-java "1.1.2.1"]]}
:dev [:1.8 :test :dev [:1.8 :test
{:plugins {:plugins
[[lein-pprint "1.1.2"] [[lein-pprint "1.1.2"]
[lein-ancient "0.6.8"] [lein-ancient "0.6.8"]
[lein-codox "0.9.0"]]}]} [lein-codox "0.9.1"]]}]}
:test-paths ["test" "src"] :test-paths ["test" "src"]

4
src/taoensso/nippy.clj
View file

@ -1,6 +1,6 @@
(ns taoensso.nippy (ns taoensso.nippy
"High-performance JVM Clojure serialization library. Originally adapted from "High-performance serialization library for Clojure.
Deep-Freeze (https://goo.gl/OePPGr)." Originally adapted from Deep-Freeze (Ref. https://goo.gl/OePPGr)."
{:author "Peter Taoussanis (@ptaoussanis)"} {:author "Peter Taoussanis (@ptaoussanis)"}
(:require [taoensso.encore :as enc] (:require [taoensso.encore :as enc]
[taoensso.nippy [taoensso.nippy