README.md (11906B)
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. 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 ### Testing 158 159 The makefile offers the way to execute basic tests. Just type `make test`. 160 161 By default, if valgrind is available, tests are using it. It can be disabled 162 by typing `make test valgrind=no` or `NOVALGRIND=1 make test`. 163 164 ## Extensions 165 166 The current implementation provides extensions to specifications of **mustache**. 167 This extensions can be activated or deactivated using flags. 168 169 Here is the summary. 170 171 Flag name | Description 172 -------------------------------+------------------------------------------------ 173 Mustach_With_Colon | Explicit tag substitution with colon 174 Mustach_With_EmptyTag | Empty Tag Allowed 175 -------------------------------+------------------------------------------------ 176 Mustach_With_Equal | Value Testing Equality 177 Mustach_With_Compare | Value Comparing 178 Mustach_With_JsonPointer | Interpret JSON Pointers 179 Mustach_With_ObjectIter | Iteration On Objects 180 Mustach_With_EscFirstCmp | Escape First Compare 181 Mustach_With_ErrorUndefined | Error when a requested tag is undefined 182 -------------------------------+------------------------------------------------ 183 Mustach_With_AllExtensions | Activate all known extensions 184 Mustach_With_NoExtensions | Disable any extension 185 186 For the details, see below. 187 188 ### Explicit Tag Substitution With Colon (Mustach_With_Colon) 189 190 In somecases the name of the key used for substitution begins with a 191 character reserved for mustach: one of `#`, `^`, `/`, `&`, `{`, `>` and `=`. 192 193 This extension introduces the special character `:` to explicitly 194 tell mustach to just substitute the value. So `:` becomes a new special 195 character. 196 197 This is a core extension implemented in file **mustach.c**. 198 199 ### Empty Tag Allowed (Mustach_With_EmptyTag) 200 201 When an empty tag is found, instead of automatically raising the error 202 MUSTACH\_ERROR\_EMPTY\_TAG pass it. 203 204 This is a core extension implemented in file **mustach.c**. 205 206 ### Value Testing Equality (Mustach_With_Equal) 207 208 This extension allows you to test the value of the selected key. 209 It allows to write `key=value` (matching test) or `key=!value` 210 (not matching test) in any query. 211 212 This is a wrap extension implemented in file **mustach-wrap.c**. 213 214 ### Value Comparing (Mustach_With_Compare) 215 216 These extension extends the extension for testing equality to also 217 compare values if greater or lesser. 218 Its allows to write `key>value` (greater), `key>=value` (greater or equal), 219 `key<value` (lesser) and `key<=value` (lesser or equal). 220 221 It the comparator sign appears in the first column it is ignored 222 as if it was escaped. 223 224 This is a wrap extension implemented in file **mustach-wrap.c**. 225 226 ### Interpret JSON Pointers (Mustach_With_JsonPointer) 227 228 This extension allows to use JSON pointers as defined in IETF RFC 6901. 229 If active, any key starting with "/" is a JSON pointer. 230 This implies to use the colon to introduce JSON keys. 231 232 A special escaping is used for `=`, `<`, `>` signs when 233 values comparisons are enabled: `~=` gives `=` in the key. 234 235 This is a wrap extension implemented in file **mustach-wrap.c**. 236 237 ### Iteration On Objects (Mustach_With_ObjectIter) 238 239 With this extension, using the pattern `{{#X.*}}...{{/X.*}}` 240 allows to iterate on fields of `X`. 241 242 Example: 243 244 - `{{s.*}} {{*}}:{{.}}{{/s.*}}` applied on `{"s":{"a":1,"b":true}}` produces ` a:1 b:true` 245 246 Here the single star `{{*}}` is replaced by the iterated key 247 and the single dot `{{.}}` is replaced by its value. 248 249 This is a wrap extension implemented in file **mustach-wrap.c**. 250 251 ### Error when a requested tag is undefined (Mustach_With_ErrorUndefined) 252 253 Report the error MUSTACH_ERROR_UNDEFINED_TAG when a requested tag 254 is not defined. 255 256 This is a wrap extension implemented in file **mustach-wrap.c**. 257 258 ### Access To Current Value 259 260 *this was an extension but is now always enforced* 261 262 The value of the current field can be accessed using single dot. 263 264 Examples: 265 266 - `{{#key}}{{.}}{{/key}}` applied to `{"key":3.14}` produces `3.14` 267 - `{{#array}} {{.}}{{/array}}` applied to `{"array":[1,2]}` produces ` 1 2`. 268 269 This is a wrap extension implemented in file **mustach-wrap.c**. 270 271 ### Partial Data First 272 273 *this was an extension but is now always enforced* 274 275 The default resolution for partial pattern like `{{> name}}` 276 is to search for `name` in the current json context and 277 as a file named `name` or if not found `name.mustache`. 278 279 By default, the order of the search is (1) as a file, 280 and if not found, (2) in the current json context. 281 282 When this option is set, the order is reverted and content 283 of partial is search (1) in the current json context, 284 and if not found, (2) as a file. 285 286 That option is useful to keep the compatibility with 287 versions of *mustach* anteriors to 1.2.0. 288 289 This is a wrap extension implemented in file **mustach-wrap.c**. 290 291 ### Escape First Compare 292 293 This extension automatically escapes comparisons appears as 294 first characters. 295 296 This is a wrap extension implemented in file **mustach-wrap.c**. 297 298 ## Difference with version 0.99 and previous 299 300 ### Extensions 301 302 The extensions can no more be removed at compile time, use 303 flags to select your required extension on need. 304 305 ### Name of functions 306 307 Names of functions were improved. Old names remain but are obsolete 308 and legacy. Their removal in far future versions is possible. 309 310 The table below summarize the changes. 311 312 legacy name | name since version 1.0.0 313 ------------------+----------------------- 314 fmustach | mustach_file 315 fdmustach | mustach_fd 316 mustach | mustach_mem 317 fmustach_json_c | mustach_json_c_file 318 fdmustach_json_c | mustach_json_c_fd 319 mustach_json_c | mustach_json_c_mem 320 mustach_json_c | mustach_json_c_write