Text.Mustache

How to use this library

This module exposes some of the most convenient functions for dealing with mustache templates.

Compiling with automatic partial discovery

The easiest way of compiling a file and its potential includes (called partials) is by using the automaticCompile function.

main :: IO ()
main = do
  let searchSpace = [".", "./templates"]
      templateName = "main.mustache"

  compiled <- automaticCompile searchSpace templateName
  case compiled of
    Left err -> print err
    Right template -> return () -- this is where you can start using it

The searchSpace encompasses all directories in which the compiler should search for the template source files. The search itself is conducted in order, from left to right.

Should your search space be only the current working directory, you can use localAutomaticCompile.

The templateName is the relative path of the template to any directory of the search space.

automaticCompile not only finds and compiles the template for you, it also recursively finds any partials included in the template as well, compiles them and stores them in the partials hash attached to the resulting template.

The compiler will throw errors if either the template is malformed or the source file for a partial or the template itself could not be found in any of the directories in searchSpace.

Substituting

In order to substitute data into the template it must be an instance of the ToMustache typeclass or be of type Value.

This libray tries to imitate the API of aeson by allowing you to define conversions of your own custom data types into Value, the type used internally by the substitutor via typeclass and a selection of operators and convenience functions.

Example

  data Person = { age :: Int, name :: String }

  instance ToMustache Person where
    toMustache person = object
      [ "age" ~> age person
      , "name" ~> name person
      ]

The values to the left of the ~> operator has to be of type Text, hence the OverloadedStrings can becomes very handy here.

Values to the right of the ~> operator must be an instance of the ToMustache typeclass. Alternatively, if your value to the right of the ~> operator is not an instance of ToMustache but an instance of ToJSON you can use the ~= operator, which accepts ToJSON values.

  data Person = { age :: Int, name :: String, address :: Address }

  data Address = ...

  instance ToJSON Address where
    ...

  instance ToMustache Person where
    toMustache person = object
      [ "age" ~> age person
      , "name" ~> name person
      , "address" ~= address person
      ]

All operators are also provided in a unicode form, for those that, like me, enjoy unicode operators.

Manual compiling

You can compile templates manually without requiring the IO monad at all, using the compileTemplate function. This is the same function internally used by automaticCompile and does not check if required partial are present.

More functions for manual compilation can be found in the Compile module. Including helpers for finding lists of partials in templates.

Additionally the compileTemplateWithCache function is exposed here which you may use to automatically compile a template but avoid some of the compilation overhead by providing already compiled partials as well.

Fundamentals

This library builds on three important data structures/types.

Value

A data structure almost identical to Data.Aeson.Value extended with lambda functions which represents the data the template is being filled with.

ToMustache

A typeclass for converting arbitrary types to Value, similar to Data.Aeson.ToJSON but with support for lambdas.

Template

Contains the STree, the syntax tree, which is basically a list of text blocks and mustache tags. The name of the template and its partials cache.

Compiling

During the compilation step the template file is located, read, then parsed in a single pass (compileTemplate), resulting in a Template with an empty partials section.

Subsequenty the STree of the template is scanned for included partials, any present TemplateCache is queried for the partial (compileTemplateWithCache), if not found it will be searched for in the searchSpace, compiled and inserted into the template's own cache as well as the global cache for the compilation process.

Internally no partial is compiled twice, as long as the names stay consistent.

Once compiled templates may be used multiple times for substitution or as partial for other templates.

Partials are not being embedded into the templates during compilation, but during substitution, hence the partials cache is vital to the template even after compilation has been completed. Any non existent partial in the cache will rsubstitute to an empty string.

Substituting

Compiling

Automatic

automaticCompile :: [FilePath] -> FilePath -> IO (Either ParseError Template)

Compiles a mustache template provided by name including the mentioned partials.

The same can be done manually using getFile, mustacheParser and getPartials.

This function also ensures each partial is only compiled once even though it may be included by other partials including itself.

A reference to the included template will be found in each including templates partials section.

localAutomaticCompile :: FilePath -> IO (Either ParseError Template)

Compile the template with the search space set to only the current directory

Manually

compileTemplateWithCache :: [FilePath] -> TemplateCache -> FilePath -> IO (Either ParseError Template)

Compile a mustache template providing a list of precompiled templates that do not have to be recompiled.

compileTemplate :: String -> Text -> Either ParseError Template

Compiles a Template directly from Text without checking for missing partials. the result will be a Template with an empty partials cache.

data Template

A compiled Template with metadata.

Constructors

Template

Fields

• name :: String
• ast :: STree
• partials :: TemplateCache

Instances

Show Template

Defined in Text.Mustache.Internal.Types

Methods

showsPrec :: Int -> Template -> ShowS

show :: Template -> String

showList :: [Template] -> ShowS

Lift Template

Defined in Text.Mustache.Internal.Types

Methods

lift :: Template -> Q Exp

liftTyped :: Template -> Q (TExp Template)

Lift TemplateCache

Defined in Text.Mustache.Internal.Types

Methods

lift :: TemplateCache -> Q Exp

