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

Since: 1.16

Access the standard version (used primarily when encoding or decoding Dhall expressions to and from a binary representation)

Since: 1.17

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 (Type a) represents a way to marshal a value of type 'a' from Dhall into Haskell

You can produce Types either explicitly:

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

... or implicitly using auto:

example :: Type (Vector Text)
example = auto

You can consume Types using the input function:

input :: Type a -> Text -> IO a

The RecordType applicative functor allows you to build a Type parser 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 parser has type Type Project, but we can't build that out of any smaller parsers, as Types cannot be combined (they are only Functors). However, we can use a RecordType to build a Type for Project:

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

The UnionType monoid allows you to build a Type parser 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 = "Finish succesfully"
| Queued : Natural
| Errored : Text
>

Our parser has type Type Status, but we can't build that out of any smaller parsers, as Types cannot be combined (they are only Functors). However, we can use a UnionType to build a Type for Status:

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

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

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

>>> input auto "[1, 2, 3]" :: IO (Vector Natural)
[1,2,3]

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

Every Type must obey the contract that if an expression's type matches the the expected type then the extract function must succeed. If not, then this exception is thrown

This exception indicates that an invalid Type was provided to the input function

Use the default options for interpreting a configuration file

auto = autoWith defaultInterpretOptions

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

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

Default interpret options, which you can tweak or override, like this:

autoWith
    (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 () from an empty record.

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

Decode a String

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

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

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

Run a RecordType parser to build a Type parser.

Parse a single field of a record.

Run a UnionType parser to build a Type parser.

Parse a single constructor of a union

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

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

This class is used by Interpret instance for functions:

instance (Inject a, Interpret b) => Interpret (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 X)
• Applying the Dhall function (i.e. f :: Expr Src X) 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

Use the default options for injecting a value

inject = inject defaultInterpretOptions

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

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

The UnionInputType monoid allows you to build an InputType injector 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 = "Finish succesfully"
| Queued : Natural
| Errored : Text
>

Our injector has type InputType Status, but we can't build that out of any smaller injectors, as InputTypes cannot be combined. However, we can use an UnionInputType to build an InputType for Status:

>>> :{
injectStatus :: InputType Status
injectStatus = adapt >$< inputUnion
  (   inputConstructorWith "Queued"  inject
  >|< inputConstructorWith "Result"  inject
  >|< inputConstructorWith "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 Inject instance to inject each branch, we could write

>>> :{
injectStatus :: InputType Status
injectStatus = adapt >$< inputUnion
  (   inputConstructor "Queued"
  >|< inputConstructor "Result"
  >|< inputConstructor "Errored"
  )
  where
    adapt (Queued  n) = Left n
    adapt (Result  t) = Right (Left t)
    adapt (Errored e) = Right (Right e)
:}

Combines two UnionInputType values. See UnionInputType for usage notes.

Ideally, this matches chosen; however, this allows UnionInputType 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 RecordInputType divisible (contravariant) functor allows you to build an InputType injector 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 injector has type InputType Project, but we can't build that out of any smaller injectors, as InputTypes cannot be combined (they are only Contravariants). However, we can use an InputRecordType to build an InputType for Project:

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

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

>>> :{
injectProject :: InputType Project
injectProject =
  inputRecord
    ( adapt >$< inputField "name"
            >*< inputField "description"
            >*< inputField "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.

Boxed vectors, supporting efficient slicing.

Representable types of kind *. This class is derivable in GHC with the DeriveGeneric flag on.

A Generic instance must satisfy the following laws:

from . to ≡ id
to . from ≡ id