diff options
Diffstat (limited to 'src/templating/README.md')
-rw-r--r-- | src/templating/README.md | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/src/templating/README.md b/src/templating/README.md new file mode 100644 index 000000000..a6df19f64 --- /dev/null +++ b/src/templating/README.md @@ -0,0 +1,214 @@ +# 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. |