| Copyright | (c) Justin Le 2018 |
|---|---|
| License | BSD3 |
| Maintainer | justin@jle.im |
| Stability | experimental |
| Portability | non-portable |
| Safe Haskell | None |
| Language | Haskell2010 |
Hakyll.Web.Dhall
Contents
Description
Hakyll compiler and loader for Dhall files. Functions are intended to track all local dependencies within the project directory, so rebuilds are properly triggered on up-stream imports. Provides options for customizing rebuilding behavior for network, environment variable, and non-project local files.
loadDhall and loadDhallExpr allow for loading and parsing of Dhall
files for usage within the Compiler monad, so you can use the results
as intermediate parts in building your pages. parseDhall allows
directly passing in Dhall strings to parse and resolve, tracking
imports. dhallCompiler is meant as a "final end-point", which just
pretty-prints a parsed Dhall file, with optional normalization.
Synopsis
- data DhallCompilerOptions a = DCO {}
- data DhallCompilerTrust
- defaultDhallCompilerOptions :: DefaultDhallResolver a => DhallCompilerOptions a
- dcoResolver :: Functor f => LensLike f (DhallCompilerOptions a) (DhallCompilerOptions b) (DhallResolver a) (DhallResolver b)
- dcoMinimize :: Functor f => LensLike' f (DhallCompilerOptions a) Bool
- dcoNormalize :: Functor f => LensLike' f (DhallCompilerOptions a) Bool
- data DhallResolver :: Type -> Type where
- DRRaw :: {..} -> DhallResolver Import
- DRFull :: {..} -> DhallResolver X
- class DefaultDhallResolver a where
- drRemap :: Functor f => LensLike' f (DhallResolver Import) (Import -> Compiler (Expr Src Import))
- drFull :: Functor f => LensLike' f (DhallResolver X) (Set DhallCompilerTrust)
- loadDhall :: Type a -> Identifier -> Compiler (Item a)
- loadDhallWith :: DhallCompilerOptions X -> Type a -> Identifier -> Compiler (Item a)
- loadDhallExpr :: DefaultDhallResolver a => Identifier -> Compiler (Item (Expr Src a))
- loadDhallExprWith :: DhallCompilerOptions a -> Identifier -> Compiler (Item (Expr Src a))
- newtype DExpr a = DExpr {}
- parseDhall :: DefaultDhallResolver a => Maybe Identifier -> Text -> Compiler (Expr Src a)
- parseDhallWith :: DhallCompilerOptions a -> Maybe Identifier -> Text -> Compiler (Expr Src a)
- dhallCompiler :: forall a. (DefaultDhallResolver a, Pretty a) => Compiler (Item String)
- dhallRawCompiler :: Compiler (Item String)
- dhallFullCompiler :: Compiler (Item String)
- dhallCompilerWith :: Pretty a => DhallCompilerOptions a -> Compiler (Item String)
- parseRawDhallWith :: DhallCompilerOptions Import -> Maybe Identifier -> Text -> Compiler (Expr Src Import)
- resolveDhallImports :: DhallCompilerOptions X -> Maybe Identifier -> Expr Src Import -> Compiler (Expr Src X)
Configuration and Options
data DhallCompilerOptions a Source #
Options for loading Dhall files.
Constructors
| DCO | |
Fields
| |
Instances
data DhallCompilerTrust Source #
Types of external imports that a Dhall file may have.
Constructors
| DCTLocal | File on local filesystem outside of project directory, and therefore not tracked by Hakyll |
| DCTRemote | Link to remote resource over a network connection |
| DCTEnv | Reference to environment variable on machine |
Instances
defaultDhallCompilerOptions :: DefaultDhallResolver a => DhallCompilerOptions a Source #
Default DhallCompilerOptions. If the type variable is not
inferrable, it can be helpful to use TypeApplications syntax:
defaultCompilerOptions@Import-- do not resolve importsdefaultCompilerOptions@X-- resolve imports
dcoResolver :: Functor f => LensLike f (DhallCompilerOptions a) (DhallCompilerOptions b) (DhallResolver a) (DhallResolver b) Source #
Lens for _dcoResolver field of DhallCompilerOptions.
dcoMinimize :: Functor f => LensLike' f (DhallCompilerOptions a) Bool Source #
Lens for _dcoMinimize field of DhallCompilerOptions.
dcoNormalize :: Functor f => LensLike' f (DhallCompilerOptions a) Bool Source #
Lens for _dcoNormalize field of DhallCompilerOptions.
Resolver Behaviors
data DhallResolver :: Type -> Type where Source #
Method for resolving imports.
The choice will determine the type of expression that loadDhallExpr
and family will produce.
Note that at this moment, the only available options are "all or nothing" --- either resolve all types imports completely and fully, or none of them. Hopefully one day this library will offer the ability to resolve only certain types of imports (environment variables, absolute paths) and not others (remote network, local paths).
Constructors
| DRRaw :: {..} -> DhallResolver Import | Leave imports as imports, but optionally remap the destinations. |
| DRFull :: {..} -> DhallResolver X | Completely resolve all imports in IO. All imports within Hakyll project are tracked, and changes to dependencies will trigger rebuilds upstream. |
Fields
| |
class DefaultDhallResolver a where Source #
Helper typeclass to allow functions to be polymorphic over different
DhallResolver types.
Provides default behavior for each resolver type.
Minimal complete definition
Methods
Instances
| DefaultDhallResolver X Source # | Only trust remote imports remain unchanged. Rebuild every time if any absolute, home-directory-based, or environment variable imports are in file. |
Defined in Hakyll.Web.Dhall Methods | |
| DefaultDhallResolver Import Source # | Leave all imports unchanged |
Defined in Hakyll.Web.Dhall Methods | |
drRemap :: Functor f => LensLike' f (DhallResolver Import) (Import -> Compiler (Expr Src Import)) Source #
Lens for _drRemap field of DhallResolver.
drFull :: Functor f => LensLike' f (DhallResolver X) (Set DhallCompilerTrust) Source #
Lens for _drFull field of DhallResolver.
Load Dhall Files
As as custom Haskell types
loadDhall :: Type a -> Identifier -> Compiler (Item a) Source #
Load a value of type a that is parsed from a Dhall file at the given
Identifier. Tracks dependencies within project.
loadDhallWith :: DhallCompilerOptions X -> Type a -> Identifier -> Compiler (Item a) Source #
Version of loadDhall taking custom DhallCompilerOptions.
As raw expressions
loadDhallExpr :: DefaultDhallResolver a => Identifier -> Compiler (Item (Expr Src a)) Source #
Load and parse the body of the given Identifier as a Dhall
expression.
If you wrap the result in DExpr, you can save the result as
a snapshot.
loadDhallExprWith :: DhallCompilerOptions a -> Identifier -> Compiler (Item (Expr Src a)) Source #
Version of loadDhallExpr taking custom DhallCompilerOptions.
Newtype wrapper over Expr Src aBinary instance, meant to be usable as a compilable
Hakyll result that can be saved with saveSnapshot, load, etc.
Parse raw Dhall expressions
Arguments
| :: DefaultDhallResolver a | |
| => Maybe Identifier | Optional |
| -> Text | |
| -> Compiler (Expr Src a) |
Parse a Dhall source. Meant to be useful for patterns similar to
dhall-to-text. If using examples from
https://github.com/dhall-lang/dhall-text, you can use:
parseDhallNothing"./make-items ./people"
Any local dependencies within the project directory (./make-items and ./people above, for example) are tracked by Hakyll, and so modifications to required files will also cause upstream files to be rebuilt.
Arguments
| :: DhallCompilerOptions a | |
| -> Maybe Identifier | Optional |
| -> Text | |
| -> Compiler (Expr Src a) |
Version of parseDhall taking custom DhallCompilerOptions.
Compile (prettify, normalize, re-map) Dhall Files
dhallCompiler :: forall a. (DefaultDhallResolver a, Pretty a) => Compiler (Item String) Source #
Essentially a Dhall pretty-printer, (optional) normalizer, and
re-formatter. Compile the Dhall file as text according to default
DhallCompilerOptions. Note that this is polymorphic over both "raw"
and "fully resolved" versions; it must be called with
TypeApplications.
dhallRawCompiler=dhallCompiler@ImportdhallFullCompiler=dhallCompiler@X
It might be more convenient to just use dhallRawCompiler or
dhallFullCompiler.
dhallRawCompiler :: Compiler (Item String) Source #
Compile the Dhall file as text according to default
DhallCompilerOptions while leaving all imports unchanged and
unresolved. Essentially a Dhall pretty-printer, (optional) normalizer,
and re-formatter.
dhallFullCompiler :: Compiler (Item String) Source #
Compile the Dhall file as text according to default
DhallCompilerOptions, resolving all imports in IO and tracking
dependencies. Essentially a Dhall pretty-printer, (optional)
normalizer, and re-formatter.
dhallCompilerWith :: Pretty a => DhallCompilerOptions a -> Compiler (Item String) Source #
dhallCompiler, but with custom DhallCompilerOptions.
Internal Utilities
parseRawDhallWith :: DhallCompilerOptions Import -> Maybe Identifier -> Text -> Compiler (Expr Src Import) Source #
Version of parseDhallWith that only acceps the DRRaw resolver,
remapping the imports with the function in the DRRaw. Does not
perform any normalization.
Arguments
| :: DhallCompilerOptions X | |
| -> Maybe Identifier | Optional |
| -> Expr Src Import | |
| -> Compiler (Expr Src X) |
Resolve all imports in a parsed Dhall expression.
This implements the "magic" of dependency tracking: implemented so that any local dependencies within the project directory are tracked by Hakyll, and so modifications to required files will also cause upstream files to be rebuilt.