-- 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 <a>Text.JSON</a> is
--   painful. And autoderivation is not always posible. Check documentation
--   of <a>Text.JSON.Gen</a> for more info.
@package fields-json
@version 0.2.2.4


-- | 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 Text.JSON.JSValueContainer.JSValueContainer Text.JSON.Types.JSValue
instance Text.JSON.JSValueContainer.JSValueContainer (Data.Sequence.Internal.Seq (GHC.Base.String, Text.JSON.Types.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>).
--   
--   Example implementation:
--   
--   <pre>
--   data D = D String Int
--   
--   instance FromJSValue D where
--     fromJSValue = do
--       s &lt;- fromJSValue "string_key"
--       i &lt;- fromJSValue "int_key"
--       return (D &lt;$&gt; s &lt;*&gt; i)
--   </pre>
--   
--   Note that we make use of <a>MonadReader</a> instance for "(-&gt;)" and
--   of <a>Applicative</a> programming style with <a>&lt;$&gt;</a> and
--   <a>&lt;*&gt;</a>.
--   
--   Note: <a>fromJSValueM</a> is deprecated, in future <a>fromJSValue</a>
--   will be generalized to work in any <a>MonadReader</a> <a>JSValue</a>.
class FromJSValue a
fromJSValue :: FromJSValue a => JSValue -> Maybe a
fromJSValueM :: (FromJSValue a, JSValueContainer c, MonadReader c m) => m (Maybe a)

-- | Structures that can be <tt>parsed</tt> from JSON, fields absent in the
--   JSON will be filled in using (optional) original structure.
--   
--   By convention JSON null should be treated as a request to reset
--   structure element to default value.
class FromJSValueWithUpdate a
fromJSValueWithUpdate :: FromJSValueWithUpdate a => Maybe a -> JSValue -> Maybe a
fromJSValueWithUpdateM :: (FromJSValueWithUpdate a, JSValueContainer c, MonadReader c m) => Maybe a -> m (Maybe a)

-- | Structures that can be matched with JSValue
class MatchWithJSValue a
matchesWithJSValue :: MatchWithJSValue a => a -> JSValue -> Bool
matchesWithJSValueM :: (MatchWithJSValue a, JSValueContainer c, MonadReader c m) => a -> m Bool

-- | Reading the value that is on some field. Returns <a>Nothing</a> if
--   JSON is not an object or field is present but cannot be parsed, 'Just
--   Nothing' if absent, and 'Just (Just a)' otherwise
jsValueField :: (JSValueContainer c, MonadReader c m, FromJSValue a) => String -> m (Maybe (Maybe a))

-- | Reading the value that is on a field. Semantics are a bit involved,
--   example GHCi session should clarify:
--   
--   <pre>
--   Prelude&gt; :set -XNoMonomorphismRestriction
--   Prelude&gt; let x = withJSValue (JSObject (toJSObject [("key",JSString $ toJSString "value")]))
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe Int)
--   Nothing
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe (Maybe Int))
--   Just Nothing
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe (Maybe (Maybe Int)))
--   Just (Just Nothing)
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe String)
--   Just "value"
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe (Maybe String))
--   Just (Just "value")
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe (Maybe (Maybe String)))
--   Just (Just (Just "value"))
--   Prelude&gt; let x = withJSValue (JSArray [])
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe String)
--   Nothing
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe (Maybe String))
--   Nothing
--   Prelude&gt; x (fromJSValueField "key") :: IO (Maybe (Maybe (Maybe String)))
--   Nothing
--   </pre>
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])

-- | Runs parser on each element of underlying json. Returns <a>Just</a>
--   iff JSON is an array.
--   
--   Note: This method has quadratic complexity. It is better to write less
--   general matching algorithms that use Maps.
fromJSValueManyWithUpdate :: (JSValueContainer c, MonadReader c m, FromJSValueWithUpdate a, MatchWithJSValue a) => [a] -> m (Maybe [a])

