github.com/wynshop-open-source/gomplate@v3.5.0+incompatible/docs-src/content/functions/data.yml (about) 1 ns: data 2 preamble: | 3 A collection of functions that retrieve, parse, and convert structured data. 4 funcs: 5 - name: datasource 6 alias: ds 7 description: | 8 Parses a given datasource (provided by the [`--datasource/-d`](#--datasource-d) argument or [`defineDatasource`](#definedatasource)). 9 10 If the `alias` is undefined, but is a valid URL, `datasource` will dynamically read from that URL. 11 12 See [Datasources](../../datasources) for (much!) more information. 13 pipeline: false 14 arguments: 15 - name: alias 16 required: true 17 description: the datasource alias (or a URL for dynamic use) 18 - name: subpath 19 required: false 20 description: the subpath to use, if supported by the datasource 21 rawExamples: 22 - | 23 _`person.json`:_ 24 ```json 25 { "name": "Dave" } 26 ``` 27 28 ```console 29 $ gomplate -d person.json -i 'Hello {{ (datasource "person").name }}' 30 Hello Dave 31 ``` 32 - name: datasourceExists 33 description: | 34 Tests whether or not a given datasource was defined on the commandline (with the 35 [`--datasource/-d`](#--datasource-d) argument). This is intended mainly to allow 36 a template to be rendered differently whether or not a given datasource was 37 defined. 38 39 Note: this does _not_ verify if the datasource is reachable. 40 41 Useful when used in an `if`/`else` block. 42 pipeline: false 43 arguments: 44 - name: alias 45 required: true 46 description: the datasource alias 47 examples: 48 - | 49 $ echo '{{if (datasourceExists "test")}}{{datasource "test"}}{{else}}no worries{{end}}' | gomplate 50 no worries 51 - name: datasourceReachable 52 description: | 53 Tests whether or not a given datasource is defined and reachable, where the definition of "reachable" differs by datasource, but generally means the data is able to be read successfully. 54 55 Useful when used in an `if`/`else` block. 56 pipeline: false 57 arguments: 58 - name: alias 59 required: true 60 description: the datasource alias 61 examples: 62 - | 63 $ gomplate -i '{{if (datasourceReachable "test")}}{{datasource "test"}}{{else}}no worries{{end}}' -d test=https://bogus.example.com/wontwork.json 64 no worries 65 - name: defineDatasource 66 description: | 67 Define a datasource alias with target URL inside the template. Overridden by the [`--datasource/-d`](#--datasource-d) flag. 68 69 Note: once a datasource is defined, it can not be redefined (i.e. if this function is called twice with the same alias, only the first applies). 70 71 This function can provide a good way to set a default datasource when sharing templates. 72 73 See [Datasources](../../datasources) for (much!) more information. 74 pipeline: false 75 arguments: 76 - name: alias 77 required: true 78 description: the datasource alias 79 - name: url 80 required: true 81 description: the datasource's URL 82 rawExamples: 83 - | 84 _`person.json`:_ 85 ```json 86 { "name": "Dave" } 87 ``` 88 89 ```console 90 $ gomplate -i '{{ defineDatasource "person" "person.json" }}Hello {{ (ds "person").name }}' 91 Hello Dave 92 $ FOO='{"name": "Daisy"}' gomplate -d person=env:///FOO -i '{{ defineDatasource "person" "person.json" }}Hello {{ (ds "person").name }}' 93 Hello Daisy 94 ``` 95 - name: include 96 description: | 97 Includes the content of a given datasource (provided by the [`--datasource/-d`](../usage/#datasource-d) argument). 98 99 This is similar to [`datasource`](#datasource), except that the data is not parsed. There is no restriction on the type of data included, except that it should be textual. 100 pipeline: false 101 arguments: 102 - name: alias 103 required: true 104 description: the datasource alias, as provided by [`--datasource/-d`](../usage/#datasource-d) 105 - name: subpath 106 required: false 107 description: the subpath to use, if supported by the datasource 108 rawExamples: 109 - | 110 _`person.json`:_ 111 ```json 112 { "name": "Dave" } 113 ``` 114 115 _`input.tmpl`:_ 116 ```go 117 { 118 "people": [ 119 {{ include "person" }} 120 ] 121 } 122 ``` 123 124 ```console 125 $ gomplate -d person.json -f input.tmpl 126 { 127 "people": [ 128 { "name": "Dave" } 129 ] 130 } 131 ``` 132 - name: data.JSON 133 alias: json 134 description: | 135 Converts a JSON string into an object. Only works for JSON Objects (not Arrays or other valid JSON types). This can be used to access properties of JSON objects. 136 137 #### Encrypted JSON support (EJSON) 138 139 If the input is in the [EJSON](https://github.com/Shopify/ejson) format (i.e. has a `_public_key` field), this function will attempt to decrypt the document first. A private key must be provided by one of these methods: 140 141 - set the `EJSON_KEY` environment variable to the private key's value 142 - set the `EJSON_KEY_FILE` environment variable to the path to a file containing the private key 143 - set the `EJSON_KEYDIR` environment variable to the path to a directory containing private keys (filename must be the public key), just like [`ejson decrypt`'s `--keydir`](https://github.com/Shopify/ejson/blob/master/man/man1/ejson.1.ronn) flag. Defaults to `/opt/ejson/keys`. 144 pipeline: true 145 arguments: 146 - name: in 147 required: true 148 description: the input string 149 rawExamples: 150 - | 151 _`input.tmpl`:_ 152 ``` 153 Hello {{ (getenv "FOO" | json).hello }} 154 ``` 155 156 ```console 157 $ export FOO='{"hello":"world"}' 158 $ gomplate < input.tmpl 159 Hello world 160 ``` 161 - name: data.JSONArray 162 alias: jsonArray 163 description: | 164 Converts a JSON string into a slice. Only works for JSON Arrays. 165 pipeline: true 166 arguments: 167 - name: in 168 required: true 169 description: the input string 170 rawExamples: 171 - | 172 _`input.tmpl`:_ 173 ``` 174 Hello {{ index (getenv "FOO" | jsonArray) 1 }} 175 ``` 176 177 ```console 178 $ export FOO='[ "you", "world" ]' 179 $ gomplate < input.tmpl 180 Hello world 181 ``` 182 - name: data.YAML 183 alias: yaml 184 description: | 185 Converts a YAML string into an object. Only works for YAML Objects (not Arrays or other valid YAML types). This can be used to access properties of YAML objects. 186 pipeline: true 187 arguments: 188 - name: in 189 required: true 190 description: the input string 191 rawExamples: 192 - | 193 _`input.tmpl`:_ 194 ``` 195 Hello {{ (getenv "FOO" | yaml).hello }} 196 ``` 197 198 ```console 199 $ export FOO='hello: world' 200 $ gomplate < input.tmpl 201 Hello world 202 ``` 203 - name: data.YAMLArray 204 alias: yamlArray 205 description: | 206 Converts a YAML string into a slice. Only works for YAML Arrays. 207 pipeline: true 208 arguments: 209 - name: in 210 required: true 211 description: the input string 212 rawExamples: 213 - | 214 _`input.tmpl`:_ 215 ``` 216 Hello {{ index (getenv "FOO" | yamlArray) 1 }} 217 ``` 218 219 ```console 220 $ export FOO='[ "you", "world" ]' 221 $ gomplate < input.tmpl 222 Hello world 223 ``` 224 - name: data.TOML 225 alias: toml 226 description: | 227 Converts a [TOML](https://github.com/toml-lang/toml) document into an object. 228 This can be used to access properties of TOML documents. 229 230 Compatible with [TOML v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md). 231 pipeline: true 232 arguments: 233 - name: input 234 required: true 235 description: the TOML document to parse 236 rawExamples: 237 - | 238 _`input.tmpl`:_ 239 ``` 240 {{ $t := `[data] 241 hello = "world"` -}} 242 Hello {{ (toml $t).hello }} 243 ``` 244 245 ```console 246 $ gomplate -f input.tmpl 247 Hello world 248 ``` 249 - name: data.CSV 250 alias: csv 251 description: | 252 Converts a CSV-format string into a 2-dimensional string array. 253 254 By default, the [RFC 4180](https://tools.ietf.org/html/rfc4180) format is 255 supported, but any single-character delimiter can be specified. 256 pipeline: true 257 arguments: 258 - name: delim 259 required: false 260 description: the (single-character!) field delimiter, defaults to `","` 261 - name: input 262 required: true 263 description: the CSV-format string to parse 264 rawExamples: 265 - | 266 _`input.tmpl`:_ 267 ``` 268 {{ $c := `C,32 269 Go,25 270 COBOL,357` -}} 271 {{ range ($c | csv) -}} 272 {{ index . 0 }} has {{ index . 1 }} keywords. 273 {{ end }} 274 ``` 275 276 ```console 277 $ gomplate < input.tmpl 278 C has 32 keywords. 279 Go has 25 keywords. 280 COBOL has 357 keywords. 281 ``` 282 - name: data.CSVByRow 283 alias: csvByRow 284 description: | 285 Converts a CSV-format string into a slice of maps. 286 287 By default, the [RFC 4180](https://tools.ietf.org/html/rfc4180) format is 288 supported, but any single-character delimiter can be specified. 289 290 Also by default, the first line of the string will be assumed to be the header, 291 but this can be overridden by providing an explicit header, or auto-indexing 292 can be used. 293 pipeline: true 294 arguments: 295 - name: delim 296 required: false 297 description: the (single-character!) field delimiter, defaults to `","` 298 - name: header 299 required: false 300 description: comma-separated list of column names, set to `""` to get auto-named columns (A-Z), defaults to using the first line of `input` 301 - name: input 302 required: true 303 description: the CSV-format string to parse 304 rawExamples: 305 - | 306 _`input.tmpl`:_ 307 ``` 308 {{ $c := `lang,keywords 309 C,32 310 Go,25 311 COBOL,357` -}} 312 {{ range ($c | csvByRow) -}} 313 {{ .lang }} has {{ .keywords }} keywords. 314 {{ end }} 315 ``` 316 317 ```console 318 $ gomplate < input.tmpl 319 C has 32 keywords. 320 Go has 25 keywords. 321 COBOL has 357 keywords. 322 ``` 323 - name: data.CSVByColumn 324 alias: csvByColumn 325 description: | 326 Like [`csvByRow`](#csvByRow), except that the data is presented as a columnar 327 (column-oriented) map. 328 pipeline: true 329 arguments: 330 - name: delim 331 required: false 332 description: the (single-character!) field delimiter, defaults to `","` 333 - name: header 334 required: false 335 description: comma-separated list of column names, set to `""` to get auto-named columns (A-Z), defaults to using the first line of `input` 336 - name: input 337 required: true 338 description: the CSV-format string to parse 339 rawExamples: 340 - | 341 _`input.tmpl`:_ 342 ``` 343 {{ $c := `C;32 344 Go;25 345 COBOL;357` -}} 346 {{ $langs := ($c | csvByColumn ";" "lang,keywords").lang -}} 347 {{ range $langs }}{{ . }} 348 {{ end -}} 349 ``` 350 351 ```console 352 $ gomplate < input.tmpl 353 C 354 Go 355 COBOL 356 ``` 357 - name: data.ToJSON 358 alias: toJSON 359 description: | 360 Converts an object to a JSON document. Input objects may be the result of `json`, `yaml`, `jsonArray`, or `yamlArray` functions, or they could be provided by a `datasource`. 361 pipeline: true 362 arguments: 363 - name: obj 364 required: true 365 description: the object to marshal 366 rawExamples: 367 - | 368 _This is obviously contrived - `json` is used to create an object._ 369 370 _`input.tmpl`:_ 371 ``` 372 {{ (`{"foo":{"hello":"world"}}` | json).foo | toJSON }} 373 ``` 374 375 ```console 376 $ gomplate < input.tmpl 377 {"hello":"world"} 378 ``` 379 - name: data.ToJSONPretty 380 alias: toJSONPretty 381 description: | 382 Converts an object to a pretty-printed (or _indented_) JSON document. 383 Input objects may be the result of functions like `data.JSON`, `data.YAML`, 384 `data.JSONArray`, or `data.YAMLArray` functions, or they could be provided 385 by a [`datasource`](../general/datasource). 386 387 The indent string must be provided as an argument. 388 pipeline: true 389 arguments: 390 - name: indent 391 required: true 392 description: the string to use for indentation 393 - name: obj 394 required: true 395 description: the object to marshal 396 rawExamples: 397 - | 398 _`input.tmpl`:_ 399 ``` 400 {{ `{"hello":"world"}` | data.JSON | data.ToJSONPretty " " }} 401 ``` 402 403 ```console 404 $ gomplate < input.tmpl 405 { 406 "hello": "world" 407 } 408 ``` 409 - name: data.ToYAML 410 alias: toYAML 411 description: | 412 Converts an object to a YAML document. Input objects may be the result of 413 `data.JSON`, `data.YAML`, `data.JSONArray`, or `data.YAMLArray` functions, 414 or they could be provided by a [`datasource`](../general/datasource). 415 pipeline: true 416 arguments: 417 - name: obj 418 required: true 419 description: the object to marshal 420 rawExamples: 421 - | 422 _This is obviously contrived - `data.JSON` is used to create an object._ 423 424 _`input.tmpl`:_ 425 ``` 426 {{ (`{"foo":{"hello":"world"}}` | data.JSON).foo | data.ToYAML }} 427 ``` 428 429 ```console 430 $ gomplate < input.tmpl 431 hello: world 432 ``` 433 - name: data.ToTOML 434 alias: toTOML 435 description: | 436 Converts an object to a [TOML](https://github.com/toml-lang/toml) document. 437 pipeline: true 438 arguments: 439 - name: obj 440 required: true 441 description: the object to marshal as a TOML document 442 examples: 443 - | 444 $ gomplate -i '{{ `{"foo":"bar"}` | data.JSON | data.ToTOML }}' 445 foo = "bar" 446 - name: data.ToCSV 447 alias: toCSV 448 description: | 449 Converts an object to a CSV document. The input object must be a 2-dimensional 450 array of strings (a `[][]string`). Objects produced by [`data.CSVByRow`](#conv-csvbyrow) 451 and [`data.CSVByColumn`](#conv-csvbycolumn) cannot yet be converted back to CSV documents. 452 453 **Note:** With the exception that a custom delimiter can be used, `data.ToCSV` 454 outputs according to the [RFC 4180](https://tools.ietf.org/html/rfc4180) format, 455 which means that line terminators are `CRLF` (Windows format, or `\r\n`). If 456 you require `LF` (UNIX format, or `\n`), the output can be piped through 457 [`strings.ReplaceAll`](../strings/#strings-replaceall) to replace `"\r\n"` with `"\n"`. 458 pipeline: true 459 arguments: 460 - name: delim 461 required: false 462 description: the (single-character!) field delimiter, defaults to `","` 463 - name: input 464 required: true 465 description: the object to convert to a CSV 466 rawExamples: 467 - | 468 _`input.tmpl`:_ 469 ```go 470 {{ $rows := (jsonArray `[["first","second"],["1","2"],["3","4"]]`) -}} 471 {{ data.ToCSV ";" $rows }} 472 ``` 473 474 ```console 475 $ gomplate -f input.tmpl 476 first,second 477 1,2 478 3,4 479 ```