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


-- | Bidirectional JSON parsing and generation.
--   
--   Bidirectional JSON parsing and generation with automatic documentation
--   support.
@package unjson
@version 0.14


-- | <tt>Unjson</tt>: bidirectional JSON (de)serialization with strong
--   error reporting capabilities and automatic documentation generation.
--   
--   <tt>Data.Unjson</tt> offers:
--   
--   <ul>
--   <li>single definition for serialization and deserialization</li>
--   <li>parse and update mode</li>
--   <li>exact error reporting</li>
--   <li>required, optional and fields with default values</li>
--   <li>first class object, array and tuple support</li>
--   <li>lifting of Aeson instances</li>
--   <li>automatic documentation generation</li>
--   </ul>
--   
--   Example:
--   
--   <pre>
--   data Example = Example
--      { exampleName     :: Text.Text,
--        exampleArray    :: [Int],
--        exampleOptional :: Maybe Bool }
--   
--   unjsonExample :: UnjsonDef Example
--   unjsonExample = objectOf $ pure Example
--     &lt;*&gt; field "name"
--             exampleName
--             "Name used for example"
--     &lt;*&gt; fieldDefBy "array_of_ints" []
--             exampleArray
--             "Array of integers, optional, defaults to empty list"
--             arrayOf
--     &lt;*&gt; fieldOpt "optional_bool"
--             exampleOptional
--             "Optional boolean"
--   </pre>
--   
--   Rendered documentation:
--   
--   <pre>
--   name (req):
--       Name used for example
--       Text
--   array_of_ints (def):
--       Array of integers, optional, defaults to empty list
--       array of:
--           Int
--   optional_bool (opt):
--       Optional boolean
--       Bool
--   </pre>
--   
--   Documentation has some colors that could not be reproduced in haddock.
--   
--   Parsing:
--   
--   <pre>
--   let Result val iss = parse unjsonExample (Anchored mempty $
--                                   object [ "name" .= 123,
--                                            "array_of_ints" .= [toJSON 123, toJSON "abc"],
--                                            "optional_bool" .= True ])
--   </pre>
--   
--   Error reporting:
--   
--   <pre>
--   mapM_ print iss
--   &gt; name: "when expecting a Text, encountered Number instead"
--   &gt; array_of_ints[1]: "when expecting a Integral, encountered String instead"
--   </pre>
--   
--   Partial results:
--   
--   <pre>
--   print (exampleOptional val)
--   &gt; Just True
--   </pre>
--   
--   Bottom errors in partial results:
--   
--   <pre>
--   print (exampleName val)
--   &gt; "*** Exception: name: "when expecting a Text, encountered Number instead"
--   </pre>
--   
--   Note: if list of issues is empty then there are not bottoms,
--   guaranteed.
--   
--   For more examples have a look at <a>Unjson</a>, <a>parse</a>,
--   <a>update</a>, <a>unjsonToJSON</a>, <a>unjsonToByteStringLazy</a>,
--   <a>unjsonToByteStringBuilder</a> and <a>render</a>.
module Data.Unjson

-- | Given a definition of a value and a value produce a <a>Value</a>.
--   
--   Example:
--   
--   <pre>
--   let v = Thing { ... }
--   let json = unjsonToJSON unjsonThing v
--   </pre>
unjsonToJSON :: UnjsonDef a -> a -> Value

-- | Given a definition of a value and a value produce a <a>Value</a>.
--   Takes <a>Options</a>.
--   
--   Example:
--   
--   <pre>
--   let v = Thing { ... }
--   let json = unjsonToJSON' options unjsonThing v
--   </pre>
unjsonToJSON' :: Options -> UnjsonDef a -> a -> Value

-- | Given a definition of a value and a value produce a <a>ByteString</a>.
--   
--   Example:
--   
--   <pre>
--   let v = Thing { ... }
--   let utf8bsrep = unjsonToByteStringLazy unjsonThing v
--   </pre>
unjsonToByteStringLazy :: UnjsonDef a -> a -> ByteString

-- | Given a definition of a value and a value produce a <a>ByteString</a>.
--   Also takes formatting <a>Options</a>.
--   
--   Example:
--   
--   <pre>
--   let v = Thing { ... }
--   let utf8bsrep = unjsonToByteStringLazy' options unjsonThing v
--   </pre>
unjsonToByteStringLazy' :: Options -> UnjsonDef a -> a -> ByteString

-- | Given a definition of a value and a value produce a <a>Builder</a>.
--   Functionally it is the same as <a>unjsonToByteStringLazy</a> but
--   useful if json serialization is a part of some bigger serialization
--   function.
unjsonToByteStringBuilder :: UnjsonDef a -> a -> Builder

