Text.DocTemplates

This is the text templating system used by pandoc. Its basic function is to fill holes in a template in a Context that provides values for variables. Control structures are provided to test that a variable has a non-blank value and to iterate over the items of a list. Partials—that is, subtemplates defined in different files—are also supported.

Templates may be rendered to lazy or strict Text, String, or a doclayout Doc. (Using a Doc allows rendered documents to wrap flexibly on breaking spaces.) A Context can be constructed manually or an aeson Value may be used.

Unlike the various HTML-centered template engines, doctemplates is output-format agnostic, so no automatic escaping is done on interpolated values. Values are assumed to be escaped properly in the Context.

Example of use

import Data.Text (Text)
import qualified Data.Text.IO as T
import Data.Aeson
import Text.DocTemplates

data Employee = Employee { firstName :: String
                         , lastName  :: String
                         , salary    :: Maybe Int }
instance ToJSON Employee where
  toJSON e = object [ "name" .= object [ "first" .= firstName e
                                       , "last"  .= lastName e ]
                    , "salary" .= salary e ]

template :: Text
template = "$for(employee)$Hi, $employee.name.first$. $if(employee.salary)$You make $employee.salary$.$else$No salary data.$endif$$sep$\n$endfor$"

main :: IO ()
main = do
  res <- compileTemplate "mytemplate.txt" template
  case res of
         Left e    -> error e
         Right t   -> T.putStrLn $ renderTemplate t $ object
                        ["employee" .=
                          [ Employee "John" "Doe" Nothing
                          , Employee "Omar" "Smith" (Just 30000)
                          , Employee "Sara" "Chen" (Just 60000) ]
                        ]

Delimiters

To mark variables and control structures in the template, either $…$ or ${…} may be used as delimiters. The styles may also be mixed in the same template, but the opening and closing delimiter must match in each case. The opening delimiter may be followed by one or more spaces or tabs, which will be ignored. The closing delimiter may be followed by one or more spaces or tabs, which will be ignored.

To include a literal $ in the document, use $$.

Comments

Anything between the sequence $-- and the end of the line will be treated as a comment and omitted from the output.

Interpolated variables

A slot for an interpolated variable is a variable name surrounded by matched delimiters. Variable names must begin with a letter and can contain letters, numbers, _, -, and .. The keywords it, if, else, endif, for, sep, and endfor may not be used as variable names. Examples:

$foo$
$foo.bar.baz$
$foo_bar.baz-bim$
$ foo $
${foo}
${foo.bar.baz}
${foo_bar.baz-bim}
${ foo }

The values of variables are determined by the Context that is passed as a parameter to renderTemplate. So, for example, title will return the value of the title field, and employee.salary will return the value of the salary field of the object that is the value of the employee field.

• If the value of the variable is simple value, it will be rendered verbatim. (Note that no escaping is done; the assumption is that the calling program will escape the strings appropriately for the output format.)
• If the value is a list, the values will be concatenated.
• If the value is a map, the string true will be rendered.
• Every other value will be rendered as the empty string.

When a Context is derived from an aeson (JSON) Value, the following conversions are done:

• If the value is a number, it will be rendered as an integer if possible, otherwise as a floating-point number.
• If the value is a JSON boolean, it will be rendered as true if true, and as the empty string if false.

The value of a variable that occurs by itself on a line will be indented to the same level as the opening delimiter of the variable.

Conditionals

A conditional begins with if(variable) (enclosed in matched delimiters) and ends with endif (enclosed in matched delimiters). It may optionally contain an else (enclosed in matched delimiters). The if section is used if variable has a non-empty value, otherwise the else section is used (if present). (Note that even the string false counts as a true value.) Examples:

$if(foo)$bar$endif$

$if(foo)$
  $foo$
$endif$

$if(foo)$
part one
$else$
part two
$endif$

${if(foo)}bar${endif}

${if(foo)}
  ${foo}
${endif}

${if(foo)}
${ foo.bar }
${else}
no foo!
${endif}

The keyword elseif may be used to simplify complex nested conditionals. Thus

