-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Very fast JSON serialisation and parsing library
--   
@package highjson
@version 0.2.0.1

module Data.Json.Serialiser

-- | Serialise json to a strict <a>ByteString</a>
serialiseJsonBs :: ToJson a => a -> ByteString

-- | Serialise json to a lazy <a>ByteString</a>
serialiseJsonBsl :: ToJson a => a -> ByteString

-- | Serialise json to a strict <a>Text</a>
serialiseJsonT :: ToJson a => a -> Text

-- | The class of types that can be converted to JSON values. See
--   <a>ObjectBuilder</a> for an example of writing a <a>ToJson</a>
--   instance for a custom data type.
--   
--   <a>ToJson</a> instances are provided for many common types. For
--   example, to create a JSON array, call <a>toJson</a> on a list or
--   <a>Vector</a>. To create a JSON object, call <a>toJson</a> on a
--   <a>HashMap</a>.
class ToJson a
toJson :: ToJson a => a -> Value
runSerSpec :: SerSpec k -> k -> Value

-- | Parser specification. Use <tt>OnlyConstr</tt> for normal types and
--   'FirstConstr'/'NextConstr' for sum types
data SerSpec k
SingleConstr :: SerObjSpec k ts -> SerSpec k
MultiConstr :: (k -> KeyedSerialiser k) -> SerSpec k

-- | Associate a JSON key with a serialiser
(.<-) :: ToJson a => Text -> a -> KeyedSerialiser k
data KeyedSerialiser k

-- | List of <a>SpecKey</a>s defining the serialisation of values to json
data SerObjSpec k (ts :: [*])
SerObjSpecNil :: SerObjSpec k []
(:&&&:) :: !(SpecKey k t) -> !(SerObjSpec k ts) -> SerObjSpec k (t : ts)

-- | A json key and a getter
data SpecKey k t

-- | Construct a <a>SpecKey</a> mapping a json key to a getter function
(.:) :: (ToJson t, Typeable t) => Text -> (k -> t) -> SpecKey k t

-- | Construct a <a>SpecKey</a> mapping a json key to a getter function of
--   a <a>Maybe</a> type. This allows to omit the key when generating json
--   instead of setting it to null.
(.:?) :: (ToJson t, Typeable t) => Text -> (k -> Maybe t) -> SpecKey k (Maybe t)

-- | Builds a JSON object.
--   
--   An <a>ObjectBuilder</a> builds one or more key-value pairs of a JSON
--   object. They are constructed with the <a>.=</a> operator and combined
--   with <a>&lt;&gt;</a>.
--   
--   To turn an <a>ObjectBuilder</a> into a <a>Value</a>, use its
--   <a>ToJson</a> class instance.
--   
--   <pre>
--   data Friend = Friend
--       { fId :: !Int
--       , fName :: !Text
--       } deriving (Eq, Show)
--   
--   instance ToJson Friend where
--       toJson friend = toJson $
--                  "id"   .= fId friend
--               &lt;&gt; "name" .= fName friend
--   </pre>
--   
--   <b>WARNING</b>: <a>ObjectBuilder</a> does not check uniqueness of
--   object keys. If two keys with the same value are inserted, then the
--   resulting JSON document will be illegal.
data ObjectBuilder :: *

-- | A <a>Value</a> that produces the empty object.
emptyObject :: Value

-- | Represents a JSON value.
--   
--   <a>Value</a>s are built up from either <a>ToJson</a> instances or from
--   primitives like <a>emptyObject</a>, <a>array</a>, and <a>null</a>.
--   
--   In special cases, or when performance is of utmost importance, the
--   unsafe functions <a>unsafeAppendUtf8Builder</a> are available.
--   
--   Internally, Value encodes an action or sequence of actions that append
--   JSON-encoded text to the underlying <a>Utf8Builder</a>.
data Value :: *

-- | Create an <a>ObjectBuilder</a> from a key and a value.
(.=) :: ToJson a => Text -> a -> ObjectBuilder

