Safe Haskell	None
Language	Haskell2010

Dhall.Import

Contents

Import

Description

Dhall lets you import external expressions located either in local files or hosted on network endpoints.

To import a local file as an expression, just insert the path to the file, prepending a ./ if the path is relative to the current directory. For example, if you create a file named id with the following contents:

$ cat id
λ(a : Type) → λ(x : a) → x

Then you can use the file directly within a dhall program just by referencing the file's path:

$ dhall
./id Bool True
<Ctrl-D>
Bool

True

Imported expressions may contain imports of their own, too, which will continue to be resolved. However, Dhall will prevent cyclic imports. For example, if you had these two files:

$ cat foo
./bar

$ cat bar
./foo

... Dhall would throw the following exception if you tried to import foo:

$ dhall
./foo
^D
↳ ./foo
  ↳ ./bar

Cyclic import: ./foo

You can also import expressions hosted on network endpoints. Just use the URL

http://host[:port]/path

The compiler expects the downloaded expressions to be in the same format as local files, specifically UTF8-encoded source code text.

For example, if our id expression were hosted at http://example.com/id, then we would embed the expression within our code using:

http://example.com/id

You can also import expressions stored within environment variables using env:NAME, where NAME is the name of the environment variable. For example:

$ export FOO=1
$ export BAR='"Hi"'
$ export BAZ='λ(x : Bool) → x == False'
$ dhall <<< "{ foo = env:FOO , bar = env:BAR , baz = env:BAZ }"
{ bar : Text, baz : ∀(x : Bool) → Bool, foo : Integer }

{ bar = "Hi", baz = λ(x : Bool) → x == False, foo = 1 }

If you wish to import the raw contents of an impoert as Text then add as Text to the end of the import:

$ dhall <<< "http://example.com as Text"
Text

"<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>\n\n    <meta
 charset=\"utf-8\" />\n    <meta http-equiv=\"Content-type\" content=\"text/html