liftTyped :: TemplateCache -> Q (TExp TemplateCache)

MonadReader (Context Value, TemplateCache) SubM

Defined in Text.Mustache.Internal.Types

Methods

ask :: SubM (Context Value, TemplateCache)

local :: ((Context Value, TemplateCache) -> (Context Value, TemplateCache)) -> SubM a -> SubM a

reader :: ((Context Value, TemplateCache) -> a) -> SubM a

Rendering

Generic

substitute :: ToMustache k => Template -> k -> Text

Substitutes all mustache defined tokens (or tags) for values found in the provided data structure.

Equivalent to substituteValue . toMustache.

checkedSubstitute :: ToMustache k => Template -> k -> ([SubstitutionError], Text)

Substitutes all mustache defined tokens (or tags) for values found in the provided data structure and report any errors and warnings encountered during substitution.

This function always produces results, as in a fully substituted/rendered template, it never halts on errors. It simply reports them in the first part of the tuple. Sites with errors are usually substituted with empty string.

The second value in the tuple is a template rendered with errors ignored. Therefore if you must enforce that there were no errors during substitution you must check that the error list in the first tuple value is empty.

Equivalent to checkedSubstituteValue . toMustache.

Specialized

substituteValue :: Template -> Value -> Text

Substitutes all mustache defined tokens (or tags) for values found in the provided data structure.

checkedSubstituteValue :: Template -> Value -> ([SubstitutionError], Text)

Substitutes all mustache defined tokens (or tags) for values found in the provided data structure and report any errors and warnings encountered during substitution.

This function always produces results, as in a fully substituted/rendered template, it never halts on errors. It simply reports them in the first part of the tuple. Sites with errors are usually substituted with empty string.

The second value in the tuple is a template rendered with errors ignored. Therefore if you must enforce that there were no errors during substitution you must check that the error list in the first tuple value is empty.

In Lambdas

substituteNode :: Node Text -> SubM ()

Main substitution function

substituteAST :: STree -> SubM ()

Substitute an entire STree rather than just a single Node

catchSubstitute :: SubM a -> SubM (a, Text)

Catch the results of running the inner substitution.

Data Conversion

class ToMustache ω

Conversion class

Minimal complete definition

toMustache

Instances

ToMustache Bool

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Bool -> Value

listToMustache :: [Bool] -> Value

ToMustache Char

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Char -> Value

listToMustache :: [Char] -> Value

ToMustache Double

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Double -> Value

listToMustache :: [Double] -> Value

ToMustache Float

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Float -> Value

listToMustache :: [Float] -> Value

ToMustache Int

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Int -> Value

listToMustache :: [Int] -> Value

ToMustache Int8

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Int8 -> Value

listToMustache :: [Int8] -> Value

ToMustache Int16

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Int16 -> Value

listToMustache :: [Int16] -> Value

ToMustache Int32

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Int32 -> Value

listToMustache :: [Int32] -> Value

ToMustache Int64

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Int64 -> Value

listToMustache :: [Int64] -> Value

ToMustache Integer

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Integer -> Value

listToMustache :: [Integer] -> Value

ToMustache Natural

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Natural -> Value

listToMustache :: [Natural] -> Value

ToMustache Word

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Word -> Value

listToMustache :: [Word] -> Value

ToMustache Word8

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Word8 -> Value

listToMustache :: [Word8] -> Value

ToMustache Word16

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Word16 -> Value

listToMustache :: [Word16] -> Value

ToMustache Word32

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Word32 -> Value

listToMustache :: [Word32] -> Value

ToMustache Word64

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Word64 -> Value

listToMustache :: [Word64] -> Value

ToMustache ()

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: () -> Value

listToMustache :: [()] -> Value

ToMustache Scientific

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Scientific -> Value

listToMustache :: [Scientific] -> Value

ToMustache Text

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Text -> Value

listToMustache :: [Text] -> Value

ToMustache Value

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Value -> Value0

listToMustache :: [Value] -> Value0

ToMustache Text

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Text -> Value

listToMustache :: [Text] -> Value

ToMustache Value

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Value -> Value

listToMustache :: [Value] -> Value

ToMustache α => ToMustache [α]

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: [α] -> Value

listToMustache :: [[α]] -> Value

