aboutsummaryrefslogtreecommitdiff
path: root/src/templating/README.md
blob: 7034ef99f43c156044046d9bbaa2d9a15e6770d0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
# Introduction to Mustach 1.2

`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 simplest way to use mustach is to copy the files **mustach.h** and **mustach.c**
directly into your project and use it.

If you are using one of the JSON libraries listed below, you can get extended feature
by also including **mustach-wrap.h**, **mustach-wrap.c**, **mustach-XXX.h** and
**mustach-XXX.c** in your project (see below for **XXX**)

- [json-c](https://github.com/json-c/json-c): use **XXX** = **json-c**
- [jansson](http://www.digip.org/jansson/): use **XXX** = **jansson**
- [cJSON](https://github.com/DaveGamble/cJSON): use **XXX** = **cjson**

Alternatively, make and meson files are provided for building `mustach` and
`libmustach.so` shared library.

Since version 1.0, the makefile allows to compile and install different
flavours. See below for details.

## 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

## Known projects using Mustach

This [wiki page](https://gitlab.com/jobol/mustach/-/wikis/projects-using-mustach)
lists the known project that are using mustach and that kindly told it.

Don't hesitate to tell us if you are interested to be listed there.

## 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-wrap.c** generic wrapper of mustach for easier integration
- **mustach-wrap.h** header file for using mustach-wrap
- **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-c wrapper
- **mustach-cjson.c** tiny json wrapper of mustach using [cJSON](https://github.com/DaveGamble/cJSON)
- **mustach-cjson.h** header file for using the tiny cJSON wrapper
- **mustach-jansson.c** tiny json wrapper of mustach using [jansson](https://www.digip.org/jansson/)
- **mustach-jansson.h** header file for using the tiny jansson wrapper
- **mustach-tool.c** simple tool for applying template files to one JSON file

The file **mustach-json-c.c** is the historical example of use of **mustach** and
**mustach-wrap** 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).

Since version 1.0, the project also provide integration of other JSON libraries:
**cJSON** and **jansson**.

*If you integrate a new library with* **mustach**, *your contribution will be
welcome here*.

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:

	CFLAGS=-DNO_OPEN_MEMSTREAM make

### Integration

The files **mustach.h** and **mustach-wrap.h** are 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`.

### Compilation Using Make

Building and installing can be done using make.

Example:

    $ make tool=cjson libs=none PREFIX=/usr/local DESTDIR=/ install
    $ make tool=jsonc libs=single PREFIX=/ DESTDIR=$HOME/.local install

The makefile knows following switches (\*: default):

     Switch name  | Values  | Description
    --------------+---------+-----------------------------------------------
     jsonc        | (unset) | Auto detection of json-c
                  | no      | Don't compile for json-c
                  | yes     | Compile for json-c that must exist
    --------------+---------+-----------------------------------------------
     cjson        | (unset) | Auto detection of cJSON
                  | no      | Don't compile for cJSON
                  | yes     | Compile for cJSON that must exist
    --------------+---------+-----------------------------------------------
     jansson      | (unset) | Auto detection of jansson
                  | no      | Don't compile for jansson
                  | yes     | Compile for jansson that must exist
    --------------+---------+-----------------------------------------------
     tool         | (unset) | Auto detection
                  | cjson   | Use cjson library
                  | jsonc   | Use jsonc library
                  | jansson | Use jansson library
                  | none    | Don't compile the tool
    --------------+---------+----------------------------------------------
     libs         | (unset) | Like 'all'
                  | all     | Like 'single' AND 'split'
                  | single  | Only libmustach.so
                  | split   | All the possible libmustach-XXX.so ...
                  | none    | No library is produced

The libraries that can be produced are:

     Library name       | Content
    --------------------+--------------------------------------------------------
     libmustach-core    | mustach.c mustach-wrap.c
     libmustach-cjson   | mustach.c mustach-wrap.c mustach-cjson.c
     libmustach-jsonc   | mustach.c mustach-wrap.c mustach-json-c.c
     libmustach-jansson | mustach.c mustach-wrap.c mustach-jansson.c
     libmustach         | mustach.c mustach-wrap.c mustach-{cjson,json-c,jansson}.c

There is no dependencies of a library to an other. This is intended and doesn't
hurt today because the code is small.

## Extensions

The current implementation provides extensions to specifications of **mustache**.
This extensions can be activated or deactivated using flags.

