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

Data.BufferBuilder.Json

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

 Source # Methods

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 #

Instances

 Source # Methods Source # Methods Source # Methods Source # Methods Source # Methods Source # Methods ToJson a => ToJson [a] Source # MethodstoJson :: [a] -> Value Source # ToJson a => ToJson (Maybe a) Source # MethodstoJson :: Maybe a -> Value Source # ToJson a => ToJson (Vector a) Source # MethodstoJson :: Vector a -> Value Source # (Storable a, ToJson a) => ToJson (Vector a) Source # MethodstoJson :: Vector a -> Value Source # (Vector Vector a, ToJson a) => ToJson (Vector a) Source # MethodstoJson :: Vector a -> Value Source # (Prim a, ToJson a) => ToJson (Vector a) Source # MethodstoJson :: Vector a -> Value Source # ToJson a => ToJson (HashMap Text a) Source # Methods

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

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

Represents a JSON "null".

# Unsafe

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.

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.