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


-- | Abusing monadic syntax JSON objects generation.
--   
--   Generation of big, complex JSON objects with Text.JSON is painful. And
--   autoderivation is not always posible. Check documentation of
--   Text.JSON.Gen for more info.
@package fields-json
@version 0.2.1


-- | Data structures that hold JSValue inside. Value can be extracted or
--   replaced, but is always inside.
module Text.JSON.JSValueContainer
class JSValueContainer a
getJSValue :: JSValueContainer a => a -> JSValue
setJSValue :: JSValueContainer a => JSValue -> a -> a
instance [incoherent] JSValueContainer (Seq (String, JSValue))
instance [incoherent] JSValueContainer JSValue


-- | Interface for extracting data from JSValue.
module Text.JSON.FromJSValue

-- | Structures that can be <tt>parsed</tt> from JSON. Instances must
--   declare either <a>fromJSValue</a> (parse directly from <a>JSValue</a>)
--   or <a>fromJSValueM</a> (uses <a>MonadReader</a>)
class FromJSValue a where fromJSValue j = runIdentity $ withJSValue j $ liftM fromJSValueM askJSValue fromJSValueM = liftM fromJSValue askJSValue
fromJSValue :: FromJSValue a => JSValue -> Maybe a
fromJSValueM :: (FromJSValue a, JSValueContainer c, MonadReader c m) => m (Maybe a)

-- | Reading the value that is on some field. With field if current JSON is
--   not object
fromJSValueField :: (JSValueContainer c, MonadReader c m, FromJSValue a) => String -> m (Maybe a)

-- | Version of <a>fromJSValueField</a> for Base64 encoded data to avoid
--   memory leak.
fromJSValueFieldBase64 :: (JSValueContainer c, MonadReader c m) => String -> m (Maybe ByteString)

-- | Generalization of <a>fromJSValueField</a>. Does not use
--   <a>FromJSValue</a> instances
fromJSValueFieldCustom :: (JSValueContainer c, MonadReader c m) => String -> m (Maybe a) -> m (Maybe a)

-- | Runs parser on each element of underlaying json. Returns Just iff JSON
--   is array.
fromJSValueCustomMany :: (JSValueContainer c, MonadReader c m) => m (Maybe a) -> m (Maybe [a])

-- | Generalization of <a>fromJSValueCustomMany</a>, where each element of
--   array can have different parser.
fromJSValueCustomList :: (JSValueContainer c, MonadReader c m) => [m (Maybe a)] -> m (Maybe [a])

-- | Simple runner
withJSValue :: Monad m => JSValue -> ReaderT JSValue m a -> m a
instance [incoherent] (FromJSValue a, FromJSValue b) => FromJSValue (a, b)
instance [incoherent] FromJSValue a => FromJSValue (Maybe a)
instance [incoherent] FromJSValue a => FromJSValue [a]
instance [incoherent] FromJSValue Bool
instance [incoherent] FromJSValue Int
instance [incoherent] FromJSValue Integer
instance [incoherent] FromJSValue ByteString
instance [incoherent] FromJSValue String
instance [incoherent] FromJSValue JSValue


-- | Unifing some structures so they can be serialized to JSValue
module Text.JSON.ToJSValue
class ToJSValue a
toJSValue :: ToJSValue a => a -> JSValue
instance [incoherent] (ToJSValue a, ToJSValue b) => ToJSValue (a, b)
instance [incoherent] ToJSValue a => ToJSValue (Maybe a)
instance [incoherent] ToJSValue a => ToJSValue (Map String a)
instance [incoherent] ToJSValue a => ToJSValue [a]
instance [incoherent] Real a => ToJSValue a
instance [incoherent] ToJSValue String
instance [incoherent] ToJSValue Bool
instance [incoherent] ToJSValue JSValue


-- | Abusing monadic 'do' notation library for generating JSON object.
--   Hard-binded to json package from hackage. Main ideas
--   
--   <ul>
--   <li>Overloaded function <a>value</a> to set values in underlying JSON
--   - <a>Bool</a>, <a>Int</a>, <a>String</a>, lists etc.</li>
--   <li>JSON generation may not be pure with <a>valueM</a>. You can
--   perform some IO while generating JSON. This is usefull skip useless
--   inner binding.</li>
--   <li>Compositionality - use <a>object</a> to easy create JSON
--   objects</li>
--   <li>Monadic notation - it really looks nicer then composition with
--   <a>.</a> or some magic combinator</li>
--   </ul>
--   
--   <pre>
--   runJSONGen $ do
--       value "a" "a"
--       value "b" [1,2,3]
--       object "c" $ do
--           value "x" True
--           value "y" False
--   </pre>
--   
--   Will generate json object {a : <a>a</a>, b: [1,2,3], c: {x: true, y :
--   false}}
module Text.JSON.Gen

-- | Basic types
type JSONGen = JSONGenT Identity
data JSONGenT m a

-- | Simple runner
runJSONGen :: JSONGen () -> JSValue
runJSONGenT :: Monad m => JSONGenT m () -> m JSValue

-- | Set pure value under given name in final JSON object
value :: (Monad m, ToJSValue a) => String -> a -> JSONGenT m ()

-- | Monadic verion of <a>value</a>
valueM :: (Monad m, ToJSValue a) => String -> m a -> JSONGenT m ()

-- | Embed other JSON object as field in resulting JSON object.
object :: Monad m => String -> JSONGenT m () -> JSONGenT m ()

-- | Version for lists of objects.
objects :: Monad m => String -> [JSONGenT m ()] -> JSONGenT m ()
instance [incoherent] (Monad m, Functor m) => Applicative (JSONGenT m)
instance [incoherent] Functor m => Functor (JSONGenT m)
instance [incoherent] Monad m => Monad (JSONGenT m)
instance [incoherent] MonadTrans JSONGenT
instance [incoherent] MonadIO m => MonadIO (JSONGenT m)
instance [incoherent] Monad m => MonadReader (Seq (String, JSValue)) (JSONGenT m)