{- |
    Module      :  Text.Bravo
    Copyright   :  Matthias Reisner
    License     :  BSD3

    Maintainer  :  Matthias Reisner <matthias.reisner@googlemail.com>
    Stability   :  experimental
    Portability :  unknown

    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.

-}

module Text.Bravo (
        module Text.Bravo.Translate
    )
where

import Text.Bravo.Translate