github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs/content/functions/coll.md (about) 1 --- 2 title: collection functions 3 menu: 4 main: 5 parent: functions 6 --- 7 8 These functions help manipulate and query collections of data, like lists (slices, or arrays) and maps (dictionaries). 9 10 #### Implementation Note 11 For the functions that return an array, a Go `[]interface{}` is returned, regardless of whether or not the 12 input was a different type. 13 14 ## `coll.Dict` 15 16 **Alias:** `dict` 17 18 Dict is a convenience function that creates a map with string keys. 19 Provide arguments as key/value pairs. If an odd number of arguments 20 is provided, the last is used as the key, and an empty string is 21 set as the value. 22 23 All keys are converted to strings. 24 25 This function is equivalent to [Sprig's `dict`](http://masterminds.github.io/sprig/dicts.html#dict) 26 function, as used in [Helm templates](https://docs.helm.sh/chart_template_guide#template-functions-and-pipelines). 27 28 For creating more complex maps, see [`data.JSON`](../data/#data-json) or [`data.YAML`](../data/#data-yaml). 29 30 For creating arrays, see [`coll.Slice`](#coll-slice). 31 32 ### Usage 33 34 ```go 35 coll.Dict in... 36 ``` 37 38 ### Arguments 39 40 | name | description | 41 |------|-------------| 42 | `in...` | _(required)_ The key/value pairs | 43 44 ### Examples 45 46 ```console 47 $ gomplate -i '{{ coll.Dict "name" "Frank" "age" 42 | data.ToYAML }}' 48 age: 42 49 name: Frank 50 $ gomplate -i '{{ dict 1 2 3 | toJSON }}' 51 {"1":2,"3":""} 52 ``` 53 ```console 54 $ cat <<EOF| gomplate 55 {{ define "T1" }}Hello {{ .thing }}!{{ end -}} 56 {{ template "T1" (dict "thing" "world")}} 57 {{ template "T1" (dict "thing" "everybody")}} 58 EOF 59 Hello world! 60 Hello everybody! 61 ``` 62 63 ## `coll.Slice` 64 65 **Alias:** `slice` 66 67 Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables. 68 69 ### Usage 70 71 ```go 72 coll.Slice in... 73 ``` 74 75 ### Arguments 76 77 | name | description | 78 |------|-------------| 79 | `in...` | _(required)_ the elements of the slice | 80 81 ### Examples 82 83 ```console 84 $ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}' 85 Hello, Bart 86 Hello, Lisa 87 Hello, Maggie 88 ``` 89 90 ## `coll.Has` 91 92 **Alias:** `has` 93 94 Reports whether a given object has a property with the given key, or whether a given array/slice contains the given value. Can be used with `if` to prevent the template from trying to access a non-existent property in an object. 95 96 ### Usage 97 98 ```go 99 coll.Has in item 100 ``` 101 102 ### Arguments 103 104 | name | description | 105 |------|-------------| 106 | `in` | _(required)_ The object or list to search | 107 | `item` | _(required)_ The item to search for | 108 109 ### Examples 110 111 ```console 112 $ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar' 113 there is a bar 114 ``` 115 ```console 116 $ export DATA='{"foo": "bar"}' 117 $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}} 118 {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}' 119 bar 120 ``` 121 ```console 122 $ export DATA='{"baz": "qux"}' 123 $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}} 124 {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}' 125 THERE IS NO FOO 126 ``` 127 128 ## `coll.JSONPath` 129 130 **Alias:** `jsonpath` 131 132 Extracts portions of an input object or list using a [JSONPath][] expression. 133 134 Any object or list may be used as input. The output depends somewhat on the expression; if multiple items are matched, an array is returned. 135 136 JSONPath expressions can be validated at https://jsonpath.com 137 138 [JSONPath]: https://goessner.net/articles/JsonPath 139 140 ### Usage 141 142 ```go 143 coll.JSONPath expression in 144 ``` 145 ```go 146 in | coll.JSONPath expression 147 ``` 148 149 ### Arguments 150 151 | name | description | 152 |------|-------------| 153 | `expression` | _(required)_ The JSONPath expression | 154 | `in` | _(required)_ The object or list to query | 155 156 ### Examples 157 158 ```console 159 $ gomplate -i '{{ .books | jsonpath `$..works[?( @.edition_count > 400 )].title` }}' -c books=https://openlibrary.org/subjects/fantasy.json 160 [Alice's Adventures in Wonderland Gulliver's Travels] 161 ``` 162 163 ## `coll.Keys` 164 165 **Alias:** `keys` 166 167 Return a list of keys in one or more maps. 168 169 The keys will be ordered first by map position (if multiple maps are given), 170 then alphabetically. 171 172 See also [`coll.Values`](#coll-values). 173 174 ### Usage 175 176 ```go 177 coll.Keys in... 178 ``` 179 ```go 180 in... | coll.Keys 181 ``` 182 183 ### Arguments 184 185 | name | description | 186 |------|-------------| 187 | `in...` | _(required)_ the maps | 188 189 ### Examples 190 191 ```console 192 $ gomplate -i '{{ coll.Keys (dict "foo" 1 "bar" 2) }}' 193 [bar foo] 194 $ gomplate -i '{{ $map1 := dict "foo" 1 "bar" 2 -}}{{ $map2 := dict "baz" 3 "qux" 4 -}}{{ coll.Keys $map1 $map2 }}' 195 [bar foo baz qux] 196 ``` 197 198 ## `coll.Values` 199 200 **Alias:** `values` 201 202 Return a list of values in one or more maps. 203 204 The values will be ordered first by map position (if multiple maps are given), 205 then alphabetically by key. 206 207 See also [`coll.Keys`](#coll-keys). 208 209 ### Usage 210 211 ```go 212 coll.Values in... 213 ``` 214 ```go 215 in... | coll.Values 216 ``` 217 218 ### Arguments 219 220 | name | description | 221 |------|-------------| 222 | `in...` | _(required)_ the maps | 223 224 ### Examples 225 226 ```console 227 $ gomplate -i '{{ coll.Values (dict "foo" 1 "bar" 2) }}' 228 [2 1] 229 $ gomplate -i '{{ $map1 := dict "foo" 1 "bar" 2 -}}{{ $map2 := dict "baz" 3 "qux" 4 -}}{{ coll.Values $map1 $map2 }}' 230 [2 1 3 4] 231 ``` 232 233 ## `coll.Append` 234 235 **Alias:** `append` 236 237 Append a value to the end of a list. 238 239 _Note that this function does not change the given list; it always produces a new one._ 240 241 See also [`coll.Prepend`](#coll-prepend). 242 243 ### Usage 244 245 ```go 246 coll.Append value list... 247 ``` 248 ```go 249 list... | coll.Append value 250 ``` 251 252 ### Arguments 253 254 | name | description | 255 |------|-------------| 256 | `value` | _(required)_ the value to add | 257 | `list...` | _(required)_ the slice or array to append to | 258 259 ### Examples 260 261 ```console 262 $ gomplate -i '{{ slice 1 1 2 3 | append 5 }}' 263 [1 1 2 3 5] 264 ``` 265 266 ## `coll.Prepend` 267 268 **Alias:** `prepend` 269 270 Prepend a value to the beginning of a list. 271 272 _Note that this function does not change the given list; it always produces a new one._ 273 274 See also [`coll.Append`](#coll-append). 275 276 ### Usage 277 278 ```go 279 coll.Prepend value list... 280 ``` 281 ```go 282 list... | coll.Prepend value 283 ``` 284 285 ### Arguments 286 287 | name | description | 288 |------|-------------| 289 | `value` | _(required)_ the value to add | 290 | `list...` | _(required)_ the slice or array to prepend to | 291 292 ### Examples 293 294 ```console 295 $ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}' 296 [5 4 3 2 1] 297 ``` 298 299 ## `coll.Uniq` 300 301 **Alias:** `uniq` 302 303 Remove any duplicate values from the list, without changing order. 304 305 _Note that this function does not change the given list; it always produces a new one._ 306 307 See also [`coll.Append`](#coll-append). 308 309 ### Usage 310 311 ```go 312 coll.Uniq list 313 ``` 314 ```go 315 list | coll.Uniq 316 ``` 317 318 ### Arguments 319 320 | name | description | 321 |------|-------------| 322 | `list` | _(required)_ the input list | 323 324 ### Examples 325 326 ```console 327 $ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}' 328 [5 4 3 2 1] 329 ``` 330 331 ## `coll.Reverse` 332 333 **Alias:** `reverse` 334 335 Reverse a list. 336 337 _Note that this function does not change the given list; it always produces a new one._ 338 339 ### Usage 340 341 ```go 342 coll.Reverse list 343 ``` 344 ```go 345 list | coll.Reverse 346 ``` 347 348 ### Arguments 349 350 | name | description | 351 |------|-------------| 352 | `list` | _(required)_ the list to reverse | 353 354 ### Examples 355 356 ```console 357 $ gomplate -i '{{ slice 4 3 2 1 | reverse }}' 358 [1 2 3 4] 359 ``` 360 361 ## `coll.Sort` 362 363 **Alias:** `sort` 364 365 Sort a given list. Uses the natural sort order if possible. For inputs 366 that are not sortable (either because the elements are of different types, 367 or of an un-sortable type), the input will simply be returned, unmodified. 368 369 Maps and structs can be sorted by a named key. 370 371 _Note that this function does not modify the input._ 372 373 ### Usage 374 375 ```go 376 coll.Sort [key] list 377 ``` 378 ```go 379 list | coll.Sort [key] 380 ``` 381 382 ### Arguments 383 384 | name | description | 385 |------|-------------| 386 | `key` | _(optional)_ the key to sort by, for lists of maps or structs | 387 | `list` | _(required)_ the slice or array to sort | 388 389 ### Examples 390 391 ```console 392 $ gomplate -i '{{ slice "foo" "bar" "baz" | coll.Sort }}' 393 [bar baz foo] 394 ``` 395 ```console 396 $ gomplate -i '{{ sort (slice 3 4 1 2 5) }}' 397 [1 2 3 4 5] 398 ``` 399 ```console 400 $ cat <<EOF > in.json 401 [{"a": "foo", "b": 1}, {"a": "bar", "b": 8}, {"a": "baz", "b": 3}] 402 EOF 403 $ gomplate -d in.json -i '{{ range (include "in" | jsonArray | coll.Sort "b") }}{{ print .a "\n" }}{{ end }}' 404 foo 405 baz 406 bar 407 ``` 408 409 ## `coll.Merge` 410 411 **Alias:** `merge` 412 413 Merge maps together by overriding src with dst. 414 415 In other words, the src map can be configured the "default" map, whereas the dst 416 map can be configured the "overrides". 417 418 Many source maps can be provided. Precedence is in left-to-right order. 419 420 _Note that this function does not modify the input._ 421 422 ### Usage 423 424 ```go 425 coll.Merge dst srcs... 426 ``` 427 ```go 428 srcs... | coll.Merge dst 429 ``` 430 431 ### Arguments 432 433 | name | description | 434 |------|-------------| 435 | `dst` | _(required)_ the map to merge _into_ | 436 | `srcs...` | _(required)_ the map (or maps) to merge _from_ | 437 438 ### Examples 439 440 ```console 441 $ gomplate -i '{{ $default := dict "foo" 1 "bar" 2}} 442 {{ $config := dict "foo" 8 }} 443 {{ merge $config $default }}' 444 map[bar:2 foo:8] 445 ``` 446 ```console 447 $ gomplate -i '{{ $dst := dict "foo" 1 "bar" 2 }} 448 {{ $src1 := dict "foo" 8 "baz" 4 }} 449 {{ $src2 := dict "foo" 3 "bar" 5 }} 450 {{ coll.Merge $dst $src1 $src2 }}' 451 map[foo:1 bar:5 baz:4] 452 ```