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


-- | Support for serialising Haskell to and from JSON
--   
@package json
@version 0.9


module Text.JSON.Types

-- | JSON values
--   
--   The type to which we encode Haskell values. There's a set of
--   primitives, and a couple of heterogenous collection types.
--   
--   Objects:
--   
--   An object structure is represented as a pair of curly brackets
--   surrounding zero or more name/value pairs (or members). A name is a
--   string. A single colon comes after each name, separating the name from
--   the value. A single comma separates a value from a following name.
--   
--   Arrays:
--   
--   An array structure is represented as square brackets surrounding zero
--   or more values (or elements). Elements are separated by commas.
--   
--   Only valid JSON can be constructed this way
data JSValue
JSNull :: JSValue
JSBool :: !Bool -> JSValue
JSRational :: Bool -> !Rational -> JSValue
JSString :: JSString -> JSValue
JSArray :: [JSValue] -> JSValue
JSObject :: (JSObject JSValue) -> JSValue

-- | Strings can be represented a little more efficiently in JSON
newtype JSString
JSONString :: String -> JSString
fromJSString :: JSString -> String

-- | Turn a Haskell string into a JSON string.
toJSString :: String -> JSString

-- | As can association lists
newtype JSObject e
JSONObject :: [(String, e)] -> JSObject e
fromJSObject :: JSObject e -> [(String, e)]

-- | Make JSON object out of an association list.
toJSObject :: [(String, a)] -> JSObject a

-- | Get the value of a field, if it exist.
get_field :: JSObject a -> String -> Maybe a

-- | Set the value of a field. Previous values are overwritten.
set_field :: JSObject a -> String -> a -> JSObject a
instance Typeable JSString
instance Typeable JSObject
instance Typeable JSValue
instance Eq JSString
instance Ord JSString
instance Show JSString
instance Read JSString
instance Eq e => Eq (JSObject e)
instance Ord e => Ord (JSObject e)
instance Show e => Show (JSObject e)
instance Read e => Read (JSObject e)
instance Show JSValue
instance Read JSValue
instance Eq JSValue
instance Ord JSValue


module Text.JSON.String

-- | Parsing JSON
--   
--   The type of JSON parsers for String
data GetJSON a

-- | Run a JSON reader on an input String, returning some Haskell value.
--   All input will be consumed.
runGetJSON :: GetJSON a -> String -> Either String a

-- | Read the JSON null type
readJSNull :: GetJSON JSValue

-- | Read the JSON Bool type
readJSBool :: GetJSON JSValue

-- | Read the JSON String type
readJSString :: GetJSON JSValue

-- | Read an Integer or Double in JSON format, returning a Rational
readJSRational :: GetJSON Rational

-- | Read a list in JSON format
readJSArray :: GetJSON JSValue

-- | Read an object in JSON format
readJSObject :: GetJSON JSValue

-- | Read one of several possible JS types
readJSValue :: GetJSON JSValue

-- | Top level JSON can only be Arrays or Objects
readJSTopType :: GetJSON JSValue

-- | Write the JSON null type
showJSNull :: ShowS

-- | Write the JSON Bool type
showJSBool :: Bool -> ShowS

-- | Show a list in JSON format
showJSArray :: [JSValue] -> ShowS

-- | Show an association list in JSON format
showJSObject :: JSObject JSValue -> ShowS

-- | Show a Rational in JSON format
showJSRational :: Rational -> ShowS
showJSRational' :: Bool -> Rational -> ShowS

-- | Show JSON values
showJSValue :: JSValue -> ShowS

-- | Writing JSON
--   
--   Show strict JSON top level types. Values not permitted at the top
--   level are wrapped in a singleton array.
showJSTopType :: JSValue -> ShowS
instance Monad GetJSON
instance Applicative GetJSON
instance Functor GetJSON