Here is the summary.

     Flag name                     | Description
    -------------------------------+------------------------------------------------
     Mustach_With_Colon            | Explicit tag substitution with colon
     Mustach_With_EmptyTag         | Empty Tag Allowed
    -------------------------------+------------------------------------------------
     Mustach_With_Equal            | Value Testing Equality
     Mustach_With_Compare          | Value Comparing
     Mustach_With_JsonPointer      | Interpret JSON Pointers
     Mustach_With_ObjectIter       | Iteration On Objects
     Mustach_With_EscFirstCmp      | Escape First Compare
     Mustach_With_ErrorUndefined   | Error when a requested tag is undefined
    -------------------------------+------------------------------------------------
     Mustach_With_AllExtensions    | Activate all known extensions
     Mustach_With_NoExtensions     | Disable any extension

For the details, see below.

### Explicit Tag Substitution With Colon (Mustach_With_Colon)

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.

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

### Empty Tag Allowed (Mustach_With_EmptyTag)

When an empty tag is found, instead of automatically raising the error
MUSTACH\_ERROR\_EMPTY\_TAG pass it.

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

### Value Testing Equality (Mustach_With_Equal)

This extension allows you to test the value of the selected key.
It allows to write `key=value` (matching test) or `key=!value`
(not matching test) in any query.

This is a wrap extension implemented in file **mustach-wrap.c**.

### Value Comparing (Mustach_With_Compare)

These extension extends the extension for testing equality to also
compare values if greater or lesser.
Its allows to write `key>value` (greater), `key>=value` (greater or equal),
`key<value` (lesser) and `key<=value` (lesser or equal).

It the comparator sign appears in the first column it is ignored
as if it was escaped.

This is a wrap extension implemented in file **mustach-wrap.c**.

### Interpret JSON Pointers (Mustach_With_JsonPointer)

This extension allows to use JSON pointers as defined in IETF RFC 6901.
If active, any key starting with "/" is a JSON pointer.
This implies to use the colon to introduce JSON keys.

A special escaping is used for `=`, `<`, `>` signs when
values comparisons are enabled: `~=` gives `=` in the key.

This is a wrap extension implemented in file **mustach-wrap.c**.

### Iteration On Objects (Mustach_With_ObjectIter)

With this extension, using the pattern `{{#X.*}}...{{/X.*}}`
allows 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.

This is a wrap extension implemented in file **mustach-wrap.c**.

### Error when a requested tag is undefined (Mustach_With_ErrorUndefined)

Report the error MUSTACH_ERROR_UNDEFINED_TAG when a requested tag
is not defined.

This is a wrap extension implemented in file **mustach-wrap.c**.

### Access To Current Value

*this was an extension but is now always enforced*

The value of the current field can be accessed using single dot.

Examples:

- `{{#key}}{{.}}{{/key}}` applied to `{"key":3.14}` produces `3.14`
- `{{#array}} {{.}}{{/array}}` applied to `{"array":[1,2]}` produces ` 1 2`.

This is a wrap extension implemented in file **mustach-wrap.c**.

### Partial Data First

*this was an extension but is now always enforced*

The default resolution for partial pattern like `{{> name}}`
is to search for `name` in the current json context and
as a file named `name` or if not found `name.mustache`.

By default, the order of the search is (1) as a file,
and if not found, (2) in the current json context.

When this option is set, the order is reverted and content
of partial is search (1) in the current json context,
and if not found, (2) as a file.

That option is useful to keep the compatibility with
versions of *mustach* anteriors to 1.2.0.

This is a wrap extension implemented in file **mustach-wrap.c**.

### Escape First Compare

This extension automatically escapes comparisons appears as
first characters.

This is a wrap extension implemented in file **mustach-wrap.c**.

## Difference with version 0.99 and previous

### Extensions

The extensions can no more be removed at compile time, use
flags to select your required extension on need.

### Name of functions

Names of functions were improved. Old names remain but are obsolete
and legacy. Their removal in far future versions is possible.

The table below summarize the changes.

     legacy name      | name since version 1.0.0
    ------------------+-----------------------
     fmustach         | mustach_file
     fdmustach        | mustach_fd
     mustach          | mustach_mem
     fmustach_json_c  | mustach_json_c_file
     fdmustach_json_c | mustach_json_c_fd
     mustach_json_c   | mustach_json_c_mem
     mustach_json_c   | mustach_json_c_write