stache
Mustache templates for Haskell
https://github.com/stackbuilders/stache
Version on this page: | 2.3.0 |
LTS Haskell 22.39: | 2.3.4@rev:2 |
Stackage Nightly 2024-11-02: | 2.3.4@rev:3 |
Latest on Hackage: | 2.3.4@rev:3 |
stache-2.3.0@sha256:528bf59d8d6257fbf988130ab0a79f28dcbadbea61d1966a24ebc9c7ca7828c4,4340
Module documentation for 2.3.0
Stache
This is a Haskell implementation of Mustache templates. The implementation conforms to the version 1.1.3 of the official Mustache specification. It has a minimal but complete API—three functions to compile templates (from directory, from file, and from lazy text) and one to render them.
The implementation uses the Megaparsec parsing library to parse the templates which results in high-quality error messages.
For rendering one only needs to create Aeson’s Value
that is used for
interpolation of template variables. Since the library re-uses Aeson’s
instances and most data types in the Haskell ecosystem are instances of
classes like Data.Aeson.ToJSON
, the process is simple for the end user.
Template Haskell helpers for compilation of templates at compile time are
available in the Text.Mustache.Compile.TH
module.
One feature that is not currently supported is lambdas. The feature is marked as optional in the spec and can be emulated via processing of parsed template representation. The decision to drop lambdas is intentional, for the sake of simplicity and better integration with Aeson.
Quick start
Here is an example of basic usage:
{-# LANGUAGE OverloadedStrings #-}
module Main (main) where
import Data.Aeson
import Data.Text
import Text.Megaparsec
import Text.Mustache
import qualified Data.Text.Lazy.IO as TIO
main :: IO ()
main = do
let res = compileMustacheText "foo"
"Hi, {{name}}! You have:\n{{#things}}\n * {{.}}\n{{/things}}\n"
case res of
Left bundle -> putStrLn (errorBundlePretty bundle)
Right template -> TIO.putStr $ renderMustache template $ object
[ "name" .= ("John" :: Text)
, "things" .= ["pen" :: Text, "candle", "egg"]
]
If I run the program, it prints the following:
Hi, John! You have:
* pen
* candle
* egg
For more information about Mustache templates the following links may be helpful:
- The official Mustache site: https://mustache.github.io/
- The manual: https://mustache.github.io/mustache.5.html
- The specification: https://github.com/mustache/spec
- Stack Builders Stache tutorial: https://www.stackbuilders.com/tutorials/haskell/mustache-templates/
Contribution
Issues, bugs, and questions may be reported in the GitHub issue tracker for this project.
Pull requests are also welcome.
License
Copyright © 2016–present Stack Builders
Distributed under BSD 3 clause license.
Changes
Stache 2.3.0
- Allowed parsing a wider range of keys in the templates thus making the library’s behavior closer to other existing implementations.
Stache 2.2.1
- Works with GHC 9.0.1, dropped support for GHC 8.6.x and older.
Stache 2.2.0
- Added the executable program.
Stache 2.1.1
-
Fixed the bug related to incorrect indentation with nested partials. Issue 44.
-
Dropped support for GHC 8.2 and older.
Stache 2.1.0
-
Dropped support for GHC 8.0 and older.
-
Documentation improvements.
-
Added Template Haskell
Lift
instance for theTemplate
type and its sub-components.
Stache 2.0.1
- Now interpolation with escaping also escapes single quotes as
'
.
Stache 2.0.0
- Uses Megaparsec 7. In particular, the parser now returns
ParseErrorBundle
on failure and the bundle is also insideMustacheException
.
Stache 1.2.1
- Fixed a bug in
compileMustacheDir'
fromText.Mustache.Compile.TH
: it did not use the supplied predicate and selected only.mustache
files likecompileMustacheDir
.
Stache 1.2.0
-
Added
compileMustacheDir'
andgetMusthacheFilesInDir'
that allow for a custom template predicate. Also exposedisMustacheFile
as the default predicate used by functions likecompileMustacheDir
. -
Abandon attempts to support GHC 7.8.
Stache 1.1.2
- Fixed compilation of the test suite with Cabal 2.0/GHC 8.2.1.
Stache 1.1.1
- Exported
mustacheRenderW
,MustacheWarning
, anddisplayMustacheWarning
fromText.Mustache
.
Stache 1.1.0
- Added
mustacheRenderW
that allows to render aTemplate
collecting warnings in the process. Also added theMusthacheWarning
type representing the warnings themselves anddisplayMustacheWarning
to pretty-print the warnings.
Stache 1.0.0
-
Improved metadata and documentation.
-
Breaking change: the
renderMustache
function does not throw exceptions when referenced key is not provided as per the spec. This is the behaviour we had before 0.2.0, and it played better with the rest of Mustache. Correspondingly,MustacheRenderException
was removed. -
Stache now uses Megaparsec 6 for parsing.
-
MustacheException
now includes original input asText
. -
compileMustacheText
andparseMustache
now accept strictText
instead of lazyText
. -
Minor improvement in rendering speed.
-
Stop depending on
exceptions
and dropMonadThrow
constraints.
Stache 0.2.2
-
Add the
getMustacheFilesInDir
function. -
Make TH helpers
compileMustacheDir
andcompileMustacheFile
detect changes in the templates and force recompilation.
Stache 0.2.1
- Made TH parse errors nicer.
Stache 0.2.0
-
Breaking change: the
renderMustache
function will throw an exception when referenced key was not provided. This is a better behavior than silent interpolation of an empty string, because missing values are almost always a mistake and it’s easy to provide empty strings explicitly anyway. -
Allowed
directory-1.3.0.0
.
Stache 0.1.8
- Rename
specs
directory tospecification
as the previous name somehow caused conflicts when deploying an application on Heroku with Stache as a dependency.
Stache 0.1.7
- Added
mustache
quasi-quoter.
Stache 0.1.6
- Fixed a bug in the lookup algorithm for dot-separated keys.
Stache 0.1.5
-
When section’s key is a number or non-empty string, it’s accessible as
.
in the section body. -
Allow Aeson 1.0.
Stache 0.1.4
-
Numbers are now treated as “true” values.
-
Added
Semigroup
instance forKey
. -
Now change of delimiters affects special unescaped variable syntax as well, for example:
{{=<< >>=}}<<{var}>>
will be parsed as unescaped variablevar
. -
compileMustacheFile
now shows full path to malformed template when the template cannot be parsed. -
Defined
displayException
method ofException
type class forMustacheException
usingparseErrorPretty
from Megaparsec.
Stache 0.1.3
-
Cosmetic improvements.
-
Minor improvement in performance of parser.
Stache 0.1.2
- Fixed compilation of benchmarks with Megaparsec 5.0.1 and later.
Stache 0.1.1
- Added benchmarks.
Stache 0.1.0
- Initial release.