stache-2.3.4: Mustache templates for Haskell
Copyright© 2016–present Stack Builders
LicenseBSD 3 clause
MaintainerMark Karpov <markkarpov92@gmail.com>
Stabilityexperimental
Portabilityportable
Safe HaskellNone
LanguageHaskell2010

Text.Mustache

Description

This is a Haskell implementation of Mustache templates. The implementation conforms to the version 1.1.3 of the official Mustache specification https://github.com/mustache/spec. 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 Megaparsec parsing library to parse the templates which results in high-quality error messages.

For rendering you only need 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 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.

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:

Synopsis

Types

data Template #

Mustache template as the name of the “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

  • templateActual :: PName

    The name of the currently “selected” template.

  • templateCache :: Map PName [Node]

    A collection of all templates that are available for interpolation (as partials). The top-level one is also contained here and the “focus” can be switched easily by modifying templateActual.

Instances

Instances details
Semigroup Template # 
Instance details

Defined in Text.Mustache.Type

Data Template # 
Instance details

Defined in Text.Mustache.Type

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Template -> c Template #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Template #

toConstr :: Template -> Constr #

dataTypeOf :: Template -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Template) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Template) #

gmapT :: (forall b. Data b => b -> b) -> Template -> Template #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Template -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Template -> r #

gmapQ :: (forall d. Data d => d -> u) -> Template -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> Template -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Template -> m Template #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Template -> m Template #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Template -> m Template #

Generic Template # 
Instance details

Defined in Text.Mustache.Type

Associated Types

type Rep Template 
Instance details

Defined in Text.Mustache.Type