-- | Given a definition of a value and a value produce a <a>Builder</a>.
--   Functionally it is the same as <a>unjsonToByteStringLazy</a> but
--   useful if json serialization is a part of some bigger serialization
--   function. Also takes formatting <a>Options</a>.
unjsonToByteStringBuilder' :: Options -> UnjsonDef a -> a -> Builder

-- | Given a definition of a value and a value produce a <a>Builder</a>.
--   Useful when JSON serialization is a part of a bigger serialization
--   function.
unjsonToByteStringBuilder'' :: Int -> Options -> UnjsonDef a -> a -> Builder

-- | Formatting options when serializing to JSON. Used in
--   <a>unjsonToJSON'</a>, <a>unjsonToByteStringLazy'</a> and
--   <a>unjsonToByteStringBuilder'</a>.
data Options
Options :: Bool -> Int -> Bool -> Options

-- | Pretty format. Use spaces and newlines.
[pretty] :: Options -> Bool

-- | Amount of spaces for indent. 4 looks good.
[indent] :: Options -> Int

-- | Output explicit nulls for absent optional fields.
[nulls] :: Options -> Bool

-- | <a>Unjson</a> typeclass describes all types that can be parsed from
--   JSON and JSON generated from their values.
--   
--   Example declaration:
--   
--   <pre>
--   instance Unjson Thing where
--       unjsonDef = objectOf $ pure Thing
--           &lt;*&gt; field "key1"
--                 thingField1
--                 "Required field of type with Unjson instance"
--           &lt;*&gt; fieldBy "key2"
--                 thingField2
--                 "Required field with parser given below"
--                 unjsonForKey2
--           &lt;*&gt; fieldOpt "key4"
--                 thingField4
--                 "Optional field of type with Unjson instance"
--           &lt;*&gt; fieldOptBy "key5"
--                 thingField5
--                 "Optional field with parser given below"
--                 unjsonForKey5
--           &lt;*&gt; fieldDef "key7"
--                 thingField7
--                 "Optional field with default of type with Unjson instance"
--           &lt;*&gt; fieldDefBy "key8"
--                 thingField8
--                 "Optional field with default with parser given below"
--                 unjsonForKey8
--   </pre>
class Unjson a

-- | Definition of a bidirectional parser for a type <tt>a</tt>. See
--   <a>parse</a>, <a>update</a>, <tt>serialize</tt> and <a>render</a> to
--   see how to use <a>UnjsonDef</a>.
unjsonDef :: Unjson a => UnjsonDef a

-- | Opaque <a>UnjsonDef</a> defines a bidirectional JSON parser.
data UnjsonDef a
[SimpleUnjsonDef] :: Text -> (Value -> Result k) -> (k -> Value) -> UnjsonDef k
[ArrayUnjsonDef] :: Maybe (PrimaryKeyExtraction k) -> ArrayMode -> ([k] -> Result v) -> (v -> [k]) -> UnjsonDef k -> UnjsonDef v
[ObjectUnjsonDef] :: Ap (FieldDef k) (Result k) -> UnjsonDef k
[TupleUnjsonDef] :: Ap (TupleFieldDef k) (Result k) -> UnjsonDef k
[DisjointUnjsonDef] :: Text -> [(Text, k -> Bool, Ap (FieldDef k) (Result k))] -> UnjsonDef k
[UnionUnjsonDef] :: [(k -> Bool, Ap (FieldDef k) (Result k))] -> UnjsonDef k
[MapUnjsonDef] :: UnjsonDef k -> (HashMap Text k -> Result v) -> (v -> HashMap Text k) -> UnjsonDef v

-- | Declare an object as bidirectional mapping from JSON object to Haskell
--   record and back.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure Thing
--      ...field definitions go here
--   </pre>
--   
--   Use field functions to specify fields of an object: <a>field</a>,
--   <a>fieldBy</a>, <a>fieldOpt</a>, <a>fieldOptBy</a>, <a>fieldDef</a> or
--   <a>fieldDefBy</a>.
objectOf :: Ap (FieldDef a) a -> UnjsonDef a

-- | Declare a required field with definition from <a>Unjson</a> typeclass.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure Thing
--      &lt;*&gt; field "credentials"
--            thingCredentials
--            "Credentials to use"
--   
--   data Thing = Thing { thingCredentials :: Credentials, ... }
--   instance Unjson Credentials where ...
--   </pre>
field :: (Unjson a) => Text -> (s -> a) -> Text -> Ap (FieldDef s) a

