JSON Decoder

A value that describes how values are decoded from JSON. This type is an alternative to Aeson's FromJSON instance implementation.

Use decode, decode, eitherDecode, eitherDecode' decodeStrict, decodeStrict', eitherDecodeStrict or eitherDecodeStrict' alternatives provided by this module for decoding from BytString.

For decoding files use decodeFileStrict, decodeFileStrict' eitherDecodeFileStrict, eitherDecodeFileStrict' also provided by this module.

Using Instances of Decoder

Functor to map function over Decoder

intToString :: Decoder String
intToString = show <$> Decode.int

>>> decode intToString "2"
Just "2"

Applicateve to construct products

stringIntPair :: Decoder (String, Int)
stringIntPair = (,) <$> index 0 string
                    <*> index 1 int

>>> decode stringIntPair "[\"hello\", 42]"
Just ("hello", 42)

Alternative to construct sums

eitherTextOrInt :: Decoder (Either Text Int)
eitherTextOrInt = Left  <$> Decode.text
              <|> Right <$> Decode.int

>>> decode eitherTextOrInt "\"Lorem Ipsum\""
Just (Left "Lorem Ipsum")
>>> decode eitherTextOrInt "42"
Just (Right 42)

Monad for Decoder chaining

odd :: Decoder Int
odd = do
  val <- int
  if val `mod` 2 == 1
  then $ return val
  else fail $ "Expected odd value, got " <> show val

>>> eitherDecode odd "3"
Left 3
>>> eitherDecode odd "4"
Right "Error in $: Expected odd value, got 4"

Decoder is compatible with Aeson's FromJSON class. auto decoder acts like a proxy to instance implementation. Any type that is an instance of this class is automatically compatible.

While auto is universally usable for all primitive values, this library provides individual type constraint functions for decoding those values.

Decode any JSON value to Void value which is impossible to construct.

This Decoder is guarenteed to fail.

Decode JSON null into '()'

Decode JSON booleans to Haskell Bool

Decode JSON number to Int

Decode JSON number to unbounded Integer

Decode JSON number to Int8

Decode JSON number to Int16

Decode JSON number to Int32

Decode JSON number to Int64

Decode JSON number to bounded Word

Decode JSON number to bounded Word8

Decode JSON number to bounded Word16

Decode JSON number to bounded Word32

Decode JSON number to bounded Word64

Decode JSON number to GHC's Natural (non negative)

This function requires base >= 4.8.0

Decode JSON number to Float

Decode JSON number to Double

Decode JSON number to arbitrary precision Scientific

Decode single character JSON string to Char

Decode JSON string to Text

Decode JSON string to String

Decode JSON string to UUID

Decode JSON string to Version

Decode JSON string to ZonedTime using Aeson's instance implementation.

Supported string formats:

YYYY-MM-DD HH:MM Z YYYY-MM-DD HH:MM:SS Z YYYY-MM-DD HH:MM:SS.SSS Z

The first space may instead be a T, and the second space is optional. The Z represents UTC. The Z may be replaced with a time zone offset of the form +0000 or -08:00, where the first two digits are hours, the : is optional and the second two digits (also optional) are minutes.

Decode JSON string to LocalTime using Aeson's instance implementation.

Decode JSON string to TimeOfDay using Aeson's instance implementation.

Decode JSON string to UTCTime using Aesons's instance implementation

Decode JSON string to Day using Aesons's instance implementation

Decode JSON string to DayOfWeek using Aesons's instance implementation

Decode JSON null and other JSON value to Maybe. JSON null will be decoded to Nothing. Other value decoded by provided Decoder to Just

Decode JSON array of values to '[a]' of values using provided Decoder.

Decode JSON array of values to Vector of values using provided Decoder.

Decode JSON object to HashMap with Text key using provided Decoder.

Decode JSON object to HashMap with Text key using provided Decoder.

Decode JSON object to Map with Text key using provided Decoder.

Decode JSON object to Map with Text key using provided Decoder.

Decode JSON null to any value. This function is usefull if you have custom constructor which represented by null in JSONs.

data Codomain = NotSet | Foo | Bar

myDomainDecoder :: Decoder Codomain
myDomainDecoder = jsonNull NotSet
              <|> (text >>= fooBar)
   where fooBar "foo"   = return Foo
         fooBar "bar"   = return Bar
         fooBar unknown = fail $ "Unknown value " <> show unknown

Extract JSON value from JSON object key

>>> decode (key "data" int) "{\"data\": 42}"
Just 42

Extract JSON value from JSON object keys

>>> decode (at ["data", "value"] int) "{\"data\": {\"value\": 42}}"
Just 42

Extract JSON value from JSON array index

>>> decode (index 2 int) "[0,1,2,3,4]"
Just 2

Extract JSON value from JSON array indexes

>>> decode (indexes [0,1,0] int) "[[true, [42]]]"
Just 42

Decode value from JSON structure.

From object key:

>>> decode (element (Key "data") text) "{\"data\": \"foo\"}"
Just "foo"

From array index:

>>> decode (element (Index 1) int) "[0,1,2]"
Just 1

Decode value from deep JSON structure.

>>> decode (path [Key "data", Index 0] bool) "{\"data\":[true, false, false]}"
Just True

Efficiently deserialize a JSON value from a lazy ByteString. If this fails due to incomplete or invalid input, Nothing is returned.

The input must consist solely of a JSON document, with no trailing data except for whitespace.

This function parses immediately, but defers conversion. See json for details.

Efficiently deserialize a JSON value from a lazy ByteString. If this fails due to incomplete or invalid input, Nothing is returned.

The input must consist solely of a JSON document, with no trailing data except for whitespace.

This function parses and performs conversion immediately. See json' for details.

Like decode but returns an error message when decoding fails.

Like decode' but returns an error message when decoding fails.

Efficiently deserialize a JSON value from a strict ByteString. If this fails due to incomplete or invalid input, Nothing is returned.

The input must consist solely of a JSON document, with no trailing data except for whitespace.

This function parses immediately, but defers conversion. See json for details.

Efficiently deserialize a JSON value from a strict ByteString. If this fails due to incomplete or invalid input, Nothing is returned.

The input must consist solely of a JSON document, with no trailing data except for whitespace.

This function parses and performs conversion immediately. See json' for details.

Like decodeStrict but returns an error message when decoding fails.

Like decodeStrict' but returns an error message when decoding fails.

Efficiently deserialize a JSON value from a file. If this fails due to incomplete or invalid input, Nothing is returned.

The input file's content must consist solely of a JSON document, with no trailing data except for whitespace.

This function parses immediately, but defers conversion. See json for details.

Efficiently deserialize a JSON value from a file. If this fails due to incomplete or invalid input, Nothing is returned.

The input file's content must consist solely of a JSON document, with no trailing data except for whitespace.

This function parses and performs conversion immediately. See json' for details.

Like decodeFileStrict but returns an error message when decoding fails.

Like decodeFileStrict' but returns an error message when decoding fails.