215 lines
7.0 KiB
Markdown
215 lines
7.0 KiB
Markdown
# Introduction to Mustach 0.99
|
|
|
|
`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 best way to use mustach is to copy the files **mustach.h** and **mustach.c**
|
|
directly into your project and use it.
|
|
|
|
Alternatively, make and meson files are provided for building `mustach` and
|
|
`libmustach.so` shared library.
|
|
|
|
## 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
|
|
|
|
## 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-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 wrapper
|
|
- **mustach-tool.c** simple tool for applying template files to a JSON file
|
|
|
|
The file **mustach-json-c.c** is the main example of use of **mustach** 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).
|
|
|
|
HELP REQUESTED TO GIVE EXAMPLE BASED ON OTHER LIBRARIES (ex: janson, ...).
|
|
|
|
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:
|
|
|
|
gcc -DNO_OPEN_MEMSTREAM
|
|
|
|
### Integration
|
|
|
|
The file **mustach.h** is 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`.
|
|
|
|
### Extensions
|
|
|
|
By default, the current implementation provides the following extensions:
|
|
|
|
#### Explicit Substitution
|
|
|
|
This is a core extension implemented in file **mustach.c**.
|
|
|
|
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.
|
|
|
|
#### Value Testing and Comparing
|
|
|
|
This are a tool extension implemented in file **mustach-json-c.c**.
|
|
|
|
These extensions allows you to test the value of the selected key.
|
|
They allow to write `key=value` (matching test) or `key=!value`
|
|
(not matching test) in any query.
|
|
|
|
The specific comparison extension also allows to compare if greater,
|
|
lesser, etc.. than a value. It allows to write `key>value`.
|
|
|
|
It the comparator sign appears in the first column it is ignored
|
|
as if it was escaped.
|
|
|
|
#### Access to current value
|
|
|
|
The value of the current field can be accessed using single dot like
|
|
in `{{#key}}{{.}}{{/key}}` that applied to `{"key":3.14}` produces `3.14`
|
|
and `{{#array}} {{.}}{{/array}}` applied to `{"array":[1,2]}` produces
|
|
` 1 2`.
|
|
|
|
#### Iteration on objects
|
|
|
|
Using the pattern `{{#X.*}}...{{/X.*}}` it is possible 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.
|
|
|
|
### Removing Extensions
|
|
|
|
When compiling mustach.c or mustach-json-c.c,
|
|
extensions can be removed by defining macros
|
|
using option -D.
|
|
|
|
The possible macros are of 3 categories, the global,
|
|
the mustach core specific and the mustach-json-c example
|
|
of implementation specific.
|
|
|
|
#### Global macros
|
|
|
|
- `NO_EXTENSION_FOR_MUSTACH`
|
|
|
|
This macro disables any current or future
|
|
extensions for the core or the example.
|
|
|
|
#### Macros for the core mustach engine (mustach.c)
|
|
|
|
- `NO_COLON_EXTENSION_FOR_MUSTACH`
|
|
|
|
This macro remove the ability to use colon (:)
|
|
as explicit command for variable substitution.
|
|
This extension allows to have name starting
|
|
with one of the mustach character `:#^/&{=>`
|
|
|
|
- `NO_ALLOW_EMPTY_TAG`
|
|
|
|
Generate the error MUSTACH_ERROR_EMPTY_TAG automatically
|
|
when an empty tag is encountered.
|
|
|
|
#### Macros for the implementation example (mustach-json-c.c)
|
|
|
|
- `NO_EQUAL_VALUE_EXTENSION_FOR_MUSTACH`
|
|
|
|
This macro allows the program to check whether
|
|
the actual value is equal to an expected value.
|
|
This is useful in `{{#key=val}}` or `{{^key=val}}`
|
|
with the corresponding `{{/key=val}}`.
|
|
It can also be used in `{{key=val}}` but this
|
|
doesn't seem to be useful.
|
|
|
|
- `NO_COMPARE_VALUE_EXTENSION_FOR_MUSTACH`
|
|
|
|
This macro allows the program to compare the actual
|
|
value with an expected value. The comparison operators
|
|
are `=`, `>`, `<`, `>=`, `<=`. The meaning of the
|
|
comparison numeric or alphabetic depends on the type
|
|
of the inspected value. Also the result of the comparison
|
|
can be inverted if the value starts with `!`.
|
|
Example of use: `{{key>=val}}`, or `{{#key>=val}}` and
|
|
`{{^key>=val}}` with their matching `{{/key>=val}}`.
|
|
|
|
- `NO_USE_VALUE_ESCAPE_FIRST_EXTENSION_FOR_MUSTACH`
|
|
|
|
This macro fordids automatic escaping of coparison
|
|
sign appearing at first column.
|
|
|
|
- `NO_JSON_POINTER_EXTENSION_FOR_MUSTACH`
|
|
|
|
This macro removes the possible use of JSON pointers.
|
|
JSON pointers are defined in IETF RFC 6901.
|
|
If not set, any key starting with "/" is a JSON pointer.
|
|
This implies to use the colon to introduce keys.
|
|
So `NO_COLON_EXTENSION_FOR_MUSTACH` implies
|
|
`NO_JSON_POINTER_EXTENSION_FOR_MUSTACH`.
|
|
A special escaping is used for `=`, `<`, `>` signs when
|
|
values comparisons are enabled: `~=` gives `=` in the key.
|
|
|
|
- `NO_OBJECT_ITERATION_FOR_MUSTACH`
|
|
|
|
Disable the object iteration extension. That extension allows
|
|
to iterate over the keys of an object. The iteration on object
|
|
is selected by using the selector `{{#key.*}}`. In the context
|
|
of iterating over object keys, the single key `{{*}}` returns the
|
|
key and `{{.}}` returns the value.
|
|
|
|
- `NO_SINGLE_DOT_EXTENSION_FOR_MUSTACH`
|
|
|
|
Disable access to current object value using single dot
|
|
like in `{{.}}`.
|
|
|
|
- `NO_INCLUDE_PARTIAL_FALLBACK`
|
|
|
|
Disable include of file by partial pattern like `{{> name}}`.
|
|
By default if a such pattern is found, **mustach** search
|
|
for `name` in the current json context. This what is done
|
|
historically and when `NO_INCLUDE_PARTIAL_FALLBACK` is defined.
|
|
When `NO_INCLUDE_PARTIAL_FALLBACK` is defined, if the value is
|
|
found in the json context, the files `name` and `name.mustache`
|
|
are searched in that order and the first file found is used
|
|
as partial content. The macro `INCLUDE_PARTIAL_EXTENSION` can
|
|
be use for changing the extension added.
|