-- | Declare a required field with definition given inline by valuedef.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure Thing
--      &lt;*&gt; fieldBy "credentials"
--            thingCredentials
--            "Credentials to use"
--            unjsonCredentials
--   
--   data Thing = Thing { thingCredentials :: Credentials, ... }
--   unjsonCredentials :: UnjsonDef Credentials
--   </pre>
fieldBy :: Text -> (s -> a) -> Text -> UnjsonDef a -> Ap (FieldDef s) a

-- | Declare an optional field and definition by <a>Unjson</a> typeclass.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure Thing
--      &lt;*&gt; fieldOpt "credentials"
--            thingCredentials
--            "Optional credentials to use"
--   
--   data Thing = Thing { thingCredentials :: Credentials, ... }
--   instance Unjson Credentials where ...
--   </pre>
fieldOpt :: (Unjson a) => Text -> (s -> Maybe a) -> Text -> Ap (FieldDef s) (Maybe a)

-- | Declare an optional field and definition by valuedef.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure Thing
--      &lt;*&gt; fieldOptBy "credentials"
--            thingCredentials
--            "Optional credentials to use"
--            unjsonCredentials
--   
--   data Thing = Thing { thingCredentials :: Credentials, ... }
--   unjsonCredentials :: UnjsonDef Credentials
--   </pre>
fieldOptBy :: Text -> (s -> Maybe a) -> Text -> UnjsonDef a -> Ap (FieldDef s) (Maybe a)

-- | Declare a field with default value and definition by <a>Unjson</a>
--   typeclass.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure Thing
--      &lt;*&gt; fieldDef "port" 80
--            thingPort
--            "Port to listen on, defaults to 80"
--   
--   data Thing = Thing { thingPort :: Int, ... }
--   </pre>
fieldDef :: (Unjson a) => Text -> a -> (s -> a) -> Text -> Ap (FieldDef s) a

-- | Declare a field with default value and definition by valuedef.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure Thing
--      &lt;*&gt; fieldDefBy "credentials" defaultCredentials
--            thingCredentials
--            "Credentials to use, defaults to defaultCredentials"
--            unjsonCredentials
--   
--   data Thing = Thing { thingCredentials :: Credentials, ... }
--   unjsonCredentials :: UnjsonDef Credentials
--   </pre>
fieldDefBy :: Text -> a -> (s -> a) -> Text -> UnjsonDef a -> Ap (FieldDef s) a

-- | Declare a field that is readonly from the point of view of Haskell
--   structures, it will be serialized to JSON but never read from JSON.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure (\s -&gt; Thing 59123 s)
--      &lt;* fieldReadonly "port"
--            thingPort
--            "Random port the server is listening on"
--      &lt;*&gt; field "string"
--            thingString
--            "Additional string"
--   
--   data Thing = Thing { thingPort :: Int, thingString :: String, ... }
--   </pre>
fieldReadonly :: (Unjson a) => Text -> (s -> a) -> Text -> Ap (FieldDef s) ()

-- | Declare a field that is readonly from the point of view of Haskell
--   structures, it will be serialized to JSON but never read from JSON.
--   Accepts unjson parser as a parameter.
--   
--   Example:
--   
--   <pre>
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = objectOf $ pure (\s -&gt; Thing 59123 s)
--      &lt;* fieldReadonlyBy "port"
--            thingPort
--            "Random port the server is listening on"
--            unjsonPort
--      &lt;*&gt; field "string"
--            thingString
--            "Additional string"
--   
--   data Thing = Thing { thingPort :: Port, thingString :: String, ... }
--   </pre>
fieldReadonlyBy :: Text -> (s -> a) -> Text -> UnjsonDef a -> Ap (FieldDef s) ()

-- | Define a relation between a field of an object in JSON and a field in
--   a Haskell record structure. <a>FieldDef</a> holds information about a
--   documentation string, key name, Haskell data accessor and parsing
--   definition. <a>FieldDef</a> has three cases for fields that are
--   required, optional (via <a>Maybe</a>) or jave default value.
data FieldDef s a
[FieldReqDef] :: Text -> Text -> (s -> a) -> UnjsonDef a -> FieldDef s a
[FieldOptDef] :: Text -> Text -> (s -> Maybe a) -> UnjsonDef a -> FieldDef s (Maybe a)
[FieldDefDef] :: Text -> Text -> a -> (s -> a) -> UnjsonDef a -> FieldDef s a
[FieldRODef] :: Text -> Text -> (s -> a) -> UnjsonDef a -> FieldDef s ()

-- | Declare array of values where each of them is described by valuedef.
--   Use <a>unjsonAeson</a> to parse.
--   
--   Example:
--   
--   <pre>
--   unjsonArrayOfThings :: UnjsonDef [Thing]
--   unjsonArrayOfThings = arrayOf unjsonThing
--   
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = ...
--   </pre>
arrayOf :: UnjsonDef a -> UnjsonDef [a]

