design: Add variable expansion design document

Author: cmouse

docs/core/design/var_expand.md

@@ -0,0 +1,61 @@
+---
+layout: doc
+title: Variable expansion design
+dovecotlinks:
+  var_expand: variable expansion design
+---
+
+# Variable expansion design
+
+Dovecot comes with powerful variable expansion system, which allows constructing reuseable text templates.
+This has been upgraded since v2.3 to a more flexible system.
+
+## Syntax
+
+```
+<var> ::= <expression-list>
+<expression-list> ::= <expression-list> <expression>
+<expression> ::= <VALUE>, "{" <filter-list> "}", "%"
+<filter-list> ::= <filter-list> "|" <filter>, <filter>
+<filter> ::= <func> <math-list>
+<math-list> ::= <math>
+<math> ::= <operator> <number>, <operator> <NAME>
+<number> ::= "-" <NUMBER>, <NUMBER>
+<operator> ::= "+", "-", "*", "/"
+<func> ::= <NAME> <arguments>
+<arguments> ::= "(" <argument-list> ")"
+<argument-list> ::= <argument-list> "," <argument>
+<argument> ::= <VALUE>, <NAME>, <number>, <key> "=" <number>, <key> "=" <NAME>, <key> "=" <VALUE>
+
+NAME = string
+VALUE = "string" or 'string'
+NUMBER = [0-9]+
+```
+
+## Design
+
+The system uses programs to perform the actual expansion. All expressions are first parsed into a program that can then be executed one or more times with parameters.
+
+Program parameters consists from variable table(s), provider(s) and escape function. A program can be executed with different parameters.
+
+## Parameters
+
+Parameters are provided via `struct var_expand_params`. Key-value mappings are provided via `const struct var_expand_table` array, which is `VAR_EXPAND_TABLE_END` terminated list of
+key-value mappings. Key's value can also be provided by a function.
+
+Providers are used to handle scoped variables, such as passdb, ldap etc. There are also global providers which are always available.
+
+Providers can be provide with `const struct var_expand_provider` array which contains prefix and provider function, and is `VAR_EXPAND_TABLE_END` terminated.
+
+It is also possible to provide escape function, which is applied to each %{pipeline} output.
+
+Key functions and providers use the same context.
+
+Key-value tables and providers can also be provided as arrays of arrays, which must be NULL terminated.
+Contexts for these must be provided in an array that is `VAR_EXPAND_CONTEXTS_END` terminated.
+
+When these arrays are used, first match wins.
+
+## Missing values
+
+If there is no key in table or provider, error will occur. This error can be negated with `default(value)` filter.