b73fc8e · hakyll · git.iko.soy

git.iko.soy/hakyll

Add some more information on metacompilation

commitb73fc8e831806abf6432e5e443834e94c70dd4e7 authorJasper Van der Jeugt <jaspervdj@gmail.com> dateSat 26 Feb 2011, 11:07 (16 years ago) parentc89cfdb

2 files changed+28−3

compare with master

unifiedsplit

examples/hakyll/tutorial.markdown+8−2 src/Hakyll/Core/Rules.hs+20−1

examples/hakyll/tutorial.markdown+8−2

@@ -150,7 +150,8 @@ later[^1].

150150 template compile rule at the bottom -- this would make no difference.

151151

152152Now, it's time to actually render our pages. We use the `forM_` monad combinator

153−so we can describe all files at once.

153+so we can describe all files at once (instead of compiling all three files

154+manually).

154155

155156~~~~~{.haskell}

156157forM_ ["about.rst", "index.markdown", "code.lhs"] $ \page -> do

@@ -170,7 +171,7 @@ DSL there.

170171

171172The gist of it is that the `Compiler a b` type has two parameters -- it is an

172173Arrow, and we can chain compilers using the `>>>` operator. The [compiler]

173−reference page has some more information on this subject.

174+reference page has some more readable information on this subject.

174175

175176[compiler]: /reference/Hakyll-Core-Compiler.html

176177

@@ -179,3 +180,8 @@ compile page $ pageCompiler

179180 >>> applyTemplateCompiler "templates/default.html"

180181 >>> relativizeUrlsCompiler

181182~~~~~

183+

184+Note that we can only use `applyTemplateCompiler` with

185+`"templates/default.html"` because we compiled `"templates/default.html"`. If we

186+didn't list a rule for that item, the compilation would fail (Hakyll would not

187+know what `"templates/default.html"` is!).

src/Hakyll/Core/Rules.hs+20−1

@@ -81,7 +81,9 @@ compile pattern compiler = RulesM $ do

8181-- | Add a compilation rule

8282--

8383-- This sets a compiler for the given identifier. No resource is needed, since

84−-- we are creating the item from scratch.

84+-- we are creating the item from scratch. This is useful if you want to create a

85+-- page on your site that just takes content from other items -- but has no

86+-- actual content itself.

8587--

8688create :: (Binary a, Typeable a, Writable a)

8789 => Identifier -> Compiler () a -> Rules

@@ -98,6 +100,23 @@ route pattern route' = tellRoute $ ifMatch pattern route'

98100-- Metacompilers are a special class of compilers: they are compilers which

99101-- produce other compilers.

100102--

103+-- This is needed when the list of compilers depends on something we cannot know

104+-- before actually running other compilers. The most typical example is if we

105+-- have a blogpost using tags.

106+--

107+-- Every post has a collection of tags. For example,

108+--

109+-- > post1: code, haskell

110+-- > post2: code, random

111+--

112+-- Now, we want to create a list of posts for every tag. We cannot write this

113+-- down in our 'Rules' DSL directly, since we don't know what tags the different

114+-- posts will have -- we depend on information that will only be available when

115+-- we are actually compiling the pages.

116+--

117+-- The solution is simple, using 'metaCompile', we can add a compiler that will

118+-- parse the pages and produce the compilers needed for the different tag pages.

119+--

101120-- And indeed, we can see that the first argument to 'metaCompile' is a

102121-- 'Compiler' which produces a list of ('Identifier', 'Compiler') pairs. The

103122-- idea is simple: 'metaCompile' produces a list of compilers, and the