-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Data structure agnostic JSON serialization
--
-- Most json packages dictate a data structure that corresponds to json
-- values. To serialize other values to json, then that value must be
-- marshalled into the specified structure.
--
-- This library avoids this marshalling step, and is thus potentially
-- more efficient when serializing arbitrary data structures.
-- Unfortunately json-builder cannot yet read or process json data, and
-- it's not clear to me yet how pull a similar kind of trick to avoid
-- unnecessary data structures when parsing json data into arbitrary data
-- types.
@package json-builder
@version 0.2.4
-- | Internal bits. By using the constructors provided in this module, you
-- can break the abstraction that json-builder provides and emit invalid
-- JSON syntax. Also, this module is not as stable as the public
-- interface and can change at any time.
module Data.Json.Builder.Internal
-- | The Json type represents valid json syntax. It cannot be
-- directly analyzed, however it can be turned into a Builder via
-- toBuilder, a (lazy) ByteString via toJsonBS or
-- toJsonLBS, or used as a component of a json Array or
-- json Object using element or row.
newtype Json
Json :: Builder -> Json
-- | The Object type represents syntax for a json object. It has a
-- singleton constructor row, and an instance of Monoid, so
-- that mempty represents the empty object and mappend
-- concatinates two objects. Arbitrary objects can be constructed using
-- these operators.
--
-- Note that duplicate field names will appear in the output, so it is up
-- to the user of this interface to avoid duplicate field names.
newtype Object
Object :: CommaMonoid -> Object
-- | The Array type represents syntax for a json array. It has been
-- given a singleton constructor element and an instance of
-- Monoid, so that mempty represents the empty array and
-- mappend concatinates two arrays. Arbitrary arrays can be
-- constructed using these operators.
newtype Array
Array :: CommaMonoid -> Array
-- | The Escaped type represents json string syntax. The purpose of
-- this type is so that json strings can be efficiently constructed from
-- multiple Haskell strings without superfluous conversions or
-- concatinations.
--
-- Internally, it is just a Builder value which must produce a
-- UTF-8 encoded bytestring with backslashes, quotes, and control
-- characters appropriately escaped. It also must not render the opening
-- or closing quote, which are instead rendered by toJson.
newtype Escaped
Escaped :: Builder -> Escaped
-- | A CommaMonoid inserts commas between builders. In order to
-- satisify the Monoid identity laws, Empty must be
-- distinguished from Comma mempty. To demonstrate
-- the difference:
--
--
-- mconcat ["foo", "" , "bar"] == "foo,,bar"
-- mconcat ["foo", Empty , "bar"] == "foo,bar"
--
--
-- The strings in this example denote CommaMonoids via
-- fromString = Comma . fromString. Thus
-- "" is equivalent to Comma mempty.
data CommaMonoid
Empty :: CommaMonoid
Comma :: !Builder -> CommaMonoid
-- | Data structure agnostic JSON serialization
module Data.Json.Builder
-- | The Json type represents valid json syntax. It cannot be
-- directly analyzed, however it can be turned into a Builder via
-- toBuilder, a (lazy) ByteString via toJsonBS or
-- toJsonLBS, or used as a component of a json Array or
-- json Object using element or row.
data Json
toBuilder :: Value a => a -> Builder
toJsonBS :: Value a => a -> ByteString
toJsonLBS :: Value a => a -> ByteString
-- | The Value typeclass represents types that can be rendered into
-- valid json syntax.
class Value a
toJson :: Value a => a -> Json
-- | The Array type represents syntax for a json array. It has been
-- given a singleton constructor element and an instance of
-- Monoid, so that mempty represents the empty array and
-- mappend concatinates two arrays. Arbitrary arrays can be
-- constructed using these operators.
data Array
-- | The element function constructs a json array consisting of
-- exactly one value. These arrays can be concatinated using
-- mappend.
element :: Value a => a -> Array
class JsArray a
toArray :: JsArray a => a -> Array
-- | The Object type represents syntax for a json object. It has a
-- singleton constructor row, and an instance of Monoid, so
-- that mempty represents the empty object and mappend
-- concatinates two objects. Arbitrary objects can be constructed using
-- these operators.
--
-- Note that duplicate field names will appear in the output, so it is up
-- to the user of this interface to avoid duplicate field names.
data Object
-- | The row function constructs a json object consisting of exactly
-- one field. These objects can be concatinated using mappend.
row :: (JsString k, Value a) => k -> a -> Object
class JsObject a
toObject :: JsObject a => a -> Object
-- | The Escaped type represents json string syntax. The purpose of
-- this type is so that json strings can be efficiently constructed from
-- multiple Haskell strings without superfluous conversions or
-- concatinations.
--
-- Internally, it is just a Builder value which must produce a
-- UTF-8 encoded bytestring with backslashes, quotes, and control
-- characters appropriately escaped. It also must not render the opening
-- or closing quote, which are instead rendered by toJson.
data Escaped
-- | The JsString typeclass represents types that can be render into
-- json string syntax. They are special because only strings can appear
-- as field names of json objects.
class Value a => JsString a
escape :: JsString a => a -> Escaped
-- | The class of monoids (types with an associative binary operation that
-- has an identity). Instances should satisfy the following laws:
--
--
--
-- The method names refer to the monoid of lists under concatenation, but
-- there are many other instances.
--
-- Minimal complete definition: mempty and mappend.
--
-- Some types can be viewed as a monoid in more than one way, e.g. both
-- addition and multiplication on numbers. In such cases we often define
-- newtypes and make those instances of Monoid, e.g.
-- Sum and Product.
class Monoid a
mempty :: Monoid a => a
mappend :: Monoid a => a -> a -> a
mconcat :: Monoid a => [a] -> a