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