https://github.com/hoytech/templar

https://github.com/hoytech/templar

Last synced: 1 day ago
JSON representation

• Host: GitHub
• URL: https://github.com/hoytech/templar
• Owner: hoytech
• Created: 2023-05-16T17:31:51.000Z (over 2 years ago)
• Default Branch: master
• Last Pushed: 2023-06-21T06:16:33.000Z (over 2 years ago)
• Last Synced: 2025-09-13T01:46:50.436Z (26 days ago)
• Language: Perl
• Size: 35.2 KB
• Stars: 2
• Watchers: 3
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Templar

C++ HTML template compiler

This is a perl script that compiles a directory of `.tmpl` files into a C++17 header file. This header file can then be used in a C++ application to emit HTML.

Inspired by [hypertextcpp](https://github.com/kamchatka-volcano/hypertextcpp) with a few differences:

* Automatic HTML escaping to protect against XSS bugs

  * The normal `$(...)` replacement will perform escaping, ie convert `<` into `<` etc

  * If the replacement is inside an HTML attribute, single/double quotes are also escaped

  * When using sub-templates, no escaping is performed. For example, to use the template in `items/myItem.tmpl` as a sub-template, this will do the right thing: `$(items::myItem(ctx.item))`

  * If you want to *not* do the escaping, use the form `$!(...)` (be careful!)

* React-style empty tags `<>...>` for grouping items in conditions or loops without requiring enclosing tag

* Minification: Non-semantic whitespace in the template HTML is (mostly) removed at compile-time

* Single header output, as opposed to header per template

  * Converts directory structure of templates into namespaces

  * All templates are forward-declared so any template can call into another sub-template

* Instead of iostreams, this module concatenates strings

  * Rather than outputing independent C++ statements for each tag, templar coalesces adjacent literals into a single statement

  * I don't know if the above changes improve or degrade performance. There are arguments both ways, and I have not benchmarked anything

* Single-stage build process (no need to compile the template compiler)

* Output headers start with `#pragma once`

* Parameter struct is named `ctx` not `cfg`

* Less tested, missing some features

  * Currently unimplemented: sections (haven't needed it yet), procedures (use sub-templates), shared library renderer (no plans to do this)

  * A bit more limited in what types `$()` can handle. It has to be a string/string_view, or have an `std::to_string()` overload

## Dependencies

Template depends on `Regexp::Grammars` and `Template` perl modules. On debian/ubuntu systems you can install these packages:

    sudo apt install -y libregexp-grammars-perl libtemplate-perl

## Usage

See the setup in the `ex` directory. To compile:

    ./templar.pl tmpls/ tmpl mytmpls.h

* `tmpls/` is a directory that contains `.tmpl` files (all sub-directories are also searched)

* `tmpl` is the C++ namespace for your templates

* `mytmpls.h` is the output header file

## Copyright

(C) 2023 Doug Hoyte

MIT license