exchange/src/templating

Introduction to Mustach 1.2

mustach is a C implementation of the mustache template specification.

The main site for mustach is on gitlab.

The simplest way to use mustach is to copy the files mustach.h and mustach.c directly into your project and use it.

If you are using one of the JSON libraries listed below, you can get extended feature by also including mustach-wrap.h, mustach-wrap.c, mustach-XXX.h and mustach-XXX.c in your project (see below for XXX)

• json-c: use XXX = json-c
• jansson: use XXX = jansson
• cJSON: use XXX = cjson

Alternatively, make and meson files are provided for building mustach and libmustach.so shared library.

Since version 1.0, the makefile allows to compile and install different flavours. See below for details.

Distributions offering mustach package

Alpine Linux

apk add mustach
apk add mustach-lib
apk add mustach-dev

NetBSD

cd devel/mustach
make

See http://pkgsrc.se/devel/mustach

Known projects using Mustach

This wiki page lists the known project that are using mustach and that kindly told it.

Don't hesitate to tell us if you are interested to be listed there.

Using Mustach from sources

The file mustach.h is the main documentation. Look at it.

The current source files are:

• mustach.c core implementation of mustache in C
• mustach.h header file for core definitions
• mustach-wrap.c generic wrapper of mustach for easier integration
• mustach-wrap.h header file for using mustach-wrap
• mustach-json-c.c tiny json wrapper of mustach using json-c
• mustach-json-c.h header file for using the tiny json-c wrapper
• mustach-cjson.c tiny json wrapper of mustach using cJSON
• mustach-cjson.h header file for using the tiny cJSON wrapper
• mustach-jansson.c tiny json wrapper of mustach using jansson
• mustach-jansson.h header file for using the tiny jansson wrapper
• mustach-tool.c simple tool for applying template files to one JSON file

The file mustach-json-c.c is the historical example of use of mustach and mustach-wrap core and it is also a practical implementation that can be used. It uses the library json-c. (NOTE for Mac OS: available through homebrew).

Since version 1.0, the project also provide integration of other JSON libraries: cJSON and jansson.

If you integrate a new library with mustach, your contribution will be welcome here.

The tool mustach is build using make, its usage is:

mustach json template [template]...

It then outputs the result of applying the templates files to the JSON file.

Portability

Some system does not provide open_memstream. In that case, tell your preferred compiler to declare the preprocessor symbol NO_OPEN_MEMSTREAM. Example:

CFLAGS=-DNO_OPEN_MEMSTREAM make

Integration

The files mustach.h and mustach-wrap.h are the main documentation. Look at it.

The file mustach-json-c.c provides a good example of integration.

If you intend to use basic HTML/XML escaping and standard C FILE, the callbacks of the interface mustach_itf that you have to implement are: enter, next, leave, get.

If you intend to use specific escaping and/or specific output, the callbacks of the interface mustach_itf that you have to implement are: enter, next, leave, get and emit.

Compilation Using Make

Building and installing can be done using make.

Example:

$ make tool=cjson libs=none PREFIX=/usr/local DESTDIR=/ install
$ make tool=jsonc libs=single PREFIX=/ DESTDIR=$HOME/.local install

The makefile knows following switches (*: default):

 Switch name  | Values  | Description
--------------+---------+-----------------------------------------------
 jsonc        | (unset) | Auto detection of json-c
              | no      | Don't compile for json-c
              | yes     | Compile for json-c that must exist
--------------+---------+-----------------------------------------------
 cjson        | (unset) | Auto detection of cJSON
              | no      | Don't compile for cJSON
              | yes     | Compile for cJSON that must exist
--------------+---------+-----------------------------------------------
 jansson      | (unset) | Auto detection of jansson
              | no      | Don't compile for jansson
              | yes     | Compile for jansson that must exist
--------------+---------+-----------------------------------------------
 tool         | (unset) | Auto detection
              | cjson   | Use cjson library
              | jsonc   | Use jsonc library
              | jansson | Use jansson library
              | none    | Don't compile the tool
--------------+---------+----------------------------------------------
 libs         | (unset) | Like 'all'
              | all     | Like 'single' AND 'split'
              | single  | Only libmustach.so
              | split   | All the possible libmustach-XXX.so ...
              | none    | No library is produced

The libraries that can be produced are:

 Library name       | Content
--------------------+--------------------------------------------------------
 libmustach-core    | mustach.c mustach-wrap.c
 libmustach-cjson   | mustach.c mustach-wrap.c mustach-cjson.c
 libmustach-jsonc   | mustach.c mustach-wrap.c mustach-json-c.c
 libmustach-jansson | mustach.c mustach-wrap.c mustach-jansson.c
 libmustach         | mustach.c mustach-wrap.c mustach-{cjson,json-c,jansson}.c

