README.md

Cheshire

'Cheshire Puss,' she began, rather timidly, as she did not at all know
whether it would like the name: however, it only grinned a little
wider. 'Come, it's pleased so far,' thought Alice, and she went
on. 'Would you tell me, please, which way I ought to go from here?'

'That depends a good deal on where you want to get to,' said the Cat.

'I don't much care where--' said Alice.

'Then it doesn't matter which way you go,' said the Cat.

'--so long as I get SOMEWHERE,' Alice added as an explanation.

'Oh, you're sure to do that,' said the Cat, 'if you only walk long
enough.'

Cheshire is fast JSON encoding, based off of clj-json and
clojure-json, with additional features like Date/UUID/Set/Symbol
encoding and SMILE support.

Why?

clojure-json had really nice features (custom encoders), but was slow;
clj-json had no features, but was fast. Cheshire encodes JSON fast,
with added support for more types and the ability to use custom
encoders.

Custom Encoders

Custom encoding is supported from 2.0.0 and up, if you encounter a
bug, please open a github issue. From 5.0.0 onwards, custom encoding
has been moved to be part of the core namespace (not requiring a
namespace change)

;; Custom encoders allow you to swap out the api for the fast;; encoder with one that is slightly slower, but allows custom;; things to be encoded:
(nsmyns
(:require [cheshire.core :refer:all]
[cheshire.generate :refer [add-encoder encode-str remove-encoder]]))
;; First, add a custom encoder for a class:
(add-encoder java.awt.Color
(fn [c jsonGenerator]
(.writeString jsonGenerator (str c))))
;; There are also helpers for common encoding actions:
(add-encoder java.net.URL encode-str)
;; List of common encoders that can be used: (see generate.clj);; encode-nil;; encode-number;; encode-seq;; encode-date;; encode-bool;; encode-named;; encode-map;; encode-symbol;; encode-ratio;; Then you can use encode from the custom namespace as normal
(encode (java.awt.Color.123))
;; => "java.awt.Color[r=1,g=2,b=3]";; Custom encoders can also be removed:
(remove-encoder java.awt.Color)
;; Decoding remains the same, you are responsible for doing custom decoding.

NOTE: `cheshire.custom` has been deprecated in version 5.0.0

In version 3.0.0 and above, custom encoding first attempts to encode
the object using the core encoding (because it would be faster). If
the encoding fails, it uses the custom encoding mechanics to encode
the JSON. If this is undesirable, use the `generate-string*`,
`generate-stream*` and `generate-smile*` methods to overwrite this.
Custom (slower) and Core (faster) encoding can be mixed and matched by
requiring both namespaces and using the custom one only when you need
to encode custom classes. The API methods for cheshire.core and
cheshire.custom are exactly the same (except for add-encoder,
remove-encoder and the methods ending with '*' in the custom
namespace).

Custom and Core encoding have been combined in Cheshire 5.0.0, so
there is no longer any need to require a different namespace depending
on what you would like to use.

Benchmarks for custom encoding coming soon. - check out the
benchmarks in cheshire.test.benchmark; or run lein benchmark. If
you have scenarios where Cheshire is not performing as well as
expected (compared to a different library), please let me know.

Advanced customization for factories

See
this
and
this
for a list of features that can be customized if desired. A custom
factory can be used like so: