README.md 3.01 KB
Newer Older
Atlas's avatar
Atlas committed
1
Introduction to Mustach
josé bollo's avatar
josé bollo committed
2 3
=======================

Atlas's avatar
Atlas committed
4
`mustach` is a C implementation of the [mustache](http://mustache.github.io "main site for mustache") template library.
josé bollo's avatar
josé bollo committed
5

Atlas's avatar
Atlas committed
6
The main site for `mustach` is on [gitlab](https://gitlab.com/jobol/mustach).
josé bollo's avatar
josé bollo committed
7 8

The best way to use mustach is to copy the files **mustach.h** and **mustach.c**
Atlas's avatar
Atlas committed
9
directly into your project and use it.
josé bollo's avatar
josé bollo committed
10 11 12 13 14 15

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)
Atlas's avatar
Atlas committed
16 17
- **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
josé bollo's avatar
josé bollo committed
18 19 20 21

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.

Atlas's avatar
Atlas committed
22
The tool **mustach** is build using `make`,  its usage is:
josé bollo's avatar
josé bollo committed
23 24 25

    mustach json template [template]...

Atlas's avatar
Atlas committed
26
It then outputs the result of applying the templates files to the JSON file.
josé bollo's avatar
josé bollo committed
27

28 29 30
Extensions
==========

Atlas's avatar
Atlas committed
31
By default, the current implementation provides the following extensions:
32

Atlas's avatar
Atlas committed
33
Explicit Substitution
34 35 36 37 38 39
---------------------

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

In somecases the name of the key used for substition begins with a
character reserved for mustach: one of '#', '^', '/', '&', '{', '>' and '='.
Atlas's avatar
Atlas committed
40
This extension introduces the special character ':' to explicitly
41
tell mustach to just substitute the value. So ':' becomes a new special
Atlas's avatar
Atlas committed
42
character.
43

Atlas's avatar
Atlas committed
44 45
Value Testing
-------------
46 47 48

This is a tool extension implmented in file **mustach-json-c.c**.

Atlas's avatar
Atlas committed
49
This extension allows you to test the value of the selected key.
50 51 52
It is allowed to write key=value (matching test) or key=!value
(not matching test) in any query.

Atlas's avatar
Atlas committed
53
Removing Extensions
54 55 56 57 58 59 60 61
-------------------

When compiling mustach.c or mustach-json-c.c,
extensions can be removed by defining macros
using option -D.

The possible macros are:

Atlas's avatar
Atlas committed
62
- `NO_COLON_EXTENSION_FOR_MUSTACH`
63 64 65 66 67 68

  This macro remove the ability to use colon (:)
  as explicit command for variable substituion.
  This extension allows to have name starting
  with one of the mustach character :#^/&{=<

Atlas's avatar
Atlas committed
69
- `NO_EQUAL_VALUE_EXTENSION_FOR_MUSTACH`
70

Atlas's avatar
Atlas committed
71
  This macro allows the program to check the whether
72
  the actual value is equal to an expected value.
Atlas's avatar
Atlas committed
73 74 75
  This is useful in `{{#key=val}}` or `{{^key=val}}`
  with the corresponding `{{/key=val}}`.
  It can also be used in `{{key=val}}` but this
76 77
  doesn't seem to be useful.

Atlas's avatar
Atlas committed
78
- `NO_JSON_POINTER_EXTENSION_FOR_MUSTACH`
79 80

  This macro removes the possible use of JSON pointers.
Atlas's avatar
Atlas committed
81 82
  JSON pointers are defined in IETF RFC 6901.
  If not set, any key starting with "/" is a JSON pointer.
83
  This implies to use the colon to introduce keys.
Atlas's avatar
Atlas committed
84 85 86 87
  So `NO_COLON_EXTENSION_FOR_MUSTACH` implies
  `NO_JSON_POINTER_EXTENSION_FOR_MUSTACH`.
  A special escaping is used for "=" signs when
  values comparison is enabled: "~=" leaves "=" in the key.
88

Atlas's avatar
Atlas committed
89
- `NO_EXTENSION_FOR_MUSTACH`
90

Atlas's avatar
Atlas committed
91 92
  This macro disables any current or future
  extensions.
josé bollo's avatar
josé bollo committed
93