microstache-1: Mustache templates for Haskell

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

Contents

- Types
- Compiling
- Rendering

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:

- 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/

Synopsis

- data Template = Template {
  - templateActual :: PName
  - templateCache :: Map PName [Node]
  }
- data Node
  - = TextBlock Text
  - | EscapedVar Key
  - | UnescapedVar Key
  - | Section Key [Node]
  - | InvertedSection Key [Node]
  - | Partial PName (Maybe Word)
- newtype Key = Key {
  - unKey :: [Text]
  }
- newtype PName = PName {
  - unPName :: Text
  }
- data MustacheException
  - = MustacheParserException ParseError
  - | MustacheRenderException PName Key
- compileMustacheDir :: PName -> FilePath -> IO Template
- compileMustacheFile :: FilePath -> IO Template
- compileMustacheText :: PName -> Text -> Either ParseError Template
- renderMustache :: Template -> Value -> Text

# Types

data Template #

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 `Template`s (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 # |
Methods (==) :: Template -> Template -> Bool # (/=) :: Template -> Template -> Bool #
Data Template # |
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 # |
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 # |
Methods showsPrec :: Int -> Template -> ShowS # show :: Template -> String # showList :: [Template] -> ShowS #
Generic Template # |
Associated Types type Rep Template :: * -> * # Methods from :: Template -> Rep Template x # to :: Rep Template x -> Template #
Semigroup Template # |
Methods (<>) :: Template -> Template -> Template # sconcat :: NonEmpty Template -> Template # stimes :: Integral b => b -> Template -> Template #
type Rep Template # |
type Rep Template = D1 (MetaData "Template" "Text.Microstache.Type" "microstache-1-CC3vTsMGspBE6G4D112hRE" 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 #

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 # |
Methods (==) :: Node -> Node -> Bool # (/=) :: Node -> Node -> Bool #
Data Node # |
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 # |
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 # |
Methods showsPrec :: Int -> Node -> ShowS # show :: Node -> String # showList :: [Node] -> ShowS #
Generic Node # |
Associated Types type Rep Node :: * -> * # Methods from :: Node -> Rep Node x # to :: Rep Node x -> Node #
type Rep Node # |
type Rep Node = D1 (MetaData "Node" "Text.Microstache.Type" "microstache-1-CC3vTsMGspBE6G4D112hRE" False) ((:+:) ((:+:) (C1 (MetaCons "TextBlock" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text))) ((:+:) (C1 (MetaCons "EscapedVar" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key))) (C1 (MetaCons "UnescapedVar" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key))))) ((:+:) (C1 (MetaCons "Section" PrefixI False) ((:*:) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key)) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Node])))) ((:+:) (C1 (MetaCons "InvertedSection" PrefixI False) ((:*:) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key)) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Node])))) (C1 (MetaCons "Partial" PrefixI False) ((:*:) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PName)) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Word))))))))

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 unKey :: [Text]

Instances

Eq Key # |
Methods (==) :: Key -> Key -> Bool # (/=) :: Key -> Key -> Bool #
Data Key # |
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 # |
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 # |
Methods showsPrec :: Int -> Key -> ShowS # show :: Key -> String # showList :: [Key] -> ShowS #
Generic Key # |
Associated Types type Rep Key :: * -> * # Methods from :: Key -> Rep Key x # to :: Rep Key x -> Key #
Semigroup Key # |
Methods (<>) :: Key -> Key -> Key # sconcat :: NonEmpty Key -> Key # stimes :: Integral b => b -> Key -> Key #
Monoid Key # |
Methods mempty :: Key # mappend :: Key -> Key -> Key # mconcat :: [Key] -> Key #
NFData Key # |
Methods rnf :: Key -> () #
type Rep Key # |
type Rep Key = D1 (MetaData "Key" "Text.Microstache.Type" "microstache-1-CC3vTsMGspBE6G4D112hRE" True) (C1 (MetaCons "Key" PrefixI True) (S1 (MetaSel (Just Symbol "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 unPName :: Text

Instances

Eq PName # |
Methods (==) :: PName -> PName -> Bool # (/=) :: PName -> PName -> Bool #
Data PName # |
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 # |
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 # |
Methods showsPrec :: Int -> PName -> ShowS # show :: PName -> String # showList :: [PName] -> ShowS #
IsString PName # |
Methods fromString :: String -> PName #
Generic PName # |
Associated Types type Rep PName :: * -> * # Methods from :: PName -> Rep PName x # to :: Rep PName x -> PName #
NFData PName # |
Methods rnf :: PName -> () #
type Rep PName # |
type Rep PName = D1 (MetaData "PName" "Text.Microstache.Type" "microstache-1-CC3vTsMGspBE6G4D112hRE" True) (C1 (MetaCons "PName" PrefixI True) (S1 (MetaSel (Just Symbol "unPName") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text)))

data MustacheException #

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. Before version 0.2.0 it was called `MustacheException`.
MustacheRenderException PName Key | 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 # |
Methods (==) :: MustacheException -> MustacheException -> Bool # (/=) :: MustacheException -> MustacheException -> Bool #
Show MustacheException # |
Methods showsPrec :: Int -> MustacheException -> ShowS # show :: MustacheException -> String # showList :: [MustacheException] -> ShowS #
Generic MustacheException # |
Associated Types type Rep MustacheException :: * -> * # Methods from :: MustacheException -> Rep MustacheException x # to :: Rep MustacheException x -> MustacheException #
Exception MustacheException # |
Methods toException :: MustacheException -> SomeException # fromException :: SomeException -> Maybe MustacheException # displayException :: MustacheException -> String #
type Rep MustacheException # |
type Rep MustacheException = D1 (MetaData "MustacheException" "Text.Microstache.Type" "microstache-1-CC3vTsMGspBE6G4D112hRE" False) ((:+:) (C1 (MetaCons "MustacheParserException" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ParseError))) (C1 (MetaCons "MustacheRenderException" PrefixI False) ((:*:) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PName)) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Key)))))

# Compiling

compileMustacheDir #

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 #

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 #

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 #

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.