Dhall.Core

Constants for a pure type system

The axioms are:

⊦ Type : Kind
⊦ Kind : Sort

... and the valid rule pairs are:

⊦ Type ↝ Type : Type  -- Functions from terms to terms (ordinary functions)
⊦ Kind ↝ Type : Type  -- Functions from types to terms (type-polymorphic functions)
⊦ Sort ↝ Type : Type  -- Functions from kinds to terms
⊦ Kind ↝ Kind : Kind  -- Functions from types to types (type-level functions)
⊦ Sort ↝ Kind : Sort  -- Functions from kinds to types (kind-polymorphic functions)
⊦ Sort ↝ Sort : Sort  -- Functions from kinds to kinds (kind-level functions)

Note that Dhall does not support functions from terms to types and therefore Dhall is not a dependently typed language

Internal representation of a directory that stores the path components in reverse order

In other words, the directory /foo/bar/baz is encoded as Directory { components = [ "baz", "bar", "foo" ] }

A File is a directory followed by one additional path component representing the file name

The beginning of a file path which anchors subsequent path components

Reference to an external resource

A ImportType extended with an optional hash for semantic integrity checks

How to interpret the import's contents (i.e. as Dhall code or raw text)

The type of import (i.e. local vs. remote vs. environment)

This type stores all of the components of a remote import

The URI scheme

This wrapper around Double exists for its Eq instance which is defined via the binary encoding of Dhall Doubles.

Label for a bound variable

The Text field is the variable's name (i.e. "x").

The Int field disambiguates variables with the same name if there are multiple bound variables of the same name in scope. Zero refers to the nearest bound variable and the index increases by one for each bound variable of the same name going outward. The following diagram may help:

                              ┌──refers to──┐
                              │             │
                              v             │
λ(x : Type) → λ(y : Type) → λ(x : Type) → x@0

┌─────────────────refers to─────────────────┐
│                                           │
v                                           │
λ(x : Type) → λ(y : Type) → λ(x : Type) → x@1

This Int behaves like a De Bruijn index in the special case where all variables have the same name.

You can optionally omit the index if it is 0:

                              ┌─refers to─┐
                              │           │
                              v           │
λ(x : Type) → λ(y : Type) → λ(x : Type) → x

Zero indices are omitted when pretty-printing Vars and non-zero indices appear as a numeric suffix.

Record the binding part of a let expression.

For example,

let {- A -} x {- B -} : {- C -} Bool = {- D -} True in x

… will be instantiated as follows:

• bindingSrc0 corresponds to the A comment.

• variable is "x"

• bindingSrc1 corresponds to the B comment.

• annotation is Just a pair, corresponding to the C comment and Bool.

• bindingSrc2 corresponds to the D comment.

• value corresponds to True.

Construct a Binding with no source information and no type annotation.

The body of an interpolated Text literal

Used to record the origin of a // operator (i.e. from source code or a product of desugaring)

Record the field of a record-type and record-literal expression. The reason why we use the same ADT for both of them is because they store the same information.

For example,

{ {- A -} x {- B -} : {- C -} T }

... or

{ {- A -} x {- B -} = {- C -} T }

will be instantiated as follows:

• recordFieldSrc0 corresponds to the A comment.

• recordFieldValue is T

• recordFieldSrc1 corresponds to the B comment.

• recordFieldSrc2 corresponds to the C comment.

Although the A comment isn't annotating the T Record Field, this is the best place to keep these comments.

Note that recordFieldSrc2 is always Nothing when the RecordField is for a punned entry, because there is no = sign. For example,

{ {- A -} x {- B -} }

will be instantiated as follows:

• recordFieldSrc0 corresponds to the A comment.

• recordFieldValue corresponds to (Var "x")

• recordFieldSrc1 corresponds to the B comment.

• recordFieldSrc2 will be Nothing

The labels involved in a record using dot-syntax like in this example:

{ {- A -} a {- B -} . {- C -} b {- D -} . {- E -} c {- F -} = {- G -} e }

will be instantiated as follows:

• For both the a and b field, recordfieldSrc2 is Nothing

• For the a field:

• recordFieldSrc0 corresponds to the A comment

• recordFieldSrc1 corresponds to the B comment

• For the b field:

• recordFieldSrc0 corresponds to the C comment

• recordFieldSrc1 corresponds to the D comment

• For the c field:

• recordFieldSrc0 corresponds to the E comment

• recordFieldSrc1 corresponds to the F comment

• recordFieldSrc2 corresponds to the G comment

