hairy
=====

The `hairy` crate provides text templates, not unlike mustache and handlebars (and the earlier ctemplate original), but a bit different.
Scoping is different: variables must specify explicitly which scope they use (by using `a.b` syntax). This is to avoid implicit behaviour when variables are (accidentally) overwritten.
To catch errors early on, optionally types can be added, which are checked compile time.
All errors are treated as hard errors and are reported.
So missing values and typing errors are not silently ignored.
Also, the templates support evaluation: `{{=expression}}`.
The supported expressions are from the [`expry`] crate, which allows executing expression on binary encoded JSON-like values (with support for defining custom functions).
Auto-escaping is applied to the output to avoid security issues (such as letting user input be exected as javascript).

# Syntax
In short the features and syntax:
- Variables can be declared at top of an input file with `type key: expry` pairs (JSON is a valid expry). `type` can be either `inline` (value is replaced during compilation of the template) or `default` (which is a default value that is added to the evaluation time value if the key does not exist). The first non-parsable line signals the end of the variables.
- Values can be outputted with `{{=value}}` (supports expressions, see below). Escape mode can
  be specified with `{{=value:escape_mode}}`. Values are processed by a user-definable escaper
  that can take the escape mode into account. Normally only strings and numbers are displayed,
  and the `null` value is considered a skip (without generating an error). Other values are considered an error, except when the `sjs` (script-js) or `js` escape modes are used.
- Conditionals with `{{if value}}contents{{end}}`. Contents is displayed if value evaluates to `true`. An else construct is supported: `{{if value}}foo{{else}}bar{{end}}`.
- Iterators with `{{for variable in name}}content{{end}}`, which can be used to iterate over (arrays of) any type. The contents of the array is available in the loop body under key `variable`;
- Template definition with `{{define name}}content{{end}}`. Templates can have optional default values (in an object) with `{{define name defaults object}}content{{end}}`. Defaults are resolved at template compile time, using the global context given to the compile function;
- Template instantiation with `{{call name}}` or `{{call name with value}}`. `name` can be an expression. If the name starts with a `*`, name can be an expression that resolves to a string (which is treated as a template name). If the name starts with `**`, name should be an expression that resolves to a binary form template code (as produced by the compile functions). If the `with` syntax is used, only the data specified in `value` is passed along (so the current context is not automatically transferred/merged, to do that use for value `{...this, key: value}`). This is done to avoid errors.
- Error handling is different from normal Mustache: missing fields is always considered an error. Errors can be suppressed with the `expr ??? alternative` try syntax (on error in `expr`, `alternative` will be executed). Shorthand for `expr ??? null` is `expr ???`, which can be used in loops with `{{for i in someField???}}`, which ignores errors if the field is not found. Same for conditionals.

`expry` expressions can be used instead of values as above (think of expressions, functional calls, selectors, etc).

Related
-------
- Mustache & Handlebars are the inspiration, however they lack the error handling of hairy (e.g. absent fields, type errors), and does not support expressions.
- [Ramhorns](https://crates.io/crates/ramhorns) is a Mustache implementation in Rust (still lacking handling absent fields), but with a nice macro that allows using native Rust data structures as input for the templates.
- [Askama](https://crates.io/crates/askama) is a type-safe compiled templating engine written in Rust. It does feature checking for absent fields, but does not support dynamic templates.