-- | Simple runner. Example:
--   
--   <pre>
--   let (v :: MyStruct) = runIdentity $ withJSValue js (fromJSValueM)
--   </pre>
--   
--   or inline:
--   
--   <pre>
--   let z = runIdentity $ withJSValue js $ do
--               a &lt;- fromJSValueField "a"
--               b &lt;- fromJSValueField "b"
--               c &lt;- fromJSValueField "c"
--               return ((,,) &lt;$&gt; a &lt;*&gt; b &lt;*&gt; &lt;*&gt; c)
--   </pre>
--   
--   or using the monad transformer:
--   
--   <pre>
--   z &lt;- withJSValue js $ do
--               a &lt;- fromJSValueField "a"
--               b &lt;- fromJSValueField "b"
--               c &lt;- fromJSValueField "c"
--               return ((,,) &lt;$&gt; a &lt;*&gt; b &lt;*&gt; c)
--   </pre>
withJSValue :: Monad m => JSValue -> ReaderT JSValue m a -> m a
instance Text.JSON.FromJSValue.FromJSValue Text.JSON.Types.JSValue
instance Text.JSON.FromJSValue.FromJSValue GHC.Base.String
instance Text.JSON.FromJSValue.FromJSValue Data.ByteString.Internal.ByteString
instance Text.JSON.FromJSValue.FromJSValue GHC.Integer.Type.Integer
instance Text.JSON.FromJSValue.FromJSValue GHC.Types.Int
instance Text.JSON.FromJSValue.FromJSValue GHC.Int.Int16
instance Text.JSON.FromJSValue.FromJSValue GHC.Int.Int32
instance Text.JSON.FromJSValue.FromJSValue GHC.Int.Int64
instance Text.JSON.FromJSValue.FromJSValue GHC.Types.Bool
instance Text.JSON.FromJSValue.FromJSValue GHC.Types.Double
instance Text.JSON.FromJSValue.FromJSValue GHC.Types.Float
instance Text.JSON.FromJSValue.FromJSValue a => Text.JSON.FromJSValue.FromJSValue [a]
instance Text.JSON.FromJSValue.FromJSValue a => Text.JSON.FromJSValue.FromJSValue (GHC.Maybe.Maybe a)
instance (Text.JSON.FromJSValue.FromJSValue a, Text.JSON.FromJSValue.FromJSValue b) => Text.JSON.FromJSValue.FromJSValue (a, b)
instance (Text.JSON.FromJSValue.FromJSValue a, Text.JSON.FromJSValue.FromJSValue b, Text.JSON.FromJSValue.FromJSValue c) => Text.JSON.FromJSValue.FromJSValue (a, b, c)
instance (Text.JSON.FromJSValue.FromJSValue a, Text.JSON.FromJSValue.FromJSValue b, Text.JSON.FromJSValue.FromJSValue c, Text.JSON.FromJSValue.FromJSValue d) => Text.JSON.FromJSValue.FromJSValue (a, b, c, d)
instance (Text.JSON.FromJSValue.FromJSValue a, Text.JSON.FromJSValue.FromJSValue b, Text.JSON.FromJSValue.FromJSValue c, Text.JSON.FromJSValue.FromJSValue d, Text.JSON.FromJSValue.FromJSValue e) => Text.JSON.FromJSValue.FromJSValue (a, b, c, d, e)
instance (Text.JSON.FromJSValue.FromJSValue a, Text.JSON.FromJSValue.FromJSValue b, Text.JSON.FromJSValue.FromJSValue c, Text.JSON.FromJSValue.FromJSValue d, Text.JSON.FromJSValue.FromJSValue e, Text.JSON.FromJSValue.FromJSValue f) => Text.JSON.FromJSValue.FromJSValue (a, b, c, d, e, f)


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


-- | Abusing monadic 'do' notation library for generating JSON object.
--   Hard-bound to <a>JSValue</a> from 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.
--   The <a>objects</a> function is there to support arrays of
--   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:
--   
--   <pre>
--   {a : "a", b: [1,2,3], c: {x: true, y : false}}
--   </pre>
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 Control.Monad.Trans.Class.MonadTrans Text.JSON.Gen.JSONGenT
instance GHC.Base.Monad m => GHC.Base.Monad (Text.JSON.Gen.JSONGenT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Text.JSON.Gen.JSONGenT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Text.JSON.Gen.JSONGenT m)
instance GHC.Base.Monad m => Control.Monad.Reader.Class.MonadReader (Data.Sequence.Internal.Seq (GHC.Base.String, Text.JSON.Types.JSValue)) (Text.JSON.Gen.JSONGenT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Text.JSON.Gen.JSONGenT m)