Show HN: WL, a new templating engine for C

3 weeks ago 2

WL is a powerful and flexible, yet experimental scripting language for templating with first-class support for HTML.

To learn about the language check out the LANGUAGE.md file. But for a sneak peek, here's an example:

let title = "Title of my webpage" let items = ["A", "B", "C"] let navigator = <nav> <a href="/home">Home</a> <a href="/about">About</a> </nav> let some_list = <ul> \for item in items: <li>\{escape item}</li> </ul> <html> <head> <title>\{escape title}</title> </head> <body> \{navigator} <article> \{some_list} </article> </body> </html>

Turing-complete language with first-class HTML support, procedures, and an import system
Easy to embed: The interpreter is a single C file with no dependencies that performs no allocations or I/O
Built-in XSS protection: escape() operator to sanitize dynamic HTML

The WL interpreter is intended to be used as a library, but you can use the CLI to get a feel for the language. You can compile it by running:

This will generate the wl executable that you can call to evaluate .wl files.

If you are using vscode, you can also install the language extension ide/vscode/wl-language by dropping it into your editor's extension folder and reloading it. The extension folder should be one of these:

Windows: %USERPROFILE%\.vscode\extensions
macOS: ~/.vscode/extensions
Linux: ~/.vscode/extensions

If you're sold on the language and want to embed it in your application, just add the wl.c and wl.h files to your build and read the "Embedding" section.

If you get stuck, have questions, or want to contribute, feel free to open an issue or join my discord server here.

Happy templatin'!

WL programs need to first be translated to bytecode, then evaluated in a virtual machine. The bytecode is completely standalone and can be cached.

The API is quite involved as it tries not to take resource ownership from the caller. Ideally parent applications will have their own simplified wrapper over this API with caching and support for their own object model.

To compile a script, you need to create a WL_Compiler object and add the source file to it

#include <stdio.h> #include "wl.h" int main(void) { WL_String source = WL_STR("<p>Hello, world!</p>"); // Allocate some memory for the compiler char memory[1<<16]; WL_Arena arena = { memory, sizeof(memory), 0 }; // Create the translation unit object WL_Compiler *c = wl_compiler_init(&arena); if (c == NULL) { /* error */ } // Add a file to the unit WL_AddResult res = wl_compiler_add(c, (WL_String) { NULL, 0 }, source); if (res.type == WL_ADD_ERROR) { fprintf(stderr, "Error: %s\n", wl_compiler_error(c).ptr); return -1; } if (res.type != WL_ADD_LINK) { fprintf(stderr, "Error: Unexpected compiler state\n"); return -1; } // Produce the template executable WL_Program program; int ret = wl_compiler_link(c, &program); if (ret < 0) { WL_String err = wl_compiler_error(c); fprintf(stderr, "Error: %s\n", err.ptr); return -1; } // Done! // The WL_Program is just a string of bytes you can // write to a file or store in a cache return 0; }

If the initial script includes other files, the wl_compiler_add function will return an WL_AddResult of type WL_ADD_AGAIN and contain the path of the file that needs to be added next. The program will then need to call wl_compiler_add again with that file, until either an error occurs or WL_ADD_LINK is returned.

Once a bytecode program has been obtained, this is how you set up the virtual machine to run it:

#include <stdio.h> #include "wl.h" int main(void) { WL_Program program; get_program_from_somewhere(&program); WL_Runtime *rt = wl_runtime_init(&arena, program); if (rt == NULL) { printf("error\n"); return -1; } for (bool done = false; !done; ) { WL_EvalResult res = wl_runtime_eval(rt); switch (res.type) { case WL_EVAL_NONE: // Dummy value. This is never returned. break; case WL_EVAL_DONE: // Evaluation complete done = true; break; case WL_EVAL_ERROR: // Runtime error occurred printf("Error: %s\n", wl_runtime_error(rt).ptr); return -1; case WL_EVAL_OUTPUT: // Output string available fwrite(res.str.ptr, 1, res.str.len, stdout); break; case WL_EVAL_SYSVAR: // External variable referenced break; case WL_EVAL_SYSCALL: // External function called break; } } return 0; }

When during the evaluation of a program the WL_EVAL_SYSVAR result is returned, it means the program referenced an external symbol as a variable. The host program needs to push onto the stack of the VM the value relative to that symbol.

Say your environment defined three external symbols "varA", "varB", "varC" with values 1, 2, 3. The way you would implement this is by doing:

for (bool done = false; !done; ) { WL_EvalResult res = wl_runtime_eval(rt); switch (res.type) { case WL_EVAL_NONE: break; case WL_EVAL_DONE: done = true; break; case WL_EVAL_ERROR: return -1; case WL_EVAL_OUTPUT: fwrite(res.str.ptr, 1, res.str.len, output); break; case WL_EVAL_SYSVAR: if (wl_streq(res.str, "varA", -1)) wl_push_s64(rt, 1); if (wl_streq(res.str, "varB", -1)) wl_push_s64(rt, 2); if (wl_streq(res.str, "varC", -1)) wl_push_s64(rt, 3); break; case WL_EVAL_SYSCALL: // External function called break; } }

You first check the name of the referenced symbol in res.str, then use one of the wl_push_* functions to add the associated value.

If the program performs a call to an external function, the VM will return a result of type WL_EVAL_SYSCALL.

The parent program can then get the number of arguments using the wl_arg_count function and wl_push_arg to set the top of the VM stack to the argument with the specified index. The argument can then be read using one of the wl_pop_* functions.

The caller then needs to push the return value of the call on top of the stack using one of the wl_push_* functions.

Read Entire Article