-- | Declare array of values where each of them is described by valuedef.
--   Accepts mode specifier.
--   
--   Example:
--   
--   <pre>
--   unjsonArrayOfThings :: UnjsonDef [Thing]
--   unjsonArrayOfThings = arrayOf unjsonThing
--   
--   unjsonThing :: UnjsonDef Thing
--   unjsonThing = ...
--   </pre>
arrayWithModeOf :: ArrayMode -> UnjsonDef a -> UnjsonDef [a]

-- | Declare array of objects with given parsers that should be matched by
--   a primary key. Uses <a>ArrayModeStrict</a>.
--   
--   Primary key:
--   
--   Primary keys are used to match objects in <a>update</a> mode. When a
--   request to update array is issued and array has primary key
--   specification then the following steps are used:
--   
--   <ol>
--   <li>primary keys from old array elements are extracted and a mapping
--   from primary key to element is created. Mapping is left biased meaning
--   that first element with specific primary key in array is used</li>
--   <li>for each object in json array primary key is extracted and is
--   looked up in old elements mapping</li>
--   <li>if mapping is found then element is <a>update</a>d, if mapping is
--   not found then element is <a>parse</a>d</li>
--   <li>in all cases the order of elements in the *new* array is
--   respected</li>
--   </ol>
--   
--   Example:
--   
--   <pre>
--   unjsonArrayOfIntToInt :: UnjsonDef [(Int,Int)]
--   unjsonArrayOfIntToInt = arrayWithPrimaryKeyOf
--                                (fst)
--                                (objectOf $ pure id
--                                   &lt;*&gt; field "key" id "Key in mapping")
--                                (objectOf $ pure (,)
--                                   &lt;*&gt; field "key" fst "Key in mapping"
--                                   &lt;*&gt; field "value" fst "Value in mapping")
--   </pre>
arrayWithPrimaryKeyOf :: (Ord pk) => (a -> pk) -> UnjsonDef pk -> UnjsonDef a -> UnjsonDef [a]

-- | Declare array of objects with given parsers that should be matched by
--   a primary key and accepts mode specifier.
--   
--   For discussion of primary key see <a>arrayWithPrimaryKeyOf</a>. For
--   discussion of array modes see <a>ArrayMode</a>.
--   
--   Example:
--   
--   <pre>
--   unjsonArrayOfIntToInt :: UnjsonDef [(Int,Int)]
--   unjsonArrayOfIntToInt = arrayWithPrimaryKeyOf ArrayModeParseSingle
--                                (fst)
--                                (objectOf $ pure id
--                                   &lt;*&gt; field "key" id "Key in mapping")
--                                (objectOf $ pure (,)
--                                   &lt;*&gt; field "key" fst "Key in mapping"
--                                   &lt;*&gt; field "value" fst "Value in mapping")
--   </pre>
arrayWithModeAndPrimaryKeyOf :: (Ord pk) => ArrayMode -> (a -> pk) -> UnjsonDef pk -> UnjsonDef a -> UnjsonDef [a]

-- | Specify how arrays should be handled. Default is
--   <a>ArrayModeStrict</a> that does not do anything special with arrays.
--   
--   <a>ArrayMode</a> is used in <a>arrayWithModeAndPrimaryKeyOf</a> and
--   <a>arrayWithModeOf</a>.
data ArrayMode

-- | Require JSON array. On output always output array.
ArrayModeStrict :: ArrayMode

-- | Allow non-array element, in that case it will be treated as a single
--   element array. On output always output array.
ArrayModeParseSingle :: ArrayMode

-- | Allow non-array element, in that case it will be treated as a single
--   element array. On output output single element if array has one
--   element.
ArrayModeParseAndOutputSingle :: ArrayMode

-- | Gather all keys with respective values in a map.
--   
--   Example:
--   
--   <pre>
--   data X = X { xMap :: LazyHashMap.HashMap Text.Text x }
--   
--   objectOf $ pure X
--     &lt;*&gt; fieldBy "xmap" xMap
--         "Map string to Y value"
--         (mapOf unjsonY)
--   </pre>
--   
--   Note that overloading allows for automatic conversion to more map
--   types, for example:
--   
--   <pre>
--   data X = X { xMap :: Map.Map String x }
--   
--   objectOf $ pure X
--     &lt;*&gt; field "xmap" xMap
--         "Map string to Y value"
--   </pre>
mapOf :: UnjsonDef x -> UnjsonDef (HashMap Text x)

