# Introduction to Mustach 1.2 `mustach` is a C implementation of the [mustache](http://mustache.github.io "main site for mustache") template specification. The main site for `mustach` is on [gitlab](https://gitlab.com/jobol/mustach). 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](https://github.com/json-c/json-c): use **XXX** = **json-c** - [jansson](http://www.digip.org/jansson/): use **XXX** = **jansson** - [cJSON](https://github.com/DaveGamble/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 ```sh apk add mustach apk add mustach-lib apk add mustach-dev ``` ### NetBSD ```sh cd devel/mustach make ``` See http://pkgsrc.se/devel/mustach ## Known projects using Mustach This [wiki page](https://gitlab.com/jobol/mustach/-/wikis/projects-using-mustach) 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](https://github.com/json-c/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](https://github.com/DaveGamble/cJSON) - **mustach-cjson.h** header file for using the tiny cJSON wrapper - **mustach-jansson.c** tiny json wrapper of mustach using [jansson](https://www.digip.org/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. ### Testing The makefile offers the way to execute basic tests. Just type `make test`. By default, if valgrind is available, tests are using it. It can be disabled by typing `make test valgrind=no` or `NOVALGRIND=1 make test`. ## 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` 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