-- 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 possible. Check
--   documentation of <a>Text.JSON.Gen</a> for more info.
@package fields-json
@version 0.4.0.0


-- | 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;- fromJSValueField "string_key"
--       i &lt;- fromJSValueField "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, MonadReader JSValue 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, MonadReader JSValue 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, MonadReader JSValue 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 :: (MonadReader JSValue 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 :: (MonadReader JSValue m, FromJSValue a) => String -> m (Maybe a)

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

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

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

-- | Generalization of <a>fromJSValueCustomMany</a>, where each element of
--   array can have different parser.
fromJSValueCustomList :: MonadReader JSValue 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 :: (MonadReader JSValue 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; 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.Word
instance Text.JSON.FromJSValue.FromJSValue GHC.Word.Word16
instance Text.JSON.FromJSValue.FromJSValue GHC.Word.Word32
instance Text.JSON.FromJSValue.FromJSValue GHC.Word.Word64
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 Text.JSON.ToJSValue.ToJSValue GHC.Integer.Type.Integer
instance Text.JSON.ToJSValue.ToJSValue GHC.Types.Int
instance Text.JSON.ToJSValue.ToJSValue GHC.Int.Int8
instance Text.JSON.ToJSValue.ToJSValue GHC.Int.Int16
instance Text.JSON.ToJSValue.ToJSValue GHC.Int.Int32
instance Text.JSON.ToJSValue.ToJSValue GHC.Int.Int64
instance Text.JSON.ToJSValue.ToJSValue GHC.Types.Word
instance Text.JSON.ToJSValue.ToJSValue GHC.Word.Word8
instance Text.JSON.ToJSValue.ToJSValue GHC.Word.Word16
instance Text.JSON.ToJSValue.ToJSValue GHC.Word.Word32
instance Text.JSON.ToJSValue.ToJSValue GHC.Word.Word64
instance Text.JSON.ToJSValue.ToJSValue GHC.Types.Double
instance Text.JSON.ToJSValue.ToJSValue GHC.Types.Float
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

-- | A monad that keeps currently constructed JSON.
data JSONGenT m a

-- | Runner. Example:
--   
--   <pre>
--   let js = runJSONGen $ do
--              value "abc" "def"
--   </pre>
runJSONGen :: JSONGen () -> JSValue

-- | Runner as monad transformer. Example:
--   
--   <pre>
--   js &lt;- runJSONGenT $ do
--              d &lt;- lift $ getFromOuterMonad
--              value "abc" d
--   </pre>
runJSONGenT :: Monad m => JSONGenT m () -> m JSValue

-- | Set pure value under given name in final JSON object. Example:
--   
--   <pre>
--   value "key" "value"
--   </pre>
value :: (Monad m, ToJSValue a) => String -> a -> JSONGenT m ()

-- | Monadic verion of <a>value</a> using monad transformer. Example:
--   
--   <pre>
--   js &lt;- runJSONGenT $ do
--            valueM "abc" (getLine)
--   </pre>
valueM :: (Monad m, ToJSValue a) => String -> m a -> JSONGenT m ()

-- | Embed other JSON object as field in a resulting JSON object. Example:
--   
--   <pre>
--   let js = runJSONGen $ do
--              object "nested" $ do
--                  value "abc" "def"
--   </pre>
object :: Monad m => String -> JSONGenT m () -> JSONGenT m ()

-- | Version for lists of objects. Example:
--   
--   <pre>
--   let js = runJSONGen $ do
--              objects "nested" [ do
--                                   value "abc" "def"
--                                   value "x" "y",
--                                 do
--                                   value "qwe" "rty"
--                               ]
--   </pre>
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 Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Text.JSON.Gen.JSONGenT m)