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 # 
Instance details

Defined in Text.Microstache.Type

Methods

(==) :: Template -> Template -> Bool

(/=) :: Template -> Template -> Bool

Data Template Source # 
Instance details

Defined in Text.Microstache.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 :: (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 # 
Instance details

Defined in Text.Microstache.Type

Methods

compare :: Template -> Template -> Ordering

(<) :: Template -> Template -> Bool

(<=) :: Template -> Template -> Bool

(>) :: Template -> Template -> Bool

(>=) :: Template -> Template -> Bool

max :: Template -> Template -> Template

min :: Template -> Template -> Template

Show Template Source # 
Instance details

Defined in Text.Microstache.Type

Methods

showsPrec :: Int -> Template -> ShowS

show :: Template -> String

showList :: [Template] -> ShowS

Generic Template Source # 
Instance details

Defined in Text.Microstache.Type

Associated Types

type Rep Template :: Type -> Type

Methods

from :: Template -> Rep Template x

to :: Rep Template x -> Template

Semigroup Template Source # 
Instance details

Defined in Text.Microstache.Type

Methods

(<>) :: Template -> Template -> Template

sconcat :: NonEmpty Template -> Template

stimes :: Integral b => b -> Template -> Template

type Rep Template Source # 
Instance details

Defined in Text.Microstache.Type

type Rep Template = D1 (MetaData "Template" "Text.Microstache.Type" "microstache-1.0.1.1-9Y49Sr3VffsBxqLMGaaR3" 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 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 # 
Instance details

Defined in Text.Microstache.Type

Methods

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

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

Data Node Source # 
Instance details

Defined in Text.Microstache.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 :: (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 # 
Instance details

Defined in Text.Microstache.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

Show Node Source # 
Instance details

Defined in Text.Microstache.Type

Methods

showsPrec :: Int -> Node -> ShowS

show :: Node -> String

showList :: [Node] -> ShowS

Generic Node Source # 
Instance details

Defined in Text.Microstache.Type

Associated Types

type Rep Node :: Type -> Type

Methods

from :: Node -> Rep Node x

to :: Rep Node x -> Node

type Rep Node Source # 
Instance details

Defined in Text.Microstache.Type

type Rep Node = D1 (MetaData "Node" "Text.Microstache.Type" "microstache-1.0.1.1-9Y49Sr3VffsBxqLMGaaR3" False) ((C1 (MetaCons "TextBlock" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text)) :+: (C1 (MetaCons "EscapedVar" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key)) :+: C1 (MetaCons "UnescapedVar" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key)))) :+: (C1 (MetaCons "Section" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Node])) :+: (C1 (MetaCons "InvertedSection" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Node])) :+: C1 (MetaCons "Partial" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PName) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Word))))))

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 # 
Instance details

Defined in Text.Microstache.Type

Methods

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

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

Data Key Source # 
Instance details

Defined in Text.Microstache.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 :: (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 # 
Instance details

Defined in Text.Microstache.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

Show Key Source # 
Instance details

Defined in Text.Microstache.Type

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

Generic Key Source # 
Instance details

Defined in Text.Microstache.Type

Associated Types

type Rep Key :: Type -> Type

Methods

from :: Key -> Rep Key x

to :: Rep Key x -> Key

Semigroup Key Source # 
Instance details

Defined in Text.Microstache.Type

Methods

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

sconcat :: NonEmpty Key -> Key

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

Monoid Key Source # 
Instance details

Defined in Text.Microstache.Type

Methods

mempty :: Key

mappend :: Key -> Key -> Key

mconcat :: [Key] -> Key

NFData Key Source # 
Instance details

Defined in Text.Microstache.Type

Methods

rnf :: Key -> ()

type Rep Key Source # 
Instance details

Defined in Text.Microstache.Type

type Rep Key = D1 (MetaData "Key" "Text.Microstache.Type" "microstache-1.0.1.1-9Y49Sr3VffsBxqLMGaaR3" True) (C1 (MetaCons "Key" PrefixI True) (S1 (MetaSel (Just "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 # 
Instance details

Defined in Text.Microstache.Type

Methods

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

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

Data PName Source # 
Instance details

Defined in Text.Microstache.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 :: (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 # 
Instance details

Defined in Text.Microstache.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

Show PName Source # 
Instance details

Defined in Text.Microstache.Type

Methods

showsPrec :: Int -> PName -> ShowS

show :: PName -> String

showList :: [PName] -> ShowS

IsString PName Source # 
Instance details

Defined in Text.Microstache.Type

Methods

fromString :: String -> PName

Generic PName Source # 
Instance details

Defined in Text.Microstache.Type

Associated Types

type Rep PName :: Type -> Type

Methods

from :: PName -> Rep PName x

to :: Rep PName x -> PName

NFData PName Source # 
Instance details

Defined in Text.Microstache.Type

Methods

rnf :: PName -> ()

type Rep PName Source # 
Instance details

Defined in Text.Microstache.Type

type Rep PName = D1 (MetaData "PName" "Text.Microstache.Type" "microstache-1.0.1.1-9Y49Sr3VffsBxqLMGaaR3" True) (C1 (MetaCons "PName" PrefixI True) (S1 (MetaSel (Just "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.

Instances
Eq MustacheException Source # 
Instance details

Defined in Text.Microstache.Type

Show MustacheException Source # 
Instance details

Defined in Text.Microstache.Type

Methods

showsPrec :: Int -> MustacheException -> ShowS

show :: MustacheException -> String

showList :: [MustacheException] -> ShowS

Generic MustacheException Source # 
Instance details

Defined in Text.Microstache.Type

Associated Types

type Rep MustacheException :: Type -> Type

Exception MustacheException Source # 
Instance details

Defined in Text.Microstache.Type

Methods

toException :: MustacheException -> SomeException

fromException :: SomeException -> Maybe MustacheException

displayException :: MustacheException -> String

type Rep MustacheException Source # 
Instance details

Defined in Text.Microstache.Type

type Rep MustacheException = D1 (MetaData "MustacheException" "Text.Microstache.Type" "microstache-1.0.1.1-9Y49Sr3VffsBxqLMGaaR3" False) (C1 (MetaCons "MustacheParserException" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ParseError)) :+: C1 (MetaCons "MustacheRenderException" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PName) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 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

Instances
Eq MustacheWarning Source # 
Instance details

Defined in Text.Microstache.Type

Show MustacheWarning Source # 
Instance details

Defined in Text.Microstache.Type

Methods

showsPrec :: Int -> MustacheWarning -> ShowS

show :: MustacheWarning -> String

showList :: [MustacheWarning] -> ShowS

Generic MustacheWarning Source # 
Instance details

Defined in Text.Microstache.Type

Associated Types

type Rep MustacheWarning :: Type -> Type

Exception MustacheWarning Source # 
Instance details

Defined in Text.Microstache.Type

Methods

toException :: MustacheWarning -> SomeException

fromException :: SomeException -> Maybe MustacheWarning

displayException :: MustacheWarning -> String

type Rep MustacheWarning Source # 
Instance details

Defined in Text.Microstache.Type

type Rep MustacheWarning = D1 (MetaData "MustacheWarning" "Text.Microstache.Type" "microstache-1.0.1.1-9Y49Sr3VffsBxqLMGaaR3" 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 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