-- | Parse JSON values using the ReadP combinators.
module Text.JSON.ReadP
p_value :: ReadP JSValue
p_null :: ReadP ()
p_boolean :: ReadP Bool
p_array :: ReadP [JSValue]
p_string :: ReadP String
p_object :: ReadP [(String, JSValue)]
p_number :: ReadP Rational
p_js_string :: ReadP JSString
p_js_object :: ReadP (JSObject JSValue)


-- | Parse JSON values using the Parsec combinators.
module Text.JSON.Parsec
p_value :: CharParser () JSValue
p_null :: CharParser () ()
p_boolean :: CharParser () Bool
p_array :: CharParser () [JSValue]
p_string :: CharParser () String
p_object :: CharParser () [(String, JSValue)]
p_number :: CharParser () Rational
p_js_string :: CharParser () JSString
p_js_object :: CharParser () (JSObject JSValue)
p_jvalue :: CharParser () JSValue


-- | Display JSON values using pretty printing combinators.
module Text.JSON.Pretty
pp_value :: JSValue -> Doc
pp_null :: Doc
pp_boolean :: Bool -> Doc
pp_number :: Bool -> Rational -> Doc
pp_array :: [JSValue] -> Doc
pp_string :: String -> Doc
pp_object :: [(String, JSValue)] -> Doc
pp_js_string :: JSString -> Doc
pp_js_object :: JSObject JSValue -> Doc


module Text.JSON

-- | JSON values
--   
--   The type to which we encode Haskell values. There's a set of
--   primitives, and a couple of heterogenous collection types.
--   
--   Objects:
--   
--   An object structure is represented as a pair of curly brackets
--   surrounding zero or more name/value pairs (or members). A name is a
--   string. A single colon comes after each name, separating the name from
--   the value. A single comma separates a value from a following name.
--   
--   Arrays:
--   
--   An array structure is represented as square brackets surrounding zero
--   or more values (or elements). Elements are separated by commas.
--   
--   Only valid JSON can be constructed this way
data JSValue
JSNull :: JSValue
JSBool :: !Bool -> JSValue
JSRational :: Bool -> !Rational -> JSValue
JSString :: JSString -> JSValue
JSArray :: [JSValue] -> JSValue
JSObject :: (JSObject JSValue) -> JSValue

-- | The class of types serialisable to and from JSON
class JSON a where readJSONs (JSArray as) = mapM readJSON as readJSONs _ = mkError "Unable to read list" showJSONs = JSArray . map showJSON
readJSON :: JSON a => JSValue -> Result a
showJSON :: JSON a => a -> JSValue
readJSONs :: JSON a => JSValue -> Result [a]
showJSONs :: JSON a => [a] -> JSValue

-- | A type for parser results
data Result a
Ok :: a -> Result a
Error :: String -> Result a

-- | Encode a Haskell value into a string, in JSON format.
--   
--   This is a superset of JSON, as types other than Array and Object are
--   allowed at the top level.
encode :: JSON a => a -> String

-- | Decode a String representing a JSON value (either an object, array,
--   bool, number, null)
--   
--   This is a superset of JSON, as types other than Array and Object are
--   allowed at the top level.
decode :: JSON a => String -> Result a

-- | Encode a value as a String in strict JSON format. This follows the
--   spec, and requires all values at the top level to be wrapped in either
--   an Array or Object. JSON types to be an Array or Object.
encodeStrict :: JSON a => a -> String

-- | Decode a String representing a strict JSON value. This follows the
--   spec, and requires top level JSON types to be an Array or Object.
decodeStrict :: JSON a => String -> Result a

-- | Strings can be represented a little more efficiently in JSON
data JSString

-- | Turn a Haskell string into a JSON string.
toJSString :: String -> JSString
fromJSString :: JSString -> String

-- | As can association lists
data JSObject e

-- | Make JSON object out of an association list.
toJSObject :: [(String, a)] -> JSObject a
fromJSObject :: JSObject e -> [(String, e)]