-- | Create an <a>ObjectBuilder</a> from a key and a value. The key is an
--   ASCII-7, unescaped, zero-terminated <a>Addr#</a>.
--   
--   <b>WARNING</b>: 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.
--   
--   <pre>
--   data Friend = Friend
--       { fId :: !Int
--       , fName :: !Text
--       } deriving (Eq, Show)
--   
--   instance ToJson Friend where
--       toJson friend = toJson $
--                  "id"#   .=# fId friend
--               &lt;&gt; "name"# .=# fName friend
--   </pre>
(.=#) :: ToJson a => Addr# -> a -> ObjectBuilder

-- | Create an ObjectBuilder from an arbitrary key and value. The key can
--   be any type with a <a>ToJsonString</a> instance.
row :: (ToJsonString k, ToJson v) => k -> v -> ObjectBuilder

-- | Serialize any <a>Foldable</a> as a JSON array. This is generally
--   slower than directly calling <a>toJson</a> on a list or <a>Vector</a>,
--   but it will convert any <a>Foldable</a> type into an array.
array :: (Foldable t, ToJson a) => t a -> Value

-- | Represents a JSON "null".
nullValue :: Value
instance ToJson Int64
instance (ToJson a, ToJson b) => ToJson (a, b)
instance (ToJson a, ToJson b) => ToJson (Either a b)

module Data.Json.Parser

-- | Parse json from a strict <a>ByteString</a>
parseJsonBs :: JsonReadable t => ByteString -> Either String t

-- | Parse json from a lazy <a>ByteString</a>
parseJsonBsl :: JsonReadable t => ByteString -> Either String t

-- | Parse json from a strict <a>Text</a>
parseJsonT :: JsonReadable t => Text -> Either String t

-- | Typeclass defining an attoparsec <a>Parser</a> how Haskell types
--   should be parsed from JSON. Use predifined instances (with
--   <a>readJson</a>) and <a>runSpec</a> (on <a>ObjSpec</a>) to define
--   instances for custom types
class JsonReadable t
readJson :: JsonReadable t => Parser t

-- | Convert a <a>ParseSpec</a> into a <a>Parser</a>
runParseSpec :: ParseSpec k -> Parser k

-- | List of <a>TypedKey</a>s, should be in the same order as your
--   constructor in <a>runSpec</a> will expect them
data ObjSpec (ts :: [*])
ObjSpecNil :: ObjSpec []
(:&&:) :: !(TypedKey t) -> !(ObjSpec ts) -> ObjSpec (t : ts)

-- | Parser specification. Use <a>:$:</a> for normal types and
--   <a>FirstConstr</a> / <a>:|:</a> for sum types
data ParseSpec k
(:$:) :: HVectElim ts k -> ObjSpec ts -> ParseSpec k
FirstConstr :: KeyedConstr k -> ParseSpec k
(:|:) :: KeyedConstr k -> ParseSpec k -> ParseSpec k

-- | Associates a json key with a parser
data KeyedConstr k

-- | Choice between multiple constructors
(<||>) :: KeyedConstr k -> ParseSpec k -> ParseSpec k
class ConstrTagger r where type family ResultType r :: *
(.->) :: ConstrTagger r => Text -> Parser (ResultType r) -> r

-- | Json object key to a value t
data TypedKey t

-- | Required json object key. Use <a>IsString</a> instance for automatic
--   choice
reqKey :: Typeable t => Text -> TypedKey t

-- | Optional json object key. Use <a>IsString</a> instance for automatic
--   choice
optKey :: Typeable t => Text -> TypedKey (Maybe t)

-- | Get the textual key of a <a>TypedKey</a>
typedKeyKey :: TypedKey t -> Text

-- | Parse a json object given a value parser for each key
readObject :: (Text -> Maybe (Parser a)) -> Parser (HashMap Text a)
type Parser = Parser ByteString

-- | A value that is <a>Typeable</a> and <a>JsonReadable</a>
data WrappedValue
WrappedValue :: !t -> WrappedValue

-- | Get a value out of the map returned by <a>readObject</a>
getValueByKey :: (Monad m, Typeable t) => Text -> HashMap Text WrappedValue -> m t

-- | Optionally get a value out of the map returned by <a>readObject</a>
getOptValueByKey :: (Monad m, Typeable t) => Text -> HashMap Text WrappedValue -> m (Maybe t)
instance [overlap ok] ConstrTagger (ParseSpec k)
instance [overlap ok] ConstrTagger (KeyedConstr k)
instance [overlap ok] Typeable t => IsString (TypedKey t)
instance [overlap ok] Typeable t => IsString (TypedKey (Maybe t))
instance [overlap ok] JsonReadable a => JsonReadable (HVect '[a])
instance [overlap ok] (JsonReadable a, JsonReadable b) => JsonReadable (Either a b)
instance [overlap ok] JsonReadable t => JsonReadable (Maybe t)
instance [overlap ok] JsonReadable Text
instance [overlap ok] JsonReadable Word64
instance [overlap ok] JsonReadable Word32
instance [overlap ok] JsonReadable Word16
instance [overlap ok] JsonReadable Word8
instance [overlap ok] JsonReadable Word
instance [overlap ok] JsonReadable Int64
instance [overlap ok] JsonReadable Int32
instance [overlap ok] JsonReadable Int16
instance [overlap ok] JsonReadable Int8
instance [overlap ok] JsonReadable Int
instance [overlap ok] JsonReadable Double
instance [overlap ok] JsonReadable Scientific
instance [overlap ok] JsonReadable Bool
instance [overlap ok] JsonReadable t => JsonReadable (t, t)
instance [overlap ok] JsonReadable t => JsonReadable (Vector t)
instance [overlap ok] JsonReadable t => JsonReadable [t]

module Data.Json

-- | Describes JSON parsing and serialisation of a Haskell type
data JsonSpec k (ts :: [*])
JsonSpec :: !(HVectElim ts k) -> !(FieldSpec k ts) -> JsonSpec k
j_constr :: JsonSpec k -> !(HVectElim ts k)
j_fields :: JsonSpec k -> !(FieldSpec k ts)

-- | Describes JSON parsing and serialisation of a list of fields
data FieldSpec k (ts :: [*])
EmptySpec :: FieldSpec k []
(:+:) :: !(FieldKey k t) -> !(FieldSpec k ts) -> FieldSpec k (t : ts)

-- | Describes a json key
data FieldKey k t

-- | Required json object key. Use <a>IsString</a> instance for automatic
--   choice
reqKey :: Typeable t => Text -> TypedKey t

-- | Optional json object key. Use <a>IsString</a> instance for automatic
--   choice
optKey :: Typeable t => Text -> TypedKey (Maybe t)

-- | Json object key to a value t
data TypedKey t

-- | Construct a <a>FieldKey</a> mapping a json key to a getter function
(.=) :: (ToJson t, JsonReadable t, Typeable t) => TypedKey t -> (k -> t) -> FieldKey k t

-- | Construct a <a>FieldKey</a> mapping a json key to a getter function of
--   a <a>Maybe</a> type. This allows to omit the key when generating json
--   instead of setting it to null.
(.=?) :: (ToJson t, JsonReadable t, Typeable t) => TypedKey (Maybe t) -> (k -> Maybe t) -> FieldKey k (Maybe t)

-- | Describes JSON parsing and serialisation of a Haskell sum type.
--   Currently the library can only guarantee matching parsers/serialisers
--   for non-sum types using <a>JsonSpec</a>.
data JsonSumSpec k
JsonSumSpec :: !(ParseSpec k) -> !(k -> KeyedSerialiser k) -> JsonSumSpec k
js_parser :: JsonSumSpec k -> !(ParseSpec k)
js_serialiser :: JsonSumSpec k -> !(k -> KeyedSerialiser k)

-- | Associate a json key with a parser
(.->) :: ConstrTagger r => Text -> Parser (ResultType r) -> r

-- | Choice between multiple constructors
(<||>) :: KeyedConstr k -> ParseSpec k -> ParseSpec k

-- | Associate a JSON key with a serialiser
(.<-) :: ToJson a => Text -> a -> KeyedSerialiser k

-- | Construct a <a>Parser</a> from <a>JsonSpec</a> to implement
--   <a>JsonReadable</a> instances
makeParser :: JsonSpec k ts -> Parser k

-- | Construct a function from <a>JsonSpec</a> to implement <a>ToJson</a>
--   instances
makeSerialiser :: JsonSpec k ts -> k -> Value

-- | Construct a <a>Parser</a> from <a>JsonSumSpec</a> to implement
--   <a>JsonReadable</a> instances
makeSumParser :: JsonSumSpec k -> Parser k

-- | Construct a function from <a>JsonSumSpec</a> to implement
--   <a>ToJson</a> instances
makeSumSerialiser :: JsonSumSpec k -> k -> Value

-- | The class of types that can be converted to JSON values. See
--   <a>ObjectBuilder</a> for an example of writing a <a>ToJson</a>
--   instance for a custom data type.
--   
--   <a>ToJson</a> instances are provided for many common types. For
--   example, to create a JSON array, call <a>toJson</a> on a list or
--   <a>Vector</a>. To create a JSON object, call <a>toJson</a> on a
--   <a>HashMap</a>.
class ToJson a
toJson :: ToJson a => a -> Value

-- | Typeclass defining an attoparsec <a>Parser</a> how Haskell types
--   should be parsed from JSON. Use predifined instances (with
--   <a>readJson</a>) and <a>runSpec</a> (on <a>ObjSpec</a>) to define
--   instances for custom types
class JsonReadable t
readJson :: JsonReadable t => Parser t

-- | Parse json from a strict <a>ByteString</a>
parseJsonBs :: JsonReadable t => ByteString -> Either String t

-- | Parse json from a lazy <a>ByteString</a>
parseJsonBsl :: JsonReadable t => ByteString -> Either String t

-- | Parse json from a strict <a>Text</a>
parseJsonT :: JsonReadable t => Text -> Either String t

-- | Serialise json to a strict <a>ByteString</a>
serialiseJsonBs :: ToJson a => a -> ByteString

-- | Serialise json to a lazy <a>ByteString</a>
serialiseJsonBsl :: ToJson a => a -> ByteString

-- | Serialise json to a strict <a>Text</a>
serialiseJsonT :: ToJson a => a -> Text