Given a definition of a value and a value produce a Value.

Example:

let v = Thing { ... }
let json = unjsonToJSON unjsonThing v

Given a definition of a value and a value produce a Value. Takes Options.

Example:

let v = Thing { ... }
let json = unjsonToJSON' options unjsonThing v

Given a definition of a value and a value produce a ByteString.

Example:

let v = Thing { ... }
let utf8bsrep = unjsonToByteStringLazy unjsonThing v

Given a definition of a value and a value produce a ByteString. Also takes formatting Options.

Example:

let v = Thing { ... }
let utf8bsrep = unjsonToByteStringLazy' options unjsonThing v

Given a definition of a value and a value produce a Builder. Functionally it is the same as unjsonToByteStringLazy but useful if json serialization is a part of some bigger serialization function.

Given a definition of a value and a value produce a Builder. Functionally it is the same as unjsonToByteStringLazy but useful if json serialization is a part of some bigger serialization function. Also takes formatting Options.

Given a definition of a value and a value produce a Builder. Useful when JSON serialization is a part of a bigger serialization function.

Formatting options when serializing to JSON. Used in unjsonToJSON', unjsonToByteStringLazy' and unjsonToByteStringBuilder'.

Unjson typeclass describes all types that can be parsed from JSON and JSON generated from their values.

Example declaration:

instance Unjson Thing where
    unjsonDef = objectOf $ pure Thing
        <*> field "key1"
              thingField1
              "Required field of type with Unjson instance"
        <*> fieldBy "key2"
              thingField2
              "Required field with parser given below"
              unjsonForKey2
        <*> fieldOpt "key4"
              thingField4
              "Optional field of type with Unjson instance"
        <*> fieldOptBy "key5"
              thingField5
              "Optional field with parser given below"
              unjsonForKey5
        <*> fieldDef "key7"
              thingField7
              "Optional field with default of type with Unjson instance"
        <*> fieldDefBy "key8"
              thingField8
              "Optional field with default with parser given below"
              unjsonForKey8

Opaque UnjsonDef defines a bidirectional JSON parser.

Declare an object as bidirectional mapping from JSON object to Haskell record and back.

Example:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure Thing
   ...field definitions go here

Use field functions to specify fields of an object: field, fieldBy, fieldOpt, fieldOptBy, fieldDef or fieldDefBy.

Declare a required field with definition from Unjson typeclass.

Example:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure Thing
   <*> field "credentials"
         thingCredentials
         "Credentials to use"

data Thing = Thing { thingCredentials :: Credentials, ... }
instance Unjson Credentials where ...

Declare a required field with definition given inline by valuedef.

Example:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure Thing
   <*> fieldBy "credentials"
         thingCredentials
         "Credentials to use"
         unjsonCredentials

data Thing = Thing { thingCredentials :: Credentials, ... }
unjsonCredentials :: UnjsonDef Credentials

Declare an optional field and definition by Unjson typeclass.

Example:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure Thing
   <*> fieldOpt "credentials"
         thingCredentials
         "Optional credentials to use"

data Thing = Thing { thingCredentials :: Credentials, ... }
instance Unjson Credentials where ...

Declare an optional field and definition by valuedef.

Example:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure Thing
   <*> fieldOptBy "credentials"
         thingCredentials
         "Optional credentials to use"
         unjsonCredentials

data Thing = Thing { thingCredentials :: Credentials, ... }
unjsonCredentials :: UnjsonDef Credentials

Declare a field with default value and definition by Unjson typeclass.

Example:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure Thing
   <*> fieldDef "port" 80
         thingPort
         "Port to listen on, defaults to 80"

data Thing = Thing { thingPort :: Int, ... }

Declare a field with default value and definition by valuedef.

Example:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure Thing
   <*> fieldDefBy "credentials" defaultCredentials
         thingCredentials
         "Credentials to use, defaults to defaultCredentials"
         unjsonCredentials

data Thing = Thing { thingCredentials :: Credentials, ... }
unjsonCredentials :: UnjsonDef Credentials

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:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure (\s -> Thing 59123 s)
   <* fieldReadonly "port"
         thingPort
         "Random port the server is listening on"
   <*> field "string"
         thingString
         "Additional string"

data Thing = Thing { thingPort :: Int, thingString :: String, ... }

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:

unjsonThing :: UnjsonDef Thing
unjsonThing = objectOf $ pure (\s -> Thing 59123 s)
   <* fieldReadonlyBy "port"
         thingPort
         "Random port the server is listening on"
         unjsonPort
   <*> field "string"
         thingString
         "Additional string"

data Thing = Thing { thingPort :: Port, thingString :: String, ... }

Define a relation between a field of an object in JSON and a field in a Haskell record structure. FieldDef holds information about a documentation string, key name, Haskell data accessor and parsing definition. FieldDef has three cases for fields that are required, optional (via Maybe) or jave default value.

Declare array of values where each of them is described by valuedef. Use unjsonAeson to parse.

Example:

unjsonArrayOfThings :: UnjsonDef [Thing]
unjsonArrayOfThings = arrayOf unjsonThing

unjsonThing :: UnjsonDef Thing
unjsonThing = ...

Declare array of values where each of them is described by valuedef. Accepts mode specifier.

Example:

unjsonArrayOfThings :: UnjsonDef [Thing]
unjsonArrayOfThings = arrayOf unjsonThing

unjsonThing :: UnjsonDef Thing
unjsonThing = ...

Declare array of objects with given parsers that should be matched by a primary key. Uses ArrayModeStrict.

