github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs-src/content/functions/conv.yml (about) 1 ns: conv 2 title: conversion functions 3 preamble: | 4 These are a collection of functions that mostly help converting from one type 5 to another - generally from a `string` to something else, and vice-versa. 6 funcs: 7 - name: conv.Bool 8 alias: bool 9 description: | 10 **Note:** See also [`conv.ToBool`](#conv-tobool) for a more flexible variant. 11 12 Converts a true-ish string to a boolean. Can be used to simplify conditional statements based on environment variables or other text input. 13 pipeline: true 14 arguments: 15 - name: in 16 required: true 17 description: the input string 18 rawExamples: 19 - | 20 _`input.tmpl`:_ 21 ``` 22 {{if bool (getenv "FOO")}}foo{{else}}bar{{end}} 23 ``` 24 25 ```console 26 $ gomplate < input.tmpl 27 bar 28 $ FOO=true gomplate < input.tmpl 29 foo 30 ``` 31 - name: conv.Default 32 alias: default 33 description: | 34 Provides a default value given an empty input. Empty inputs are `0` for numeric 35 types, `""` for strings, `false` for booleans, empty arrays/maps, and `nil`. 36 37 Note that this will not provide a default for the case where the input is undefined 38 (i.e. referencing things like `.foo` where there is no `foo` field of `.`), but 39 [`conv.Has`](#conv-has) can be used for that. 40 pipeline: true 41 arguments: 42 - name: default 43 required: true 44 description: the default value 45 - name: in 46 required: true 47 description: the input 48 examples: 49 - | 50 $ gomplate -i '{{ "" | default "foo" }} {{ "bar" | default "baz" }}' 51 foo bar 52 - name: conv.Dict 53 deprecated: Renamed to [`coll.Dict`](#coll-dict) 54 alias: dict 55 description: | 56 Dict is a convenience function that creates a map with string keys. 57 Provide arguments as key/value pairs. If an odd number of arguments 58 is provided, the last is used as the key, and an empty string is 59 set as the value. 60 61 All keys are converted to strings. 62 63 This function is equivalent to [Sprig's `dict`](http://masterminds.github.io/sprig/dicts.html#dict) 64 function, as used in [Helm templates](https://docs.helm.sh/chart_template_guide#template-functions-and-pipelines). 65 66 For creating more complex maps, see [`data.JSON`](../data/#data-json) or [`data.YAML`](../data/#data-yaml). 67 68 For creating arrays, see [`conv.Slice`](#conv-slice). 69 arguments: 70 - name: in... 71 required: true 72 description: The key/value pairs 73 examples: 74 - | 75 $ gomplate -i '{{ conv.Dict "name" "Frank" "age" 42 | data.ToYAML }}' 76 age: 42 77 name: Frank 78 $ gomplate -i '{{ dict 1 2 3 | toJSON }}' 79 {"1":2,"3":""} 80 - | 81 $ cat <<EOF| gomplate 82 {{ define "T1" }}Hello {{ .thing }}!{{ end -}} 83 {{ template "T1" (dict "thing" "world")}} 84 {{ template "T1" (dict "thing" "everybody")}} 85 EOF 86 Hello world! 87 Hello everybody! 88 - name: conv.Slice 89 deprecated: Renamed to [`coll.Slice`](#coll-slice) 90 alias: slice 91 description: | 92 Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables. 93 pipeline: false 94 arguments: 95 - name: in... 96 required: true 97 description: the elements of the slice 98 examples: 99 - | 100 $ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}' 101 Hello, Bart 102 Hello, Lisa 103 Hello, Maggie 104 - name: conv.Has 105 deprecated: Renamed to [`coll.Has`](#coll-has) 106 alias: has 107 description: | 108 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. 109 pipeline: false 110 arguments: 111 - name: in 112 required: true 113 description: The object or list to search 114 - name: item 115 required: true 116 description: The item to search for 117 examples: 118 - | 119 $ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar' 120 there is a bar 121 - | 122 $ export DATA='{"foo": "bar"}' 123 $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}} 124 {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}' 125 bar 126 - | 127 $ export DATA='{"baz": "qux"}' 128 $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}} 129 {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}' 130 THERE IS NO FOO 131 - name: conv.Join 132 alias: join 133 description: | 134 Concatenates the elements of an array to create a string. The separator string `sep` is placed between elements in the resulting string. 135 arguments: 136 - name: in 137 required: true 138 description: the array or slice 139 - name: sep 140 required: true 141 description: the separator 142 examples: 143 - | 144 $ gomplate -i '{{ $a := slice 1 2 3 }}{{ join $a "-" }}' 145 1-2-3 146 - name: conv.URL 147 alias: urlParse 148 description: | 149 Parses a string as a URL for later use. Equivalent to [url.Parse](https://golang.org/pkg/net/url/#Parse) 150 arguments: 151 - name: in 152 required: true 153 description: the URL string to parse 154 rawExamples: 155 - | 156 _`input.tmpl`:_ 157 ``` 158 {{ $u := conv.URL "https://example.com:443/foo/bar" }} 159 The scheme is {{ $u.Scheme }} 160 The host is {{ $u.Host }} 161 The path is {{ $u.Path }} 162 ``` 163 164 ```console 165 $ gomplate < input.tmpl 166 The scheme is https 167 The host is example.com:443 168 The path is /foo/bar 169 ``` 170 - name: conv.ParseInt 171 description: | 172 _**Note:**_ See [`conv.ToInt64`](#conv-toint64) instead for a simpler and more flexible variant of this function. 173 174 Parses a string as an int64. Equivalent to [strconv.ParseInt](https://golang.org/pkg/strconv/#ParseInt) 175 rawExamples: 176 - | 177 _`input.tmpl`:_ 178 ``` 179 {{ $val := conv.ParseInt (getenv "HEXVAL") 16 32 }} 180 The value in decimal is {{ $val }} 181 ``` 182 183 ```console 184 $ HEXVAL=7C0 gomplate < input.tmpl 185 186 The value in decimal is 1984 187 ``` 188 - name: conv.ParseFloat 189 description: | 190 _**Note:**_ See [`conv.ToFloat`](#conv-tofloat) instead for a simpler and more flexible variant of this function. 191 192 Parses a string as an float64 for later use. Equivalent to [strconv.ParseFloat](https://golang.org/pkg/strconv/#ParseFloat) 193 rawExamples: 194 - | 195 _`input.tmpl`:_ 196 ``` 197 {{ $pi := conv.ParseFloat (getenv "PI") 64 }} 198 {{- if (gt $pi 3.0) -}} 199 pi is greater than 3 200 {{- end }} 201 ``` 202 203 ```console 204 $ PI=3.14159265359 gomplate < input.tmpl 205 pi is greater than 3 206 ``` 207 - name: conv.ParseUint 208 description: | 209 Parses a string as an uint64 for later use. Equivalent to [strconv.ParseUint](https://golang.org/pkg/strconv/#ParseUint) 210 rawExamples: 211 - | 212 _`input.tmpl`:_ 213 ``` 214 {{ conv.ParseInt (getenv "BIG") 16 64 }} is max int64 215 {{ conv.ParseUint (getenv "BIG") 16 64 }} is max uint64 216 ``` 217 218 ```console 219 $ BIG=FFFFFFFFFFFFFFFF gomplate < input.tmpl 220 9223372036854775807 is max int64 221 18446744073709551615 is max uint64 222 ``` 223 - name: conv.Atoi 224 description: | 225 _**Note:**_ See [`conv.ToInt`](#conv-toint) and [`conv.ToInt64`](#conv-toint64) instead for simpler and more flexible variants of this function. 226 227 Parses a string as an int for later use. Equivalent to [strconv.Atoi](https://golang.org/pkg/strconv/#Atoi) 228 rawExamples: 229 - | 230 _`input.tmpl`:_ 231 ``` 232 {{ $number := conv.Atoi (getenv "NUMBER") }} 233 {{- if (gt $number 5) -}} 234 The number is greater than 5 235 {{- else -}} 236 The number is less than 5 237 {{- end }} 238 ``` 239 240 ```console 241 $ NUMBER=21 gomplate < input.tmpl 242 The number is greater than 5 243 ``` 244 - name: conv.ToBool 245 description: | 246 Converts the input to a boolean value. 247 Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"` 248 (any capitalizations). All other values are considered `false`. 249 pipeline: true 250 arguments: 251 - name: input 252 required: true 253 description: The input to convert 254 examples: 255 - | 256 $ gomplate -i '{{ conv.ToBool "yes" }} {{ conv.ToBool true }} {{ conv.ToBool "0x01" }}' 257 true true true 258 $ gomplate -i '{{ conv.ToBool false }} {{ conv.ToBool "blah" }} {{ conv.ToBool 0 }}' 259 false false false 260 - name: conv.ToBools 261 description: | 262 Converts a list of inputs to an array of boolean values. 263 Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"` 264 (any capitalizations). All other values are considered `false`. 265 pipeline: true 266 arguments: 267 - name: input 268 required: true 269 description: The input array to convert 270 examples: 271 - | 272 $ gomplate -i '{{ conv.ToBools "yes" true "0x01" }}' 273 [true true true] 274 $ gomplate -i '{{ conv.ToBools false "blah" 0 }}' 275 [false false false] 276 - name: conv.ToInt64 277 description: | 278 Converts the input to an `int64` (64-bit signed integer). 279 280 This function attempts to convert most types of input (strings, numbers, 281 and booleans), but behaviour when the input can not be converted is 282 undefined and subject to change. Unconvertable inputs may result in 283 errors, or `0` or `-1`. 284 285 Floating-point numbers (with decimal points) are truncated. 286 arguments: 287 - name: in 288 required: true 289 description: the value to convert 290 examples: 291 - | 292 $ gomplate -i '{{conv.ToInt64 "9223372036854775807"}}' 293 9223372036854775807 294 - | 295 $ gomplate -i '{{conv.ToInt64 "0x42"}}' 296 66 297 - | 298 $ gomplate -i '{{conv.ToInt64 true }}' 299 1 300 - name: conv.ToInt 301 description: | 302 Converts the input to an `int` (signed integer, 32- or 64-bit depending 303 on platform). This is similar to [`conv.ToInt64`](#conv-toint64) on 64-bit 304 platforms, but is useful when input to another function must be provided 305 as an `int`. 306 307 See also [`conv.ToInt64`](#conv-toint64). 308 arguments: 309 - name: in 310 required: true 311 description: the value to convert 312 examples: 313 - | 314 $ gomplate -i '{{conv.ToInt "9223372036854775807"}}' 315 9223372036854775807 316 - | 317 $ gomplate -i '{{conv.ToInt "0x42"}}' 318 66 319 - | 320 $ gomplate -i '{{conv.ToInt true }}' 321 1 322 - name: conv.ToInt64s 323 description: | 324 Converts the inputs to an array of `int64`s. 325 326 This delegates to [`conv.ToInt64`](#conv-toint64) for each input argument. 327 arguments: 328 - name: in... 329 required: true 330 description: the inputs to be converted 331 examples: 332 - | 333 gomplate -i '{{ conv.ToInt64s true 0x42 "123,456.99" "1.2345e+3"}}' 334 [1 66 123456 1234] 335 - name: conv.ToInts 336 description: | 337 Converts the inputs to an array of `int`s. 338 339 This delegates to [`conv.ToInt`](#conv-toint) for each input argument. 340 arguments: 341 - name: in... 342 required: true 343 description: the inputs to be converted 344 examples: 345 - | 346 gomplate -i '{{ conv.ToInts true 0x42 "123,456.99" "1.2345e+3"}}' 347 [1 66 123456 1234] 348 - name: conv.ToFloat64 349 description: | 350 Converts the input to a `float64`. 351 352 This function attempts to convert most types of input (strings, numbers, 353 and booleans), but behaviour when the input can not be converted is 354 undefined and subject to change. Unconvertable inputs may result in 355 errors, or `0` or `-1`. 356 arguments: 357 - name: in 358 required: true 359 description: the value to convert 360 examples: 361 - | 362 $ gomplate -i '{{ conv.ToFloat64 "8.233e-1"}}' 363 0.8233 364 $ gomplate -i '{{ conv.ToFloat64 "9,000.09"}}' 365 9000.09 366 - name: conv.ToFloat64s 367 description: | 368 Converts the inputs to an array of `float64`s. 369 370 This delegates to [`conv.ToFloat64`](#conv-tofloat64) for each input argument. 371 arguments: 372 - name: in... 373 required: true 374 description: the inputs to be converted 375 examples: 376 - | 377 $ gomplate -i '{{ conv.ToFloat64s true 0x42 "123,456.99" "1.2345e+3"}}' 378 [1 66 123456.99 1234.5] 379 - name: conv.ToString 380 description: | 381 Converts the input (of any type) to a `string`. 382 383 The input will always be represented in _some_ way. 384 arguments: 385 - name: in 386 required: true 387 description: the value to convert 388 examples: 389 - | 390 $ gomplate -i '{{ conv.ToString 0xFF }}' 391 255 392 $ gomplate -i '{{ dict "foo" "bar" | conv.ToString}}' 393 map[foo:bar] 394 $ gomplate -i '{{ conv.ToString nil }}' 395 nil 396 - name: conv.ToStrings 397 description: | 398 Converts the inputs (of any type) to an array of `string`s 399 400 This delegates to [`conv.ToString`](#conv-tostring) for each input argument. 401 arguments: 402 - name: in... 403 required: true 404 description: the inputs to be converted 405 examples: 406 - | 407 $ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (slice 1 2 3) }}' 408 [nil 42 true 15 [1 2 3]]