From dc8d14070795a040c4f48de124a8a50842c19bc2 Mon Sep 17 00:00:00 2001
From: RunasSudo <runassudo@yingtongli.me>
Date: Thu, 15 May 2025 17:39:00 +1000
Subject: [PATCH] Add README.md
---
README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 60 insertions(+)
create mode 100644 README.md
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 %}
+<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.