Dhall

dhall-1.42.2: A configuration language guaranteed to terminate

Safe Haskell | None
Language | Haskell2010

Dhall

Contents

- Input
- Decoders
- Encoders
- Individual phases
- Miscellaneous

Description

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

Synopsis

- input :: Decoder a -> Text -> IO a
- inputWithSettings :: InputSettings -> Decoder a -> Text -> IO a
- inputFile :: Decoder a -> FilePath -> IO a
- inputFileWithSettings :: EvaluateSettings -> Decoder a -> FilePath -> IO a
- inputExpr :: Text -> IO (Expr Src Void)
- inputExprWithSettings :: InputSettings -> Text -> IO (Expr Src Void)
- interpretExpr :: Expr Src Import -> IO (Expr Src Void)
- interpretExprWithSettings :: InputSettings -> Expr Src Import -> IO (Expr Src Void)
- fromExpr :: Decoder a -> Expr Src Import -> IO a
- fromExprWithSettings :: InputSettings -> Decoder a -> Expr Src Import -> IO a
- rootDirectory :: Functor f => LensLike' f InputSettings FilePath
- sourceName :: Functor f => LensLike' f InputSettings FilePath
- startingContext :: (Functor f, HasEvaluateSettings s) => LensLike' f s (Context (Expr Src Void))
- substitutions :: (Functor f, HasEvaluateSettings s) => LensLike' f s (Substitutions Src Void)
- normalizer :: (Functor f, HasEvaluateSettings s) => LensLike' f s (Maybe (ReifiedNormalizer Void))
- newManager :: (Functor f, HasEvaluateSettings s) => LensLike' f s (IO Manager)
- defaultInputSettings :: InputSettings
- data InputSettings
- defaultEvaluateSettings :: EvaluateSettings
- data EvaluateSettings
- class HasEvaluateSettings s where
  - evaluateSettings :: Functor f => LensLike' f s EvaluateSettings
- detailed :: IO a -> IO a
- module Dhall.Marshal.Decode
- module Dhall.Marshal.Encode
- parseWithSettings :: MonadThrow m => InputSettings -> Text -> m (Expr Src Import)
- resolveWithSettings :: InputSettings -> Expr Src Import -> IO (Expr Src Void)
- resolveAndStatusWithSettings :: InputSettings -> Expr Src Import -> IO (Expr Src Void, Status)
- typecheckWithSettings :: MonadThrow m => InputSettings -> Expr Src Void -> m ()
- checkWithSettings :: MonadThrow m => InputSettings -> Expr Src Void -> Expr Src Void -> m ()
- expectWithSettings :: MonadThrow m => InputSettings -> Decoder a -> Expr Src Void -> m ()
- normalizeWithSettings :: InputSettings -> Expr Src Void -> Expr Src Void
- rawInput :: Alternative f => Decoder a -> Expr s Void -> f a

# 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

interpretExpr :: Expr Src Import -> IO (Expr Src Void) #

Interpret a Dhall Expression

This takes care of import resolution, type-checking, and normalization

interpretExprWithSettings :: InputSettings -> Expr Src Import -> IO (Expr Src Void) #

Like `interpretExpr`, but customizable using `InputSettings`

fromExpr :: Decoder a -> Expr Src Import -> IO a #

Decode a Dhall expression

This takes care of import resolution, type-checking and normalization

fromExprWithSettings :: InputSettings -> Decoder a -> Expr Src Import -> IO a #

Like `fromExpr`, but customizable using `InputSettings`

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

Instances details

HasEvaluateSettings InputSettings # |
Instance details 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

Instances details

HasEvaluateSettings EvaluateSettings # |
Instance details 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

Instances details

HasEvaluateSettings EvaluateSettings # |
Instance details Defined in Dhall Methods evaluateSettings :: Functor f => LensLike' f EvaluateSettings EvaluateSettings #
HasEvaluateSettings InputSettings # |
Instance details 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

# Individual phases

parseWithSettings :: MonadThrow m => InputSettings -> Text -> m (Expr Src Import) #

Parse an expression, using the supplied `InputSettings`

resolveWithSettings :: InputSettings -> Expr Src Import -> IO (Expr Src Void) #

Resolve an expression, using the supplied `InputSettings`

Note that this also applies any substitutions specified in the `InputSettings`

resolveAndStatusWithSettings :: InputSettings -> Expr Src Import -> IO (Expr Src Void, Status) #

A version of `resolveWithSettings` that also returns the import `Status` together with the resolved expression.

typecheckWithSettings :: MonadThrow m => InputSettings -> Expr Src Void -> m () #

Type-check an expression, using the supplied `InputSettings`

checkWithSettings #

Arguments

:: MonadThrow m |
=> InputSettings | The input settings
-> Expr Src Void | The expected type of the expression
-> Expr Src Void | The expression to check
-> m () |

Type-check an expression against a type provided as a Dhall expreession, using the supplied `InputSettings`

expectWithSettings :: MonadThrow m => InputSettings -> Decoder a -> Expr Src Void -> m () #

Type-check an expression against a `Decoder`'s expected type, using the supplied `InputSettings`. This is equivalent of using the `expected` type of a `Decoder` as the second argument to `checkWithSettings`.

normalizeWithSettings :: InputSettings -> Expr Src Void -> Expr Src Void #

Normalize an expression, using the supplied `InputSettings`

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