RunasSudo/htmlcc
1
Fork 0
Code Issues Pull Requests Activity

Add README.md

Browse Source
This commit is contained in:
RunasSudo 2025-05-15 17:39:00 +10:00
parent 9111bbad61
commit dc8d140707
Signed by: RunasSudo
GPG Key ID: 7234E476BF21C61A
1 changed files with 60 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
README.md Normal file
View File

@ -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 %}
<html>
<body>Hello world, my name is {{ my_name }}!</body>
</html>
{% endpage %}
```
The above template transpiles into the following C code:
```c
#include <stdio.h>
void output_variable_as_text(char *variable) { /* escape special characters ... */ }
char *my_name = "Alice";
void hello_world(void) {
printf("%s", "<html>\n");
printf("%s", " <body>Hello world, my name is ");
output_variable_as_text(my_name);
printf("%s", "!</body>\n");
printf("%s", "</html>\n");
}
```
See *examples/helloworld.html* for a more complex example making use of variables and control flow.