ductape

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

blob: 040803d2da3f65c753bd588e3d495df13c69afbb (2747 bytes)[doc][blame][raw]

 1# ductape
 2
 3Static template generator for C
 4
 5## Installation
 6
 7```
 8git clone git@soophie.de:/srv/git/ductape
 9cd ductape
10sudo make install
11```
12
13## Quick Start
14
15Create 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.
16
17The file can be extended with custom macros (like `STRING`, `NUMBER`, `MARKDOWN`, etc.), to simplify writing more complex templates.
18
19```c
20#define DUC_OUT ((str_t *) out) // cast custom handle
21#define DUC_WRITE($str) { str_append(DUC_OUT, $str); } // define custom write function
22
23#define STRING DUC_WRITE
24```
25
26The 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 `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 `ENDTEMPL`. Inside the template definition. the content is rendered, while content outside will be ignored.
27
28The 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.
29
30```html
31% #include "macro.h" %
32
33% TEMPLDEF(
34  example,
35  char *message;
36) %
37
38<p>% STRING(ctx->message) %</p>
39
40% ENDTEMPL %
41```
42
43The 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.
44
45```
46ductape example.html
47```
48
49Finally, 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.
50
51```c
52#include "example.h"
53
54int main(void) {
55  str_t out = STR_NULL;
56  example_t ctx = {
57    .message = "It works!",
58  };
59  int ret = example_render(&out, &ctx);
60  if (ret == 0) {
61    printf("%s", (char *) str_get(&out))
62    str_free(&out);
63  }
64  return ret;
65}
66```
67
68## License
69
70This project is licensed under the **GNU General Public License v3.0 (GPLv3)**.
71
72**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.
73
74See the [LICENSE](?license) file for the full legal text.

so://phie

ductape