type Rep Template = D1 ('MetaData "Template" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'False) (C1 ('MetaCons "Template" 'PrefixI 'True) (S1 ('MetaSel ('Just "templateActual") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 PName) :*: S1 ('MetaSel ('Just "templateCache") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map PName [Node]))))

Methods

from :: Template -> Rep Template x #

to :: Rep Template x -> Template #

Show Template # 
Instance details

Defined in Text.Mustache.Type

Eq Template # 
Instance details

Defined in Text.Mustache.Type

Ord Template # 
Instance details

Defined in Text.Mustache.Type

Lift Template #

Since: 2.1.0

Instance details

Defined in Text.Mustache.Type

Methods

lift :: Quote m => Template -> m Exp #

liftTyped :: forall (m :: Type -> Type). Quote m => Template -> Code m Template #

type Rep Template # 
Instance details

Defined in Text.Mustache.Type

type Rep Template = D1 ('MetaData "Template" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'False) (C1 ('MetaCons "Template" 'PrefixI 'True) (S1 ('MetaSel ('Just "templateActual") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 PName) :*: S1 ('MetaSel ('Just "templateCache") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map PName [Node]))))

data Node #

A structural element of a template.

Constructors

TextBlock Text

Plain text contained between tags

EscapedVar Key

HTML-escaped variable

UnescapedVar Key

Unescaped variable

Section Key [Node]

Mustache section

InvertedSection Key [Node]

Inverted section

Partial PName (Maybe Pos)

Partial with indentation level (Nothing means it was inlined)

Instances

Instances details
Data Node # 
Instance details

Defined in Text.Mustache.Type

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Node -> c Node #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Node #

toConstr :: Node -> Constr #

dataTypeOf :: Node -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Node) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Node) #

gmapT :: (forall b. Data b => b -> b) -> Node -> Node #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Node -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Node -> r #

gmapQ :: (forall d. Data d => d -> u) -> Node -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> Node -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Node -> m Node #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Node -> m Node #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Node -> m Node #

Generic Node # 
Instance details

Defined in Text.Mustache.Type

Methods

from :: Node -> Rep Node x #

to :: Rep Node x -> Node #

Show Node # 
Instance details

Defined in Text.Mustache.Type

Methods

showsPrec :: Int -> Node -> ShowS #

show :: Node -> String #

showList :: [Node] -> ShowS #

Eq Node # 
Instance details

Defined in Text.Mustache.Type

Methods

(==) :: Node -> Node -> Bool #

(/=) :: Node -> Node -> Bool #

Ord Node # 
Instance details

Defined in Text.Mustache.Type

Methods

compare :: Node -> Node -> Ordering #

(<) :: Node -> Node -> Bool #

(<=) :: Node -> Node -> Bool #

(>) :: Node -> Node -> Bool #

(>=) :: Node -> Node -> Bool #

max :: Node -> Node -> Node #

min :: Node -> Node -> Node #

Lift Node #

Since: 2.1.0

Instance details

Defined in Text.Mustache.Type

Methods

lift :: Quote m => Node -> m Exp #

liftTyped :: forall (m :: Type -> Type). Quote m => Node -> Code m Node #

type Rep Node # 
Instance details

Defined in Text.Mustache.Type

newtype Key #

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.

Constructors

Key 

Fields

Instances

Instances details
NFData Key # 
Instance details

Defined in Text.Mustache.Type

Methods

rnf :: Key -> () #

Monoid Key # 
Instance details

Defined in Text.Mustache.Type

Methods

mempty :: Key #

mappend :: Key -> Key -> Key #

mconcat :: [Key] -> Key #

Semigroup Key # 
Instance details

Defined in Text.Mustache.Type

Methods

(<>) :: Key -> Key -> Key #

sconcat :: NonEmpty Key -> Key #

stimes :: Integral b => b -> Key -> Key #

Data Key # 
Instance details

Defined in Text.Mustache.Type

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Key -> c Key #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Key #

toConstr :: Key -> Constr #

dataTypeOf :: Key -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Key) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Key) #

gmapT :: (forall b. Data b => b -> b) -> Key -> Key #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Key -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Key -> r #

gmapQ :: (forall d. Data d => d -> u) -> Key -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> Key -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Key -> m Key #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Key -> m Key #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Key -> m Key #

Generic Key # 
Instance details

Defined in Text.Mustache.Type

Associated Types

type Rep Key 
Instance details

Defined in Text.Mustache.Type

type Rep Key = D1 ('MetaData "Key" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'True) (C1 ('MetaCons "Key" 'PrefixI 'True) (S1 ('MetaSel ('Just "unKey") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Text])))

Methods

from :: Key -> Rep Key x #

to :: Rep Key x -> Key #

Show Key # 
Instance details

Defined in Text.Mustache.Type

Methods

showsPrec :: Int -> Key -> ShowS #

show :: Key -> String #

showList :: [Key] -> ShowS #

Eq Key # 
Instance details

Defined in Text.Mustache.Type

Methods

(==) :: Key -> Key -> Bool #

(/=) :: Key -> Key -> Bool #

Ord Key # 
Instance details

Defined in Text.Mustache.Type

Methods

compare :: Key -> Key -> Ordering #

(<) :: Key -> Key -> Bool #

(<=) :: Key -> Key -> Bool #

(>) :: Key -> Key -> Bool #

(>=) :: Key -> Key -> Bool #

max :: Key -> Key -> Key #

min :: Key -> Key -> Key #

Lift Key #

Since: 2.1.0

Instance details

Defined in Text.Mustache.Type

Methods

lift :: Quote m => Key -> m Exp #

liftTyped :: forall (m :: Type -> Type). Quote m => Key -> Code m Key #

type Rep Key # 
Instance details

Defined in Text.Mustache.Type

type Rep Key = D1 ('MetaData "Key" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'True) (C1 ('MetaCons "Key" 'PrefixI 'True) (S1 ('MetaSel ('Just "unKey") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Text])))

newtype PName #

Identifier for partials. Note that with the OverloadedStrings extension you can use just string literals to create values of this type.

Constructors

PName 

Fields

Instances

Instances details
NFData PName # 
Instance details

Defined in Text.Mustache.Type

Methods

rnf :: PName -> () #

Data PName # 
Instance details

Defined in Text.Mustache.Type

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> PName -> c PName #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c PName #

toConstr :: PName -> Constr #

dataTypeOf :: PName -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c PName) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c PName) #

gmapT :: (forall b. Data b => b -> b) -> PName -> PName #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> PName -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> PName -> r #

gmapQ :: (forall d. Data d => d -> u) -> PName -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> PName -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> PName -> m PName #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> PName -> m PName #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> PName -> m PName #

IsString PName # 
Instance details

Defined in Text.Mustache.Type

Methods

fromString :: String -> PName #

Generic PName # 
Instance details

Defined in Text.Mustache.Type

Associated Types

type Rep PName 
Instance details

Defined in Text.Mustache.Type

type Rep PName = D1 ('MetaData "PName" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'True) (C1 ('MetaCons "PName" 'PrefixI 'True) (S1 ('MetaSel ('Just "unPName") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text)))

Methods

from :: PName -> Rep PName x #

to :: Rep PName x -> PName #

Show PName # 
Instance details

Defined in Text.Mustache.Type

Methods

showsPrec :: Int -> PName -> ShowS #

show :: PName -> String #

showList :: [PName] -> ShowS #

Eq PName # 
Instance details

Defined in Text.Mustache.Type

Methods

(==) :: PName -> PName -> Bool #

(/=) :: PName -> PName -> Bool #

Ord PName # 
Instance details

Defined in Text.Mustache.Type

Methods

compare :: PName -> PName -> Ordering #

(<) :: PName -> PName -> Bool #

(<=) :: PName -> PName -> Bool #

(>) :: PName -> PName -> Bool #

(>=) :: PName -> PName -> Bool #

max :: PName -> PName -> PName #

min :: PName -> PName -> PName #

Lift PName #

Since: 2.1.0

Instance details

Defined in Text.Mustache.Type

Methods

lift :: Quote m => PName -> m Exp #

liftTyped :: forall (m :: Type -> Type). Quote m => PName -> Code m PName #

type Rep PName # 
Instance details

Defined in Text.Mustache.Type

type Rep PName = D1 ('MetaData "PName" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'True) (C1 ('MetaCons "PName" 'PrefixI 'True) (S1 ('MetaSel ('Just "unPName") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text)))

newtype MustacheException #

Exception that is thrown when parsing of a template fails or referenced values are not provided.

Constructors

MustacheParserException (ParseErrorBundle Text Void)

Template parser has failed. This contains the parse error.

Before version 0.2.0 it was called MustacheException.

The Text field was added in version 1.0.0.

Instances

Instances details
Exception MustacheException # 
Instance details

Defined in Text.Mustache.Type

Generic MustacheException # 
Instance details

Defined in Text.Mustache.Type

Associated Types

type Rep MustacheException 
Instance details

Defined in Text.Mustache.Type

type Rep MustacheException = D1 ('MetaData "MustacheException" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'True) (C1 ('MetaCons "MustacheParserException" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (ParseErrorBundle Text Void))))
Show MustacheException # 
Instance details

Defined in Text.Mustache.Type

Eq MustacheException # 
Instance details

Defined in Text.Mustache.Type

type Rep MustacheException # 
Instance details

Defined in Text.Mustache.Type

type Rep MustacheException = D1 ('MetaData "MustacheException" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'True) (C1 ('MetaCons "MustacheParserException" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (ParseErrorBundle Text Void))))

data MustacheWarning #

Warning that may be generated during rendering of a Template.

Since: 1.1.1

Constructors

MustacheVariableNotFound Key

The template contained a variable for which there was no data in the current context.

MustacheDirectlyRenderedValue Key

A complex value such as an Object or Array was directly rendered into the template.

Instances

Instances details
Generic MustacheWarning # 
Instance details

Defined in Text.Mustache.Type

Associated Types

type Rep MustacheWarning 
Instance details

Defined in Text.Mustache.Type

type Rep MustacheWarning = D1 ('MetaData "MustacheWarning" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'False) (C1 ('MetaCons "MustacheVariableNotFound" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Key)) :+: C1 ('MetaCons "MustacheDirectlyRenderedValue" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Key)))
Show MustacheWarning # 
Instance details

Defined in Text.Mustache.Type

Eq MustacheWarning # 
Instance details

Defined in Text.Mustache.Type

type Rep MustacheWarning # 
Instance details

Defined in Text.Mustache.Type

type Rep MustacheWarning = D1 ('MetaData "MustacheWarning" "Text.Mustache.Type" "stache-2.3.4-12n8t6Z2eXACjf6tDo3vkh" 'False) (C1 ('MetaCons "MustacheVariableNotFound" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Key)) :+: C1 ('MetaCons "MustacheDirectlyRenderedValue" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Key)))

Compiling

compileMustacheDir #

Arguments

:: MonadIO m 
=> PName

Which template to select after compiling

-> FilePath

Directory with templates

-> m Template

The resulting template

Compile all templates in the specified directory and select one. Template files should have the extension mustache, (e.g. foo.mustache) to be recognized. This function does not scan the directory recursively.

Note that each template/partial will get an identifier which consists of the name of corresponding template file with extension .mustache dropped. This is important for e.g. selecting active template after loading (the first argument).

The action can throw MustacheParserException and the same exceptions as getDirectoryContents, and readFile.

compileMustacheDir = complieMustacheDir' isMustacheFile

compileMustacheDir' #

Arguments

:: MonadIO m 
=> (FilePath -> Bool)

Template selection predicate

-> PName

Which template to select after compiling

-> FilePath

Directory with templates

-> m Template

The resulting template

The same as compileMustacheDir, but allows using a custom predicate for template selection.

Since: 1.2.0

compileMustacheFile #

Arguments

:: MonadIO m 
=> FilePath

Location of the file

-> m Template 

Compile a Mustache template and select it.

The action can throw MustacheParserException and the same exceptions as readFile.

compileMustacheText #

Arguments

:: PName

How to name the template?

-> Text

The template to compile

-> Either (ParseErrorBundle Text Void) Template

The result

Compile a Mustache template from a Text value. The cache will contain only this template named according to given PName.

Rendering

renderMustache :: Template -> Value -> Text #

Render a Mustache Template using Aeson's Value to get actual values for interpolation.

renderMustacheW :: Template -> Value -> ([MustacheWarning], Text) #

Like renderMustache, but also returns a collection of warnings.

Since: 1.1.1