-- | Provide sum type support for parametersless constructors.
--   
--   For related functionality see <a>disjointUnionOf</a>.
--   
--   Example:
--   
--   <pre>
--   data X = A | B
--   
--   unjsonX = enumOf "type_thing"
--               [("a_thing", A),
--                ("b_thing", B)]
--   </pre>
enumOf :: (Eq k) => Text -> [(Text, k)] -> UnjsonDef k

-- | Provide sum type support. Bidirectional case matching in Haskell is
--   not good, so some obvious information needs to be given manually.
--   
--   For related functionality see <a>enumOf</a>.
--   
--   Example:
--   
--   <pre>
--   data X = A { aString :: String } | B { bInt :: Int }
--               deriving (Data,Typeable)
--   
--   unjsonX = disjointUnionOf "type"
--               [("a_thing", unjsonIsConstrByName "A",
--                 pure A &lt;*&gt; field "string" "A string value"),
--                ("b_thing", unjsonIsConstrByName "B",
--                 pure B &lt;*&gt; field "string" "An int value")]
--   </pre>
--   
--   Note that each case in list must be able to discriminate between
--   constructors in a data type and ti has to be able to this both ways:
--   to find out based on json contents which constructor applies and also
--   based on data contructor which of serialization cases to use.
--   
--   Note that <a>unjsonIsConstrByName</a> is helpful, but you may use
--   usual <tt>case ... of</tt> if you do not like the <a>Data</a>
--   typeclass.
disjointUnionOf :: Text -> [(Text, k -> Bool, Ap (FieldDef k) k)] -> UnjsonDef k

-- | Provide sum type support, non-disjoin version. Bidirectional case
--   matching in Haskell is not good, so some obvious information needs to
--   be given manually.
--   
--   For related functionality see <a>enumOf</a>.
--   
--   Example:
--   
--   <pre>
--   data X = A { aString :: String } | B { bInt :: Int }
--               deriving (Data,Typeable)
--   
--   unjsonX = unionOf
--               [(unjsonIsConstrByName "A",
--                 pure A &lt;*&gt; field "string" "A string value"),
--                (unjsonIsConstrByName "B",
--                 pure B &lt;*&gt; field "int" "An int value")]
--   </pre>
--   
--   Note that each case in list must be able to discriminate between
--   constructors in a data type and ti has to be able to this both ways:
--   to find out based on json contents which constructor applies and also
--   based on data contructor which of serialization cases to use. To know
--   what constructor to use at parsing time unjson looks at fields present
--   in json object and on list of field names required to satisfy. First
--   constructor for which all fields are present is chosen.
--   
--   Note that <a>unjsonIsConstrByName</a> is helpful, but you may use
--   usual <tt>case ... of</tt> if you do not like the <a>Data</a>
--   typeclass.
unionOf :: [(k -> Bool, Ap (FieldDef k) k)] -> UnjsonDef k

-- | Use <a>fromJSON</a> and <a>toJSON</a> to create a <a>UnjsonDef</a>.
--   This function is useful when lifted type is one of the primitives.
--   Although it can be used to lift user defined instances, it is not
--   advisable as there is too much information lost in the process and
--   proper error infomation is not possible. Use full <a>UnjsonDef</a>
--   instance whenever possible.
--   
--   Example:
--   
--   <pre>
--   instance FromJSON MyType where ...
--   instance ToJSON MyType where ...
--   instance Unjson MyType where
--       unjsonDef = unjsonAeson
--   </pre>
unjsonAeson :: forall a. (FromJSON a, ToJSON a, Typeable a) => UnjsonDef a

-- | Like <a>unjsonAeson</a> but accepts docstring as additional parameter
--   that should identify type.
unjsonAesonWithDoc :: (FromJSON a, ToJSON a) => Text -> UnjsonDef a

-- | Renders documentation for a parser into a multiline string. It is
--   expected that this string is a human readable representation that can
--   go directly to console.
--   
--   Example rendering:
--   
--   <pre>
--   hostname (req):
--       The hostname this service is visible as
--       Text
--   port (def):
--       Port to listen on, defaults to 80
--       Int
--   credentials (req):
--       User admin credentials
--       username (req):
--           Name of the user
--           Text
--       password (req):
--           Password for the user
--           Text
--       domain (opt):
--           Domain for user credentials
--           Text
--   comment (opt):
--       Optional comment, free text
--       Text
--   options (def):
--       Additional options, defaults to empty
--       array of:
--           Text
--   alternates (opt):
--       Alternate names for this server
--       tuple of size 2 with elements:
--       0:
--           Text
--       1:
--           username (req):
--               Name of the user
--               Text
--           password (req):
--               Password for the user
--               Text
--           domain (opt):
--               Domain for user credentials
--               Text
--   </pre>
render :: UnjsonDef a -> String

