Data.BufferBuilder.Json

A library for efficiently building up a valid JSON document.

The difference between Data.BufferBuilder.Json and the excellent Data.Aeson is that Aeson represents the JSON document as an in-memory tree structure before encoding it into bytes. This module, on the other hand, represents each value as an action that writes its representation directly into the output buffer. At the cost of reduced flexibility, this results in significantly improved encoding performance. At the time of this writing, encoding a custom record type into JSON using this module was almost 5x faster than using Aeson.

This module is built on top of Data.Utf8Builder.

Encoding Values

data Value

Represents a JSON value.

Values are built up from either ToJson instances or from primitives like emptyObject, array, and null.

In special cases, or when performance is of utmost importance, the unsafe functions unsafeAppendUtf8Builder are available.

Internally, Value encodes an action or sequence of actions that append JSON-encoded text to the underlying Utf8Builder.

Instances

ToJson Value

Methods

toJson :: Value -> Value

class ToJson a where

The class of types that can be converted to JSON values. See ObjectBuilder for an example of writing a ToJson instance for a custom data type.

ToJson instances are provided for many common types. For example, to create a JSON array, call toJson on a list or Vector. To create a JSON object, call toJson on a HashMap.

Minimal complete definition

toJson

Methods

toJson :: a -> Value

Instances

ToJson Bool

Methods

toJson :: Bool -> Value

ToJson Double

Methods

toJson :: Double -> Value

ToJson Int

Methods

toJson :: Int -> Value

ToJson Text

Methods

toJson :: Text -> Value

ToJson ObjectBuilder

Methods

toJson :: ObjectBuilder -> Value

ToJson JsonString

Methods

toJson :: JsonString -> Value

ToJson Value

Methods

toJson :: Value -> Value

ToJson a => ToJson [a]

Methods

toJson :: [a] -> Value

ToJson a => ToJson (Maybe a)

Methods

toJson :: Maybe a -> Value

ToJson a => ToJson (Vector a)

Methods

toJson :: Vector a -> Value

(Storable a, ToJson a) => ToJson (Vector a)

Methods

toJson :: Vector a -> Value

(Vector Vector a, ToJson a) => ToJson (Vector a)

Methods

toJson :: Vector a -> Value

(Prim a, ToJson a) => ToJson (Vector a)

Methods

toJson :: Vector a -> Value

(ToJsonString k, ToJson v) => ToJson (HashMap k v)

Methods

toJson :: HashMap k v -> Value

encodeJson :: ToJson a => a -> ByteString

Encode a value into a ByteString containing valid UTF-8-encoded JSON. The argument value must have a corresponding ToJson instance.

WARNING: There are three cases where the resulting ByteString may not contain legal JSON:

• An unsafe function was used to encode a JSON value.
• The root value is not an object or array, as the JSON specification requires.
• An object has multiple keys with the same value. For maximum efficiency, ObjectBuilder does not check key names for uniqueness, so it's possible to construct objects with duplicate keys.

Encoding Strings

data JsonString

Represents a JSON string.

Instances

ToJsonString JsonString

Methods

toJsonString :: JsonString -> JsonString

ToJson JsonString

Methods

toJson :: JsonString -> Value

class ToJson a => ToJsonString a where

The class of types that can be converted to JSON strings. Any type that provides ToJsonString also provides ToJson, and thus can be used as JSON values.

Minimal complete definition

toJsonString

Methods

toJsonString :: a -> JsonString

Instances

ToJsonString Text

Methods

toJsonString :: Text -> JsonString

ToJsonString JsonString

Methods

toJsonString :: JsonString -> JsonString

Objects

data ObjectBuilder

Builds a JSON object.

An ObjectBuilder builds one or more key-value pairs of a JSON object. They are constructed with the .= operator and combined with <>.

To turn an ObjectBuilder into a Value, use its ToJson class instance.

    data Friend = Friend
        { fId :: !Int
        , fName :: !Text
        } deriving (Eq, Show)

    instance ToJson Friend where
        toJson friend = toJson $
                   "id"   .= fId friend
                <> "name" .= fName friend

WARNING: ObjectBuilder does not check uniqueness of object keys. If two keys with the same value are inserted, then the resulting JSON document will be illegal.

Instances

Monoid ObjectBuilder

Methods

mempty :: ObjectBuilder

mappend :: ObjectBuilder -> ObjectBuilder -> ObjectBuilder

mconcat :: [ObjectBuilder] -> ObjectBuilder

ToJson ObjectBuilder

Methods

toJson :: ObjectBuilder -> Value

emptyObject :: Value

A Value that produces the empty object.

(.=) :: ToJson a => Text -> a -> ObjectBuilder infixr 8

Create an ObjectBuilder from a key and a value.

(.=#) :: ToJson a => Addr# -> a -> ObjectBuilder infixr 8

Create an ObjectBuilder from a key and a value. The key is an ASCII-7, unescaped, zero-terminated Addr#.

WARNING: This function is unsafe. If the key is NOT zero-terminated, then an access violation might result. If the key is not a sequence of unescaped ASCII characters, the resulting JSON document will be illegal.

This function is provided for maximum performance in the common case that object keys are ASCII-7. It achieves performance by avoiding the CAF for a Text literal and avoiding the need to transcode UTF-16 to UTF-8 and escape.

To use this function, the calling source file must have the MagicHash extension enabled.

    data Friend = Friend
        { fId :: !Int
        , fName :: !Text
        } deriving (Eq, Show)

    instance ToJson Friend where
        toJson friend = toJson $
                   "id"#   .=# fId friend
                <> "name"# .=# fName friend

row :: (ToJsonString k, ToJson v) => k -> v -> ObjectBuilder infixr 8

Create an ObjectBuilder from an arbitrary key and value. The key can be any type with a ToJsonString instance.

Arrays

array :: (Foldable t, ToJson a) => t a -> Value

Serialize any Foldable as a JSON array. This is generally slower than directly calling toJson on a list or Vector, but it will convert any Foldable type into an array.

Null

nullValue :: Value

Represents a JSON "null".

Unsafe

unsafeValueUtf8Builder :: Utf8Builder () -> Value

Unsafely convert a Utf8Builder into a JSON value. This function does not escape, quote, or decorate the string in any way. This function is unsafe because you can trivially use it to generate illegal JSON.

unsafeStringUtf8Builder :: Utf8Builder () -> JsonString

Unsafely convert a Utf8Builder into a JSON string. This function does not escape, quote, or decorate the string in any way. This function is unsafe because you can trivially use it to generate illegal JSON.

Deprecated

unsafeAppendUtf8Builder :: Utf8Builder () -> Value

Deprecated: Use unsafeValueUtf8Builder or unsafeStringUtf8Builder instead

unsafeAppendBS :: ByteString -> Value

Deprecated: Use unsafeValueUtf8Builder or unsafeStringUtf8Builder instead