Safe Haskell	None
Language	Haskell2010

Data.BufferBuilder.Json

Contents

Encoding Values
Objects
Arrays
Null
Unsafe

Description

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.

Synopsis

Encoding Values

data Value Source

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 unsafeAppendBS and unsafeAppendUtf8Builder are available.

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

Instances

ToJson Value

class ToJson a where Source

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.

Methods

toJson :: a -> Value Source

Instances

ToJson Bool
ToJson Double
ToJson Int
ToJson Text
ToJson ObjectBuilder
ToJson Value
ToJson a => ToJson [a]
ToJson a => ToJson (Maybe a)
ToJson a => ToJson (Vector a)
(Vector Vector a, ToJson a) => ToJson (Vector a)
(Storable a, ToJson a) => ToJson (Vector a)
(Prim a, ToJson a) => ToJson (Vector a)
ToJson a => ToJson (HashMap Text a)

encodeJson :: ToJson a => a -> ByteString Source

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.

Objects

data ObjectBuilder Source

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
ToJson ObjectBuilder

emptyObject :: Value Source

A Value that produces the empty object.

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

Create an ObjectBuilder from a key and a value.

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

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

Arrays

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

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 Source

Represents a JSON "null".

Unsafe

unsafeAppendBS :: ByteString -> Value Source

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

unsafeAppendUtf8Builder :: Utf8Builder () -> Value Source

Unsafely append a Utf8Builder into a JSON document. 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.