That is, for every label except the last one the semantics of recordFieldSrc0 and recordFieldSrc1 are the same from a regular record label but recordFieldSrc2 is always Nothing. For the last keyword, all srcs are Just

Construct a RecordField with no src information

Record the label of a function or a function-type expression

For example,

λ({- A -} a {- B -} : {- C -} T) -> e

… will be instantiated as follows:

• functionBindingSrc0 corresponds to the A comment

• functionBindingVariable is a

• functionBindingSrc1 corresponds to the B comment

• functionBindingSrc2 corresponds to the C comment

• functionBindingAnnotation is T

Smart constructor for FunctionBinding with no src information

Record the field on a selector-expression

For example,

e . {- A -} x {- B -}

… will be instantiated as follows:

• fieldSelectionSrc0 corresponds to the A comment

• fieldSelectionLabel corresponds to x

• fieldSelectionSrc1 corresponds to the B comment

Given our limitation that not all expressions recover their whitespaces, the purpose of fieldSelectionSrc1 is to save the Text.Megaparsec.SourcePos where the fieldSelectionLabel ends, but we still use a 'Maybe Dhall.Src.Src' (s = Src) to be consistent with similar data types such as Binding, for example.

Smart constructor for FieldSelection with no src information

A path component for a with expression

Syntax tree for expressions

The s type parameter is used to track the presence or absence of Src spans:

• If s = Src then the code may contains Src spans (either in a Note constructor or inline within another constructor, like Let)

• If s = Void then the code has no Src spans

The a type parameter is used to track the presence or absence of imports

• If a = Import then the code may contain unresolved Imports

• If a = Void then the code has no Imports

α-normalize an expression by renaming all bound variables to "_" and using De Bruijn indices to distinguish them

>>> mfb = Syntax.makeFunctionBinding>>> alphaNormalize (Lam mempty (mfb "a" (Const Type)) (Lam mempty (mfb "b" (Const Type)) (Lam mempty (mfb "x" "a") (Lam mempty (mfb "y" "b") "x"))))Lam Nothing (FunctionBinding {functionBindingSrc0 = Nothing, functionBindingVariable = "_", functionBindingSrc1 = Nothing, functionBindingSrc2 = Nothing, functionBindingAnnotation = Const Type}) (Lam Nothing (FunctionBinding {functionBindingSrc0 = Nothing, functionBindingVariable = "_", functionBindingSrc1 = Nothing, functionBindingSrc2 = Nothing, functionBindingAnnotation = Const Type}) (Lam Nothing (FunctionBinding {functionBindingSrc0 = Nothing, functionBindingVariable = "_", functionBindingSrc1 = Nothing, functionBindingSrc2 = Nothing, functionBindingAnnotation = Var (V "_" 1)}) (Lam Nothing (FunctionBinding {functionBindingSrc0 = Nothing, functionBindingVariable = "_", functionBindingSrc1 = Nothing, functionBindingSrc2 = Nothing, functionBindingAnnotation = Var (V "_" 1)}) (Var (V "_" 1)))))

α-normalization does not affect free variables:

>>> alphaNormalize "x"Var (V "x" 0)

Reduce an expression to its normal form, performing beta reduction

normalize does not type-check the expression. You may want to type-check expressions before normalizing them since normalization can convert an ill-typed expression into a well-typed expression.

normalize can also fail with error if you normalize an ill-typed expression

Reduce an expression to its normal form, performing beta reduction and applying any custom definitions.

normalizeWith is designed to be used with function typeWith. The typeWith function allows typing of Dhall functions in a custom typing context whereas normalizeWith allows evaluating Dhall expressions in a custom context.

To be more precise normalizeWith applies the given normalizer when it finds an application term that it cannot reduce by other means.

Note that the context used in normalization will determine the properties of normalization. That is, if the functions in custom context are not total then the Dhall language, evaluated with those functions is not total either.

normalizeWith can fail with an error if you normalize an ill-typed expression

This function generalizes normalizeWith by allowing the custom normalizer to use an arbitrary Monad

normalizeWithM can fail with an error if you normalize an ill-typed expression

An variation on NormalizerM for pure normalizers

Use this to wrap you embedded functions (see normalizeWith) to make them polymorphic enough to be used.

A reified Normalizer, which can be stored in structures without running into impredicative polymorphism.

Returns True if two expressions are α-equivalent and β-equivalent and False otherwise

judgmentallyEqual can fail with an error if you compare ill-typed expressions

