commit e4f467ec012957ca07e5d424e648cb1f57bc2624
parent b1dce9e2afe98ed200abbca1ba0dd94a7f11753d
Author: Jan Pobrislo <ccx@webprojekty.cz>
Date: Mon, 30 Sep 2013 22:33:20 +0200
update readme
Diffstat:
| M | README | | | 123 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- |
1 file changed, 120 insertions(+), 3 deletions(-)
diff --git a/README b/README
@@ -21,16 +21,133 @@ Currently implemented syntax:
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> }}...
+... {{<expression>}} ...
inserts awk expression into the print command. Eg. a variable or result of
computation
-... TBD
+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 = 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 --
+old readme
Awk to Awk Templates; compiles interleaved awk and text into pure posix awk
code.
