README (4565B)
1 Awk to Awk Templates; allows you to insert awk control code into plain text and 2 generate awk script to print out the text. This project started as simple 3 cheetah-like command and expression inclusion in text file and I'm working my 4 way to more featured and extensible approach inspired by jinja2 so the amount 5 of raw code that needs to be inserted is kept at minimum. 6 7 Currently implemented syntax: 8 9 <text> 10 any text not matching syntax below is printed out (a print statement will 11 be generated in the resulting script) 12 13 |<code> 14 lines starting with | are considered awk code and are expressed verbatim in 15 resulting script 16 17 ||<text> 18 escape for above syntax, prints text out with one bar prepended 19 20 @<macro> 21 special command to affect how the code is generated. user-defined macros 22 should be possible 23 24 @@<text> 25 escape for above syntax, prints text out with one at prepended 26 27 ... {% <code> %} ... 28 similar to |<code> but works as a block, doesn't have to happen at column 0 29 30 ... {{<expression>}} ... 31 inserts awk expression into the print command. Eg. a variable or result of 32 computation 33 34 Unimplemented: 35 36 ... {<string>} ... 37 ... {<string|function arg|...>} ... 38 handling similar to jinja2. pass string to user-defined function, possibly 39 define more functions to process it afterwards 40 41 ... {@macro@} ... 42 maybe? or perhaps just {% @macro %} to avoid yet another syntax 43 44 ... {#<comment>#} ... 45 46 Implemented macros: 47 48 @include <file> 49 Macro to recursively parse another template 50 51 @awk <file> 52 Macro to insert another file as verbatim code 53 54 @text <file> 55 Macro to insert another file as text 56 57 Implemented macros via external postprocesor: 58 59 @for <variable> in <field> 60 @for <variable> var <expression> 61 @endfor 62 helper for data.awk loops 63 64 Unimplemented macros: 65 66 @function <name> 67 set function to process {<...>} with 68 69 @out 70 @out ><filename> 71 @out <variable> 72 make the output be printed to stdout, specific file, or appended to a 73 variable respectively 74 75 @filter 76 @macro 77 @call 78 @autoescape 79 like in jinja2 80 81 --------------------------------------------------------------------------- 82 83 data.awk; simple library for structured data, suitable for input for template 84 scripts. 85 86 Syntax for data specification: 87 88 <name>=<value> 89 simple string value. If following line starts with tab, it's considered as 90 continuation of the value, similarly to MIME headers (but the newline is 91 preserved) 92 93 <name>=[ 94 <field name><tab><field name>... 95 <value><tab><value>... 96 ... 97 ] 98 field list. Simple table with named columns delimited by tab characters 99 100 currently allowed variable name regex is: /[a-zA-Z_][a-zA-Z0-9_]*/ 101 102 Functions for accessing data: 103 104 loop_start(<name>, <prefix>) -> <depth> 105 loop_iter(depth) 106 loop_end() 107 iterate through field list of given name, make value for each filed 108 accessible with given prefix. Loops can be nested, loop_end() ends the 109 innermost one. Special field names are also exposed: 110 111 _index 112 the current iteration number, counted from 1 113 114 _index0 115 the current iteration number, counted from 0 116 117 _revindex 118 number of iterations till the end of the loop, ending at 1 119 120 _revindex0 121 number of iterations till the end of the loop, ending at 0 122 123 _first 124 1 if on first item, 0 otherwise 125 126 _last 127 1 if on last item, 0 otherwise 128 129 _length 130 number of items in the field list that is being iterated through 131 132 get(<name>) -> <value> 133 returns the value of given variable, taking into account current loop state 134 135 query(<string>) -> value 136 (unimplemeted) query syntax suitable for {<...>} usage. 137 138 EBNF for query syntax: 139 query = part+ ("'" expression)? 140 part = name | "'" expression "'" | "<" query ">" 141 where: 142 name is any permissible variable name 143 expression is awk expression 144 145 nested expressions allow indirection, eg.: the_<cheese>shop would resolve 146 to get("the_" get("cheese") "shop") while awk expression allow more 147 flexible queries at expense of slightly more verbose syntax 148 149 --------------------------------------------------------------------------- 150 151 old readme 152 153 Awk to Awk Templates; compiles interleaved awk and text into pure posix awk 154 code. 155 156 This is my first attempt to create jinja2-like templates in awk. 157 (but it really works more like cheetah) 158 159 Since proper solution for custom extensible tags would be quite complex, I 160 went for generating awk code from the template and then postprocessing it with 161 sed in place of proper macro support. This should be enough for generating 162 system configuration files. 163 164 The syntax feels quite ugly since the inner workings don't match jinja2 at 165 all, so I might end up changing it. 166 167 To test it out run: ./bin/aat hello.aat