ToMustache ω => ToMustache (Maybe ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Maybe ω -> Value

listToMustache :: [Maybe ω] -> Value

ToMustache ω => ToMustache (Seq ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Seq ω -> Value

listToMustache :: [Seq ω] -> Value

ToMustache ω => ToMustache (Set ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Set ω -> Value

listToMustache :: [Set ω] -> Value

ToMustache ω => ToMustache (HashSet ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: HashSet ω -> Value

listToMustache :: [HashSet ω] -> Value

ToMustache ω => ToMustache (Vector ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Vector ω -> Value

listToMustache :: [Vector ω] -> Value

ToMustache (Context Value -> STree -> String)

Defined in Text.Mustache.Render

Methods

toMustache :: (Context Value -> STree -> String) -> Value

listToMustache :: [Context Value -> STree -> String] -> Value

ToMustache (Context Value -> STree -> Text)

Defined in Text.Mustache.Render

Methods

toMustache :: (Context Value -> STree -> Text) -> Value

listToMustache :: [Context Value -> STree -> Text] -> Value

ToMustache (Context Value -> STree -> Text)

Defined in Text.Mustache.Render

Methods

toMustache :: (Context Value -> STree -> Text) -> Value

listToMustache :: [Context Value -> STree -> Text] -> Value

ToMustache (Context Value -> STree -> STree)

Defined in Text.Mustache.Render

Methods

toMustache :: (Context Value -> STree -> STree) -> Value

listToMustache :: [Context Value -> STree -> STree] -> Value

ToMustache (STree -> SubM Text)

Defined in Text.Mustache.Render

Methods

toMustache :: (STree -> SubM Text) -> Value

listToMustache :: [STree -> SubM Text] -> Value

ToMustache (STree -> SubM STree)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: (STree -> SubM STree) -> Value

listToMustache :: [STree -> SubM STree] -> Value

(ToMustache α, ToMustache β) => ToMustache (α, β)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: (α, β) -> Value

listToMustache :: [(α, β)] -> Value

ToMustache ω => ToMustache (Map String ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Map String ω -> Value

listToMustache :: [Map String ω] -> Value

ToMustache ω => ToMustache (Map Text ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Map Text ω -> Value

listToMustache :: [Map Text ω] -> Value

ToMustache ω => ToMustache (Map Text ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: Map Text ω -> Value

listToMustache :: [Map Text ω] -> Value

ToMustache ω => ToMustache (HashMap String ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: HashMap String ω -> Value

listToMustache :: [HashMap String ω] -> Value

ToMustache ω => ToMustache (HashMap Text ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: HashMap Text ω -> Value

listToMustache :: [HashMap Text ω] -> Value

ToMustache ω => ToMustache (HashMap Text ω)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: HashMap Text ω -> Value

listToMustache :: [HashMap Text ω] -> Value

(ToMustache α, ToMustache β, ToMustache γ) => ToMustache (α, β, γ)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: (α, β, γ) -> Value

listToMustache :: [(α, β, γ)] -> Value

(ToMustache α, ToMustache β, ToMustache γ, ToMustache δ) => ToMustache (α, β, γ, δ)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: (α, β, γ, δ) -> Value

listToMustache :: [(α, β, γ, δ)] -> Value

(ToMustache α, ToMustache β, ToMustache γ, ToMustache δ, ToMustache ε) => ToMustache (α, β, γ, δ, ε)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: (α, β, γ, δ, ε) -> Value

listToMustache :: [(α, β, γ, δ, ε)] -> Value

(ToMustache α, ToMustache β, ToMustache γ, ToMustache δ, ToMustache ε, ToMustache ζ) => ToMustache (α, β, γ, δ, ε, ζ)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: (α, β, γ, δ, ε, ζ) -> Value

listToMustache :: [(α, β, γ, δ, ε, ζ)] -> Value

(ToMustache α, ToMustache β, ToMustache γ, ToMustache δ, ToMustache ε, ToMustache ζ, ToMustache η) => ToMustache (α, β, γ, δ, ε, ζ, η)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: (α, β, γ, δ, ε, ζ, η) -> Value

listToMustache :: [(α, β, γ, δ, ε, ζ, η)] -> Value

(ToMustache α, ToMustache β, ToMustache γ, ToMustache δ, ToMustache ε, ToMustache ζ, ToMustache η, ToMustache θ) => ToMustache (α, β, γ, δ, ε, ζ, η, θ)

Defined in Text.Mustache.Internal.Types

Methods

toMustache :: (α, β, γ, δ, ε, ζ, η, θ) -> Value

listToMustache :: [(α, β, γ, δ, ε, ζ, η, θ)] -> Value

toMustache :: ToMustache ω => ω -> Value

integralToMustache :: Integral ω => ω -> Value

object :: [Pair] -> Value

Convenience function for creating Object values.

This function is supposed to be used in conjuction with the ~> and ~= operators.

Examples

  data Address = Address { ... }

  instance Address ToJSON where
    ...

  data Person = Person { name :: String, address :: Address }

  instance ToMustache Person where
    toMustache (Person { name, address }) = object
      [ "name" ~> name
      , "address" ~= address
      ]

Here we can see that we can use the ~> operator for values that have themselves a ToMustache instance, or alternatively if they lack such an instance but provide an instance for the ToJSON typeclass we can use the ~= operator.

(~>) :: ToMustache ω => Text -> ω -> Pair infixr 8

Map keys to values that provide a ToMustache instance

Recommended in conjunction with the OverloadedStrings extension.

(~=) :: ToJSON ι => Text -> ι -> Pair infixr 8

Map keys to values that provide a ToJSON instance

Recommended in conjunction with the OverloadedStrings extension.

Utilities for lambdas

overText :: (Text -> Text) -> Value

Creates a Lambda which first renders the contained section and then applies the supplied function