Dhall

Please read the Dhall.Tutorial module, which contains a tutorial explaining how to use the language, the compiler, and this library

Input

input

Arguments

:: Decoder a

The decoder for the Dhall value

-> Text

The Dhall program

-> IO a

The decoded value in Haskell

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.

inputWithSettings

Arguments

:: InputSettings

-> Decoder a

The decoder for the Dhall value

-> Text

The Dhall program

-> IO a

The decoded value in Haskell

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

inputFile

Arguments

:: Decoder a

The decoder for the Dhall value

-> FilePath

The path to the Dhall program.

-> IO a

The decoded value in Haskell.

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

This uses the settings from defaultEvaluateSettings.

Since: 1.16

inputFileWithSettings

Arguments

:: EvaluateSettings

-> Decoder a

The decoder for the Dhall value

-> FilePath

The path to the Dhall program.

-> IO a

The decoded value in Haskell.

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

Since: 1.16

inputExpr

Arguments

:: Text

The Dhall program

-> IO (Expr Src Void)

The fully normalized AST

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

Uses the settings from defaultInputSettings.

inputExprWithSettings

Arguments

:: InputSettings

-> Text

The Dhall program

-> IO (Expr Src Void)

The fully normalized AST

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

rootDirectory :: Functor f => LensLike' f InputSettings FilePath

Access the directory to resolve imports relative to.

Since: 1.16

sourceName :: Functor f => LensLike' f InputSettings FilePath

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

startingContext :: (Functor f, HasEvaluateSettings s) => LensLike' f s (Context (Expr Src Void))

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

Since: 1.16

substitutions :: (Functor f, HasEvaluateSettings s) => LensLike' f s (Substitutions Src Void)

Access the custom substitutions.

Since: 1.30

normalizer :: (Functor f, HasEvaluateSettings s) => LensLike' f s (Maybe (ReifiedNormalizer Void))

Access the custom normalizer.

Since: 1.16

newManager :: (Functor f, HasEvaluateSettings s) => LensLike' f s (IO Manager)

Access the HTTP manager initializer.

Since: 1.36

defaultInputSettings :: InputSettings

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

data InputSettings

Since: 1.16

Instances

HasEvaluateSettings InputSettings

Defined in Dhall

Methods

evaluateSettings :: Functor f => LensLike' f InputSettings EvaluateSettings

defaultEvaluateSettings :: EvaluateSettings

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

Since: 1.16

data EvaluateSettings

Since: 1.16

Instances

HasEvaluateSettings EvaluateSettings

Defined in Dhall

Methods

evaluateSettings :: Functor f => LensLike' f EvaluateSettings EvaluateSettings

class HasEvaluateSettings s where

Since: 1.16

Methods

evaluateSettings :: Functor f => LensLike' f s EvaluateSettings

Instances

HasEvaluateSettings EvaluateSettings

Defined in Dhall

Methods

evaluateSettings :: Functor f => LensLike' f EvaluateSettings EvaluateSettings

HasEvaluateSettings InputSettings

Defined in Dhall

Methods

evaluateSettings :: Functor f => LensLike' f InputSettings EvaluateSettings

detailed :: IO a -> IO a

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

Decoders

module Dhall.Marshal.Decode

Encoders

module Dhall.Marshal.Encode

Miscellaneous

rawInput

Arguments

:: Alternative f

=> Decoder a

The decoder for the Dhall value

-> Expr s Void

a closed form Dhall program, which evaluates to the expected type

-> f a

The decoded value in Haskell

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.