[bug-recutils] RFC: improved templates language for recfmt

[Jose E. Marchesi]

Hi all.

The current language understood by recfmt is very poor: just {{EXPR}}
where EXPR is any selection expression.  Recent feedback from a user
convinced me that would be really useful to have conditional and
iterating constructions as well.

Here is a proposal for an extremely simple templates language.  I
inspired in several existing template languages, most of them are too
complex or too web-oriented to be used as such.

I would highly appreciate comments on this (even if it is to say "looks
good").  I would not want to implement something with evident flaws or
that won't escale properly.  Whatever results from this will go in the
1.4 release :)

Thanks in advance!


** Recutils Template Language

   A template consists on unrestricted text and marks.  Marks are anything
   enclosed between {{ and }} characters.  Anything that is not part of a mark
   is literally copied to the output.

   Marks are processed by the templates engine and replaced by some text.  The
   actual text depends on the type of mark.  Supported marks are expression
   marks, comment marks, conditional marks, looping marks and inclusion marks.
   Those are described in the following subsections.

*** Expression marks

    Expression marks contain selection expressions:

    : {{EXPR}}
    
    The enclosed selection expression can vary from simple field names to
    complex expressions.  Examples are:

    : {{Name}}                     => Jose E. Marchesi
    : {{"Mr. " & Name}}            => Mr. Jose E. Marchesi
    : Number of emails: {{#Email}} => Number of emails: 2

    If the selection expression into a mark generates the empty string then
    the mark is replaced with the empty string.

*** Comment marks

    Marks of the form

    : {{! foobar !}}

    contain comments.  The text enclosed in the mark is ignored, being
    replaced with the empty string.  This is useful to comment out parts of
    template files.  Note that the ! character also appears before the }} in
    order to support nested marks.  Comment marks can be nested as well, but
    in that case they must be balanced:

    : {{!
    :     This was part of the template:
    :     {! a list of articles !}
    :     ...
    : !}}

    Note that the ! characters shall appear immediately after {{ and
    immediately before }}.
    
*** Conditional marks

    The conditional marks allow to make if-then-else structures in the
    template.  They are used like:

    : {{%if EXPR}}
    :   This is the if part.
    : {{%elif EXPR}}
    :   Another if part.
    : {{%else}}
    :   If nothing else...
    : {{%end}}

    The semantics of each sections are the expected ones.  The %elif and %else
    marks are optional, and many %elif marks can be used.  The %end mark shall
    be present.

*** Looping marks

    The looping marks allow to code loop structures in the template.  There
    are two flavors: for and foreach.

    The 'foreach' loop allows to associate a template variable with all the
    consecutive values of a record field.  The synopsis is:

    : {{%foreach VAR FIELD_NAME}}
    :   ...
    : {{%end}}

    The mark is replaced with the concatenated bodies resulting from applying
    its contents, with %VAR being replaced by the consecutive values of
    FIELD_NAME in the current record.  For example, we could make a bullet
    list of articles using the following template:

    : {{%foreach A Article}}
    :   - {{%A}}
    : {{%end}}

    Note that {{%A}} in the example above is an expression mark.  The %VAR
    constructions are replaced only when they are found in expression marks,
    before the actual expression is computed.  For obvious reasons VAR cannot
    be equal to 'if', 'elif', 'else', 'for', 'foreach' or 'end'.

    The second flavor of looping templates is the more general 'for' loop.
    The synopsis is:

    : {{%for VAR EXPR_MIN..EXPR_MAX}}
    :   ...
    : {{%end}}
    
    The mark is replaced with the concatenated bodies resulting from applying
    its contents, with %VAR being replaced by the integral numbers in the
    range [EXPR_MIN,EXPR_MAX], both sides included.  Both EXPR_MIN and
    EXPR_MAX shall be selection expressions whose results can be interpreted
    as an integer.  Negative integers are allowed, and in case EXPR_MIN is
    bigger than EXPR_MAX then the count will be made downwards.  An example of
    the usage of those marks is:

    : {{%for I 0..#Article - 1}}
    :   - {{Article[%I]}}
    : {{%end}}

    Those marks are equivalent to the 'foreach' example above.  If we wanted
    to list the articles downwards we would reverse the expressions:

    : {{%for I #Article..0}}
    :   - {{Article[%I]}}
    : {{%end}}
    
    Note that the '..' characters separating both selection expressions shall
    not be separated.

*** Inclusion marks

    Inclusion marks allow to decompose complex templates into simpler
    templates stored in other files.  The synopsis is:

    : {{< FILE}}

    where FILE is the path of a file.  The mark is replaced by the contents of
    the file once they have been processed by the templates engine.  The path
    may be either absolute or relative.  In the later case the file is
    relative to the current working directory of the process running the
    template engine.