Documentation

A JSON encoder.

It is faster than going through Value, because Encoding is just a wrapper around a Bytes.Builder. But the aeson interface for Encoding is extremely bad, so let’s build a better one.

Convert an Enc to a strict UTF8-bytestring which is valid JSON (minified).

Convert an Enc to a lazy UTF8-bytestring which is valid JSON (minified).

Convert an Enc to a strict Text which is valid JSON (prettyfied).

ATTN: will re-parse the json through Value, so only use for user-interactions like pretty-printing.

Convert an Enc to a lazy Text which is valid JSON (prettyfied).

ATTN: will re-parse the json through Value, so only use for user-interactions like pretty-printing.

Embed a Encoding verbatim (it’s a valid JSON value)

Encode a Value verbatim (it’s a valid JSON value)

Encode an empty json list

Encode an empty json dict

Encode a Text as a json string

Encode a lazy Text as a json string

Encode a ByteString as a base64-encoded json string

Encode a Text as a base64-encoded json string

Encode a String as a json string

Encode as json null if Nothing, else use the given encoder for Just a

Encode a list as a json list

Encode a NonEmpty as a json list.

Encode the given list of keys and their encoders as json dict.

If the list contains the same key multiple times, the first value in the list is retained:

(object [ ("foo", 42), ("foo", 23) ])
~= "{"foo":42}"

A tag/value encoder; See choice

Encode a sum type as a Choice, an object with a tag/value pair, which is the conventional json sum type representation in our codebase.

foo :: Maybe Text -> Enc
foo = choice $ case
  Nothing -> Choice "no" emptyObject ()
  Just t -> Choice "yes" text t

ex = foo Nothing == "{"tag": "no", "value": {}}"
ex2 = foo (Just "hi") == "{"tag": "yes", "value": "hi"}"

Like choice, but simply encode a single possibility into a tag/value object. This can be useful, but if you want to match on an enum, use choice instead.

Encode a Map as a json dict

We can’t really set the key to anything but text (We don’t keep the tag of Encoding) so instead we allow anything that’s coercible from text as map key (i.e. newtypes).

Encode a KeyMap as a json dict

Encode Null

Encode a Bool as a json boolean

Encode an Integer as a json number. TODO: is it okay to just encode an arbitrarily-sized integer into json?

Encode a Scientific as a json number.

Encode a Natural as a json number.

Encode an Int as a json number.

Encode an Int64 as a json number.

Encode UTCTime as a json string, as an ISO8601 timestamp with timezone (yyyy-mm-ddThh:mm:ss[.sss]Z)

Implement this class if you want your type to only implement the part of Num that allows creating them from Integer-literals, then derive Num via NumLiteralOnly:

data Foo = Foo Integer
  deriving (Num) via (NumLiteralOnly Foo Foo)

instance IntegerLiteral Foo where
 integerLiteral i = Foo i

The same as IntegerLiteral but for floating point literals.

Helper class for deriving (Num) via …, implements only literal syntax for integer and floating point numbers, and throws descriptive runtime errors for any other methods in Num.

See IntegerLiteral and RationalLiteral for examples.