README.md 3.36 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

The file **mustach-json-c.c** is the main example of use of **mustach** core
20 21 22 23
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, ...).
josé bollo's avatar
josé bollo committed
24

Atlas's avatar
Atlas committed
25
The tool **mustach** is build using `make`,  its usage is:
josé bollo's avatar
josé bollo committed
26 27 28

    mustach json template [template]...

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

31 32 33 34 35 36 37 38 39
Portability
===========

Some system does not provide *open_memstream*. In that case, tell your
prefered compiler to declare the preprocessor symbol **NO_OPEN_MEMSTREAM**.
Example:

	gcc -DNO_OPEN_MEMSTREAM

40 41 42
Extensions
==========

Atlas's avatar
Atlas committed
43
By default, the current implementation provides the following extensions:
44

Atlas's avatar
Atlas committed
45
Explicit Substitution
46 47 48 49 50 51
---------------------

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
52
This extension introduces the special character ':' to explicitly
53
tell mustach to just substitute the value. So ':' becomes a new special
Atlas's avatar
Atlas committed
54
character.
55

Atlas's avatar
Atlas committed
56 57
Value Testing
-------------
58 59 60

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

Atlas's avatar
Atlas committed
61
This extension allows you to test the value of the selected key.
62 63 64
It is allowed to write key=value (matching test) or key=!value
(not matching test) in any query.

Atlas's avatar
Atlas committed
65
Removing Extensions
66 67 68 69 70 71 72 73
-------------------

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
74
- `NO_COLON_EXTENSION_FOR_MUSTACH`
75 76 77 78 79 80

  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
81
- `NO_EQUAL_VALUE_EXTENSION_FOR_MUSTACH`
82

Atlas's avatar
Atlas committed
83
  This macro allows the program to check the whether
84
  the actual value is equal to an expected value.
Atlas's avatar
Atlas committed
85 86 87
  This is useful in `{{#key=val}}` or `{{^key=val}}`
  with the corresponding `{{/key=val}}`.
  It can also be used in `{{key=val}}` but this
88 89
  doesn't seem to be useful.

Atlas's avatar
Atlas committed
90
- `NO_JSON_POINTER_EXTENSION_FOR_MUSTACH`
91 92

  This macro removes the possible use of JSON pointers.
Atlas's avatar
Atlas committed
93 94
  JSON pointers are defined in IETF RFC 6901.
  If not set, any key starting with "/" is a JSON pointer.
95
  This implies to use the colon to introduce keys.
Atlas's avatar
Atlas committed
96 97 98 99
  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.
100

Atlas's avatar
Atlas committed
101
- `NO_EXTENSION_FOR_MUSTACH`
102

Atlas's avatar
Atlas committed
103 104
  This macro disables any current or future
  extensions.
josé bollo's avatar
josé bollo committed
105