A (Decoder a) represents a way to marshal a value of type 'a' from Dhall into Haskell.

You can produce Decoders either explicitly:

example :: Decoder (Vector Text)
example = vector text

... or implicitly using auto:

example :: Decoder (Vector Text)
example = auto

You can consume Decoders using the input function:

input :: Decoder a -> Text -> IO a

Any value that implements FromDhall can be automatically decoded based on the inferred return type of input.

>>> input auto "[1, 2, 3]" :: IO (Vector Natural)
[1,2,3]
>>> input auto "toMap { a = False, b = True }" :: IO (Map Text Bool)
fromList [("a",False),("b",True)]

This class auto-generates a default implementation for types that implement Generic. This does not auto-generate an instance for recursive types.

The default instance can be tweaked using genericAutoWith/genericAutoWithInputNormalizer and custom InterpretOptions, or using DerivingVia and Codec from Dhall.Deriving.

A compatibility alias for FromDhall.

Use the default input normalizer for interpreting an input.

auto = autoWith defaultInputNormalizer

Decode a Bool.

>>> input bool "True"
True

Decode () from an empty record.

>>> input unit "{=}"  -- GHC doesn't print the result if it is ()

Decode Void from an empty union.

Since <> is uninhabited, input void will always fail.

Decode a Natural.

>>> input natural "42"
42

Decode a Word from a Dhall Natural.

>>> input word "42"
42

Decode a Word8 from a Dhall Natural.

>>> input word8 "42"
42

Decode a Word16 from a Dhall Natural.

>>> input word16 "42"
42

Decode a Word32 from a Dhall Natural.

>>> input word32 "42"
42

Decode a Word64 from a Dhall Natural.

>>> input word64 "42"
42

Decode an Integer.

>>> input integer "+42"
42

Decode an Int from a Dhall Integer.

>>> input int "-42"
-42

Decode an Int8 from a Dhall Integer.

>>> input int8 "-42"
-42

Decode an Int16 from a Dhall Integer.

>>> input int16 "-42"
-42

Decode an Int32 from a Dhall Integer.

>>> input int32 "-42"
-42

Decode an Int64 from a Dhall Integer.

>>> input int64 "-42"
-42

Decode a Scientific.

>>> input scientific "1e100"
1.0e100

Decode a Double.

>>> input double "42.0"
42.0

Decode a lazy ByteString.

>>> input lazyBytes "0x\"00FF\""
"\NUL\255"

Decode a strict ByteString

>>> input strictBytes "0x\"00FF\""
"\NUL\255"

Decode a ShortByteString

>>> input shortBytes "0x\"00FF\""
"\NUL\255"

Decode a String

>>> input string "\"ABC\""
"ABC"

Decode lazy Text.

>>> input lazyText "\"Test\""
"Test"

Decode strict Text.

>>> input strictText "\"Test\""
"Test"

Decode ShortText.

>>> input shortText "\"Test\""
"Test"

Decode TimeOfDay

>>> input timeOfDay "00:00:00"
00:00:00

Decode Day

>>> input day "2000-01-01"
2000-01-01

Decode TimeZone

>>> input timeZone "+00:00"
+0000

Decode LocalTime

>>> input localTime "2020-01-01T12:34:56"
2020-01-01 12:34:56

Decode ZonedTime

>>> input zonedTime "2020-01-01T12:34:56+02:00"
2020-01-01 12:34:56 +0200

Decode UTCTime

>>> input utcTime "2020-01-01T12:34:56+02:00"
2020-01-01 10:34:56 UTC

Decode DayOfWeek

>>> input dayOfWeek "< Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday >.Monday"
Monday

Decode a Maybe.

>>> input (maybe natural) "Some 1"
Just 1

Given a pair of Decoders, decode a tuple-record into their pairing.

>>> input (pair natural bool) "{ _1 = 42, _2 = False }"
(42,False)

Decode a Seq.

>>> input (sequence natural) "[1, 2, 3]"
fromList [1,2,3]

Decode a list.

>>> input (list natural) "[1, 2, 3]"
[1,2,3]

Decode a Vector.

>>> input (vector natural) "[1, 2, 3]"
[1,2,3]

Decode a Set from a List with distinct elements.

>>> input (setFromDistinctList natural) "[1, 2, 3]"
fromList [1,2,3]