-- | Map Results to Eithers
resultToEither :: Result a -> Either String a

-- | Read the JSON null type
readJSNull :: GetJSON JSValue

-- | Read the JSON Bool type
readJSBool :: GetJSON JSValue

-- | Read the JSON String type
readJSString :: GetJSON JSValue

-- | Read an Integer or Double in JSON format, returning a Rational
readJSRational :: GetJSON Rational

-- | Read a list in JSON format
readJSArray :: GetJSON JSValue

-- | Read an object in JSON format
readJSObject :: GetJSON JSValue

-- | Read one of several possible JS types
readJSValue :: GetJSON JSValue

-- | Write the JSON null type
showJSNull :: ShowS

-- | Write the JSON Bool type
showJSBool :: Bool -> ShowS

-- | Show a list in JSON format
showJSArray :: [JSValue] -> ShowS

-- | Show a Rational in JSON format
showJSRational :: Rational -> ShowS
showJSRational' :: Bool -> Rational -> ShowS

-- | Show an association list in JSON format
showJSObject :: JSObject JSValue -> ShowS

-- | Show JSON values
showJSValue :: JSValue -> ShowS
makeObj :: [(String, JSValue)] -> JSValue

-- | Pull a value out of a JSON object.
valFromObj :: JSON a => String -> JSObject JSValue -> Result a

-- | Haskell types that can be used as keys in JSON objects.
class JSKey a
toJSKey :: JSKey a => a -> String
fromJSKey :: JSKey a => String -> Maybe a

-- | Encode an association list as <a>JSObject</a> value.
encJSDict :: (JSKey a, JSON b) => [(a, b)] -> JSValue

-- | Decode a <a>JSObject</a> value into an association list.
decJSDict :: (JSKey a, JSON b) => String -> JSValue -> Result [(a, b)]
instance Eq a => Eq (Result a)
instance Show a => Show (Result a)
instance JSKey String
instance JSKey Int
instance JSKey JSString
instance JSON Text
instance JSON ByteString
instance JSON ByteString
instance JSON IntSet
instance (Ix i, JSON i, JSON e) => JSON (Array i e)
instance (Ord a, JSON a) => JSON (Set a)
instance JSON a => JSON (IntMap a)
instance (Ord a, JSON a, JSON b) => JSON (Map a b)
instance JSON a => JSON [a]
instance (JSON a, JSON b, JSON c, JSON d) => JSON (a, b, c, d)
instance (JSON a, JSON b, JSON c) => JSON (a, b, c)
instance (JSON a, JSON b) => JSON (a, b)
instance JSON ()
instance (JSON a, JSON b) => JSON (Either a b)
instance JSON a => JSON (Maybe a)
instance JSON Float
instance JSON Double
instance JSON Int64
instance JSON Int32
instance JSON Int16
instance JSON Int8
instance JSON Word64
instance JSON Word32
instance JSON Word16
instance JSON Word8
instance JSON Word
instance JSON Int
instance JSON Integer
instance JSON Ordering
instance JSON Char
instance JSON Bool
instance JSON a => JSON (JSObject a)
instance JSON JSString
instance JSON JSValue
instance Monad Result
instance MonadPlus Result
instance Alternative Result
instance Applicative Result
instance Functor Result


-- | JSON serializer and deserializer using Data.Generics. The functions
--   here handle algebraic data types and primitive types. It uses the same
--   representation as <a>Text.JSON</a> for <a>Prelude</a> types.
module Text.JSON.Generic

