| Copyright | © 2016–2017 Stack Builders |
|---|---|
| License | BSD 3 clause |
| Maintainer | Mark Karpov <markkarpov@openmailbox.org> |
| Stability | experimental |
| Portability | portable |
| Safe Haskell | None |
| Language | Haskell2010 |
Text.Mustache
Description
This is a Haskell implementation of Mustache templates. The implementation conforms to the version 1.1.3 of official Mustache specification https://github.com/mustache/spec. It is extremely simple and straightforward to use with 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 superior quality of error messages.
For rendering you only need to create Aeson's Value where
you put the data to interpolate. Since the library re-uses Aeson's
instances and most data types in Haskell ecosystem are instances of
classes like ToJSON, the whole process is very simple for
end user.
Template Haskell helpers for compilation of templates at compile time are available in the Text.Mustache.Compile.TH module. The helpers are currently available only for GHC 8 users though.
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.
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 err -> putStrLn (parseErrorPretty err)
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/
- data Template = Template {
- templateActual :: PName
- templateCache :: Map PName [Node]
- data Node
- newtype Key = Key {}
- newtype PName = PName {}
- data MustacheException
- compileMustacheDir :: (MonadIO m, MonadThrow m) => PName -> FilePath -> m Template
- compileMustacheFile :: (MonadIO m, MonadThrow m) => FilePath -> m Template
- compileMustacheText :: PName -> Text -> Either (ParseError Char Dec) Template
- renderMustache :: Template -> Value -> Text
Types
Mustache template as name of “top-level” template and a collection of all available templates (partials).
Template is a Semigroup. This means that you can combine Templates
(and their caches) using the ( operator, the resulting <>)Template
will have the same currently selected template as the left one. Union of
caches is also left-biased.
Constructors
| Template | |
Fields
| |
Structural element of template.
Identifier for values to interpolate.
The representation is the following:
[]— empty list means implicit iterators;[text]— single key is a normal identifier;[text1, text2]— multiple keys represent dotted names.
Identifier for partials. Note that with the OverloadedStrings
extension you can use just string literals to create values of this type.
data MustacheException Source #
Exception that is thrown when parsing of a template has failed or referenced values were not provided.
Constructors
| MustacheParserException (ParseError Char Dec) | Template parser has failed. This contains the parse error. Before version 0.2.0 it was called |
| MustacheRenderException PName Key | A referenced value was not provided. The exception provides info
about partial in which the issue happened Since: 0.2.0 |
Compiling
Arguments
| :: (MonadIO m, MonadThrow m) | |
| => PName | Which template to select after compiling |
| -> FilePath | Directory with templates |
| -> m Template | The resulting template |
Compile all templates in specified directory and select one. Template
files should have extension mustache, (e.g. foo.mustache) to be
recognized. This function does not scan the directory recursively.
The action can throw the same exceptions as getDirectoryContents, and
readFile.
Arguments
| :: (MonadIO m, MonadThrow m) | |
| => FilePath | Location of the file |
| -> m Template |
Compile single Mustache template and select it.
The action can throw the same exceptions as readFile.
Rendering
renderMustache :: Template -> Value -> Text Source #
Render a Mustache Template using Aeson's Value to get actual values
for interpolation.
As of version 0.2.0, if referenced values are missing (which almost
always indicates some sort of mistake), MustacheRenderException will be
thrown. The included Key will indicate full path to missing value and
PName will contain the name of active partial.