$if(foo)$
XXX
$elseif(bar)$
YYY
$else$
ZZZ
$endif$

is equivalent to

$if(foo)$
XXX
$else$
$if(bar)$
YYY
$else$
ZZZ
$endif$
$endif$

For loops

A for loop begins with for(variable) (enclosed in matched delimiters) and ends with endfor (enclosed in matched delimiters. If variable is an array, the material inside the loop will be evaluated repeatedly, with variable being set to each value of the array in turn. If the value of the associated variable is not an array, a single iteration will be performed on its value.

Examples:

$for(foo)$$foo$$sep$, $endfor$

$for(foo)$
  - $foo.last$, $foo.first$
$endfor$

${ for(foo.bar) }
  - ${ foo.bar.last }, ${ foo.bar.first }
${ endfor }

You may optionally specify a separator between consecutive values using sep (enclosed in matched delimiters). The material between sep and the endfor is the separator.

${ for(foo) }${ foo }${ sep }, ${ endfor }

Instead of using variable inside the loop, the special anaphoric keyword it may be used.

${ for(foo.bar) }
  - ${ it.last }, ${ it.first }
${ endfor }

Partials

Partials (subtemplates stored in different files) may be included using the syntax

${ boilerplate() }

The partials are obtained using getPartial from the TemplateMonad class. This may be implemented differently in different monads. The path passed to getPartial is computed on the basis of the original template path (a parameter to compileTemplate) and the partial’s name. The partial’s name is substituted for the base name of the original template path (leaving the original template’s extension), unless the partial has an explicit extension, in which case this is kept. So, with the TemplateMonad instance for IO, partials will be sought in the directory containing the main template, and will be assumed to have the extension of the main template.

Partials may optionally be applied to variables using a colon:

${ date:fancy() }

${ articles:bibentry() }

If articles is an array, this will iterate over its values, applying the partial bibentry() to each one. So the second example above is equivalent to

${ for(articles) }
${ it:bibentry() }
${ endfor }

Note that the anaphoric keyword it must be used when iterating over partials. In the above examples, the bibentry partial should contain it.title (and so on) instead of articles.title.

Final newlines are omitted from included partials.

Partials may include other partials. If you exceed a nesting level of 50, though, in resolving partials, the literal (loop) will be returned, to avoid infinite loops.

A separator between values of an array may be specified in square brackets, immediately after the variable name or partial:

${months[, ]}$

${articles:bibentry()[; ]$

The separator in this case is literal and (unlike with sep in an explicit for loop) cannot contain interpolated variables or other template directives.

Breakable spaces

When rendering to a Doc, a distinction can be made between breakable and unbreakable spaces. Normally, spaces in the template itself (as opposed to values of the interpolated variables) are not breakable, but they can be made breakable in part of the template by using the +reflow keyword (ended with -reflow).

${ +reflow }This long line may break if the document is rendered
with a short line length.${ -reflow }

The + keyword has no effect when rendering to Text or String.

Nesting

As noted above, the value of a variable that occurs by itself on a line will be indented to the same level as the opening delimiter of the variable.

In addition, any part of a template can be marked explicitly for indented rendering, using the +nest keyword (o start nesting at the column where it appears) and -nest to stop nesting.

Example:

$for(article)$
- $+nest$$article.author$, "$article.title$," in $article.book$
  ($article.year$).$-nest$
$endfor$

Documentation

renderTemplate :: (TemplateTarget a, ToContext a b) => Template -> b -> a

Render a compiled template in a "context" which provides values for the template's variables.

compileTemplate :: TemplateMonad m => FilePath -> Text -> m (Either String Template)

Compile a template. The FilePath parameter is used to determine a default path and extension for partials and may be left empty if partials are not used.

compileTemplateFile :: FilePath -> IO (Either String Template)

Compile a template from a file. IO errors will be raised as exceptions; template parsing errors result in Left return values.

applyTemplate :: (TemplateMonad m, TemplateTarget a, ToContext a b) => FilePath -> Text -> b -> m (Either String a)

Compile a template and apply it to a context. This is just a convenience function composing compileTemplate and renderTemplate. If a template will be rendered more than once in the same process, compile it separately for better performance.

class Monad m => TemplateMonad m where

A TemplateMonad defines a function to retrieve a partial (from the file system, from a database, or using a default value).

Methods

getPartial :: FilePath -> m Text

Instances

TemplateMonad IO

Defined in Text.DocTemplates.Internal

Methods

getPartial :: FilePath -> IO Text

TemplateMonad Identity

Defined in Text.DocTemplates.Internal

Methods

getPartial :: FilePath -> Identity Text

class Monoid a => TemplateTarget a where

A type to which templates can be rendered.

Methods

fromText :: Text -> a

toText :: a -> Text

removeFinalNewline :: a -> a

isEmpty :: a -> Bool

indent :: Int -> a -> a

breakingSpace :: a

Instances

TemplateTarget Text

Defined in Text.DocTemplates.Internal

Methods

fromText :: Text -> Text

toText :: Text -> Text

removeFinalNewline :: Text -> Text

isEmpty :: Text -> Bool

indent :: Int -> Text -> Text

breakingSpace :: Text

TemplateTarget Text

Defined in Text.DocTemplates.Internal

Methods

fromText :: Text0 -> Text

toText :: Text -> Text0

removeFinalNewline :: Text -> Text

isEmpty :: Text -> Bool

indent :: Int -> Text -> Text

breakingSpace :: Text

TemplateTarget String

Defined in Text.DocTemplates.Internal

Methods

fromText :: Text -> String

toText :: String -> Text

removeFinalNewline :: String -> String

isEmpty :: String -> Bool

indent :: Int -> String -> String

breakingSpace :: String

(HasChars a, IsString a, Eq a) => TemplateTarget (Doc a)

Defined in Text.DocTemplates.Internal

Methods

fromText :: Text -> Doc a

toText :: Doc a -> Text

removeFinalNewline :: Doc a -> Doc a

isEmpty :: Doc a -> Bool

indent :: Int -> Doc a -> Doc a

breakingSpace :: Doc a

newtype Context a

A Context defines values for template's variables.

Constructors

Context

Fields

• unContext :: Map Text (Val a)

Instances

Functor Context

Defined in Text.DocTemplates.Internal

Methods

fmap :: (a -> b) -> Context a -> Context b

(<$) :: a -> Context b -> Context a

Foldable Context

Defined in Text.DocTemplates.Internal

Methods

fold :: Monoid m => Context m -> m

foldMap :: Monoid m => (a -> m) -> Context a -> m

foldr :: (a -> b -> b) -> b -> Context a -> b

foldr' :: (a -> b -> b) -> b -> Context a -> b

foldl :: (b -> a -> b) -> b -> Context a -> b

foldl' :: (b -> a -> b) -> b -> Context a -> b

foldr1 :: (a -> a -> a) -> Context a -> a

foldl1 :: (a -> a -> a) -> Context a -> a

toList :: Context a -> [a]

null :: Context a -> Bool

length :: Context a -> Int

elem :: Eq a => a -> Context a -> Bool

maximum :: Ord a => Context a -> a

minimum :: Ord a => Context a -> a

sum :: Num a => Context a -> a

product :: Num a => Context a -> a

Traversable Context

Defined in Text.DocTemplates.Internal

Methods

traverse :: Applicative f => (a -> f b) -> Context a -> f (Context b)

sequenceA :: Applicative f => Context (f a) -> f (Context a)

mapM :: Monad m => (a -> m b) -> Context a -> m (Context b)

sequence :: Monad m => Context (m a) -> m (Context a)

TemplateTarget a => ToContext a (Context a)

Defined in Text.DocTemplates.Internal

Methods

toContext :: Context a -> Context a

toVal :: Context a -> Val a

Show a => Show (Context a)

Defined in Text.DocTemplates.Internal

Methods

showsPrec :: Int -> Context a -> ShowS

show :: Context a -> String

showList :: [Context a] -> ShowS

Semigroup (Context a)

Defined in Text.DocTemplates.Internal

Methods

(<>) :: Context a -> Context a -> Context a

sconcat :: NonEmpty (Context a) -> Context a

stimes :: Integral b => b -> Context a -> Context a

Monoid (Context a)

Defined in Text.DocTemplates.Internal

Methods

mempty :: Context a

mappend :: Context a -> Context a -> Context a

mconcat :: [Context a] -> Context a

TemplateTarget a => ToJSON (Context a)

Defined in Text.DocTemplates.Internal

Methods

toJSON :: Context a -> Value

toEncoding :: Context a -> Encoding

toJSONList :: [Context a] -> Value

toEncodingList :: [Context a] -> Encoding

TemplateTarget a => FromJSON (Context a)

Defined in Text.DocTemplates.Internal

Methods

parseJSON :: Value -> Parser (Context a)

parseJSONList :: Value -> Parser [Context a]

data Val a

A variable value.

Constructors

SimpleVal a

ListVal [Val a]

MapVal (Context a)

NullVal

Instances

Functor Val

Defined in Text.DocTemplates.Internal

Methods

fmap :: (a -> b) -> Val a -> Val b

(<$) :: a -> Val b -> Val a

Foldable Val

Defined in Text.DocTemplates.Internal

Methods

fold :: Monoid m => Val m -> m

foldMap :: Monoid m => (a -> m) -> Val a -> m

foldr :: (a -> b -> b) -> b -> Val a -> b

foldr' :: (a -> b -> b) -> b -> Val a -> b

foldl :: (b -> a -> b) -> b -> Val a -> b

foldl' :: (b -> a -> b) -> b -> Val a -> b

foldr1 :: (a -> a -> a) -> Val a -> a

foldl1 :: (a -> a -> a) -> Val a -> a

toList :: Val a -> [a]

null :: Val a -> Bool

length :: Val a -> Int

elem :: Eq a => a -> Val a -> Bool

maximum :: Ord a => Val a -> a

minimum :: Ord a => Val a -> a

sum :: Num a => Val a -> a

product :: Num a => Val a -> a

Traversable Val

Defined in Text.DocTemplates.Internal

Methods

traverse :: Applicative f => (a -> f b) -> Val a -> f (Val b)

sequenceA :: Applicative f => Val (f a) -> f (Val a)

mapM :: Monad m => (a -> m b) -> Val a -> m (Val b)

sequence :: Monad m => Val (m a) -> m (Val a)

TemplateTarget a => FromContext a (Val a)

Defined in Text.DocTemplates.Internal

Methods

fromVal :: Val a -> Maybe (Val a)

lookupContext :: Text -> Context a -> Maybe (Val a)

TemplateTarget a => ToContext a (Val a)

Defined in Text.DocTemplates.Internal

Methods

toContext :: Val a -> Context a

toVal :: Val a -> Val a

Show a => Show (Val a)

Defined in Text.DocTemplates.Internal

Methods

showsPrec :: Int -> Val a -> ShowS

show :: Val a -> String

showList :: [Val a] -> ShowS

TemplateTarget a => ToJSON (Val a)

Defined in Text.DocTemplates.Internal

Methods

toJSON :: Val a -> Value

toEncoding :: Val a -> Encoding

toJSONList :: [Val a] -> Value

toEncodingList :: [Val a] -> Encoding

TemplateTarget a => FromJSON (Val a)

Defined in Text.DocTemplates.Internal

Methods

parseJSON :: Value -> Parser (Val a)

parseJSONList :: Value -> Parser [Val a]

class ToContext a b where

The ToContext class provides automatic conversion to a Context or Val.

Minimal complete definition

toVal

Methods

toContext :: b -> Context a

toVal :: b -> Val a

Instances

TemplateTarget a => ToContext a Bool

Defined in Text.DocTemplates.Internal

Methods

toContext :: Bool -> Context a

toVal :: Bool -> Val a

TemplateTarget a => ToContext a Value

Defined in Text.DocTemplates.Internal

Methods

toContext :: Value -> Context a

toVal :: Value -> Val a

TemplateTarget a => ToContext a a

Defined in Text.DocTemplates.Internal

Methods

toContext :: a -> Context a

toVal :: a -> Val a

ToContext String String

Defined in Text.DocTemplates.Internal

Methods

toContext :: String -> Context String

toVal :: String -> Val String

ToContext a b => ToContext a [b]

Defined in Text.DocTemplates.Internal

Methods

toContext :: [b] -> Context a

toVal :: [b] -> Val a

TemplateTarget a => ToContext a (Val a)

Defined in Text.DocTemplates.Internal

Methods

toContext :: Val a -> Context a

toVal :: Val a -> Val a

TemplateTarget a => ToContext a (Context a)

Defined in Text.DocTemplates.Internal

Methods

toContext :: Context a -> Context a

toVal :: Context a -> Val a

(TemplateTarget a, HasChars a) => ToContext (Doc a) a

Defined in Text.DocTemplates.Internal

Methods

toContext :: a -> Context (Doc a)

toVal :: a -> Val (Doc a)

class FromContext a b where

The FromContext class provides functions for extracting values from Val and Context.

Minimal complete definition

fromVal

Methods

fromVal :: Val a -> Maybe b

lookupContext :: Text -> Context a -> Maybe b

Instances

TemplateTarget a => FromContext a a

Defined in Text.DocTemplates.Internal

Methods

fromVal :: Val a -> Maybe a

lookupContext :: Text -> Context a -> Maybe a

FromContext String String

Defined in Text.DocTemplates.Internal

Methods

fromVal :: Val String -> Maybe String

lookupContext :: Text -> Context String -> Maybe String

FromContext a b => FromContext a [b]

Defined in Text.DocTemplates.Internal

Methods

fromVal :: Val a -> Maybe [b]

lookupContext :: Text -> Context a -> Maybe [b]

TemplateTarget a => FromContext a (Val a)

Defined in Text.DocTemplates.Internal

Methods

fromVal :: Val a -> Maybe (Val a)

lookupContext :: Text -> Context a -> Maybe (Val a)

data Template

A template.

Instances

Eq Template

Defined in Text.DocTemplates.Internal

Methods

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

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

Data Template

Defined in Text.DocTemplates.Internal

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

Defined in Text.DocTemplates.Internal

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

Read Template

Defined in Text.DocTemplates.Internal

Methods

readsPrec :: Int -> ReadS Template

readList :: ReadS [Template]

readPrec :: ReadPrec Template

readListPrec :: ReadPrec [Template]

Show Template

Defined in Text.DocTemplates.Internal

Methods

showsPrec :: Int -> Template -> ShowS

show :: Template -> String

showList :: [Template] -> ShowS

Generic Template

Defined in Text.DocTemplates.Internal

Associated Types

type Rep Template :: Type -> Type

Methods

from :: Template -> Rep Template x

to :: Rep Template x -> Template

Semigroup Template

Defined in Text.DocTemplates.Internal

Methods

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

sconcat :: NonEmpty Template -> Template

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

Monoid Template

Defined in Text.DocTemplates.Internal

Methods

mempty :: Template

mappend :: Template -> Template -> Template

mconcat :: [Template] -> Template

type Rep Template

Defined in Text.DocTemplates.Internal

type Rep Template = D1 (MetaData "Template" "Text.DocTemplates.Internal" "doctemplates-0.6-KXFySz9w7Yu9pgADJ55XK9" False) (((C1 (MetaCons "Interpolate" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Variable)) :+: C1 (MetaCons "Conditional" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Variable) :*: (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Template) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Template)))) :+: (C1 (MetaCons "Iterate" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Variable) :*: (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Template) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Template))) :+: C1 (MetaCons "Nested" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Int) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Template)))) :+: ((C1 (MetaCons "Partial" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Template)) :+: C1 (MetaCons "Literal" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text))) :+: (C1 (MetaCons "Concat" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Template) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Template)) :+: (C1 (MetaCons "BreakingSpace" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Empty" PrefixI False) (U1 :: Type -> Type)))))