There is no dependencies of a library to an other. This is intended and doesn't hurt today because the code is small.

Extensions

The current implementation provides extensions to specifications of mustache. This extensions can be activated or deactivated using flags.

Here is the summary.

 Flag name                     | Description
-------------------------------+------------------------------------------------
 Mustach_With_Colon            | Explicit tag substitution with colon
 Mustach_With_EmptyTag         | Empty Tag Allowed
-------------------------------+------------------------------------------------
 Mustach_With_Equal            | Value Testing Equality
 Mustach_With_Compare          | Value Comparing
 Mustach_With_JsonPointer      | Interpret JSON Pointers
 Mustach_With_ObjectIter       | Iteration On Objects
 Mustach_With_EscFirstCmp      | Escape First Compare
 Mustach_With_ErrorUndefined   | Error when a requested tag is undefined
-------------------------------+------------------------------------------------
 Mustach_With_AllExtensions    | Activate all known extensions
 Mustach_With_NoExtensions     | Disable any extension

For the details, see below.

Explicit Tag Substitution With Colon (Mustach_With_Colon)

In somecases the name of the key used for substitution begins with a character reserved for mustach: one of #, ^, /, &, {, > and =.

This extension introduces the special character : to explicitly tell mustach to just substitute the value. So : becomes a new special character.

This is a core extension implemented in file mustach.c.

Empty Tag Allowed (Mustach_With_EmptyTag)

When an empty tag is found, instead of automatically raising the error MUSTACH_ERROR_EMPTY_TAG pass it.

This is a core extension implemented in file mustach.c.

Value Testing Equality (Mustach_With_Equal)

This extension allows you to test the value of the selected key. It allows to write key=value (matching test) or key=!value (not matching test) in any query.

This is a wrap extension implemented in file mustach-wrap.c.

Value Comparing (Mustach_With_Compare)

These extension extends the extension for testing equality to also compare values if greater or lesser. Its allows to write key>value (greater), key>=value (greater or equal), key<value (lesser) and key<=value (lesser or equal).

It the comparator sign appears in the first column it is ignored as if it was escaped.

This is a wrap extension implemented in file mustach-wrap.c.

Interpret JSON Pointers (Mustach_With_JsonPointer)

This extension allows to use JSON pointers as defined in IETF RFC 6901. If active, any key starting with "/" is a JSON pointer. This implies to use the colon to introduce JSON keys.

A special escaping is used for =, <, > signs when values comparisons are enabled: ~= gives = in the key.

This is a wrap extension implemented in file mustach-wrap.c.

Iteration On Objects (Mustach_With_ObjectIter)

With this extension, using the pattern {{#X.*}}...{{/X.*}} allows to iterate on fields of X.

Example:

• {{s.*}} {{*}}:{{.}}{{/s.*}} applied on {"s":{"a":1,"b":true}} produces a:1 b:true

Here the single star {{*}} is replaced by the iterated key and the single dot {{.}} is replaced by its value.

This is a wrap extension implemented in file mustach-wrap.c.

Error when a requested tag is undefined (Mustach_With_ErrorUndefined)

Report the error MUSTACH_ERROR_UNDEFINED_TAG when a requested tag is not defined.

This is a wrap extension implemented in file mustach-wrap.c.

Access To Current Value

this was an extension but is now always enforced

The value of the current field can be accessed using single dot.

Examples:

• {{#key}}{{.}}{{/key}} applied to {"key":3.14} produces 3.14
• {{#array}} {{.}}{{/array}} applied to {"array":[1,2]} produces 1 2.

This is a wrap extension implemented in file mustach-wrap.c.

Partial Data First

this was an extension but is now always enforced

The default resolution for partial pattern like {{> name}} is to search for name in the current json context and as a file named name or if not found name.mustache.

By default, the order of the search is (1) as a file, and if not found, (2) in the current json context.

When this option is set, the order is reverted and content of partial is search (1) in the current json context, and if not found, (2) as a file.

That option is useful to keep the compatibility with versions of mustach anteriors to 1.2.0.

This is a wrap extension implemented in file mustach-wrap.c.

Escape First Compare

This extension automatically escapes comparisons appears as first characters.

This is a wrap extension implemented in file mustach-wrap.c.

Difference with version 0.99 and previous

Extensions

The extensions can no more be removed at compile time, use flags to select your required extension on need.

Name of functions

Names of functions were improved. Old names remain but are obsolete and legacy. Their removal in far future versions is possible.

The table below summarize the changes.

 legacy name      | name since version 1.0.0
------------------+-----------------------
 fmustach         | mustach_file
 fdmustach        | mustach_fd
 mustach          | mustach_mem
 fmustach_json_c  | mustach_json_c_file
 fdmustach_json_c | mustach_json_c_fd
 mustach_json_c   | mustach_json_c_mem
 mustach_json_c   | mustach_json_c_write