buffer-builder-0.2.4.4: Library for efficiently building up buffers, one piece at a time

Safe HaskellNone
LanguageHaskell2010

Data.BufferBuilder.Json

Contents

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

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

Instances

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.

Minimal complete definition

toJson

Methods

toJson :: a -> Value Source #

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.

Encoding Strings

class ToJson a => ToJsonString a where Source #

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

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.

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

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

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

unsafeValueUtf8Builder :: Utf8Builder () -> Value Source #

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 Source #

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 Source #

Deprecated: Use unsafeValueUtf8Builder or unsafeStringUtf8Builder instead

unsafeAppendBS :: ByteString -> Value Source #

Deprecated: Use unsafeValueUtf8Builder or unsafeStringUtf8Builder instead