Type-check and evaluate a Dhall program, decoding the result into Haskell

The first argument determines the type of value that you decode:

>>> input integer "+2"
2
>>> input (vector double) "[1.0, 2.0]"
[1.0,2.0]

Use auto to automatically select which type to decode based on the inferred return type:

>>> input auto "True" :: IO Bool
True

This uses the settings from defaultInputSettings.

Extend input with a root directory to resolve imports relative to, a file to mention in errors as the source, a custom typing context, and a custom normalization process.

Since: 1.16

Type-check and evaluate a Dhall program that is read from the file-system.

This uses the settings from defaultEvaluateSettings.

Since: 1.16

Extend inputFile with a custom typing context and a custom normalization process.

Since: 1.16

Similar to input, but without interpreting the Dhall Expr into a Haskell type.

Uses the settings from defaultInputSettings.

Extend inputExpr with a root directory to resolve imports relative to, a file to mention in errors as the source, a custom typing context, and a custom normalization process.

Since: 1.16

Access the directory to resolve imports relative to.

Since: 1.16

Access the name of the source to report locations from; this is only used in error messages, so it's okay if this is a best guess or something symbolic.

Since: 1.16

Access the starting context used for evaluation and type-checking.

Since: 1.16

Access the custom substitutions.

Since: 1.30

Access the custom normalizer.

Since: 1.16

Default input settings: resolves imports relative to . (the current working directory), report errors as coming from (input), and default evaluation settings from defaultEvaluateSettings.

Since: 1.16

Since: 1.16

Default evaluation settings: no extra entries in the initial context, and no special normalizer behaviour.

Since: 1.16

Since: 1.16

Since: 1.16

Use this to provide more detailed error messages

> input auto "True" :: IO Integer
 *** Exception: Error: Expression doesn't match annotation

 True : Integer

 (input):1:1

> detailed (input auto "True") :: IO Integer
 *** Exception: Error: Expression doesn't match annotation

 Explanation: You can annotate an expression with its type or kind using the
 ❰:❱ symbol, like this:


     ┌───────┐
     │ x : t │  ❰x❱ is an expression and ❰t❱ is the annotated type or kind of ❰x❱
     └───────┘

 The type checker verifies that the expression's type or kind matches the
 provided annotation

 For example, all of the following are valid annotations that the type checker
 accepts:


     ┌─────────────┐
     │ 1 : Natural │  ❰1❱ is an expression that has type ❰Natural❱, so the type
     └─────────────┘  checker accepts the annotation


     ┌───────────────────────┐
     │ Natural/even 2 : Bool │  ❰Natural/even 2❱ has type ❰Bool❱, so the type
     └───────────────────────┘  checker accepts the annotation


     ┌────────────────────┐
     │ List : Type → Type │  ❰List❱ is an expression that has kind ❰Type → Type❱,
     └────────────────────┘  so the type checker accepts the annotation


     ┌──────────────────┐
     │ List Text : Type │  ❰List Text❱ is an expression that has kind ❰Type❱, so
     └──────────────────┘  the type checker accepts the annotation


 However, the following annotations are not valid and the type checker will
 reject them:


     ┌──────────┐
     │ 1 : Text │  The type checker rejects this because ❰1❱ does not have type
     └──────────┘  ❰Text❱


     ┌─────────────┐
     │ List : Type │  ❰List❱ does not have kind ❰Type❱
     └─────────────┘


 You or the interpreter annotated this expression:

 ↳ True

 ... with this type or kind:

 ↳ Integer

 ... but the inferred type or kind of the expression is actually:

 ↳ Bool

 Some common reasons why you might get this error:

 ● The Haskell Dhall interpreter implicitly inserts a top-level annotation
   matching the expected type

   For example, if you run the following Haskell code:


     ┌───────────────────────────────┐
     │ >>> input auto "1" :: IO Text │
     └───────────────────────────────┘


   ... then the interpreter will actually type check the following annotated
   expression:


     ┌──────────┐
     │ 1 : Text │
     └──────────┘


   ... and then type-checking will fail

 ────────────────────────────────────────────────────────────────────────────────

 True : Integer

 (input):1:1

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

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
    )
:}

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 )
  )
:}

An (Encoder a) represents a way to marshal a value of type 'a' from Haskell into Dhall

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 and custom InterpretOptions, or using DerivingVia and Codec from Dhall.Deriving.

A compatibility alias for FromDhall

This will eventually be removed.

Every Decoder must obey the contract that if an expression's type matches the the expected type then the extract function must not fail with a type error. If not, then this value is returned.

This value indicates that an invalid Decoder was provided to the input function

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

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

Generate a type error during extraction by specifying the expected type and the actual type

Turn a Expr message into an extraction failure

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

Use the default input normalizer for interpreting a configuration file

auto = autoWith defaultInputNormalizer

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.

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

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)

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 (== '_') })

Decode a Expr

>>> input bool "True"
True

Decode a Expr

>>> input natural "42"
42