; charset=utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width,
initial-scale=1\" />\n    <style type=\"text/css\">\n    body {\n        backgro
und-color: #f0f0f2;\n        margin: 0;\n        padding: 0;\n        font-famil
y: \"Open Sans\", \"Helvetica Neue\", Helvetica, Arial, sans-serif;\n        \n
   }\n    div {\n        width: 600px;\n        margin: 5em auto;\n        paddi
ng: 50px;\n        background-color: #fff;\n        border-radius: 1em;\n    }\n
    a:link, a:visited {\n        color: #38488f;\n        text-decoration: none;
\n    }\n    @media (max-width: 700px) {\n        body {\n            background
-color: #fff;\n        }\n        div {\n            width: auto;\n            m
argin: 0 auto;\n            border-radius: 0;\n            padding: 1em;\n
  }\n    }\n    </style>    \n</head>\n\n<body>\n<div>\n    <h1>Example Domain</
h1>\n    <p>This domain is established to be used for illustrative examples in d
ocuments. You may use this\n    domain in examples without prior coordination or
 asking for permission.</p>\n    <p><a href=\"http://www.iana.org/domains/exampl
e\">More information...</a></p>\n</div>\n</body>\n</html>\n"

Synopsis

load :: Expr Src Import -> IO (Expr Src Void)
loadRelativeTo :: FilePath -> SemanticCacheMode -> Expr Src Import -> IO (Expr Src Void)
loadWith :: Expr Src Import -> StateT Status IO (Expr Src Void)
localToPath :: MonadIO io => FilePrefix -> File -> io FilePath
hashExpression :: Expr Void Void -> SHA256Digest
hashExpressionToCode :: Expr Void Void -> Text
writeExpressionToSemanticCache :: Expr Void Void -> IO ()
warnAboutMissingCaches :: (MonadCatch m, Alternative m, MonadIO m) => m ()
assertNoImports :: MonadIO io => Expr Src Import -> io (Expr Src Void)
data Status = Status {
- _stack :: NonEmpty Chained
- _graph :: [Depends]
- _cache :: Map Chained ImportSemantics
- _manager :: Maybe Manager
- _remote :: URL -> StateT Status IO Text
- _normalizer :: Maybe (ReifiedNormalizer Void)
- _startingContext :: Context (Expr Src Void)
- _semanticCacheMode :: SemanticCacheMode
}
data SemanticCacheMode
- = IgnoreSemanticCache
- | UseSemanticCache
data Chained
chainedImport :: Chained -> Import
chainedFromLocalHere :: FilePrefix -> File -> ImportMode -> Chained
chainedChangeMode :: ImportMode -> Chained -> Chained
emptyStatus :: FilePath -> Status
stack :: Functor f => LensLike' f Status (NonEmpty Chained)
cache :: Functor f => LensLike' f Status (Map Chained ImportSemantics)
data Depends = Depends {
- parent :: Chained
- child :: Chained
}
graph :: Functor f => LensLike' f Status [Depends]
remote :: Functor f => LensLike' f Status (URL -> StateT Status IO Text)
toHeaders :: Expr s a -> [HTTPHeader]
normalizer :: Functor f => LensLike' f Status (Maybe (ReifiedNormalizer Void))
startingContext :: Functor f => LensLike' f Status (Context (Expr Src Void))
chainImport :: Chained -> Import -> StateT Status IO Chained
data ImportSemantics
newtype Cycle = Cycle {
- cyclicImport :: Import
}
newtype ReferentiallyOpaque = ReferentiallyOpaque {
- opaqueImport :: Import
}
data Imported e = Imported {
- importStack :: NonEmpty Chained
- nested :: e
}
data ImportResolutionDisabled = ImportResolutionDisabled
data PrettyHttpException = PrettyHttpException String Dynamic
data MissingFile = MissingFile FilePath
newtype MissingEnvironmentVariable = MissingEnvironmentVariable {
- name :: Text
}
newtype MissingImports = MissingImports [SomeException]
data HashMismatch = HashMismatch {
- expectedHash :: SHA256Digest
- actualHash :: SHA256Digest
}

Import

load :: Expr Src Import -> IO (Expr Src Void) Source #

Resolve all imports within an expression

loadRelativeTo :: FilePath -> SemanticCacheMode -> Expr Src Import -> IO (Expr Src Void) Source #

Resolve all imports within an expression, importing relative to the given directory.

loadWith :: Expr Src Import -> StateT Status IO (Expr Src Void) Source #

Generalized version of load

You can configure the desired behavior through the initial Status that you supply

localToPath :: MonadIO io => FilePrefix -> File -> io FilePath Source #

Construct the file path corresponding to a local import. If the import is _relative_ then the resulting path is also relative.

hashExpression :: Expr Void Void -> SHA256Digest Source #

Hash a fully resolved expression

hashExpressionToCode :: Expr Void Void -> Text Source #

Convenience utility to hash a fully resolved expression and return the base-16 encoded hash with the sha256: prefix

In other words, the output of this function can be pasted into Dhall source code to add an integrity check to an import

writeExpressionToSemanticCache :: Expr Void Void -> IO () Source #

Ensure that the given expression is present in the semantic cache. The given expression should be alpha-beta-normal.

warnAboutMissingCaches :: (MonadCatch m, Alternative m, MonadIO m) => m () Source #

Warn if no cache directory is available

assertNoImports :: MonadIO io => Expr Src Import -> io (Expr Src Void) Source #

Assert than an expression is import-free

data Status Source #

State threaded throughout the import process

Constructors

Status

Fields

_stack :: NonEmpty Chained
Stack of Imports that we've imported along the way to get to the current point
_graph :: [Depends]
Graph of all the imports visited so far, represented by a list of import dependencies.
_cache :: Map Chained ImportSemantics
Cache of imported expressions with their node id in order to avoid importing the same expression twice with different values
_manager :: Maybe Manager
Used to cache the Manager when making multiple requests
_remote :: URL -> StateT Status IO Text
The remote resolver, fetches the content at the given URL.
_normalizer :: Maybe (ReifiedNormalizer Void)
_startingContext :: Context (Expr Src Void)
_semanticCacheMode :: SemanticCacheMode

data SemanticCacheMode Source #

This enables or disables the semantic cache for imports protected by integrity checks

Constructors

IgnoreSemanticCache
UseSemanticCache

Instances

Eq SemanticCacheMode Source #
Instance details Defined in Dhall.Import.Types Methods (==) :: SemanticCacheMode -> SemanticCacheMode -> Bool # (/=) :: SemanticCacheMode -> SemanticCacheMode -> Bool #

data Chained Source #

A fully chained import, i.e. if it contains a relative path that path is relative to the current directory. If it is a remote import with headers those are well-typed (either of type `List { header : Text, value Text}` or `List { mapKey : Text, mapValue Text})` and in normal form. These invariants are preserved by the API exposed by Dhall.Import.

Instances

Eq Chained Source #
Instance details Defined in Dhall.Import.Types Methods (==) :: Chained -> Chained -> Bool # (/=) :: Chained -> Chained -> Bool #
Ord Chained Source #
Instance details Defined in Dhall.Import.Types Methods compare :: Chained -> Chained -> Ordering # (<) :: Chained -> Chained -> Bool # (<=) :: Chained -> Chained -> Bool # (>) :: Chained -> Chained -> Bool # (>=) :: Chained -> Chained -> Bool # max :: Chained -> Chained -> Chained # min :: Chained -> Chained -> Chained #
Pretty Chained Source #
Instance details Defined in Dhall.Import.Types Methods pretty :: Chained -> Doc ann # prettyList :: [Chained] -> Doc ann #

chainedImport :: Chained -> Import Source #

The underlying import

chainedFromLocalHere :: FilePrefix -> File -> ImportMode -> Chained Source #

Given a Local import construct the corresponding unhashed Chained import (interpreting relative path as relative to the current directory).

chainedChangeMode :: ImportMode -> Chained -> Chained Source #

Adjust the import mode of a chained import

emptyStatus :: FilePath -> Status Source #

Default starting Status, importing relative to the given directory.

stack :: Functor f => LensLike' f Status (NonEmpty Chained) Source #

Lens from a Status to its _stack field

cache :: Functor f => LensLike' f Status (Map Chained ImportSemantics) Source #

Lens from a Status to its _cache field

data Depends Source #

parent imports (i.e. depends on) child

Constructors

Depends
Fields parent :: Chained child :: Chained

graph :: Functor f => LensLike' f Status [Depends] Source #

Lens from a Status to its _graph field

remote :: Functor f => LensLike' f Status (URL -> StateT Status IO Text) Source #

Lens from a Status to its _remote field

toHeaders :: Expr s a -> [HTTPHeader] Source #

Given a well-typed (of type `List { header : Text, value Text }` or `List { mapKey : Text, mapValue Text }`) headers expressions in normal form construct the corresponding binary http headers; otherwise return the empty list.

normalizer :: Functor f => LensLike' f Status (Maybe (ReifiedNormalizer Void)) Source #

Lens from a Status to its _normalizer field

startingContext :: Functor f => LensLike' f Status (Context (Expr Src Void)) Source #

Lens from a Status to its _startingContext field

chainImport :: Chained -> Import -> StateT Status IO Chained Source #

Chain imports, also typecheck and normalize headers if applicable.

data ImportSemantics Source #

An import that has been fully interpeted

newtype Cycle Source #

An import failed because of a cycle in the import graph

Constructors

Cycle
Fields cyclicImport :: Import The offending cyclic import

Instances

Show Cycle Source #
Instance details Defined in Dhall.Import Methods showsPrec :: Int -> Cycle -> ShowS # show :: Cycle -> String # showList :: [Cycle] -> ShowS #
Exception Cycle Source #
Instance details Defined in Dhall.Import Methods toException :: Cycle -> SomeException # fromException :: SomeException -> Maybe Cycle # displayException :: Cycle -> String #

newtype ReferentiallyOpaque Source #

Dhall tries to ensure that all expressions hosted on network endpoints are weakly referentially transparent, meaning roughly that any two clients will compile the exact same result given the same URL.

To be precise, a strong interpretaton of referential transparency means that if you compiled a URL you could replace the expression hosted at that URL with the compiled result. Let's call this "static linking". Dhall (very intentionally) does not satisfy this stronger interpretation of referential transparency since "statically linking" an expression (i.e. permanently resolving all imports) means that the expression will no longer update if its dependencies change.

In general, either interpretation of referential transparency is not enforceable in a networked context since one can easily violate referential transparency with a custom DNS, but Dhall can still try to guard against common unintentional violations. To do this, Dhall enforces that a non-local import may not reference a local import.

Local imports are defined as:

A file
A URL with a host of localhost or 127.0.0.1

All other imports are defined to be non-local

Constructors

ReferentiallyOpaque
Fields opaqueImport :: Import The offending opaque import

Instances

Show ReferentiallyOpaque Source #
Instance details Defined in Dhall.Import Methods showsPrec :: Int -> ReferentiallyOpaque -> ShowS # show :: ReferentiallyOpaque -> String # showList :: [ReferentiallyOpaque] -> ShowS #
Exception ReferentiallyOpaque Source #
Instance details Defined in Dhall.Import Methods toException :: ReferentiallyOpaque -> SomeException # fromException :: SomeException -> Maybe ReferentiallyOpaque # displayException :: ReferentiallyOpaque -> String #

data Imported e Source #

Extend another exception with the current import stack

Constructors

Imported
Fields importStack :: NonEmpty Chained Imports resolved so far, in reverse order nested :: e The nested exception

Instances

Show e => Show (Imported e) Source #
Instance details Defined in Dhall.Import Methods showsPrec :: Int -> Imported e -> ShowS # show :: Imported e -> String # showList :: [Imported e] -> ShowS #
Exception e => Exception (Imported e) Source #
Instance details Defined in Dhall.Import Methods toException :: Imported e -> SomeException # fromException :: SomeException -> Maybe (Imported e) # displayException :: Imported e -> String #

data ImportResolutionDisabled Source #

A call to assertNoImports failed because there was at least one import

Constructors

ImportResolutionDisabled

Instances

Show ImportResolutionDisabled Source #
Instance details Defined in Dhall.Import Methods showsPrec :: Int -> ImportResolutionDisabled -> ShowS # show :: ImportResolutionDisabled -> String # showList :: [ImportResolutionDisabled] -> ShowS #
Exception ImportResolutionDisabled Source #
Instance details Defined in Dhall.Import Methods toException :: ImportResolutionDisabled -> SomeException # fromException :: SomeException -> Maybe ImportResolutionDisabled # displayException :: ImportResolutionDisabled -> String #

data PrettyHttpException Source #

Wrapper around HttpExceptions with a prettier Show instance.

In order to keep the library API constant even when the with-http Cabal flag is disabled the pretty error message is pre-rendered and the real HttpExcepion is stored in a Dynamic

Constructors

PrettyHttpException String Dynamic

Instances

Show PrettyHttpException Source #
Instance details Defined in Dhall.Import.Types Methods showsPrec :: Int -> PrettyHttpException -> ShowS # show :: PrettyHttpException -> String # showList :: [PrettyHttpException] -> ShowS #
Exception PrettyHttpException Source #
Instance details Defined in Dhall.Import.Types Methods toException :: PrettyHttpException -> SomeException # fromException :: SomeException -> Maybe PrettyHttpException # displayException :: PrettyHttpException -> String #

data MissingFile Source #

Exception thrown when an imported file is missing

Constructors

MissingFile FilePath

Instances

Show MissingFile Source #
Instance details Defined in Dhall.Import Methods showsPrec :: Int -> MissingFile -> ShowS # show :: MissingFile -> String # showList :: [MissingFile] -> ShowS #
Exception MissingFile Source #
Instance details Defined in Dhall.Import Methods toException :: MissingFile -> SomeException # fromException :: SomeException -> Maybe MissingFile # displayException :: MissingFile -> String #

newtype MissingEnvironmentVariable Source #

Exception thrown when an environment variable is missing

Constructors

MissingEnvironmentVariable
Fields name :: Text

Instances

Show MissingEnvironmentVariable Source #
Instance details Defined in Dhall.Import Methods showsPrec :: Int -> MissingEnvironmentVariable -> ShowS # show :: MissingEnvironmentVariable -> String # showList :: [MissingEnvironmentVariable] -> ShowS #
Exception MissingEnvironmentVariable Source #
Instance details Defined in Dhall.Import Methods toException :: MissingEnvironmentVariable -> SomeException # fromException :: SomeException -> Maybe MissingEnvironmentVariable # displayException :: MissingEnvironmentVariable -> String #

newtype MissingImports Source #

List of Exceptions we encounter while resolving Import Alternatives

Constructors

MissingImports [SomeException]

Instances

Show MissingImports Source #
Instance details Defined in Dhall.Import Methods showsPrec :: Int -> MissingImports -> ShowS # show :: MissingImports -> String # showList :: [MissingImports] -> ShowS #
Exception MissingImports Source #
Instance details Defined in Dhall.Import Methods toException :: MissingImports -> SomeException # fromException :: SomeException -> Maybe MissingImports # displayException :: MissingImports -> String #

data HashMismatch Source #

Exception thrown when an integrity check fails

Constructors

HashMismatch
Fields expectedHash :: SHA256Digest actualHash :: SHA256Digest

Instances

Show HashMismatch Source #
Instance details Defined in Dhall.Import Methods showsPrec :: Int -> HashMismatch -> ShowS # show :: HashMismatch -> String # showList :: [HashMismatch] -> ShowS #
Exception HashMismatch Source #
Instance details Defined in Dhall.Import Methods toException :: HashMismatch -> SomeException # fromException :: SomeException -> Maybe HashMismatch # displayException :: HashMismatch -> String #