README.md (12168B)
1 # Introduction to Mustach 1.2 2 3 `mustach` is a C implementation of the [mustache](http://mustache.github.io "main site for mustache") 4 template specification, version 1.4.1, only the mandatory part. 5 6 The main site for `mustach` is on [gitlab](https://gitlab.com/jobol/mustach). 7 8 The simplest way to use mustach is to copy the files **mustach.h** and **mustach.c** 9 directly into your project and use it. 10 11 If you are using one of the JSON libraries listed below, you can get extended feature 12 by also including **mustach-wrap.h**, **mustach-wrap.c**, **mustach-XXX.h** and 13 **mustach-XXX.c** in your project (see below for **XXX**) 14 15 - [json-c](https://github.com/json-c/json-c): use **XXX** = **json-c** 16 - [jansson](http://www.digip.org/jansson/): use **XXX** = **jansson** 17 - [cJSON](https://github.com/DaveGamble/cJSON): use **XXX** = **cjson** 18 19 Alternatively, make and meson files are provided for building `mustach` and 20 `libmustach.so` shared library. 21 22 Since version 1.0, the makefile allows to compile and install different 23 flavours. See below for details. 24 25 ## Distributions offering mustach package 26 27 ### Alpine Linux 28 29 ```sh 30 apk add mustach 31 apk add mustach-lib 32 apk add mustach-dev 33 ``` 34 35 ### NetBSD 36 37 ```sh 38 cd devel/mustach 39 make 40 ``` 41 42 See http://pkgsrc.se/devel/mustach 43 44 ## Known projects using Mustach 45 46 This [wiki page](https://gitlab.com/jobol/mustach/-/wikis/projects-using-mustach) 47 lists the known project that are using mustach and that kindly told it. 48 49 Don't hesitate to tell us if you are interested to be listed there. 50 51 ## Using Mustach from sources 52 53 The file **mustach.h** is the main documentation. Look at it. 54 55 The current source files are: 56 57 - **mustach.c** core implementation of mustache in C 58 - **mustach.h** header file for core definitions 59 - **mustach-wrap.c** generic wrapper of mustach for easier integration 60 - **mustach-wrap.h** header file for using mustach-wrap 61 - **mustach-json-c.c** tiny json wrapper of mustach using [json-c](https://github.com/json-c/json-c) 62 - **mustach-json-c.h** header file for using the tiny json-c wrapper 63 - **mustach-cjson.c** tiny json wrapper of mustach using [cJSON](https://github.com/DaveGamble/cJSON) 64 - **mustach-cjson.h** header file for using the tiny cJSON wrapper 65 - **mustach-jansson.c** tiny json wrapper of mustach using [jansson](https://www.digip.org/jansson/) 66 - **mustach-jansson.h** header file for using the tiny jansson wrapper 67 - **mustach-tool.c** simple tool for applying template files to one JSON file 68 69 The file **mustach-json-c.c** is the historical example of use of **mustach** and 70 **mustach-wrap** core and it is also a practical implementation that can be used. 71 It uses the library json-c. (NOTE for Mac OS: available through homebrew). 72 73 Since version 1.0, the project also provide integration of other JSON libraries: 74 **cJSON** and **jansson**. 75 76 *If you integrate a new library with* **mustach**, *your contribution will be 77 welcome here*. 78 79 The tool **mustach** is build using `make`, its usage is: 80 81 mustach json template [template]... 82 83 It then outputs the result of applying the templates files to the JSON file. 84 85 ### Portability 86 87 Some system does not provide *open_memstream*. In that case, tell your 88 preferred compiler to declare the preprocessor symbol **NO_OPEN_MEMSTREAM**. 89 Example: 90 91 CFLAGS=-DNO_OPEN_MEMSTREAM make 92 93 ### Integration 94 95 The files **mustach.h** and **mustach-wrap.h** are the main documentation. Look at it. 96 97 The file **mustach-json-c.c** provides a good example of integration. 98 99 If you intend to use basic HTML/XML escaping and standard C FILE, the callbacks 100 of the interface **mustach_itf** that you have to implement are: 101 `enter`, `next`, `leave`, `get`. 102 103 If you intend to use specific escaping and/or specific output, the callbacks 104 of the interface **mustach_itf** that you have to implement are: 105 `enter`, `next`, `leave`, `get` and `emit`. 106 107 ### Compilation Using Make 108 109 Building and installing can be done using make. 110 111 Example: 112 113 $ make tool=cjson libs=none PREFIX=/usr/local DESTDIR=/ install 114 $ make tool=jsonc libs=single PREFIX=/ DESTDIR=$HOME/.local install 115 116 The makefile knows following switches (\*: default): 117 118 Switch name | Values | Description 119 --------------+---------+----------------------------------------------- 120 jsonc | (unset) | Auto detection of json-c 121 | no | Don't compile for json-c 122 | yes | Compile for json-c that must exist 123 --------------+---------+----------------------------------------------- 124 cjson | (unset) | Auto detection of cJSON 125 | no | Don't compile for cJSON 126 | yes | Compile for cJSON that must exist 127 --------------+---------+----------------------------------------------- 128 jansson | (unset) | Auto detection of jansson 129 | no | Don't compile for jansson 130 | yes | Compile for jansson that must exist 131 --------------+---------+----------------------------------------------- 132 tool | (unset) | Auto detection 133 | cjson | Use cjson library 134 | jsonc | Use jsonc library 135 | jansson | Use jansson library 136 | none | Don't compile the tool 137 --------------+---------+---------------------------------------------- 138 libs | (unset) | Like 'all' 139 | all | Like 'single' AND 'split' 140 | single | Only libmustach.so 141 | split | All the possible libmustach-XXX.so ... 142 | none | No library is produced 143 144 The libraries that can be produced are: 145 146 Library name | Content 147 --------------------+-------------------------------------------------------- 148 libmustach-core | mustach.c mustach-wrap.c 149 libmustach-cjson | mustach.c mustach-wrap.c mustach-cjson.c 150 libmustach-jsonc | mustach.c mustach-wrap.c mustach-json-c.c 151 libmustach-jansson | mustach.c mustach-wrap.c mustach-jansson.c 152 libmustach | mustach.c mustach-wrap.c mustach-{cjson,json-c,jansson}.c 153 154 There is no dependencies of a library to an other. This is intended and doesn't 155 hurt today because the code is small. 156 157 ### Compilation Using Meson 158 159 Thanks to *qaqland* work, meson build is available. Please refer to **README.meson**. 160 161 ### Testing 162 163 The makefile offers the way to execute basic tests. Just type `make test`. 164 165 By default, if valgrind is available, tests are using it. It can be disabled 166 by typing `make test valgrind=no` or `NOVALGRIND=1 make test`. Conversely, 167 use of valgrind can be enforced by typing `make test valgrind=yes` or 168 `VALGRIND=1 make test`. 169 170 ## Extensions 171 172 The current implementation provides extensions to specifications of **mustache**. 173 This extensions can be activated or deactivated using flags. 174 175 Here is the summary. 176 177 Flag name | Description 178 -------------------------------+------------------------------------------------ 179 Mustach_With_Colon | Explicit tag substitution with colon 180 Mustach_With_EmptyTag | Empty Tag Allowed 181 -------------------------------+------------------------------------------------ 182 Mustach_With_Equal | Value Testing Equality 183 Mustach_With_Compare | Value Comparing 184 Mustach_With_JsonPointer | Interpret JSON Pointers 185 Mustach_With_ObjectIter | Iteration On Objects 186 Mustach_With_EscFirstCmp | Escape First Compare 187 Mustach_With_ErrorUndefined | Error when a requested tag is undefined 188 -------------------------------+------------------------------------------------ 189 Mustach_With_AllExtensions | Activate all known extensions 190 Mustach_With_NoExtensions | Disable any extension 191 192 For the details, see below. 193 194 ### Explicit Tag Substitution With Colon (Mustach_With_Colon) 195 196 In somecases the name of the key used for substitution begins with a 197 character reserved for mustach: one of `#`, `^`, `/`, `&`, `{`, `>` and `=`. 198 199 This extension introduces the special character `:` to explicitly 200 tell mustach to just substitute the value. So `:` becomes a new special 201 character. 202 203 This is a core extension implemented in file **mustach.c**. 204 205 ### Empty Tag Allowed (Mustach_With_EmptyTag) 206 207 When an empty tag is found, instead of automatically raising the error 208 MUSTACH\_ERROR\_EMPTY\_TAG pass it. 209 210 This is a core extension implemented in file **mustach.c**. 211 212 ### Value Testing Equality (Mustach_With_Equal) 213 214 This extension allows you to test the value of the selected key. 215 It allows to write `key=value` (matching test) or `key=!value` 216 (not matching test) in any query. 217 218 This is a wrap extension implemented in file **mustach-wrap.c**. 219 220 ### Value Comparing (Mustach_With_Compare) 221 222 These extension extends the extension for testing equality to also 223 compare values if greater or lesser. 224 Its allows to write `key>value` (greater), `key>=value` (greater or equal), 225 `key<value` (lesser) and `key<=value` (lesser or equal). 226 227 It the comparator sign appears in the first column it is ignored 228 as if it was escaped. 229 230 This is a wrap extension implemented in file **mustach-wrap.c**. 231 232 ### Interpret JSON Pointers (Mustach_With_JsonPointer) 233 234 This extension allows to use JSON pointers as defined in IETF RFC 6901. 235 If active, any key starting with "/" is a JSON pointer. 236 This implies to use the colon to introduce JSON keys. 237 238 A special escaping is used for `=`, `<`, `>` signs when 239 values comparisons are enabled: `~=` gives `=` in the key. 240 241 This is a wrap extension implemented in file **mustach-wrap.c**. 242 243 ### Iteration On Objects (Mustach_With_ObjectIter) 244 245 With this extension, using the pattern `{{#X.*}}...{{/X.*}}` 246 allows to iterate on fields of `X`. 247 248 Example: 249 250 - `{{s.*}} {{*}}:{{.}}{{/s.*}}` applied on `{"s":{"a":1,"b":true}}` produces ` a:1 b:true` 251 252 Here the single star `{{*}}` is replaced by the iterated key 253 and the single dot `{{.}}` is replaced by its value. 254 255 This is a wrap extension implemented in file **mustach-wrap.c**. 256 257 ### Error when a requested tag is undefined (Mustach_With_ErrorUndefined) 258 259 Report the error MUSTACH_ERROR_UNDEFINED_TAG when a requested tag 260 is not defined. 261 262 This is a wrap extension implemented in file **mustach-wrap.c**. 263 264 ### Access To Current Value 265 266 *this was an extension but is now always enforced* 267 268 The value of the current field can be accessed using single dot. 269 270 Examples: 271 272 - `{{#key}}{{.}}{{/key}}` applied to `{"key":3.14}` produces `3.14` 273 - `{{#array}} {{.}}{{/array}}` applied to `{"array":[1,2]}` produces ` 1 2`. 274 275 This is a wrap extension implemented in file **mustach-wrap.c**. 276 277 ### Partial Data First 278 279 *this was an extension but is now always enforced* 280 281 The default resolution for partial pattern like `{{> name}}` 282 is to search for `name` in the current json context and 283 as a file named `name` or if not found `name.mustache`. 284 285 By default, the order of the search is (1) as a file, 286 and if not found, (2) in the current json context. 287 288 When this option is set, the order is reverted and content 289 of partial is search (1) in the current json context, 290 and if not found, (2) as a file. 291 292 That option is useful to keep the compatibility with 293 versions of *mustach* anteriors to 1.2.0. 294 295 This is a wrap extension implemented in file **mustach-wrap.c**. 296 297 ### Escape First Compare 298 299 This extension automatically escapes comparisons appears as 300 first characters. 301 302 This is a wrap extension implemented in file **mustach-wrap.c**. 303 304 ## Difference with version 0.99 and previous 305 306 ### Extensions 307 308 The extensions can no more be removed at compile time, use 309 flags to select your required extension on need. 310 311 ### Name of functions 312 313 Names of functions were improved. Old names remain but are obsolete 314 and legacy. Their removal in far future versions is possible. 315 316 The table below summarize the changes. 317 318 legacy name | name since version 1.0.0 319 ------------------+----------------------- 320 fmustach | mustach_file 321 fdmustach | mustach_fd 322 mustach | mustach_mem 323 fmustach_json_c | mustach_json_c_file 324 fdmustach_json_c | mustach_json_c_fd 325 mustach_json_c | mustach_json_c_mem 326 mustach_json_c | mustach_json_c_write