Decode an Expr

>>> input integer "+42"
42

Decode a Scientific

>>> input scientific "1e100"
1.0e100

Decode a Expr

>>> input double "42.0"
42.0

Decode lazy Expr

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

Decode strict Expr

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

Decode a Maybe

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

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

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

>>> input (Dhall.hashMap strictText bool) "toMap { a = True, b = False }"
fromList [("a",True),("b",False)]
>>> input (Dhall.hashMap 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.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 () 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 String

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

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

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

Run a RecordDecoder to build a Decoder.

Parse a single field of a record.

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

This class is used by FromDhall instance for functions:

instance (ToDhall a, FromDhall b) => FromDhall (a -> b)

You can convert Dhall functions with "simple" inputs (i.e. instances of this class) into Haskell functions. This works by:

• Marshaling the input to the Haskell function into a Dhall expression (i.e. x :: Expr Src Void)
• Applying the Dhall function (i.e. f :: Expr Src Void) to the Dhall input (i.e. App f x)
• Normalizing the syntax tree (i.e. normalize (App f x))
• Marshaling the resulting Dhall expression back into a Haskell value

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 genericToDhallWith and custom InterpretOptions, or using DerivingVia and Codec from Dhall.Deriving.

A compatibility alias for ToDhall

This will eventually be removed.

Use the default input normalizer for injecting a value

inject = injectWith defaultInputNormalizer

Use the default options for injecting a value, whose structure is determined generically.

This can be used when you want to use ToDhall on types that you don't want to define orphan instances for.

Use custom options for injecting a value, whose structure is determined generically.

This can be used when you want to use ToDhall on types that you don't want to define orphan instances for.

Intermediate type used for building a ToDhall instance for a record

Specify how to encode one field of a record by supplying an explicit Encoder for that field

Specify how to encode one field of a record using the default ToDhall instance for that type

Convert a RecordEncoder into the equivalent Encoder

UnionEncoder allows you to build an Encoder for a Dhall record.

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 encoder has type Encoder Status, but we can't build that out of any smaller encoders, as Encoders cannot be combined. However, we can use an UnionEncoder to build an Encoder for Status:

>>> :{
injectStatus :: Encoder Status
injectStatus = adapt >$< unionEncoder
  (   encodeConstructorWith "Queued"  inject
  >|< encodeConstructorWith "Result"  inject
  >|< encodeConstructorWith "Errored" inject
  )
  where
    adapt (Queued  n) = Left n
    adapt (Result  t) = Right (Left t)
    adapt (Errored e) = Right (Right e)
:}

Or, since we are simply using the ToDhall instance to inject each branch, we could write

>>> :{
injectStatus :: Encoder Status
injectStatus = adapt >$< unionEncoder
  (   encodeConstructor "Queued"
  >|< encodeConstructor "Result"
  >|< encodeConstructor "Errored"
  )
  where
    adapt (Queued  n) = Left n
    adapt (Result  t) = Right (Left t)
    adapt (Errored e) = Right (Right e)
:}

Specify how to encode an alternative by providing an explicit Encoder for that alternative

Specify how to encode an alternative by using the default ToDhall instance for that type

Convert a UnionEncoder into the equivalent Encoder

Combines two UnionEncoder values. See UnionEncoder for usage notes.

Ideally, this matches chosen; however, this allows UnionEncoder to not need a Divisible instance itself (since no instance is possible).

Use this function to extract Haskell values directly from Dhall AST. The intended use case is to allow easy extraction of Dhall values for making the function normalizeWith easier to use.

For other use cases, use input from Dhall module. It will give you a much better user experience.

This is an infix alias for contramap.

The RecordEncoder divisible (contravariant) functor allows you to build an Encoder for 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 encoder has type Encoder Project, but we can't build that out of any smaller encoders, as Encoders cannot be combined (they are only Contravariants). However, we can use an RecordEncoder to build an Encoder for Project:

>>> :{
injectProject :: Encoder Project
injectProject =
  recordEncoder
    ( adapt >$< encodeFieldWith "name" inject
            >*< encodeFieldWith "description" inject
            >*< encodeFieldWith "stars" inject
    )
  where
    adapt (Project{..}) = (projectName, (projectDescription, projectStars))
:}

Or, since we are simply using the ToDhall instance to inject each field, we could write

>>> :{
injectProject :: Encoder Project
injectProject =
  recordEncoder
    ( adapt >$< encodeField "name"
            >*< encodeField "description"
            >*< encodeField "stars"
    )
  where
    adapt (Project{..}) = (projectName, (projectDescription, projectStars))
:}

Infix divided

Type representing arbitrary-precision non-negative integers.

>>> 2^100 :: Natural
1267650600228229401496703205376

Operations whose result would be negative throw (Underflow :: ArithException),

>>> -1 :: Natural
*** Exception: arithmetic underflow

Since: base-4.8.0.0

General-purpose finite sequences.

A space efficient, packed, unboxed Unicode text type.