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.