A (mostly logicless) textual templating language with similar syntax to Liquid or Jinja2.

(ED-E is a character from Fallout New Vegas, pronounced Eddie.)

A simple example of parsing and rendering Text containing a basic conditional expression and variable interpolation follows.

First the Template is defined:

>>> let tmpl = "{% if var %}\nHello, {{ var }}!\n{% else %}\nnegative!\n{% endif %}\n" :: Data.ByteString.ByteString

Then an Object is defined containing the environment which will be available to the Template during rendering:

>>> let env = fromPairs [ "var" .= "World" ] :: Object

Note: the fromPairs function above is a wrapper over Aeson's object which removes the Value constructor, exposing the delicious HashMap underneath.

Finally the environment is applied to the Template:

>>> render tmpl env :: Result Text
> Success "Hello, World!"

In this manner, Templates can be pre-compiled to the internal AST and the cost of parsing can be amortised if the same Template is rendered multiple times.

Another example, this time rendering a Template from a file:

import qualified Data.Text.Lazy as LText
import           Text.EDE

main :: IO ()
main = do
    r <- eitherParseFile "template.ede"
    either error print $ r >>= (`eitherRender` env)
  where
    env = fromPairs
        [ "text" .= "Some Text."
        , "int"  .= 1
        , "list" .= [5..10]
        ]

Please see the syntax section for more information about available statements and expressions.

Parsing and rendering require two separate steps intentionally so that the more expensive (and potentially impure) action of parsing and resolving includes can be embedded and re-used in a pure fashion.

• Parsing tokenises the input and converts it to an internal AST representation, resolving includes using a custom function. The result is a compiled template which can be cached for future use.
• Rendering takes a HashMap of custom Funs (functions available in the template context), an Object as the binding environment, and a parsed Template to subsitute the values into. The result is a Lazy Text value containing the rendered output.

The Resolver used to resolve include expressions determines the purity of Template parsing.

For example, using the includeFile Resolver means parsing is restricted to IO, while pre-caching a HashMap of Templates and supplying them to parseWith using includeMap offers a pure variant for include resolution.

The Result of a parse or render steps can be inspected or analysed using result as follows:

>>> result failure success $ render tmpl env

If you're only interested in dealing with errors as strings, and the positional information contained in Meta is not of use you can use the convenience functions eitherParse, eitherRender, or convert a Result to Either using eitherResult.

>>> either failure success $ eitherParse tmpl

fromPairs (or fromValue) is a wrapper around Aeson's object function which safely strips the outer Value constructor, providing the correct type signature for input into render.

It is used in combination with the re-exported .= as follows:

>>> render (fromPairs [ "foo" .= "value", "bar" .= 1 ]) :: Template -> Result Text

Syntax can be modified either via the arguments to parseWith or alternatively by specifying the delimiters via an EDE_SYNTAX pragma.

Note: The pragmas must start on line1. Subsequently encountered pragmas are parsed as textual template contents.

For example:

{! EDE_SYNTAX pragma=("{*", "*}") inline=("#@", "@#") comment=("<#", "#>") block=("$$", "$$") !}
{* EDE_SYNTAX block=("#[", "]#")  *}
...

Would result in the following syntax:

• Pragmas: {* ... *}
• Inline: #@ ... @#
• Comment: <# ... #>
• Block: #[ ... ]#

Note: EDE_SYNTAX pragmas only take effect for the current template, not child includes. If you want to override the syntax for all templates use parseWith and custom Syntax settings.

Expressions behave as any simplistic programming language with a variety of prefix, infix, and postifx operators available. (See: Text.EDE.Filters)

A rough overview of the expression grammar:

expression ::= literal | identifier | '|' filter
filter     ::= identifier
identifier ::= [a-zA-Z_]{1}[0-9A-Za-z_']*
object     ::= '{' pairs '}'
pairs      ::= string ':' literal | string ':' literal ',' pairs
array      ::= '[' elements ']'
elements   ::= literal | literal ',' elements
literal    ::= object | array | boolean | number | string
boolean    ::= true | false
number     ::= integer | double
string     ::= "char+|escape"

Variables are substituted directly for their renderable representation. An error is raised if the varaible being substituted is not a literal type (ie. an Array or Object) or doesn't exist in the supplied environment.

{{ var }}

Nested variable access is also supported for variables which resolve to an Object. Dot delimiters are used to chain access through multiple nested Objects. The right-most accessor must resolve to a renderable type as with the previous non-nested variable access.

{{ nested.var.access }}

A conditional is introduced and completed with the section syntax:

{% if <expr1> %}
   ... consequent expressions
{% elif <expr2> %}
   ... consequent expressions
{% elif <expr3> %}
   ... consequent expressions
{% else %}
   ... alternate expressions
{% endif %}

The boolean result of the expr determines the branch that is rendered by the template with multiple (or none) elif branches supported, and the else branch being optional.

In the case of a literal it conforms directly to the supported boolean or relation logical operators from Haskell. If a variable is singuarly used its existence determines the result of the predicate, the exception to this rule is boolean values which will be substituted into the expression if they exist in the supplied environment.

The following logical expressions are supported as predicates in conditional statements with parameters type checked and an error raised if the left and right hand sides are not type equivalent.

• And: &&
• Or: ||
• Equal: ==
• Not Equal: != (See: /=)
• Greater: >
• Greater Or Equal: >=
• Less: <
• Less Or Equal: <=
• Negation: ! (See: not)

See: Text.EDE.Filters

To pattern match a literal or variable, you can use the case statement:

{% case var %}
{% when "a" %}
   .. matched expressions
{% when "b" %}
   .. matched expressions
{% else %}
   .. alternate expressions
{% endcase %}

Patterns take the form of variables, literals, or the wild-card '@_@' pattern (which matches anything).

Iterating over an Array or Object can be acheived using the 'for ... in' section syntax. Attempting to iterate over any other type will raise an error.

Example:

{% for var in list %}
    ... iteration expression
{% else %}
    ... alternate expression
{% endfor %}

The iteration branch is rendering per item with the else branch being (which is optional) being rendered if the {{ list }} variable is empty.

When iterating over an Object, a stable sort using key equivalence is applied, Arrays are unmodified.

The resulting binding within the iteration expression (in this case, {{ var }}) is an Object containing the following keys:

• key :: Text: They key if the loop target is an Object
• value :: a: The value of the loop target
• loop :: Object: Loop metadata.
• length :: Int: Length of the loop
• index :: Int: Index of the iteration
• index0 :: Int: Zero based index of the iteration
• remainder :: Int: Remaining number of iterations
• remainder0 :: Int: Zero based remaining number of iterations
• first :: Bool: Is this the first iteration?
• last :: Bool: Is this the last iteration?
• odd :: Bool: Is this an odd iteration?
• even :: Bool: Is this an even iteration?

For example:

{% for item in items %}
    {{ item.index }}:{{ item.value }}
    {% if !item.last %}

    {% endif %}
{% endfor %}

Will render each item with its (1-based) loop index as a prefix, separated by a blank newline, without a trailing at the end of the document.

Valid loop targets are Objects, Arrays, and Strings, with only Objects having an available {{ var.key }} in scope.

Includes are a way to reduce the amount of noise in large templates. They can be used to abstract out common snippets and idioms into partials.

If parseFile or the includeFile resolver is used, templates will be loaded using FilePaths. (This is the default.)

For example:

{% include "/var/tmp/partial.ede" %}

Loads partial.ede from the file system.

The current environment is made directly available to the included template. Additional bindings can be created (See: let) which will be additionally available only within the include under a specific identifier:

{% include "/var/tmp/partial.ede" with some_number = 123 %}

Includes can also be resolved using pure Resolvers such as includeMap, which will treat the include expression's identifier as a HashMap key:

{% include "arbitrary_key" %}

Uses lookup to find arbitrary_key in the HashMap supplied to includeMap.

Filters are typed functions which can be applied to variables and literals. An example of rendering a lower cased boolean would be:

{{ true | show | lower }}

The input is on the LHS and chained filters (delimited by the pipe operator |) are on the RHS, with filters being applied postfix, left associatively.

See: Text.EDE.Filters

You can disable template processing for blocks of text using the raw section:

{% raw %}
Some {{{ handlebars }}} or {{ mustache }} or {{ jinja2 }} output tags etc.
{% endraw %}

This can be used to avoid parsing expressions which would otherwise be considered valid ED-E syntax.

Comments are ignored by the parser and omitted from the rendered output.

{# singleline comment #}

{#
   multiline
   comment
#}

You can also bind an identifier to values which will be available within the following expression scope.

For example:

{% let var = false %}
...
{{ var }}
...