Text.Bravo

Bravo templates can be read from strings via the mkTemplates, or from files via the mkTemplatesFromFile Template Haskell functions, so you need to enable the TemplateHaskell language extension when using Bravo in your Haskell application. Each read string or file can contain multiple templates and additional comments. A single template is delimitated by an opening splice {{ tpl name }} and a closing splice {{ endtpl }} where name is an identifier starting with a lowercase letter. Characters before and after these splices are considered to be template comments and therefore are ignored. Between these delimiters multiple inner splices are allowed, which are:

• Normal text, i.e. character sequences not including {{ or }}.
• Comment splices {{- comment text -}}. These splices are only for documentary purposes and will not occur in the produced template text.
• Expression splices {{: expression }}. Here expression can be an arbitrary Haskell expression that does not require any language extensions to be parsed. The expression itself is not evaluated at compile time but rather at runtime and the result of evaluation will be included in the produced template text. Note that the evaluated expression must be of type String, otherwise compile errors will occur in the produced declarations. Additionally, template variables of the form $name or $(name) can be used within an expression.
• Conditional splices {{ if condition_1 }} ... [ {{ elseif condition_2 }} ... ]* [ {{ else }} ... ] {{ endif }} where each ... stands for an arbitrary number of inner splices. Multiple elseif splices and/or a single else splice are optional. condition_n are Haskell expressions similar to expression in expression splices, except that they have to evaluate to a value of type Bool. All conditions will be evaluated in sequence and if one condition evaluates to True, the subsequent template splices are added to the resulting template text; all other inner splices are discarded.

After successful parsing, a new record data type with a single data constructor and a corresponding instance of class Show is created for each template. Also each used template variable is transformed to a new record field of the data constructor. When parsed with default options, the simple template

    {{tpl simple}}{{:$name}}'s favourite song is "{{:$song}}"{{endtpl}}

will be translated to the record data type

    data TplSimple = TplSimple {
                        simpleName :: String,
                        simpleSong :: String
                     }.

To customize the created data types, the mkTemplatesWithOptions or mkTemplatesFromFileWithOptions functions can be used. Finally, use the show function on a value of the created data type to convert it into a string.

Documentation

mkTemplates :: String -> Q [Dec]

Transforms a string into a list of template declarations.

mkTemplatesWithOptions :: TplOptions -> String -> Q [Dec]

Transforms a string into a list of template declarations, using custom options for the data type generation.

mkTemplatesFromFile :: FilePath -> Q [Dec]

Reads a file and transforms the read file content into a list of template declarations.

mkTemplatesFromFileWithOptions :: TplOptions -> FilePath -> Q [Dec]

Reads a file and transforms the read file content into a list of template declarations, using custom options for the data type generation.

data TplOptions

A set of functions to change the style of the generated templates.

Constructors

TplOptions

Fields

tplMkName :: String -> String

Creates the data type and constructor name for a given template name.

tplMkFieldName :: String -> String -> String

Creates the record field name for a given template name and field name.

tplModifyText :: String -> String

This function is applied to each template text splice, allowing e.g. the removal of extra whitespace etc.

defaultTplOptions :: TplOptions

The default template generation options used by mkTemplates and mkTemplatesFromFile. An example:

     tplMkName defaultTplOptions "example"              == "TplExample"
     tplMkFieldName defaultTplOptions "example" "field" == "exampleField"
     tplModifyText defaultTplOptions                    == id