microstache-1.0.1.1: Mustache templates for Haskell

Copyright© 2016–2017 Stack Builders
LicenseBSD 3 clause
MaintainerMark Karpov <markkarpov@openmailbox.org>
Stabilityexperimental
Portabilityportable
Safe HaskellNone
LanguageHaskell2010

Text.Microstache

Contents

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.Microstache.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.Microstache
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:

Synopsis

Types

data Template Source #

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

  • templateActual :: PName

    Name of currently “selected” template (top-level one).

  • templateCache :: Map PName [Node]

    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

Eq Template Source # 
Data Template Source # 

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 :: (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 #

Ord Template Source # 
Show Template Source # 
Generic Template Source # 

Associated Types

type Rep Template :: * -> * #

Methods

from :: Template -> Rep Template x #

to :: Rep Template x -> Template #

Semigroup Template Source # 
type Rep Template Source # 
type Rep Template = D1 (MetaData "Template" "Text.Microstache.Type" "microstache-1.0.1.1-A03s7o9iZQLBTWLjD1VsFt" False) (C1 (MetaCons "Template" PrefixI True) ((:*:) (S1 (MetaSel (Just Symbol "templateActual") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PName)) (S1 (MetaSel (Just Symbol "templateCache") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Map PName [Node])))))

data Node Source #

Structural element of 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 Word)

Partial with indentation level (Nothing means it was inlined)

Instances

Eq Node Source # 

Methods

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

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

Data Node Source # 

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 :: (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 #

Ord Node Source # 

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 #

Show Node Source # 

Methods

showsPrec :: Int -> Node -> ShowS #

show :: Node -> String #

showList :: [Node] -> ShowS #

Generic Node Source # 

Associated Types

type Rep Node :: * -> * #

Methods

from :: Node -> Rep Node x #

to :: Rep Node x -> Node #

type Rep Node Source # 

newtype Key Source #

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

Eq Key Source # 

Methods

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

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

Data Key Source # 

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 :: (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 #

Ord Key Source # 

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 #

Show Key Source # 

Methods

showsPrec :: Int -> Key -> ShowS #

show :: Key -> String #

showList :: [Key] -> ShowS #

Generic Key Source # 

Associated Types

type Rep Key :: * -> * #

Methods

from :: Key -> Rep Key x #

to :: Rep Key x -> Key #

Semigroup Key Source # 

Methods

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

sconcat :: NonEmpty Key -> Key #

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

Monoid Key Source # 

Methods

mempty :: Key #

mappend :: Key -> Key -> Key #

mconcat :: [Key] -> Key #

NFData Key Source # 

Methods

rnf :: Key -> () #

type Rep Key Source # 
type Rep Key = D1 (MetaData "Key" "Text.Microstache.Type" "microstache-1.0.1.1-A03s7o9iZQLBTWLjD1VsFt" True) (C1 (MetaCons "Key" PrefixI True) (S1 (MetaSel (Just Symbol "unKey") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Text])))

newtype PName Source #

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

Eq PName Source # 

Methods

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

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

Data PName Source # 

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 :: (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 #

Ord PName Source # 

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 #

Show PName Source # 

Methods

showsPrec :: Int -> PName -> ShowS #

show :: PName -> String #

showList :: [PName] -> ShowS #

IsString PName Source # 

Methods

fromString :: String -> PName #

Generic PName Source # 

Associated Types

type Rep PName :: * -> * #

Methods

from :: PName -> Rep PName x #

to :: Rep PName x -> PName #

NFData PName Source # 

Methods

rnf :: PName -> () #

type Rep PName Source # 
type Rep PName = D1 (MetaData "PName" "Text.Microstache.Type" "microstache-1.0.1.1-A03s7o9iZQLBTWLjD1VsFt" True) (C1 (MetaCons "PName" PrefixI True) (S1 (MetaSel (Just Symbol "unPName") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text)))

data MustacheException Source #

Exception that is thrown when parsing of a template has failed or referenced values were not provided.

Constructors

MustacheParserException ParseError

Template parser has failed. This contains the parse error.

MustacheRenderException PName Key

Deprecated: Not thrown anymore, will be removed in the next major version of microstache

A referenced value was not provided. The exception provides info about partial in which the issue happened PName and name of the missing key Key.

data MustacheWarning Source #

Since: 1.0.1

Constructors

MustacheVariableNotFound Key

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

MustacheDirectlyRenderedValue Key

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

Compiling

compileMustacheDir Source #

Arguments

:: PName

Which template to select after compiling

-> FilePath

Directory with templates

-> IO 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.

compileMustacheFile Source #

Arguments

:: FilePath

Location of the file

-> IO Template 

Compile single Mustache template and select it.

The action can throw the same exceptions as readFile.

compileMustacheText Source #

Arguments

:: PName

How to name the template?

-> Text

The template to compile

-> Either ParseError Template

The result

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

Rendering

renderMustache :: Template -> Value -> Text Source #

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

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

Like renderMustache but also return a list of warnings.

Since: 1.0.1