-- | Render only selected part of structure documentation. Path should
--   point to a subtree, if it does not then Nothing is returned.
renderForPath :: (Functor m, Monad m) => Path -> UnjsonDef a -> m String

-- | Renders documentation for a parser into a <a>Doc</a>. See
--   <a>render</a> for example.
renderDoc :: UnjsonDef a -> Doc

-- | Render only selected part of structure documentation as <a>Doc</a>.
--   Path should point to a subtree, if it does not then Nothing is
--   returned.
renderDocForPath :: (Monad m) => Path -> UnjsonDef a -> m Doc

-- | Parse JSON according to unjson definition.
--   
--   Example:
--   
--   <pre>
--   let json = Aeson.object [ ... ]
--   let Result val iss = parse unjsonThing (Anchored [] json)
--   if null iss
--     then putStrLn ("Parsed: " ++ show val)
--     else putStrLn ("Not parsed, issues: " ++ show iss)
--   </pre>
--   
--   Error reporting is a strong side of Unjson, see <a>Result</a>.
--   
--   For parsing of fields the following rules apply:
--   
--   <ul>
--   <li>required fields generate an error if json key is missing</li>
--   <li>for optional fields Nothing is returned if json key is missing,
--   Just value otherwise</li>
--   <li>for fields with default value, the default value is returned if
--   key is missing, otherwise the parsed value is returned</li>
--   </ul>
--   
--   Note that Unjson makes strong difference between missing keys and
--   values that result in parse errors.
--   
--   For discussion of update mode see <a>update</a>.
parse :: UnjsonDef a -> Value -> Result a

-- | Update object with JSON according to unjson definition.
--   
--   Example:
--   
--   <pre>
--   let original = Thing { ... }
--   let json = Aeson.object [ ... ]
--   let Result val iss = update original unjsonThing (Anchored [] json)
--   if null iss
--     then putStrLn ("Updated: " ++ show val)
--     else putStrLn ("Not updated, issues: " ++ show iss)
--   </pre>
--   
--   Error reporting is a strong side of Unjson, see <a>Result</a>.
--   
--   For updating of fields the following rules apply:
--   
--   <ul>
--   <li>required fields take the original value if json key is
--   missing</li>
--   <li>optional fields take the original value if json key is missing
--   unless the value is <tt>null</tt>, then Nothing is returned (reset to
--   Nothing)</li>
--   <li>fields with default value take the original value if json key is
--   missing unless the value is <tt>null</tt>, then the default value is
--   returned (reset to default)</li>
--   </ul>
--   
--   Note that Unjson makes strong difference between missing keys and
--   values that result in parse errors.
--   
--   For discussion of parse mode see <a>parse</a>.
update :: a -> UnjsonDef a -> Value -> Result a

-- | Parsing result. The value <tt>a</tt> is only reliable when
--   <a>Problems</a> is an empty list.
--   
--   <a>Problems</a> is list of issues encountered while parsing.
--   <a>Unjson</a> parsers continue forward and are able to find many
--   problems at once.
--   
--   Note that problems are anchored to specific elements of JSON so it
--   should be easy to find and spot an error.
--   
--   Even if list of problems is not empty, the returned value may be
--   partially usable.
--   
--   Examples of list of problems:
--   
--   <pre>
--   [Anchored [PathElemKey "credentials",PathElemKey "password"] "missing key",
--    Anchored [PathElemKey "tuple"] "cannot parse array of length 3 into tuple of size 4",
--    Anchored [PathElemKey "text_array",PathElemIndex 0.PathElemKey "value"]
--                                    "when expecting a Text, encountered Boolean instead"]
--   </pre>
--   
--   conveniently rendered as:
--   
--   <pre>
--   "credentials.password": "missing key"
--   "tuple": "cannot parse array of length 3 into tuple of size 4"
--   "text_array[0].value": "when expecting a Text, encountered Boolean instead"
--   </pre>
data Result a
Result :: a -> Problems -> Result a

-- | A value at a specific position in JSON object.
data Anchored a
Anchored :: Path -> a -> Anchored a

-- | Problem information is represented as a <a>Text</a> attached to a
--   specific point in the JSON represenation tree.
type Problem = Anchored Text

-- | In general JSON deserialization may result in many problems. Unjson
--   reports all the problems at once.
type Problems = [Problem]

-- | <a>Path</a>s are rendered in a nice way. For example:
--   <tt>key.key2[34]</tt> indexes into "key", then into "key2" then into
--   index 34 of an array.
newtype Path
Path :: [PathElem] -> Path

