so://phie

blob: f5ad7b5731aaba15acf77d438ac23fd1c73ab8b1 (3032 bytes)[doc][blame][raw]

 1# ductape
 2
 3Static template generator for C
 4
 5_ductape_ is static template generator with dynamic linking for C.
 6
 7```graph
 8                                 +---------+                      (dlopen)
 9                           +---> |   .so   | ---------------------- load ------------------------+
10+---------+    (ductape)   |     +---------+                                                     |
11|  .html  | --- compile ---+                                                                     v
12+---------+                |     +---------+                  +----------+      (cc)        +----------+
13                           +---> |   .h    | --- include ---> |  main.c  | --- compile ---> |   main   |
14                                 +---------+                  +----------+                  +----------+
15```
16
17## Quick Start
18
19Create a `macro.h` file which needs to define `DUC_OUT` for storing the handle the content is later written to and `DUC_WRITE` which handles consuming and writing onto the handle.
20
21The file can be extended with custom macros (like `STRING`, `NUMBER`, `MARKDOWN`, etc.), to simplify writing more complex templates.
22
23```c
24#define DUC_OUT ((str_t *) out) // cast custom handle
25#define DUC_WRITE($str) { str_append(DUC_OUT, $str); } // define custom write function
26
27#define STRING DUC_WRITE
28```
29
30The template `example.html` is defined (could be any kind of language), which includes the previously defined macro header file, followed by the start of the template definition `DUC_TEMPLDEF` with the first parameter being the UID and succeeding with varies parameters which allow for injecting dynamic data. The end of the template is marked with `DUC_ENDTEMPL`. Inside the template definition. the content is rendered, while content outside will be ignored.
31
32The symbol `%` marks the delimiter between template and C code. In order to use the delimiter in the template it needs to be repeated twice to escape the character. All parameters passed into the template are bound to the `ctx` variable.
33
34```html
35% #include "macro.h" %
36
37% DUC_TEMPLDEF(
38  example,
39  char *message;
40) %
41
42<p>% STRING(ctx->message) %</p>
43
44% DUC_ENDTEMPL %
45```
46
47The template can be compiled with the the installed CLI command `ductape`. Simply pass a list of files to the command and it will generate the corresponding `.h` (header) and `.so` (shared library) files based on the specified UID of the template.
48
49```
50ductape example.html
51```
52
53Finally, a main function can be defined which imports the compiled `example.h` header file, which contains everything needed to dynamically render the template, such as the `example_t` context structure passed into the template, as well as the `example_render` function which renders the template into the specified `out` handle.
54
55```c
56#include "example.h"
57
58int main(void) {
59  str_t out = STR_NULL;
60  example_t ctx = {
61    .message = "It works!",
62  };
63  int ret = example_render(&out, &ctx);
64  if (ret == 0) {
65    printf("%s", (char *) str_get(&out))
66    str_free(&out);
67  }
68  return ret;
69}
70```