Substitute all occurrences of a variable with an expression

subst x C B  ~  B[x := C]

shift is used by both normalization and type-checking to avoid variable capture by shifting variable indices

For example, suppose that you were to normalize the following expression:

λ(a : Type) → λ(x : a) → (λ(y : a) → λ(x : a) → y) x

If you were to substitute y with x without shifting any variable indices, then you would get the following incorrect result:

λ(a : Type) → λ(x : a) → λ(x : a) → x  -- Incorrect normalized form

In order to substitute x in place of y we need to shift x by 1 in order to avoid being misinterpreted as the x bound by the innermost lambda. If we perform that shift then we get the correct result:

λ(a : Type) → λ(x : a) → λ(x : a) → x@1

As a more worked example, suppose that you were to normalize the following expression:

    λ(a : Type)
→   λ(f : a → a → a)
→   λ(x : a)
→   λ(x : a)
→   (λ(x : a) → f x x@1) x@1

The correct normalized result would be:

    λ(a : Type)
→   λ(f : a → a → a)
→   λ(x : a)
→   λ(x : a)
→   f x@1 x

The above example illustrates how we need to both increase and decrease variable indices as part of substitution:

• We need to increase the index of the outer x@1 to x@2 before we substitute it into the body of the innermost lambda expression in order to avoid variable capture. This substitution changes the body of the lambda expression to (f x@2 x@1)

• We then remove the innermost lambda and therefore decrease the indices of both xs in (f x@2 x@1) to (f x@1 x) in order to reflect that one less x variable is now bound within that scope

Formally, (shift d (V x n) e) modifies the expression e by adding d to the indices of all variables named x whose indices are greater than (n + m), where m is the number of bound variables of the same name within that scope

In practice, d is always 1 or -1 because we either:

• increment variables by 1 to avoid variable capture during substitution

• decrement variables by 1 when deleting lambdas after substitution

n starts off at 0 when substitution begins and increments every time we descend into a lambda or let expression that binds a variable of the same name in order to avoid shifting the bound variables by mistake.

Quickly check if an expression is in normal form

Given a well-typed expression e, isNormalized e is equivalent to e == normalize e.

Given an ill-typed expression, isNormalized may fail with an error, or evaluate to either False or True!

Check if an expression is in a normal form given a context of evaluation. Unlike isNormalized, this will fully normalize and traverse through the expression.

It is much more efficient to use isNormalized.

isNormalizedWith can fail with an error if you check an ill-typed expression

Remove all Note constructors from an Expr (i.e. de-Note)

This also remove CharacterSet annotations.

The "opposite" of denote, like first absurd but faster

Remove any outermost Note constructors

This is typically used when you want to get the outermost non-Note constructor without removing internal Note constructors

Detect if the given variable is free within the given expression

>>> "x" `freeIn` "x"True>>> "x" `freeIn` "y"False>>> "x" `freeIn` Lam mempty (Syntax.makeFunctionBinding "x" (Const Type)) "x"False

Pretty-print a value

A traversal over the immediate sub-expressions of an expression.

A traversal over the immediate sub-expressions of an expression which allows mapping embedded values

A traversal over the immediate sub-expressions in Chunks.

Traverse over the immediate Expr children in a Binding.

Traverse over the immediate Expr children in a RecordField.

Traverse over the immediate Expr children in a FunctionBinding.

Generate a MultiLet from the contents of a Let.

In the resulting MultiLet bs e, e is guaranteed not to be a Let, but it might be a (Note … (Let …)).

Given parser output, multiLet consolidates lets that formed a let-block in the original source.

Wrap let-Bindings around an Expr.

wrapInLets can be understood as an inverse for multiLet:

let MultiLet bs e1 = multiLet b e0

wrapInLets bs e1 == Let b e0

This type represents 1 or more nested Let bindings that have been coalesced together for ease of manipulation

Utility function used to throw internal errors that should never happen (in theory) but that are not enforced by the type system

The set of reserved identifiers for the Dhall language | Contains also all keywords from "reservedKeywords"

Escape a Text literal using Dhall's escaping rules

Note that the result does not include surrounding quotes

Returns True if the given Char is valid within an unquoted path component

This is exported for reuse within the Dhall.Parser.Token module

Convenience utility for converting Either-based exceptions to IO-based exceptions

Utility that powers the Text/show built-in

Utility used to implement the --censor flag, by:

• Replacing all Src text with spaces

• Replacing all Text literals inside type errors with spaces

Utility used to censor Text by replacing all characters with a space