Primary key:

Primary keys are used to match objects in update mode. When a request to update array is issued and array has primary key specification then the following steps are used:

1. 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
2. for each object in json array primary key is extracted and is looked up in old elements mapping
3. if mapping is found then element is updated, if mapping is not found then element is parsed
4. in all cases the order of elements in the *new* array is respected

Example:

unjsonArrayOfIntToInt :: UnjsonDef [(Int,Int)]
unjsonArrayOfIntToInt = arrayWithPrimaryKeyOf
                             (fst)
                             (objectOf $ pure id
                                <*> field "key" id "Key in mapping")
                             (objectOf $ pure (,)
                                <*> field "key" fst "Key in mapping"
                                <*> field "value" fst "Value in mapping")

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 arrayWithPrimaryKeyOf. For discussion of array modes see ArrayMode.

Example:

unjsonArrayOfIntToInt :: UnjsonDef [(Int,Int)]
unjsonArrayOfIntToInt = arrayWithPrimaryKeyOf ArrayModeParseSingle
                             (fst)
                             (objectOf $ pure id
                                <*> field "key" id "Key in mapping")
                             (objectOf $ pure (,)
                                <*> field "key" fst "Key in mapping"
                                <*> field "value" fst "Value in mapping")

Specify how arrays should be handled. Default is ArrayModeStrict that does not do anything special with arrays.

ArrayMode is used in arrayWithModeAndPrimaryKeyOf and arrayWithModeOf.

Gather all keys with respective values in a map.

Example:

data X = X { xMap :: LazyHashMap.HashMap Text.Text x }

objectOf $ pure X
  <*> fieldBy "xmap" xMap
      "Map string to Y value"
      (mapOf unjsonY)

Note that overloading allows for automatic conversion to more map types, for example:

data X = X { xMap :: Map.Map String x }

objectOf $ pure X
  <*> field "xmap" xMap
      "Map string to Y value"

Provide sum type support for parameterless constructors.

For related functionality see disjointUnionOf.

Example:

data X = A | B

unjsonX = enumOf "type_thing"
            [("a_thing", A),
             ("b_thing", B)]

Automatic sum type conversion with parameterless constructors.

Basically an automatic version of enumOf.

Example:

data X = A | B deriving (Eq, Data, Enum, Bounded)

instance Unjson X where unjsonDef = enumUnjsonDef

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

Example:

data X = A { aString :: String } | B { bInt :: Int }
            deriving (Data,Typeable)

unjsonX = disjointUnionOf "type"
            [("a_thing", unjsonIsConstrByName "A",
              pure A <*> field "string" "A string value"),
             ("b_thing", unjsonIsConstrByName "B",
              pure B <*> field "string" "An int value")]

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 unjsonIsConstrByName is helpful, but you may use usual case ... of if you do not like the Data typeclass.

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

Example:

data X = A { aString :: String } | B { bInt :: Int }
            deriving (Data,Typeable)

unjsonX = unionOf
            [(unjsonIsConstrByName "A",
              pure A <*> field "string" "A string value"),
             (unjsonIsConstrByName "B",
              pure B <*> field "int" "An int value")]

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 unjsonIsConstrByName is helpful, but you may use usual case ... of if you do not like the Data typeclass.

Use fromJSON and toJSON to create a UnjsonDef. 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 UnjsonDef instance whenever possible.

Example:

instance FromJSON MyType where ...
instance ToJSON MyType where ...
instance Unjson MyType where
    unjsonDef = unjsonAeson

Like unjsonAeson but accepts docstring as additional parameter that should identify type.

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:

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

Render only selected part of structure documentation. Path should point to a subtree, if it does not then Nothing is returned.

Renders documentation for a parser into a Doc. See render for example.

Render only selected part of structure documentation as Doc. Path should point to a subtree, if it does not then Nothing is returned.

Parse JSON according to unjson definition.

Example:

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)

Error reporting is a strong side of Unjson, see Result.

For parsing of fields the following rules apply:

• required fields generate an error if json key is missing
• for optional fields Nothing is returned if json key is missing, Just value otherwise
• for fields with default value, the default value is returned if key is missing, otherwise the parsed value is returned

Note that Unjson makes strong difference between missing keys and values that result in parse errors.

For discussion of update mode see update.

Update object with JSON according to unjson definition.

Example:

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)

Error reporting is a strong side of Unjson, see Result.

For updating of fields the following rules apply:

• required fields take the original value if json key is missing
• optional fields take the original value if json key is missing unless the value is null, then Nothing is returned (reset to Nothing)
• fields with default value take the original value if json key is missing unless the value is null, then the default value is returned (reset to default)

Note that Unjson makes strong difference between missing keys and values that result in parse errors.

For discussion of parse mode see parse.

Parsing result. The value a is only reliable when Problems is an empty list.

Problems is list of issues encountered while parsing. Unjson 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:

[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"]

conveniently rendered as:

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

A value at a specific position in JSON object.

Problem information is represented as a Text attached to a specific point in the JSON represenation tree.

In general JSON deserialization may result in many problems. Unjson reports all the problems at once.

Paths are rendered in a nice way. For example: key.key2[34] indexes into "key", then into "key2" then into index 34 of an array.

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: Int and Text. See Path.

Useful in DisjointUnjsonDef as second element in tuples list to check out if constructor is matching.

Example:

data X = A | B | C
unjsonIsConstrByName "B" B => True

Parse and serialize dotted decimal notation for IPv4 addresses and uses Word32 as representation type. Note that network byte order applies, so 127.0.0.1 is 0x7F000001.