An error is thrown if the list contains duplicates.

>>> input (setFromDistinctList natural) "[1, 1, 3]"
*** Exception: Error: Failed extraction

The expression type-checked successfully but the transformation to the target
type failed with the following error:

One duplicate element in the list: 1

>>> input (setFromDistinctList natural) "[1, 1, 3, 3]"
*** Exception: Error: Failed extraction

The expression type-checked successfully but the transformation to the target
type failed with the following error:

2 duplicates were found in the list, including 1

Decode a Set from a List.

>>> input (setIgnoringDuplicates natural) "[1, 2, 3]"
fromList [1,2,3]

Duplicate elements are ignored.

>>> input (setIgnoringDuplicates natural) "[1, 1, 3]"
fromList [1,3]

Decode a HashSet from a List with distinct elements.

>>> input (hashSetFromDistinctList natural) "[1, 2, 3]"
fromList [1,2,3]

An error is thrown if the list contains duplicates.

>>> input (hashSetFromDistinctList natural) "[1, 1, 3]"
*** Exception: Error: Failed extraction

The expression type-checked successfully but the transformation to the target
type failed with the following error:

One duplicate element in the list: 1

>>> input (hashSetFromDistinctList natural) "[1, 1, 3, 3]"
*** Exception: Error: Failed extraction

The expression type-checked successfully but the transformation to the target
type failed with the following error:

2 duplicates were found in the list, including 1

Decode a HashSet from a List.

>>> input (hashSetIgnoringDuplicates natural) "[1, 2, 3]"
fromList [1,2,3]

Duplicate elements are ignored.

>>> input (hashSetIgnoringDuplicates natural) "[1, 1, 3]"
fromList [1,3]

Decode a Map from a toMap expression or generally a Prelude.Map.Type.

>>> input (Dhall.map strictText bool) "toMap { a = True, b = False }"
fromList [("a",True),("b",False)]
>>> input (Dhall.map strictText bool) "[ { mapKey = \"foo\", mapValue = True } ]"
fromList [("foo",True)]

If there are duplicate mapKeys, later mapValues take precedence:

>>> let expr = "[ { mapKey = 1, mapValue = True }, { mapKey = 1, mapValue = False } ]"
>>> input (Dhall.map natural bool) expr
fromList [(1,False)]

Decode a HashMap from a toMap expression or generally a Prelude.Map.Type.

>>> fmap (List.sort . HashMap.toList) (input (Dhall.hashMap strictText bool) "toMap { a = True, b = False }")
[("a",True),("b",False)]
>>> fmap (List.sort . HashMap.toList) (input (Dhall.hashMap strictText bool) "[ { mapKey = \"foo\", mapValue = True } ]")
[("foo",True)]

If there are duplicate mapKeys, later mapValues take precedence:

>>> let expr = "[ { mapKey = 1, mapValue = True }, { mapKey = 1, mapValue = False } ]"
>>> input (Dhall.hashMap natural bool) expr
fromList [(1,False)]

Decode a tuple from a Prelude.Map.Entry record.

>>> input (pairFromMapEntry strictText natural) "{ mapKey = \"foo\", mapValue = 3 }"
("foo",3)

Decode a Dhall function into a Haskell function.

>>> f <- input (function inject bool) "Natural/even" :: IO (Natural -> Bool)
>>> f 0
True
>>> f 1
False

Decode a Dhall function into a Haskell function using the specified normalizer.

>>> f <- input (functionWith defaultInputNormalizer inject bool) "Natural/even" :: IO (Natural -> Bool)
>>> f 0
True
>>> f 1
False

The RecordDecoder applicative functor allows you to build a Decoder from a Dhall record.

For example, let's take the following Haskell data type:

>>> :{
data Project = Project
  { projectName :: Text
  , projectDescription :: Text
  , projectStars :: Natural
  }
:}

And assume that we have the following Dhall record that we would like to parse as a Project:

{ name =
    "dhall-haskell"
, description =
    "A configuration language guaranteed to terminate"
, stars =
    289
}

Our decoder has type Decoder Project, but we can't build that out of any smaller decoders, as Decoders cannot be combined (they are only Functors). However, we can use a RecordDecoder to build a Decoder for Project:

>>> :{
project :: Decoder Project
project =
  record
    ( Project <$> field "name" strictText
              <*> field "description" strictText
              <*> field "stars" natural
    )
:}

Run a RecordDecoder to build a Decoder.

Parse a single field of a record.

The UnionDecoder monoid allows you to build a Decoder from a Dhall union.

For example, let's take the following Haskell data type:

>>> :{
data Status = Queued Natural
            | Result Text
            | Errored Text
:}

And assume that we have the following Dhall union that we would like to parse as a Status:

< Result : Text
| Queued : Natural
| Errored : Text
>.Result "Finish successfully"

Our decoder has type Decoder Status, but we can't build that out of any smaller decoders, as Decoders cannot be combined (they are only Functors). However, we can use a UnionDecoder to build a Decoder for Status:

>>> :{
status :: Decoder Status
status = union
  (  ( Queued  <$> constructor "Queued"  natural )
  <> ( Result  <$> constructor "Result"  strictText )
  <> ( Errored <$> constructor "Errored" strictText )
  )
:}

Run a UnionDecoder to build a Decoder.

Parse a single constructor of a union.

This is the underlying class that powers the FromDhall class's support for automatically deriving a generic implementation.

This is the underlying class that powers the FromDhall class's support for automatically deriving a generic implementation for a union type.

genericAuto is the default implementation for auto if you derive FromDhall. The difference is that you can use genericAuto without having to explicitly provide a FromDhall instance for a type as long as the type derives Generic.

genericAutoWith is a configurable version of genericAuto.

genericAutoWithInputNormalizer is like genericAutoWith, but instead of using the defaultInputNormalizer it expects an custom InputNormalizer.

A newtype suitable for collecting one or more errors.

Render a given prefix and some errors to a string.

Every Decoder must obey the contract that if an expression's type matches the expected type then the extract function must not fail with a type error. However, decoding may still fail for other reasons (such as the decoder for Sets rejecting a Dhall List with duplicate elements).

This error type is used to indicate an internal error in the implementation of a Decoder where the expected type matched the Dhall expression, but the expression supplied to the extraction function did not match the expected type. If this happens that means that the Decoder itself needs to be fixed.

One or more errors returned from extracting a Dhall expression to a Haskell expression.

Extraction of a value can fail for two reasons, either a type mismatch (which should not happen, as expressions are type-checked against the expected type before being passed to extract), or a term-level error, described with a freeform text value.

Useful synonym for the Validation type used when marshalling Dhall expressions.

Generate a type error during extraction by specifying the expected type and the actual type. The expected type is not yet determined.

Turn a Text message into an extraction failure.

Useful synonym for the equivalent Either type used when marshalling Dhall code.

Switches from an Applicative extraction result, able to accumulate errors, to a Monad extraction result, able to chain sequential operations.

Switches from a Monad extraction result, able to chain sequential errors, to an Applicative extraction result, able to accumulate errors.

One or more errors returned when determining the Dhall type of a Haskell expression.

Error type used when determining the Dhall type of a Haskell expression.

Useful synonym for the Validation type used when marshalling Dhall expressions.

This is only used by the FromDhall instance for functions in order to normalize the function input before marshaling the input into a Dhall expression.

Default normalization-related settings (no custom normalization)

Use these options to tweak how Dhall derives a generic implementation of FromDhall.

This type specifies how to model a Haskell constructor with 1 field in Dhall

For example, consider the following Haskell datatype definition:

data Example = Foo { x :: Double } | Bar Double

Depending on which option you pick, the corresponding Dhall type could be:

< Foo : Double | Bar : Double >                   -- Bare

< Foo : { x : Double } | Bar : { _1 : Double } >  -- Wrapped

< Foo : { x : Double } | Bar : Double >           -- Smart

Default interpret options for generics-based instances, which you can tweak or override, like this:

genericAutoWith
    (defaultInterpretOptions { fieldModifier = Data.Text.Lazy.dropWhile (== '_') })

This type is exactly the same as Fix except with a different FromDhall instance. This intermediate type simplifies the implementation of the inner loop for the FromDhall instance for Fix.

Natural number

Invariant: numbers <= 0xffffffffffffffff use the NS constructor

General-purpose finite sequences.

A space efficient, packed, unboxed Unicode text type.