-- | The <a>Data</a> class comprehends a fundamental primitive
--   <a>gfoldl</a> for folding over constructor applications, say terms.
--   This primitive can be instantiated in several ways to map over the
--   immediate subterms of a term; see the <tt>gmap</tt> combinators later
--   in this class. Indeed, a generic programmer does not necessarily need
--   to use the ingenious gfoldl primitive but rather the intuitive
--   <tt>gmap</tt> combinators. The <a>gfoldl</a> primitive is completed by
--   means to query top-level constructors, to turn constructor
--   representations into proper terms, and to list all possible datatype
--   constructors. This completion allows us to serve generic programming
--   scenarios like read, show, equality, term generation.
--   
--   The combinators <a>gmapT</a>, <a>gmapQ</a>, <a>gmapM</a>, etc are all
--   provided with default definitions in terms of <a>gfoldl</a>, leaving
--   open the opportunity to provide datatype-specific definitions. (The
--   inclusion of the <tt>gmap</tt> combinators as members of class
--   <a>Data</a> allows the programmer or the compiler to derive
--   specialised, and maybe more efficient code per datatype. <i>Note</i>:
--   <a>gfoldl</a> is more higher-order than the <tt>gmap</tt> combinators.
--   This is subject to ongoing benchmarking experiments. It might turn out
--   that the <tt>gmap</tt> combinators will be moved out of the class
--   <a>Data</a>.)
--   
--   Conceptually, the definition of the <tt>gmap</tt> combinators in terms
--   of the primitive <a>gfoldl</a> requires the identification of the
--   <a>gfoldl</a> function arguments. Technically, we also need to
--   identify the type constructor <tt>c</tt> for the construction of the
--   result type from the folded term type.
--   
--   In the definition of <tt>gmapQ</tt><i>x</i> combinators, we use
--   phantom type constructors for the <tt>c</tt> in the type of
--   <a>gfoldl</a> because the result type of a query does not involve the
--   (polymorphic) type of the term argument. In the definition of
--   <a>gmapQl</a> we simply use the plain constant type constructor
--   because <a>gfoldl</a> is left-associative anyway and so it is readily
--   suited to fold a left-associative binary operation over the immediate
--   subterms. In the definition of gmapQr, extra effort is needed. We use
--   a higher-order accumulation trick to mediate between left-associative
--   constructor application vs. right-associative binary operation (e.g.,
--   <tt>(:)</tt>). When the query is meant to compute a value of type
--   <tt>r</tt>, then the result type withing generic folding is <tt>r
--   -&gt; r</tt>. So the result of folding is a function to which we
--   finally pass the right unit.
--   
--   With the <tt>-XDeriveDataTypeable</tt> option, GHC can generate
--   instances of the <a>Data</a> class automatically. For example, given
--   the declaration
--   
--   <pre>
--   data T a b = C1 a b | C2 deriving (Typeable, Data)
--   </pre>
--   
--   GHC will generate an instance that is equivalent to
--   
--   <pre>
--   instance (Data a, Data b) =&gt; Data (T a b) where
--       gfoldl k z (C1 a b) = z C1 `k` a `k` b
--       gfoldl k z C2       = z C2
--   
--       gunfold k z c = case constrIndex c of
--                           1 -&gt; k (k (z C1))
--                           2 -&gt; z C2
--   
--       toConstr (C1 _ _) = con_C1
--       toConstr C2       = con_C2
--   
--       dataTypeOf _ = ty_T
--   
--   con_C1 = mkConstr ty_T "C1" [] Prefix
--   con_C2 = mkConstr ty_T "C2" [] Prefix
--   ty_T   = mkDataType "Module.T" [con_C1, con_C2]
--   </pre>
--   
--   This is suitable for datatypes that are exported transparently.
class Typeable * a => Data a

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable (a :: k)

-- | Convert anything to a JSON value.
toJSON :: Data a => a -> JSValue

-- | Convert a JSON value to anything (fails if the types do not match).
fromJSON :: Data a => JSValue -> Result a

-- | Encode a value as a string.
encodeJSON :: Data a => a -> String

-- | Decode a string as a value.
decodeJSON :: Data a => String -> a
toJSON_generic :: Data a => a -> JSValue
fromJSON_generic :: Data a => JSValue -> Result a