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