diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,19 @@ Changelog ========= +Version 0.2.0.0 +--------------- + +*October 8, 2018* + + + +* Revamped workflow; largely incompatible with v0.1.0.0. + Version 0.1.0.0 --------------- -*October 3, 2018* +*October 7, 2018* diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -16,6 +16,24 @@ `dhallCompiler` is meant as a "final end-point", which just pretty-prints a parsed Dhall file, with optional normalization. +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. + +There are three major workflows: + +1. `dExprCompiler`, `loadDhall`, and `dhallCompiler`, for loading underlying + Dhall files, saving them into the Hakyll cache and later interpreting them + as values. + +2. `parseDhall` and `parseDhallExpr`, for parsing Dhall expressions provided as + strings, and resolving them while tracking dependencies. + +3. `dhallPrettyCompiler`, for processing and re-formatting Dhall files and + presenting them as-is as a "final end-point". + [hakyll-dhall]: http://hackage.haskell.org/package/hakyll-dhall [hakyll]: http://hackage.haskell.org/package/hakyll [dhall]: http://hackage.haskell.org/package/dhall diff --git a/app/test-app.hs b/app/test-app.hs --- a/app/test-app.hs +++ b/app/test-app.hs @@ -8,8 +8,8 @@ main = hakyll $ do match "test-dhall/**" $ do route idRoute - compile dhallFullCompiler + compile dhallFullPrettyCompiler create ["testparse.txt"] $ do route idRoute - compile $ loadDhall (auto :: Type String) "test-dhall/parse-test.dhall" + compile $ parseDhall (auto :: Type String) Nothing "./test-dhall/parse-test.dhall" diff --git a/hakyll-dhall.cabal b/hakyll-dhall.cabal --- a/hakyll-dhall.cabal +++ b/hakyll-dhall.cabal @@ -1,13 +1,11 @@ -cabal-version: 1.12 - --- This file has been generated from package.yaml by hpack version 0.30.0. +-- This file has been generated from package.yaml by hpack version 0.28.2. -- -- see: https://github.com/sol/hpack -- --- hash: 25f480672df6d437301f7a05c8f3999bdc244d13ea7a789df755a6a6419a734c +-- hash: 09eb91e35254576dbe38981485e439fbef1d3cef1b8551e4bf7591c372261be9 name: hakyll-dhall -version: 0.1.0.0 +version: 0.2.0.0 synopsis: Dhall compiler for Hakyll description: Please see the README on GitHub at category: Web @@ -20,9 +18,10 @@ license-file: LICENSE tested-with: GHC >= 8.2 && < 8.8 build-type: Simple +cabal-version: >= 1.10 extra-source-files: - README.md CHANGELOG.md + README.md test-dhall/foo.dhall test-dhall/parse-test.dhall test-dhall/test-file.dhall @@ -49,7 +48,7 @@ , data-default-class , dhall >1.17 , filepath - , hakyll + , hakyll >=4.10 , lens-family-core , mtl , prettyprinter @@ -67,6 +66,6 @@ build-depends: base >=4.7 && <5 , dhall >1.17 - , hakyll + , hakyll >=4.10 , hakyll-dhall default-language: Haskell2010 diff --git a/src/Hakyll/Web/Dhall.hs b/src/Hakyll/Web/Dhall.hs --- a/src/Hakyll/Web/Dhall.hs +++ b/src/Hakyll/Web/Dhall.hs @@ -24,13 +24,17 @@ -- 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. - +-- There are three major workflows: +-- +-- 1. 'dExprCompiler', 'loadDhall', and 'dhallCompiler', for loading +-- underlying Dhall files, saving them into the Hakyll cache and later +-- interpreting them as values. +-- +-- 2. 'parseDhall' and 'parseDhallExpr', for parsing Dhall expressions +-- provided as strings, and resolving them while tracking dependencies. +-- +-- 3. 'dhallPrettyCompiler', for processing and re-formatting Dhall +-- files and presenting them as-is as a "final end-point". module Hakyll.Web.Dhall ( -- * Configuration and Options @@ -38,20 +42,25 @@ , defaultDhallCompilerOptions, dcoResolver, dcoMinimize, dcoNormalize -- ** Resolver Behaviors , DhallResolver(..), DefaultDhallResolver(..), drRemap, drFull - -- * Load Dhall Files - -- ** As as custom Haskell types - , loadDhall, loadDhallWith - -- ** As raw expressions - , loadDhallExpr, loadDhallExprWith + -- * Import and Load Dhall Files + -- ** As Dhall expressions , DExpr(..) - -- * Parse raw Dhall expressions + , dExprCompiler, dExprCompilerWith + -- *** From Hakyll cache + , loadDhall, loadDhallSnapshot + -- ** As Haskell types + , dhallCompiler, dhallCompilerWith + -- * Parse Dhall + -- ** As Haskell types , parseDhall, parseDhallWith - -- * Compile (prettify, normalize, re-map) Dhall Files - , dhallCompiler - , dhallRawCompiler, dhallFullCompiler - , dhallCompilerWith + -- ** As Dhall Expressions + , parseDhallExpr, parseDhallExprWith + -- * Compile (prettify, normalize, re-map) Dhall text files + , dhallPrettyCompiler + , dhallRawPrettyCompiler, dhallFullPrettyCompiler + , dhallPrettyCompilerWith -- * Internal Utilities - , parseRawDhallWith + , parseRawDhallExprWith , resolveDhallImports ) where @@ -63,7 +72,7 @@ import Data.IORef import Data.Maybe import Data.Typeable (Typeable) -import Dhall hiding (maybe) +import Dhall import Dhall.Binary import Dhall.Core import Dhall.Diff @@ -140,15 +149,15 @@ -- | Types of external imports that a Dhall file may have. data DhallCompilerTrust = DCTLocal - -- ^ File on local filesystem outside of - -- project directory, and therefore not tracked - -- by Hakyll + -- ^ File on local filesystem outside of + -- project directory, and therefore not tracked + -- by Hakyll | DCTRemote - -- ^ Link to remote resource over a network - -- connection + -- ^ Link to remote resource over a network + -- connection | DCTEnv - -- ^ Reference to environment variable on - -- machine + -- ^ Reference to environment variable on + -- machine deriving (Generic, Typeable, Show, Eq, Ord) -- | Options for loading Dhall files. @@ -157,8 +166,8 @@ -- ^ Method to resolve imports encountered in files. See -- documentation of 'DhallResolver' for more details. , _dcoMinimize :: Bool - -- ^ Strictly for usage with 'dhallCompiler' and family: should the - -- result be "minimized" (all in one line) or pretty-printed for + -- ^ Strictly for usage with 'dhallPrettyCompiler' and family: should + -- the result be "minimized" (all in one line) or pretty-printed for -- human readability? -- -- Can be useful for saving bandwidth. @@ -286,16 +295,16 @@ -- /TypeApplications/. -- -- @ --- 'dhallRawCompiler' = 'dhallCompiler' \@'Import' --- 'dhallFullCompiler' = 'dhallCompiler' \@'X' +-- 'dhallRawPrettyCompiler' = 'dhallPrettyCompiler' \@'Import' +-- 'dhallFullPrettyCompiler' = 'dhallPrettyCompiler' \@'X' -- @ -- -- It might be more convenient to just use 'dhallRawCompiler' or -- 'dhallFullCompiler'. -dhallCompiler +dhallPrettyCompiler :: forall a. (DefaultDhallResolver a, PP.Pretty a) => Compiler (Item String) -dhallCompiler = dhallCompilerWith @a defaultDhallCompilerOptions +dhallPrettyCompiler = dhallPrettyCompilerWith @a defaultDhallCompilerOptions -- TODO: way to only resolve Env and Absolute and Home? -- Need to somehow hook into 'loadWith' so it can be recursive @@ -304,25 +313,23 @@ -- 'DhallCompilerOptions' while leaving all imports unchanged and -- unresolved. Essentially a Dhall pretty-printer, (optional) normalizer, -- and re-formatter. -dhallRawCompiler :: Compiler (Item String) -dhallRawCompiler = dhallCompilerWith @Import defaultDhallCompilerOptions +dhallRawPrettyCompiler :: Compiler (Item String) +dhallRawPrettyCompiler = dhallPrettyCompilerWith @Import defaultDhallCompilerOptions -- | 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. -dhallFullCompiler :: Compiler (Item String) -dhallFullCompiler = dhallCompilerWith @X defaultDhallCompilerOptions +dhallFullPrettyCompiler :: Compiler (Item String) +dhallFullPrettyCompiler = dhallPrettyCompilerWith @X defaultDhallCompilerOptions --- | 'dhallCompiler', but with custom 'DhallCompilerOptions'. -dhallCompilerWith +-- | 'dhallPrettyCompiler', but with custom 'DhallCompilerOptions'. +dhallPrettyCompilerWith :: PP.Pretty a => DhallCompilerOptions a -> Compiler (Item String) -dhallCompilerWith dco = do - i <- getUnderlying - b <- T.pack . itemBody <$> getResourceBody - e <- parseDhallWith dco (Just i) b +dhallPrettyCompilerWith dco = do + DExpr e <- itemBody <$> dExprCompilerWith dco makeItem $ T.unpack (disp e) where disp @@ -332,56 +339,186 @@ . PP.unAnnotate . prettyExpr --- | Version of 'parseDhallWith' that only acceps the 'DRRaw' resolver, --- remapping the imports with the function in the 'DRRaw'. Does not --- perform any normalization. -parseRawDhallWith - :: DhallCompilerOptions Import - -> Maybe Identifier - -> T.Text - -> Compiler (Expr Src Import) -parseRawDhallWith DCO{..} i b = - case exprFromText (maybe "Raw dhall string" toFilePath i) b of - Left e -> throwError . (:[]) $ - "Error parsing raw dhall file: " ++ show e - Right e -> join <$> traverse (_drRemap _dcoResolver) e +-- | Compile the underlying text file as a Dhall expression, wrapped in +-- a 'DExpr' newtype. Mostly useful for pre-cacheing fully resolved Dhall +-- expressions into the Hakyll cache, which you can later interpret and +-- load with 'loadDhall' or 'loadDhallSnapshot'. A @'DExpr' a@ is an +-- @'Expr' 'Src' a@, but wrapped so that it has a 'Bi.Binary' instance that +-- is usable by the Hakyll cache. +-- +-- For example, here is a rule to parse and cache all configuration files: +-- +-- @ +-- 'match' "config/**.dhall" $ do +-- 'route' 'mempty' +-- 'compile' $ 'dExprCompiler' \@'X' +-- @ +-- +-- This will save all of the dhall files in the directory ./config in the +-- Hakyll cache. They can later be loaded and interpreted in the +-- 'Compiler' monad using: +-- +-- @ +-- 'loadDhall' 'auto' "config/my_config.dhall" +-- @ +-- +-- Note that this is mostly useful for routes that match many different +-- files which will be interpreted as values of different types, or for +-- caching a single expression that you might want to interpret as +-- different types later. +-- +-- If you want to parse and immediately interpret, see 'dhallCompiler'. +dExprCompiler :: DefaultDhallResolver a => Compiler (Item (DExpr a)) +dExprCompiler = dExprCompilerWith defaultDhallCompilerOptions +-- | 'dExprCompiler', but with custom 'DhallCompilerOptions'. +dExprCompilerWith + :: DhallCompilerOptions a + -> Compiler (Item (DExpr a)) +dExprCompilerWith dco = do + b <- itemBody <$> getResourceBody + d <- takeDirectory . toFilePath <$> getUnderlying + makeItem . DExpr =<< parseDhallExprWith dco (Just d) (T.pack b) + +-- | Parse the underlying text file as a Dhall expression and directly +-- interpret it as a value of the given type. Tracks all dependencies, so +-- will trigger rebuilds based on downstream changes. +dhallCompiler + :: Type a + -> Compiler (Item a) +dhallCompiler = dhallCompilerWith defaultDhallCompilerOptions + +-- | 'dhallCompiler', but with custom 'DhallCompilerOptions'. +dhallCompilerWith + :: DhallCompilerOptions X + -> Type a + -> Compiler (Item a) +dhallCompilerWith dco t = do + DExpr e <- itemBody <$> dExprCompilerWith dco + makeItem =<< interpretDhallCompiler t e + +-- | Wrapper over 'load' and 'interpretDhallCompiler'. Pulls up a 'DExpr' +-- compiled or saved into the Hakyll cache and interprets it as a value. +-- +-- Expects item at identifier to be saved as @'DExpr' 'X'@ (possibly using +-- @'dExprCompiler' \@'X'@) +loadDhall + :: Type a + -> Identifier + -> Compiler (Item a) +loadDhall t i = do + DExpr e <- loadBody i + makeItem =<< interpretDhallCompiler t e + +-- | Wrapper over 'loadSnapshot' and 'interpretDhallCompiler'. Pulls up +-- a 'DExpr' saved into the Hakyll cache as a snapshot and interprets it as +-- a value. +-- +-- Expects item at identifier to be saved as @'DExpr' 'X'@ (possibly using +-- @'dExprCompiler' \@'X'@) +loadDhallSnapshot + :: Type a + -> Identifier + -> Snapshot + -> Compiler (Item a) +loadDhallSnapshot t i s = do + DExpr e <- loadSnapshotBody i s + makeItem =<< interpretDhallCompiler t e + -- | Parse a Dhall source. Meant to be useful for patterns similar to -- @dhall-to-text@. If using examples from -- , you can use: -- -- @ --- 'parseDhall' 'Nothing' ".\/make-items .\/people" +-- 'parseDhallExpr' 'Nothing' ".\/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. +-- +-- To directly obtain a Dhall expression, see 'parseDhallExpr'. parseDhall - :: DefaultDhallResolver a - => Maybe Identifier -- ^ Optional 'Identifier' used to specify directory root for imports + :: Type a + -> Maybe FilePath -- ^ Override directory root -> T.Text - -> Compiler (Expr Src a) + -> Compiler (Item a) parseDhall = parseDhallWith defaultDhallCompilerOptions -- | Version of 'parseDhall' taking custom 'DhallCompilerOptions'. parseDhallWith + :: DhallCompilerOptions X + -> Type a + -> Maybe FilePath -- ^ Override directory root + -> T.Text + -> Compiler (Item a) +parseDhallWith dco t fp b = do + e <- parseDhallExprWith dco fp b + makeItem =<< interpretDhallCompiler t e + +-- | Interpret a fully resolved Dhall expression as a value of a type, +-- given a 'Type'. Run in 'Compiler' to integrate error handling with +-- Hakyll. +interpretDhallCompiler + :: Type a + -> Expr Src X + -> Compiler a +interpretDhallCompiler t e = case rawInput t e of + Nothing -> throwError . (terr:) . (:[]) $ case typeOf e of + Left err -> show err + Right t0 -> T.unpack + . PP.renderStrict + . PP.layoutSmart layoutOpts + . diffNormalized (expected t) + $ t0 + Just x -> pure x + where + terr = "Error interpreting Dhall expression as desired type." + +-- | Version of 'parseDhall' that directly returns a Dhall expression, +-- instead of trying to interpret it into a custom Haskell type. +-- +-- 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. +parseDhallExpr + :: DefaultDhallResolver a + => Maybe FilePath -- ^ Override directory root + -> T.Text + -> Compiler (Expr Src a) +parseDhallExpr = parseDhallExprWith defaultDhallCompilerOptions + +-- | Version of 'parseDhallExpr' taking custom 'DhallCompilerOptions'. +parseDhallExprWith :: DhallCompilerOptions a - -> Maybe Identifier -- ^ Optional 'Identifier' used to specify directory root for imports + -> Maybe FilePath -- ^ Override directory root -> T.Text -> Compiler (Expr Src a) -parseDhallWith dco i b = case _dcoResolver dco of - DRRaw _ -> norm <$> parseRawDhallWith dco i b +parseDhallExprWith dco d b = case _dcoResolver dco of + DRRaw _ -> norm <$> parseRawDhallExprWith dco b DRFull _ -> fmap norm - . resolveDhallImports dco i - =<< parseRawDhallWith (dco { _dcoResolver = defaultDhallResolver }) - i b + . resolveDhallImports dco d + =<< parseRawDhallExprWith (dco { _dcoResolver = defaultDhallResolver }) + b where norm :: Eq b => Expr s b -> Expr s b norm | _dcoNormalize dco = normalize | otherwise = id +-- | Version of 'parseDhallExprWith' that only acceps the 'DRRaw' resolver, +-- remapping the imports with the function in the 'DRRaw'. Does not +-- perform any normalization. +parseRawDhallExprWith + :: DhallCompilerOptions Import + -> T.Text + -> Compiler (Expr Src Import) +parseRawDhallExprWith DCO{..} b = + case exprFromText "Hakyll.Web.Dhall.parseRawDhallExprWith" b of + Left e -> throwError . (:[]) $ + "Error parsing raw dhall file: " ++ show e + Right e -> join <$> traverse (_drRemap _dcoResolver) e + -- | Resolve all imports in a parsed Dhall expression. -- -- This implements the "magic" of dependency tracking: implemented so that @@ -390,14 +527,14 @@ -- files to be rebuilt. resolveDhallImports :: DhallCompilerOptions X - -> Maybe Identifier -- ^ Optional 'Identifier' used to specify directory root for imports + -> Maybe FilePath -- ^ Override directory root -> Expr Src Import -> Compiler (Expr Src X) -resolveDhallImports DCO{..} ident e = do +resolveDhallImports DCO{..} d e = do (res, imps) <- unsafeCompiler $ do iRef <- newIORef [] res <- evalStateT (loadWith e) $ - emptyStatus (takeDirectory (maybe "./" toFilePath ident)) + emptyStatus (fromMaybe "./" d) & resolver .~ \i -> do liftIO $ modifyIORef iRef (i:) exprFromImport i @@ -426,52 +563,3 @@ | otherwise -> Just neverTrust Missing -> Just neverTrust neverTrust = PatternDependency mempty mempty - --- | 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. -loadDhallExpr - :: DefaultDhallResolver a - => Identifier - -> Compiler (Item (Expr Src a)) -loadDhallExpr = loadDhallExprWith defaultDhallCompilerOptions - --- | Version of 'loadDhallExpr' taking custom 'DhallCompilerOptions'. -loadDhallExprWith - :: DhallCompilerOptions a - -> Identifier - -> Compiler (Item (Expr Src a)) -loadDhallExprWith dco i = do - b <- T.pack <$> loadBody i - Item i <$> parseDhallWith dco (Just i) b - --- | Load a value of type @a@ that is parsed from a Dhall file at the given --- 'Identifier'. Tracks dependencies within project. -loadDhall - :: Type a - -> Identifier - -> Compiler (Item a) -loadDhall = loadDhallWith defaultDhallCompilerOptions - --- | Version of 'loadDhall' taking custom 'DhallCompilerOptions'. -loadDhallWith - :: DhallCompilerOptions X - -> Type a - -> Identifier - -> Compiler (Item a) -loadDhallWith dco t ident = traverse (inp t) - =<< loadDhallExprWith dco ident - where - inp :: Type a -> Expr Src X -> Compiler a - inp t' e = case rawInput t' e of - Nothing -> throwError . (terr:) . (:[]) $ case typeOf e of - Left err -> show err - Right t0 -> T.unpack - . PP.renderStrict - . PP.layoutSmart layoutOpts - . diffNormalized (expected t) - $ t0 - Just x -> pure x - terr = "Error interpreting Dhall expression as desired type."