ductape

Static template generator for C
git clone git://soophie.de/ductape

blob: cbcf79c71f7db8944b2836e36f0ca59862cd8807 (3532 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## Installation
18
19```
20git clone git@soophie.de:/srv/git/ductape
21cd ductape
22sudo make install
23```
24
25## Quick Start
26
27Create 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.
28
29The file can be extended with custom macros (like `STRING`, `NUMBER`, `MARKDOWN`, etc.), to simplify writing more complex templates.
30
31```c
32#define DUC_OUT ((str_t *) out) // cast custom handle
33#define DUC_WRITE($str) { str_append(DUC_OUT, $str); } // define custom write function
34
35#define STRING DUC_WRITE
36```
37
38The 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.
39
40The 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.
41
42```html
43% #include "macro.h" %
44
45% DUC_TEMPLDEF(
46  example,
47  char *message;
48) %
49
50<p>% STRING(ctx->message) %</p>
51
52% DUC_ENDTEMPL %
53```
54
55The 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.
56
57```
58ductape example.html
59```
60
61Finally, 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.
62
63```c
64#include "example.h"
65
66int main(void) {
67  str_t out = STR_NULL;
68  example_t ctx = {
69    .message = "It works!",
70  };
71  int ret = example_render(&out, &ctx);
72  if (ret == 0) {
73    printf("%s", (char *) str_get(&out))
74    str_free(&out);
75  }
76  return ret;
77}
78```
79
80## License
81
82This project is licensed under the **GNU General Public License v3.0 (GPLv3)**.
83
84**What this means:** You are free to use, study, and modify this framework. However, if you distribute a program that uses this framework (including selling it), you **must** provide the full source code of your program under the same GPLv3 license.
85
86See the [LICENSE](?license) file for the full legal text.

so://phie

ductape