libghc-json-doc 0.9.1-5build4 / usr / share / doc / libghc-json-doc / html / json.txt

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


-- | Support for serialising Haskell to and from JSON
--   
--   JSON (JavaScript Object Notation) is a lightweight data-interchange
--   format. It is easy for humans to read and write. It is easy for
--   machines to parse and generate. It is based on a subset of the
--   JavaScript Programming Language, Standard ECMA-262 3rd Edition -
--   December 1999.
--   
--   This library provides a parser and pretty printer for converting
--   between Haskell values and JSON.
@package json
@version 0.9.1


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 GHC.Classes.Ord Text.JSON.Types.JSValue
instance GHC.Classes.Eq Text.JSON.Types.JSValue
instance GHC.Read.Read Text.JSON.Types.JSValue
instance GHC.Show.Show Text.JSON.Types.JSValue
instance GHC.Read.Read e => GHC.Read.Read (Text.JSON.Types.JSObject e)
instance GHC.Show.Show e => GHC.Show.Show (Text.JSON.Types.JSObject e)
instance GHC.Classes.Ord e => GHC.Classes.Ord (Text.JSON.Types.JSObject e)
instance GHC.Classes.Eq e => GHC.Classes.Eq (Text.JSON.Types.JSObject e)
instance GHC.Read.Read Text.JSON.Types.JSString
instance GHC.Show.Show Text.JSON.Types.JSString
instance GHC.Classes.Ord Text.JSON.Types.JSString
instance GHC.Classes.Eq Text.JSON.Types.JSString


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 GHC.Base.Functor Text.JSON.String.GetJSON
instance GHC.Base.Applicative Text.JSON.String.GetJSON
instance GHC.Base.Monad Text.JSON.String.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)


-- | 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


-- | 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


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 GHC.Show.Show a => GHC.Show.Show (Text.JSON.Result a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.JSON.Result a)
instance GHC.Base.Functor Text.JSON.Result
instance GHC.Base.Applicative Text.JSON.Result
instance GHC.Base.Alternative Text.JSON.Result
instance GHC.Base.MonadPlus Text.JSON.Result
instance GHC.Base.Monad Text.JSON.Result
instance Text.JSON.JSON Text.JSON.Types.JSValue
instance Text.JSON.JSON Text.JSON.Types.JSString
instance Text.JSON.JSON a => Text.JSON.JSON (Text.JSON.Types.JSObject a)
instance Text.JSON.JSON GHC.Types.Bool
instance Text.JSON.JSON GHC.Types.Char
instance Text.JSON.JSON GHC.Types.Ordering
instance Text.JSON.JSON GHC.Integer.Type.Integer
instance Text.JSON.JSON GHC.Types.Int
instance Text.JSON.JSON GHC.Types.Word
instance Text.JSON.JSON GHC.Word.Word8
instance Text.JSON.JSON GHC.Word.Word16
instance Text.JSON.JSON GHC.Word.Word32
instance Text.JSON.JSON GHC.Word.Word64
instance Text.JSON.JSON GHC.Int.Int8
instance Text.JSON.JSON GHC.Int.Int16
instance Text.JSON.JSON GHC.Int.Int32
instance Text.JSON.JSON GHC.Int.Int64
instance Text.JSON.JSON GHC.Types.Double
instance Text.JSON.JSON GHC.Types.Float
instance Text.JSON.JSON a => Text.JSON.JSON (GHC.Base.Maybe a)
instance (Text.JSON.JSON a, Text.JSON.JSON b) => Text.JSON.JSON (Data.Either.Either a b)
instance Text.JSON.JSON ()
instance (Text.JSON.JSON a, Text.JSON.JSON b) => Text.JSON.JSON (a, b)
instance (Text.JSON.JSON a, Text.JSON.JSON b, Text.JSON.JSON c) => Text.JSON.JSON (a, b, c)
instance (Text.JSON.JSON a, Text.JSON.JSON b, Text.JSON.JSON c, Text.JSON.JSON d) => Text.JSON.JSON (a, b, c, d)
instance Text.JSON.JSON a => Text.JSON.JSON [a]
instance (GHC.Classes.Ord a, Text.JSON.JSON a, Text.JSON.JSON b) => Text.JSON.JSON (Data.Map.Base.Map a b)
instance Text.JSON.JSON a => Text.JSON.JSON (Data.IntMap.Base.IntMap a)
instance (GHC.Classes.Ord a, Text.JSON.JSON a) => Text.JSON.JSON (Data.Set.Base.Set a)
instance (GHC.Arr.Ix i, Text.JSON.JSON i, Text.JSON.JSON e) => Text.JSON.JSON (GHC.Arr.Array i e)
instance Text.JSON.JSON Data.IntSet.Base.IntSet
instance Text.JSON.JSON Data.ByteString.Internal.ByteString
instance Text.JSON.JSON Data.ByteString.Lazy.Internal.ByteString
instance Text.JSON.JSON Data.Text.Internal.Text
instance Text.JSON.JSKey Text.JSON.Types.JSString
instance Text.JSON.JSKey GHC.Types.Int
instance Text.JSON.JSKey GHC.Base.String


-- | 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 k (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