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
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
- displayMustacheException :: MustacheException -> String
- data MustacheWarning
- displayMustacheWarning :: MustacheWarning -> String
- compileMustacheDir :: PName -> FilePath -> IO Template
- compileMustacheFile :: FilePath -> IO Template
- compileMustacheText :: PName -> Text -> Either ParseError Template
- renderMustache :: Template -> Value -> Text
- renderMustacheW :: Template -> Value -> ([MustacheWarning], Text)
Types
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
|
Instances
Eq Template Source # | |
Data Template Source # | |
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 # | |
Defined in Text.Microstache.Type | |
Show Template Source # | |
Generic Template Source # | |
Semigroup Template Source # | |
type Rep Template Source # | |
Defined in Text.Microstache.Type type Rep Template = D1 (MetaData "Template" "Text.Microstache.Type" "microstache-1.0.1.1-97D9z1aRdY8BDZAy1ZVJ9v" 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])))) |
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 ( |
Instances
Eq Node Source # | |
Data Node Source # | |
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 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 # | |
Show Node Source # | |
Generic Node Source # | |
type Rep Node Source # | |
Defined in Text.Microstache.Type type Rep Node = D1 (MetaData "Node" "Text.Microstache.Type" "microstache-1.0.1.1-97D9z1aRdY8BDZAy1ZVJ9v" 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)))))) |
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.
Instances
Eq Key Source # | |
Data Key Source # | |
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 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 # | |
Show Key Source # | |
Generic Key Source # | |
Semigroup Key Source # | |
Monoid Key Source # | |
NFData Key Source # | |
Defined in Text.Microstache.Type | |
type Rep Key Source # | |
Defined in Text.Microstache.Type type Rep Key = D1 (MetaData "Key" "Text.Microstache.Type" "microstache-1.0.1.1-97D9z1aRdY8BDZAy1ZVJ9v" True) (C1 (MetaCons "Key" PrefixI True) (S1 (MetaSel (Just "unKey") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Text]))) |
Identifier for partials. Note that with the OverloadedStrings
extension you can use just string literals to create values of this type.
Instances
Eq PName Source # | |
Data PName Source # | |
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 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 # | |
Show PName Source # | |
IsString PName Source # | |
Defined in Text.Microstache.Type Methods fromString :: String -> PName | |
Generic PName Source # | |
NFData PName Source # | |
Defined in Text.Microstache.Type | |
type Rep PName Source # | |
Defined in Text.Microstache.Type type Rep PName = D1 (MetaData "PName" "Text.Microstache.Type" "microstache-1.0.1.1-97D9z1aRdY8BDZAy1ZVJ9v" 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 |
Instances
Eq MustacheException Source # | |
Defined in Text.Microstache.Type Methods (==) :: MustacheException -> MustacheException -> Bool (/=) :: MustacheException -> MustacheException -> Bool | |
Show MustacheException Source # | |
Defined in Text.Microstache.Type Methods showsPrec :: Int -> MustacheException -> ShowS show :: MustacheException -> String showList :: [MustacheException] -> ShowS | |
Generic MustacheException Source # | |
Defined in Text.Microstache.Type Associated Types type Rep MustacheException :: Type -> Type Methods from :: MustacheException -> Rep MustacheException x to :: Rep MustacheException x -> MustacheException | |
Exception MustacheException Source # | |
Defined in Text.Microstache.Type Methods toException :: MustacheException -> SomeException fromException :: SomeException -> Maybe MustacheException displayException :: MustacheException -> String | |
type Rep MustacheException Source # | |
Defined in Text.Microstache.Type type Rep MustacheException = D1 (MetaData "MustacheException" "Text.Microstache.Type" "microstache-1.0.1.1-97D9z1aRdY8BDZAy1ZVJ9v" 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))) |
displayMustacheException :: MustacheException -> String Source #
Since: 1.0.1
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 # | |
Defined in Text.Microstache.Type Methods (==) :: MustacheWarning -> MustacheWarning -> Bool (/=) :: MustacheWarning -> MustacheWarning -> Bool | |
Show MustacheWarning Source # | |
Defined in Text.Microstache.Type Methods showsPrec :: Int -> MustacheWarning -> ShowS show :: MustacheWarning -> String showList :: [MustacheWarning] -> ShowS | |
Generic MustacheWarning Source # | |
Defined in Text.Microstache.Type Associated Types type Rep MustacheWarning :: Type -> Type Methods from :: MustacheWarning -> Rep MustacheWarning x to :: Rep MustacheWarning x -> MustacheWarning | |
Exception MustacheWarning Source # | |
Defined in Text.Microstache.Type Methods toException :: MustacheWarning -> SomeException fromException :: SomeException -> Maybe MustacheWarning displayException :: MustacheWarning -> String | |
type Rep MustacheWarning Source # | |
Defined in Text.Microstache.Type type Rep MustacheWarning = D1 (MetaData "MustacheWarning" "Text.Microstache.Type" "microstache-1.0.1.1-97D9z1aRdY8BDZAy1ZVJ9v" 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))) |
displayMustacheWarning :: MustacheWarning -> String Source #
Since: 1.0.1
Compiling
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
.
Arguments
:: FilePath | Location of the file |
-> IO Template |
Compile single Mustache template and select it.
The action can throw the same exceptions as readFile
.
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