jsonista.core — metosin/jsonista 0.3.13

JSON encoding and decoding based on Jackson Databind.

Encoding example:

(require '[jsonista.core :as json])
(json/write-value-as-string {:hello 1})
;; => "{\"hello\":1}"

Decoding example:

(def +data+ (json/write-value-as-string {:foo "bar"}))
(json/read-value +data+)
;; => {"foo" "bar"}

Configuration

You can configure encoding and decoding by creating a custom mapper object with jsonista.core/object-mapper. The options are passed in as a map.

For example, to convert map keys into keywords while decoding:

(json/read-value +data+ (json/object-mapper {:decode-key-fn true}))
;; => {:foo "bar"}

See the docstring of object-mapper for all available options.

Custom encoders

Custom encoder is a function that take a value and a JsonGenerator object as the parameters. The function should call JsonGenerator methods to emit the desired JSON. This is the same as how custom encoders work in Cheshire.

Custom encoders are configured by the object-mapper option :encoders, which is a map from types to encoder functions.

For example, to encode java.awt.Color:

 (let [encoders {java.awt.Color (fn [color gen] (.writeString gen (str color)))}
       mapper (json/object-mapper {:encoders encoders})]
   (json/write-value-as-string (java.awt.Color. 1 2 3) mapper))
 ;; => "\"java.awt.Color[r=1,g=2,b=3]\""

Exceptions

Jsonista just passes on all and any exceptions from Jackson. We've tried to document the possible exceptions in the docstrings, but you might also want to check the Jackson API docs.

Jsonista vs. Cheshire

jsonista uses Jackson Databind while Cheshire uses Jackson Core. In our benchmarks, jsonista performs better than Cheshire (take look at json_perf_test.clj). On the other hand, Cheshire has a wider set of features and has been used in production much more.

+default-mapper+ clj deprecated

DEPRECATED: The default ObjectMapper instance.

default-object-mapper clj

The default ObjectMapper instance.

keyword-keys-object-mapper clj

ObjectMapper instance that uses keyword keys for maps

object-mapper clj

(object-mapper)

(object-mapper options)

Create an ObjectMapper with Clojure support.

The optional first parameter is a map of options. The following options are available:

Mapper options
:modules	vector of extra ObjectMapper modules
:factory	A Jackson JsonFactory for this given mapper
:mapper	The base ObjectMapper to start with - overrides :factory

Encoding options
:order-by-keys	set to true to order map keys alphabetically
:pretty	set to true use Jacksons pretty-printing defaults
:escape-non-ascii	set to true to escape non ascii characters
:strip-nils	remove any keys that have nil values
:strip-empties	remove any keys that have nil or empty ("", {}, [], etc) values
:do-not-fail-on-empty-beans	serialize objects with no accessors as empty objects instead of throwing an exception
:date-format	string for custom date formatting. default: yyyy-MM-dd'T'HH:mm:ss'Z'
:encode-key-fn	true to coerce keyword keys to strings, false to leave them as keywords, or a function to provide custom coercion (default: true)
:encoders	a map of custom encoders where keys should be types and values should be encoder functions
:close	close OutputStreams & other closeable targets after write-value (default: true)

Encoder functions take two parameters: the value to be encoded and a JsonGenerator object. The function should call JsonGenerator methods to emit the desired JSON.

Decoding options
:decode-key-fn	true to coerce keys to keywords, false to leave them as strings, or a function to provide custom coercion (default: false)
:bigdecimals	true to decode doubles as BigDecimals (default: false)

read-value clj

(read-value object)

(read-value object mapper)

Decodes a value from a JSON from anything that satisfies ReadValue protocol. By default, File, URL, String, Reader and InputStream are supported.

To configure, pass in an ObjectMapper created with object-mapper, see object-mapper docstring for the available options.

Throws the same exceptions as ObjectMapper.readValue(): IOException, com.fasterxml.jackson.core.exc.StreamReadException, com.fasterxml.jackson.databind.DatabindException

read-values clj

(read-values object)

(read-values object mapper)

Decodes a sequence of values from a JSON as an iterator from anything that satisfies ReadValue protocol. By default, File, URL, String, Reader and InputStream are supported.

The returned object is an Iterable, Iterator and IReduceInit. It can be reduced on via [[reduce]] and turned into a lazy sequence via [[iterator-seq]].

To configure, pass in an ObjectMapper created with object-mapper, see object-mapper docstring for the available options.

Throws IOException.

ReadValue clj protocol

-read-value clj

(-read-value this mapper)

ReadValues clj protocol

-read-values clj

(-read-values this mapper)

write-value clj

(write-value to object)

(write-value to object mapper)

Encode a value as JSON and write using the provided WriteValue instance. By default, File, OutputStream, DataOutput and Writer are supported.

To configure, pass in an ObjectMapper created with object-mapper, see object-mapper docstring for the available options.

Throws the same exceptions as ObjectMapper.writeValue(): IOException, com.fasterxml.jackson.core.exc.StreamWriteException, com.fasterxml.jackson.databind.DatabindException

write-value-as-bytes clj

(write-value-as-bytes object)

(write-value-as-bytes object mapper)

Encode a value as a JSON byte-array.

To configure, pass in an ObjectMapper created with object-mapper.

Throws the same exceptions as ObjectMapper.writeValueAsBytes(): com.fasterxml.jackson.core.JsonProcessingException

write-value-as-string clj

(write-value-as-string object)

(write-value-as-string object mapper)

Encode a value as a JSON string.

To configure, pass in an ObjectMapper created with object-mapper.

Throws the same exceptions as ObjectMapper.writeValueAsString(): com.fasterxml.jackson.core.JsonProcessingException

write-values clj

(write-values to values)

(write-values to values mapper)

Encodes a sequence of values as JSON, separating values with a line return. By default, to can be a File, OutputStream, DataOutput or Writer.

By default, values can be an array or an Iterable.

To configure, pass in an ObjectMapper created with object-mapper, see object-mapper docstring for the available options.

Throws IOException.

write-values-as-array clj

(write-values-as-array to values)

(write-values-as-array to values mapper)

Encodes a sequence of values as a JSON array. By default, to can be a File, OutputStream, DataOutput or Writer.

By default, values can be an array or an Iterable.

To configure, pass in an ObjectMapper created with object-mapper, see object-mapper docstring for the available options.

Throws IOException.

WriteAll clj protocol

-write-all clj

(-write-all this writer)

WriteValue clj protocol

-write-value clj

(-write-value this value mapper)

WriteValues clj protocol

-write-values clj

(-write-values this values mapper)

-write-values-as-array clj

(-write-values-as-array this values mapper)