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