-- | Describe a path from root JSON element to a specific position. JSON
--   has only two types of containers: objects and arrays, so there are
--   only two types of keys needed to index into those containers:
--   <a>Int</a> and <a>Text</a>. See <a>Path</a>.
data PathElem
PathElemKey :: Text -> PathElem
PathElemIndex :: Int -> PathElem
unjsonInvmapR :: (a -> Result b) -> (b -> a) -> UnjsonDef a -> UnjsonDef b

-- | Useful in <a>DisjointUnjsonDef</a> as second element in tuples list to
--   check out if constructor is matching.
--   
--   Example:
--   
--   <pre>
--   data X = A | B | C
--   unjsonIsConstrByName "B" B =&gt; True
--   </pre>
unjsonIsConstrByName :: (Data a) => String -> a -> Bool

-- | Parse and serialize dotted decimal notation for IPv4 addresses and
--   uses <a>Word32</a> as representation type. Note that network byte
--   order applies, so 127.0.0.1 is 0x7F000001.
unjsonIPv4AsWord32 :: UnjsonDef Word32
instance GHC.Show.Show Data.Unjson.Options
instance GHC.Classes.Ord Data.Unjson.Options
instance GHC.Classes.Eq Data.Unjson.Options
instance GHC.Show.Show Data.Unjson.ArrayMode
instance GHC.Classes.Ord Data.Unjson.ArrayMode
instance GHC.Classes.Eq Data.Unjson.ArrayMode
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Unjson.Result a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Unjson.Result a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Unjson.Result a)
instance GHC.Base.Functor Data.Unjson.Result
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Unjson.Anchored a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Unjson.Anchored a)
instance GHC.Base.Functor Data.Unjson.Anchored
instance GHC.Base.Monoid Data.Unjson.Path
instance GHC.Classes.Ord Data.Unjson.Path
instance GHC.Classes.Eq Data.Unjson.Path
instance GHC.Show.Show Data.Unjson.PathElem
instance GHC.Classes.Ord Data.Unjson.PathElem
instance GHC.Classes.Eq Data.Unjson.PathElem
instance GHC.Show.Show Data.Unjson.Path
instance GHC.Show.Show a => GHC.Show.Show (Data.Unjson.Anchored a)
instance (Data.Typeable.Internal.Typeable a, GHC.Show.Show a) => GHC.Exception.Exception (Data.Unjson.Anchored a)
instance GHC.Base.Applicative Data.Unjson.Result
instance GHC.Base.Monad Data.Unjson.Result
instance Data.Unjson.Unjson a => Data.Unjson.Unjson [a]
instance Data.Unjson.Unjson GHC.Base.String
instance Data.Unjson.Unjson GHC.Types.Bool
instance Data.Unjson.Unjson GHC.Types.Char
instance Data.Unjson.Unjson GHC.Types.Double
instance Data.Unjson.Unjson GHC.Types.Float
instance Data.Unjson.Unjson GHC.Types.Int
instance Data.Unjson.Unjson GHC.Int.Int8
instance Data.Unjson.Unjson GHC.Int.Int16
instance Data.Unjson.Unjson GHC.Int.Int32
instance Data.Unjson.Unjson GHC.Int.Int64
instance Data.Unjson.Unjson GHC.Integer.Type.Integer
instance Data.Unjson.Unjson GHC.Types.Word
instance Data.Unjson.Unjson GHC.Word.Word8
instance Data.Unjson.Unjson GHC.Word.Word16
instance Data.Unjson.Unjson GHC.Word.Word32
instance Data.Unjson.Unjson GHC.Word.Word64
instance Data.Unjson.Unjson ()
instance Data.Unjson.Unjson Data.Text.Internal.Text
instance Data.Unjson.Unjson Data.Attoparsec.Number.Number
instance Data.Unjson.Unjson Data.IntSet.Base.IntSet
instance Data.Unjson.Unjson Data.Scientific.Scientific
instance Data.Unjson.Unjson Data.Text.Internal.Lazy.Text
instance Data.Unjson.Unjson Data.Time.LocalTime.LocalTime.ZonedTime
instance Data.Unjson.Unjson Data.Time.Clock.UTC.UTCTime
instance Data.Unjson.Unjson Data.Aeson.Types.Internal.DotNetTime
instance Data.Unjson.Unjson Data.Aeson.Types.Internal.Value
instance Data.Unjson.Unjson (GHC.Real.Ratio GHC.Integer.Type.Integer)
instance (Data.Fixed.HasResolution a, Data.Typeable.Internal.Typeable a, Data.Aeson.Types.FromJSON.FromJSON a, Data.Aeson.Types.ToJSON.ToJSON a) => Data.Unjson.Unjson (Data.Fixed.Fixed a)
instance Data.Unjson.Unjson a => Data.Unjson.Unjson (Data.Monoid.Dual a)
instance Data.Unjson.Unjson a => Data.Unjson.Unjson (Data.IntMap.Base.IntMap a)
instance (GHC.Classes.Ord a, Data.Unjson.Unjson a) => Data.Unjson.Unjson (Data.Set.Base.Set a)
instance (GHC.Classes.Eq a, Data.Hashable.Class.Hashable a, Data.Unjson.Unjson a) => Data.Unjson.Unjson (Data.HashSet.HashSet a)
instance Data.Unjson.Unjson a => Data.Unjson.Unjson (Data.Vector.Vector a)
instance (Data.Vector.Generic.Base.Vector Data.Vector.Unboxed.Base.Vector a, Data.Unjson.Unjson a, Data.Vector.Unboxed.Base.Unbox a) => Data.Unjson.Unjson (Data.Vector.Unboxed.Base.Vector a)
instance (Foreign.Storable.Storable a, Data.Unjson.Unjson a) => Data.Unjson.Unjson (Data.Vector.Storable.Vector a)
instance (Data.Primitive.Types.Prim a, Data.Unjson.Unjson a) => Data.Unjson.Unjson (Data.Vector.Primitive.Vector a)
instance Data.Unjson.Unjson v => Data.Unjson.Unjson (Data.Map.Base.Map GHC.Base.String v)
instance Data.Unjson.Unjson v => Data.Unjson.Unjson (Data.Map.Base.Map Data.Text.Internal.Text v)
instance Data.Unjson.Unjson v => Data.Unjson.Unjson (Data.Map.Base.Map Data.Text.Internal.Lazy.Text v)
instance Data.Unjson.Unjson v => Data.Unjson.Unjson (Data.HashMap.Base.HashMap GHC.Base.String v)
instance Data.Unjson.Unjson v => Data.Unjson.Unjson (Data.HashMap.Base.HashMap Data.Text.Internal.Text v)
instance Data.Unjson.Unjson v => Data.Unjson.Unjson (Data.HashMap.Base.HashMap Data.Text.Internal.Lazy.Text v)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b) => Data.Unjson.Unjson (a, b)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c) => Data.Unjson.Unjson (a, b, c)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d) => Data.Unjson.Unjson (a, b, c, d)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d, Data.Unjson.Unjson e) => Data.Unjson.Unjson (a, b, c, d, e)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d, Data.Unjson.Unjson e, Data.Unjson.Unjson f) => Data.Unjson.Unjson (a, b, c, d, e, f)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d, Data.Unjson.Unjson e, Data.Unjson.Unjson f, Data.Unjson.Unjson g) => Data.Unjson.Unjson (a, b, c, d, e, f, g)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d, Data.Unjson.Unjson e, Data.Unjson.Unjson f, Data.Unjson.Unjson g, Data.Unjson.Unjson h) => Data.Unjson.Unjson (a, b, c, d, e, f, g, h)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d, Data.Unjson.Unjson e, Data.Unjson.Unjson f, Data.Unjson.Unjson g, Data.Unjson.Unjson h, Data.Unjson.Unjson i) => Data.Unjson.Unjson (a, b, c, d, e, f, g, h, i)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d, Data.Unjson.Unjson e, Data.Unjson.Unjson f, Data.Unjson.Unjson g, Data.Unjson.Unjson h, Data.Unjson.Unjson i, Data.Unjson.Unjson j) => Data.Unjson.Unjson (a, b, c, d, e, f, g, h, i, j)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d, Data.Unjson.Unjson e, Data.Unjson.Unjson f, Data.Unjson.Unjson g, Data.Unjson.Unjson h, Data.Unjson.Unjson i, Data.Unjson.Unjson j, Data.Unjson.Unjson k) => Data.Unjson.Unjson (a, b, c, d, e, f, g, h, i, j, k)
instance (Data.Unjson.Unjson a, Data.Unjson.Unjson b, Data.Unjson.Unjson c, Data.Unjson.Unjson d, Data.Unjson.Unjson e, Data.Unjson.Unjson f, Data.Unjson.Unjson g, Data.Unjson.Unjson h, Data.Unjson.Unjson i, Data.Unjson.Unjson j, Data.Unjson.Unjson k, Data.Unjson.Unjson l) => Data.Unjson.Unjson (a, b, c, d, e, f, g, h, i, j, k, l)
instance Data.Functor.Invariant.Invariant Data.Unjson.UnjsonDef