pomade
Add a little Gleam to your Mustache
What
pomade is a Mustache library written in Gleam. I
made it primarily because I couldn't find a pure Gleam implementation of the
Mustache templating language, but also because I wanted to make something fun
and learn Gleam in the process.
Compatibility
The goal for version 1.0 is to fully support the required portions of the Mustache specification, which means:
- Variables
- Raw variables
- Custom delimiters
- Sections
- Inverted sections
- Partials
As of version 0.1.0, this target has been achieved, but no support for the optional parts of the specification is planned before the first stable release. These unsupported aspects are:
- Inheritance (blocks and parents)
- Lambdas and functions
pomade passes the full suite of tests for
the mandatory features of the specification.
How
Installing it
gleam add pomade@1
Using it
First, import the required libraries:
import gleam/dict
import gleam/string_tree.{type StringTree}
import pomade
In addition to the rendering and compilation API, pomade provides support for
heterogeneous hashmaps and values, which Mustache requires as input.
Rendering templates
The most basic use case is rendering a template with a single call:
pub fn render_template() -> Result(StringTree, pomade.Error) {
let template = "Hello, {{target}}!"
let data = pomade.dict(dict.from_list([#("target", pomade.string("world"))]))
pomade.compile_and_render(template, data, dict.new())
// -> Ok(StringTree)
// -> "Hello, world!"
}
By default, the API returns StringTrees, but there's a version that returns
Strings:
pub fn render_string() -> Result(String, pomade.Error) {
let template = "Goodbye, {{target}}"
let data = pomade.dict(dict.from_list([#("target", pomade.string("horses"))]))
pomade.compile_and_render_string(template, data, dict.new())
// -> Ok("Goodbye, horses")
}
Using partials
You can also render templates with partials, by passing a Dict(String, String)
in the partials argument, mapping a partial name to the source of that partial:
pub fn render_with_partials() -> Result(String, pomade.Error) {
let template = "Fly, you {{>other_template}}!"
let data =
pomade.dict(dict.from_list([#("adjective", pomade.string("fools"))]))
let partials = dict.from_list([#("other_template", "{{adjective}}")])
pomade.compile_and_render_string(template, data, partials)
// -> Ok("Fly, you fools!")
}
pomade takes care of caching the compiled partial, in a way that's compliant
with the Mustache spec, to save on the costs of compiling the template at
runtime every time it's needed.
Pre-compilation
If you anticipate that you'll be rendering a template often during the lifespan of your program (as in, for example, a web application), you can pre-compile templates to save some time:
pub fn precompile() -> Result(String, pomade.Error) {
let template_source = "No. I am your {{relative}}."
let assert Ok(template) = pomade.compile(template_source)
render_compiled(template)
}
You can then, of course, simply expand the pre-compiled template:
pub fn render_compiled(
template: pomade.Template,
) -> Result(String, pomade.Error) {
let data =
pomade.dict(dict.from_list([#("relative", pomade.string("father"))]))
pomade.render_string(template, data, dict.new())
// -> Ok("No. I am your father.")
//
// Or:
// pomade.render(template, data, dict.new())
// -> Ok(StringTree)
}
Information for nerds
Working on it
First, ensure that you've fetched the git submodules locally, so that the unit tests can find the Mustache specification test suite:
git submodule update --init
Then, you can run:
gleam test
Or whatever.
Benchmarking it
pomade comes with a few Glychee benchmarks, shamelessly lifted (ported) from
the repository of the Ruby version of Mustache. You can find them under
dev/pomade, and you can run them like so:
gleam run -m "pomade/compile_template_benchmark"
Results vs bbmustache (via chaplin)
With the following hardware and configuration:
Operating System: macOS
CPU Information: Apple M1
Number of Available Cores: 8
Available memory: 8 GB
Elixir 1.20.4
Erlang 29.1.1
JIT enabled: true
Benchmark suite executing with the following configuration:
warmup: 4 s
time: 4 s
memory time: 8 s
reduction time: 4 s
parallel: 1
inputs: none specified
Estimated total run time: 20 s
Excluding outliers: false
We have the following benchmarks:
Compile template benchmark
Name ips average deviation median 99th %
pomade: compile template 82.27 K 12.15 μs ±27.74% 11.54 μs 16.13 μs
chaplin: compile template 40.84 K 24.48 μs ±12.77% 23.88 μs 32.54 μs
Comparison:
pomade: compile template 82.27 K
chaplin: compile template 40.84 K - 2.01x slower +12.33 μs
Memory usage statistics:
Name Memory usage
pomade: compile template 27.85 KB
chaplin: compile template 5.68 KB - 0.20x memory usage -22.17188 KB
**All measurements for memory usage were the same**
Reduction count statistics:
Name Reduction count
pomade: compile template 1.52 K
chaplin: compile template 0.40 K - 0.26x reduction count -1.12800 K
**All measurements for reduction count were the same**
Render template without HTML escaping
Name ips average deviation median 99th %
pomade: html escape 83.71 K 11.95 μs ±27.42% 10.92 μs 23.71 μs
chaplin: html escape 46.16 K 21.66 μs ±13.53% 21.17 μs 30.08 μs
Comparison:
pomade: html escape 83.71 K
chaplin: html escape 46.16 K - 1.81x slower +9.72 μs
Memory usage statistics:
Name Memory usage
pomade: html escape 23.79 KB
chaplin: html escape 7.23 KB - 0.30x memory usage -16.56250 KB
**All measurements for memory usage were the same**
Reduction count statistics:
Name Reduction count
pomade: html escape 1.36 K
chaplin: html escape 0.65 K - 0.48x reduction count -0.71000 K
**All measurements for reduction count were the same**
Render template with HTML escaping
Name ips average deviation median 99th %
pomade: html escape 82.00 K 12.19 μs ±30.01% 11.50 μs 17.29 μs
chaplin: html escape 43.12 K 23.19 μs ±14.29% 22.54 μs 42.17 μs
Comparison:
pomade: html escape 82.00 K
chaplin: html escape 43.12 K - 1.90x slower +11.00 μs
Memory usage statistics:
Name Memory usage
pomade: html escape 23.79 KB
chaplin: html escape 8.45 KB - 0.36x memory usage -15.34375 KB
**All measurements for memory usage were the same**
Reduction count statistics:
Name Reduction count
pomade: html escape 1.43 K
chaplin: html escape 0.90 K - 0.63x reduction count -0.53400 K
**All measurements for reduction count were the same**
Render pre-compiled template with a collection with 1000 items
Name ips average deviation median 99th %
pomade: render collection 1.73 K 0.58 ms ±11.12% 0.56 ms 0.76 ms
chaplin: render collection 0.35 K 2.88 ms ±4.14% 2.90 ms 3.09 ms
Comparison:
pomade: render collection 1.73 K
chaplin: render collection 0.35 K - 4.97x slower +2.30 ms
Memory usage statistics:
Name Memory usage
pomade: render collection 0.78 MB
chaplin: render collection 2.98 MB - 3.83x memory usage +2.20 MB
**All measurements for memory usage were the same**
Reduction count statistics:
Name Reduction count
pomade: render collection 129.29 K
chaplin: render collection 376.78 K - 2.91x reduction count +247.49 K
**All measurements for reduction count were the same**
Render pre-compiled template with a collection with 1000 partials
Name ips average deviation median 99th %
render partials 3.91 K 256.07 μs ±17.10% 244.83 μs 435.27 μs
Memory usage statistics:
Name Memory usage
render partials 521.98 KB
**All measurements for memory usage were the same**
Reduction count statistics:
Name Reduction count
render partials 66.84 K
**All measurements for reduction count were the same**
License
pomade is distributed under the MIT License. You can find more details in
LICENSE.
Important
You won't find any AI slop here.