diff --git a/README.md b/README.md new file mode 100644 index 0000000..36cf907 --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# htmlcc + +htmlcc is a simple HTML templating engine for C. At compile time, htmlcc transpiles template files into C functions to generate HTML, i.e. templates are statically compiled into C. + +## Usage + +``` +python -m htmlcc input.html > output.c +``` + +By default, htmlcc emits C code which prints the generated HTML to standard output. An extensible framework is provided to customise this behaviour via the `--emitter` flag (see *htmlcc/emitter/cgit.py* for an example implementation). + +## Syntax + +htmlcc syntax is based loosely on [Jinja](https://jinja.palletsprojects.com/en/stable/), using double curly braces. + +The following language features are supported: + +* `{% page page_name %} ... {% endpage %}` declares a page function with the C signature `void page_name(void) { ... }`. + * Page functions can declare arguments using the syntax `{% page page_name(char *arg1, int arg2) %}`, etc. + * `{% block block_name %} ... {% endblock %}` is equivalent, but emitters may override this and provide for different behaviour. +* `{{ expression }}` escapes and outputs the given `char*` expression as HTML text. + * `{{ expression|attr }}` escapes and outputs the given `char*` expression as an HTML attribute. + * `{{ expression|urlencode }}` escapes and outputs the given `char*` expression as a percent-encoded URL component (not implemented for the *stdout* emitter). + * `{{ expression|%d }}`, `{{ expression|%ld }}` escape and output the given `int` and `long` expressions respectively. +* `{% if expr %} ... {% endif %}`, `{% while expr %} ... {% endwhile %}`, `{% for init_expr; cond_expr; loop_expr } ... {% endfor %}` generate if/while/for statements respectively. + * `{% if expr %} ... {% elif expr %} ... {% else %} ... {% endif %}` blocks are supported. +* `{! ... !}` inserts raw C code, e.g. `{! foo.bar(); !}`. +* `{# ... #}` is a comment, which is not included in the generated template. + +## Example + +```html +{! char *my_name = "Alice"; !} +{% page hello_world %} + + Hello world, my name is {{ my_name }}! + +{% endpage %} +``` + +The above template transpiles into the following C code: + +```c +#include + +void output_variable_as_text(char *variable) { /* escape special characters ... */ } + +char *my_name = "Alice"; + +void hello_world(void) { + printf("%s", "\n"); + printf("%s", " Hello world, my name is "); + output_variable_as_text(my_name); + printf("%s", "!\n"); + printf("%s", "\n"); +} +``` + +See *examples/helloworld.html* for a more complex example making use of variables and control flow.