README

Awk to Awk Templates; allows you to insert awk control code into plain text and
generate awk script to print out the text. This project started as simple
cheetah-like command and expression inclusion in text file and I'm working my
way to more featured and extensible approach inspired by jinja2 so the amount
of raw code that needs to be inserted is kept at minimum.

Currently implemented syntax:

<text>
        any text not matching syntax below is printed out (a print statement will
        be generated in the resulting script)

|<code>
        lines starting with | are considered awk code and are expressed verbatim in
        resulting script

||<text>
        escape for above syntax, prints text out with one bar prepended

@<macro>
        special command to affect how the code is generated. user-defined macros
        should be possible

@@<text>
        escape for above syntax, prints text out with one at prepended

... {% <code> %} ...
        similar to |<code> but works as a block, doesn't have to happen at column 0

... {{<expression>}} ...
        inserts awk expression into the print command. Eg. a variable or result of
        computation

Unimplemented:

... {<string>} ...
... {<string|function arg|...>} ...
        handling similar to jinja2. pass string to user-defined function, possibly
        define more functions to process it afterwards

... {@macro@} ...
        maybe? or perhaps just {% @macro %} to avoid yet another syntax

... {#<comment>#} ...

Implemented macros:

@include <file>
        Macro to recursively parse another template

@awk <file>
        Macro to insert another file as verbatim code

@text <file>
        Macro to insert another file as text

Implemented macros via external postprocesor:

@for <variable> in <field>
@for <variable> var <expression>
@endfor
        helper for data.awk loops

Unimplemented macros:

@function <name>
        set function to process {<...>} with

@out
@out ><filename>
@out <variable>
        make the output be printed to stdout, specific file, or appended to a
        variable respectively

@filter
@macro
@call
@autoescape
        like in jinja2

---------------------------------------------------------------------------

data.awk; simple library for structured data, suitable for input for template
scripts.

Syntax for data specification:

<name>=<value>
        simple string value. If following line starts with tab, it's considered as
        continuation of the value, similarly to MIME headers (but the newline is
        preserved)

<name>=[
<field name><tab><field name>...
<value><tab><value>...
...
]
        field list. Simple table with named columns delimited by tab characters

currently allowed variable name regex is: /[a-zA-Z_][a-zA-Z0-9_]*/

Functions for accessing data:

loop_start(<name>, <prefix>) -> <depth>
loop_iter(depth)
loop_end()
        iterate through field list of given name, make value for each filed
        accessible with given prefix. Loops can be nested, loop_end() ends the
        innermost one. Special field names are also exposed:

        _index
                the current iteration number, counted from 1

        _index0
                the current iteration number, counted from 0

        _revindex
                number of iterations till the end of the loop, ending at 1

        _revindex0
                number of iterations till the end of the loop, ending at 0

        _first
                1 if on first item, 0 otherwise

        _last
                1 if on last item, 0 otherwise

        _length
                number of items in the field list that is being iterated through

get(<name>) -> <value>
        returns the value of given variable, taking into account current loop state

query(<string>) -> value
        (unimplemeted) query syntax suitable for {<...>} usage.

        EBNF for query syntax:
        query = part+ ("'" expression)?
        part = name | "'" expression "'" | "<" query ">"
        where:
                name is any permissible variable name
                expression is awk expression

        nested expressions allow indirection, eg.: the_<cheese>shop would resolve
        to get("the_" get("cheese") "shop") while awk expression allow more
        flexible queries at expense of slightly more verbose syntax

---------------------------------------------------------------------------

old readme

Awk to Awk Templates; compiles interleaved awk and text into pure posix awk
code.

This is my first attempt to create jinja2-like templates in awk.
(but it really works more like cheetah)

Since proper solution for custom extensible tags would be quite complex, I
went for generating awk code from the template and then postprocessing it with
sed in place of proper macro support. This should be enough for generating
system configuration files.

The syntax feels quite ugly since the inner workings don't match jinja2 at
all, so I might end up changing it.

To test it out run: ./bin/aat hello.aat