tophat
Template-to-Haskell preprocessor, and templating language
https://github.com/jcranch/tophat
Version on this page: | 1.0.5.1 |
LTS Haskell 22.37: | 1.0.8.0 |
Stackage Nightly 2024-10-11: | 1.0.8.0 |
Latest on Hackage: | 1.0.8.0 |
tophat-1.0.5.1@sha256:0ed76a327a3d92c892df25b89682afd533dda148f0ccf2fdb16f412fb396ac7f,2967
Module documentation for 1.0.5.1
Tophat
Tophat is a template engine for Haskell. It has two components:
-
a preprocessor for Haskell code (source) which embeds templates directly into it, and
-
a small, fairly self-contained library (webpage, source) of template combinators, intended for use with it containing all the usual imperative control structures (
if
,for
, and so on).
An example
Here’s a short example. The Haskell source code is as follows (in the examples directory of the repository):
{-# LANGUAGE OverloadedStrings #-}
module Main where
import Data.Text (Text)
import qualified Data.Text as T
import qualified Data.Text.IO as T
import Tophat
aliceTheCamel :: Template Int Text
aliceTheCamel = {{alicethecamel.tpt.txt}}
main :: IO ()
main = T.putStr $ runTemplate aliceTheCamel 3
Meanwhile, in the file alicethecamel.tpt.txt
, we put the following:
$forH (\ n -> reverse [0..n])$
$forH (replicate 3)$
Alice the camel has $embedShow id$ humps,
$endfor$
$ifH (> 0)$
So go, Alice, go!
$endif$
$ifH (== 0)$
Because Alice is a horse.
$endif$
$endfor$
This outputs a version of a classic nursery rhyme. The spacing is idiosyncratic: the template above was formatted to make it easy to read. If we were writing HTML or another language where whitespace is insignificant, it would be fine, but the proper formatting of nursery rhymes is important. Adjusting the spacing makes it more correct but less pleasant.
$forH (\ n -> reverse [0..n]) >>> forH (replicate 3)$
Alice the camel has $embedShow id$ humps,$endfor$
$ifH (> 0)$So go, Alice, go!$endif$$ifH (== 0)$Because Alice is a horse.$endif$
$endfor$
Alternatively we can take charge of newlines, and whitespace around newlines, for ourselves, by adding a postprocessor:
$procH (T.replace ("\\n" "\n") . T.concat . fmap T.strip . T.lines)$
$forH (\ n -> reverse [0..n])$
$forH (replicate 3)$
Alice the camel has $embedShow id$ humps,\n
$endfor$
$ifH (> 0)$
So go, Alice, go!
$endif$
$ifH (== 0)$
Because Alice is a horse.
$endif$\n\n
$endfor$
$endproc$
This replacement of whitespace is useful enough that we’ve placed it
in Tophat.Text
.
Comparisons with other templating engines
Advantages
Interoperability
The code in Tophat templates is just Haskell, and so can be mixed freely with the other code in the project.
As a rule of thumb, template logic should be kept fairly simple. But it is certainly pleasant to be able to do straightforward computations in templates, and for those calculations to have exactly the same syntax as if they were done elsewhere.
Power and extensibility
Relatedly, the power of Haskell means that the control structures provided are unusually powerful. For example, the “for” command works over any instance of the Foldable typeclass.
However, the framework is fairly simple, and it is easy to define new control structures if desired.
Flexibility
Any type which is an instance of IsString
(from Data.String
) can be
used: Tophat templates can generate any of the main string types, or
more exotic ones, with equal ease.
Disadvantages
Novelty
Since other template languages are not Haskell, templates written for other engines will need some converting to work with Tophat.
New syntax
Since the templates are used directly from Haskell source code, the
{{
and }}
brackets which introduce a template are new syntax. This
may mess up editor syntax highlighting, hlint, and other tools which
depend on analysing the lexical structure of Haskell source code.
Benchmarking
I don’t have any good data.
Alternatives
I don’t know of any package that takes the same approach to templating, but the following are all entirely legitimate alternatives:
-
Haiji, using Jinja2 syntax
-
Shakespeare, as used in Yesod
-
Heterocephalus, which uses template Haskell
Forcing recompilation
Since the code that will be compiled depends on templates, it is necessary to recompile whenever the templates change, and not just when the source file changes. There are various ways of going about this.
GHC options
GHC can be asked to always recompile the file:
{-# OPTIONS_GHC -fforce-recomp #-}
Stack
Stack has options that allow extra source files to be declared
Template Haskell
Template Haskell also has options for declaring dependent files.
Why the name?
It stands for “thunks of pure Haskell as templates”, but let’s not worry about that.
Changes
Changelog for Tophat
Changes in 1.0.5.1
- Generalising bounds to allow text-2
Changes in 1.0.5.0
- Maintenance of bounds.
Changes in 1.0.1.0
- Better section headings in docs.
Changes in 1.0.0.0
- Package released!