conversion functions

These are a collection of functions that mostly help converting from one type to another - generally from a string to something else, and vice-versa.

conv.Bool

Alias: bool

Note: See also conv.ToBool for a more flexible variant.

Converts a true-ish string to a boolean. Can be used to simplify conditional statements based on environment variables or other text input.

Added in gomplate v0.2.0

Usage

conv.Bool in
in | conv.Bool

Arguments

name description
in (required) the input string

Examples

input.tmpl:

{{if bool (getenv "FOO")}}foo{{else}}bar{{end}}
$ gomplate < input.tmpl
bar
$ FOO=true gomplate < input.tmpl
foo

conv.Default

Alias: default

Provides a default value given an empty input. Empty inputs are 0 for numeric types, "" for strings, false for booleans, empty arrays/maps, and nil.

Note that this will not provide a default for the case where the input is undefined (i.e. referencing things like .foo where there is no foo field of .), but conv.Has can be used for that.

Added in gomplate v2.5.0

Usage

conv.Default default in
in | conv.Default default

Arguments

name description
default (required) the default value
in (required) the input

Examples

$ gomplate -i '{{ "" | default "foo" }} {{ "bar" | default "baz" }}'
foo bar

conv.Dict (deprecated)

Deprecation Notice: Renamed to coll.Dict

Alias: dict

Dict is a convenience function that creates a map with string keys. Provide arguments as key/value pairs. If an odd number of arguments is provided, the last is used as the key, and an empty string is set as the value.

All keys are converted to strings.

This function is equivalent to Sprig’s dict function, as used in Helm templates.

For creating more complex maps, see data.JSON or data.YAML.

For creating arrays, see coll.Slice.

Added in gomplate v3.0.0

Usage

conv.Dict in...

Arguments

name description
in... (required) The key/value pairs

Examples

$ gomplate -i '{{ conv.Dict "name" "Frank" "age" 42 | data.ToYAML }}'
age: 42
name: Frank
$ gomplate -i '{{ dict 1 2 3 | toJSON }}'
{"1":2,"3":""}
$ cat <<EOF| gomplate
{{ define "T1" }}Hello {{ .thing }}!{{ end -}}
{{ template "T1" (dict "thing" "world")}}
{{ template "T1" (dict "thing" "everybody")}}
EOF
Hello world!
Hello everybody!

conv.Slice (deprecated)

Deprecation Notice: Renamed to coll.Slice

Alias: slice

Creates a slice (like an array or list). Useful when needing to range over a bunch of variables.

Added in gomplate v0.3.0

Usage

conv.Slice in...

Arguments

name description
in... (required) the elements of the slice

Examples

$ gomplate -i '{{ range coll.Slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
Hello, Bart
Hello, Lisa
Hello, Maggie

conv.Has (deprecated)

Deprecation Notice: Renamed to coll.Has

Alias: has

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.

Added in gomplate v1.5.0

Usage

conv.Has in item

Arguments

name description
in (required) The object or list to search
item (required) The item to search for

Examples

$ gomplate -i '{{ $l := coll.Slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
there is a bar
$ export DATA='{"foo": "bar"}'
$ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
{{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
bar
$ export DATA='{"baz": "qux"}'
$ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
{{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
THERE IS NO FOO

conv.Join

Alias: join

Concatenates the elements of an array to create a string. The separator string sep is placed between elements in the resulting string.

Added in gomplate v0.4.0

Usage

conv.Join in sep

Arguments

name description
in (required) the array or slice
sep (required) the separator

Examples

$ gomplate -i '{{ $a := coll.Slice 1 2 3 }}{{ join $a "-" }}'
1-2-3

conv.URL

Alias: urlParse

Parses a string as a URL for later use. Equivalent to url.Parse

Any of url.URL’s methods can be called on the result.

Added in gomplate v2.0.0

Usage

conv.URL in

Arguments

name description
in (required) the URL string to parse

Examples

input.tmpl:

{{ $u := conv.URL "https://example.com:443/foo/bar" }}
The scheme is {{ $u.Scheme }}
The host is {{ $u.Host }}
The path is {{ $u.Path }}
$ gomplate < input.tmpl
The scheme is https
The host is example.com:443
The path is /foo/bar

Call Redacted to hide the password in the output:

$ gomplate -i '{{ (conv.URL "https://user:supersecret@example.com").Redacted }}'
https://user:xxxxx@example.com

conv.ParseInt

Note: See conv.ToInt64 instead for a simpler and more flexible variant of this function.

Parses a string as an int64. Equivalent to strconv.ParseInt

Added in gomplate v1.4.0

Usage

conv.ParseInt

Examples

input.tmpl:

{{ $val := conv.ParseInt (getenv "HEXVAL") 16 32 }}
The value in decimal is {{ $val }}
$ HEXVAL=7C0 gomplate < input.tmpl

The value in decimal is 1984

conv.ParseFloat

Note: See conv.ToFloat instead for a simpler and more flexible variant of this function.

Parses a string as an float64 for later use. Equivalent to strconv.ParseFloat

Added in gomplate v1.4.0

Usage

conv.ParseFloat

Examples

input.tmpl:

{{ $pi := conv.ParseFloat (getenv "PI") 64 }}
{{- if (gt $pi 3.0) -}}
pi is greater than 3
{{- end }}
$ PI=3.14159265359 gomplate < input.tmpl
pi is greater than 3

conv.ParseUint

Parses a string as an uint64 for later use. Equivalent to strconv.ParseUint

Added in gomplate v1.4.0

Usage

conv.ParseUint

Examples

input.tmpl:

{{ conv.ParseInt (getenv "BIG") 16 64 }} is max int64
{{ conv.ParseUint (getenv "BIG") 16 64 }} is max uint64
$ BIG=FFFFFFFFFFFFFFFF gomplate < input.tmpl
9223372036854775807 is max int64
18446744073709551615 is max uint64

conv.Atoi

Note: See conv.ToInt and conv.ToInt64 instead for simpler and more flexible variants of this function.

Parses a string as an int for later use. Equivalent to strconv.Atoi

Added in gomplate v1.4.0

Usage

conv.Atoi

Examples

input.tmpl:

{{ $number := conv.Atoi (getenv "NUMBER") }}
{{- if (gt $number 5) -}}
The number is greater than 5
{{- else -}}
The number is less than 5
{{- end }}
$ NUMBER=21 gomplate < input.tmpl
The number is greater than 5

conv.ToBool

Converts the input to a boolean value. Possible true values are: 1 or the strings "t", "true", or "yes" (any capitalizations). All other values are considered false.

Added in gomplate v2.7.0

Usage

conv.ToBool input
input | conv.ToBool

Arguments

name description
input (required) The input to convert

Examples

$ gomplate -i '{{ conv.ToBool "yes" }} {{ conv.ToBool true }} {{ conv.ToBool "0x01" }}'
true true true
$ gomplate -i '{{ conv.ToBool false }} {{ conv.ToBool "blah" }} {{ conv.ToBool 0 }}'
false false false

conv.ToBools

Converts a list of inputs to an array of boolean values. Possible true values are: 1 or the strings "t", "true", or "yes" (any capitalizations). All other values are considered false.

Added in gomplate v2.7.0

Usage

conv.ToBools input
input | conv.ToBools

Arguments

name description
input (required) The input array to convert

Examples

$ gomplate -i '{{ conv.ToBools "yes" true "0x01" }}'
[true true true]
$ gomplate -i '{{ conv.ToBools false "blah" 0 }}'
[false false false]

conv.ToInt64

Converts the input to an int64 (64-bit signed integer).

This function attempts to convert most types of input (strings, numbers, and booleans), but behaviour when the input can not be converted is undefined and subject to change. Unconvertable inputs may result in errors, or 0 or -1.

Floating-point numbers (with decimal points) are truncated.

Added in gomplate v2.2.0

Usage

conv.ToInt64 in

Arguments

name description
in (required) the value to convert

Examples

$ gomplate -i '{{conv.ToInt64 "9223372036854775807"}}'
9223372036854775807
$ gomplate -i '{{conv.ToInt64 "0x42"}}'
66
$ gomplate -i '{{conv.ToInt64 true }}'
1

conv.ToInt

Converts the input to an int (signed integer, 32- or 64-bit depending on platform). This is similar to conv.ToInt64 on 64-bit platforms, but is useful when input to another function must be provided as an int.

On 32-bit systems, given a number that is too large to fit in an int, the result is -1. This is done to protect against CWE-190 and CWE-681.

See also conv.ToInt64.

Added in gomplate v2.2.0

Usage

conv.ToInt in

Arguments

name description
in (required) the value to convert

Examples

$ gomplate -i '{{conv.ToInt "9223372036854775807"}}'
9223372036854775807
$ gomplate -i '{{conv.ToInt "0x42"}}'
66
$ gomplate -i '{{conv.ToInt true }}'
1

conv.ToInt64s

Converts the inputs to an array of int64s.

This delegates to conv.ToInt64 for each input argument.

Added in gomplate v2.2.0

Usage

conv.ToInt64s in...

Arguments

name description
in... (required) the inputs to be converted

Examples

gomplate -i '{{ conv.ToInt64s true 0x42 "123,456.99" "1.2345e+3"}}'
[1 66 123456 1234]

conv.ToInts

Converts the inputs to an array of ints.

This delegates to conv.ToInt for each input argument.

Added in gomplate v2.2.0

Usage

conv.ToInts in...

Arguments

name description
in... (required) the inputs to be converted

Examples

gomplate -i '{{ conv.ToInts true 0x42 "123,456.99" "1.2345e+3"}}'
[1 66 123456 1234]

conv.ToFloat64

Converts the input to a float64.

This function attempts to convert most types of input (strings, numbers, and booleans), but behaviour when the input can not be converted is undefined and subject to change. Unconvertable inputs may result in errors, or 0 or -1.

Added in gomplate v2.2.0

Usage

conv.ToFloat64 in

Arguments

name description
in (required) the value to convert

Examples

$ gomplate -i '{{ conv.ToFloat64 "8.233e-1"}}'
0.8233
$ gomplate -i '{{ conv.ToFloat64 "9,000.09"}}'
9000.09

conv.ToFloat64s

Converts the inputs to an array of float64s.

This delegates to conv.ToFloat64 for each input argument.

Added in gomplate v2.2.0

Usage

conv.ToFloat64s in...

Arguments

name description
in... (required) the inputs to be converted

Examples

$ gomplate -i '{{ conv.ToFloat64s true 0x42 "123,456.99" "1.2345e+3"}}'
[1 66 123456.99 1234.5]

conv.ToString

Converts the input (of any type) to a string.

The input will always be represented in some way.

Added in gomplate v2.5.0

Usage

conv.ToString in

Arguments

name description
in (required) the value to convert

Examples

$ gomplate -i '{{ conv.ToString 0xFF }}'
255
$ gomplate -i '{{ dict "foo" "bar" | conv.ToString}}'
map[foo:bar]
$ gomplate -i '{{ conv.ToString nil }}'
nil

conv.ToStrings

Converts the inputs (of any type) to an array of strings

This delegates to conv.ToString for each input argument.

Added in gomplate v2.5.0

Usage

conv.ToStrings in...

Arguments

name description
in... (required) the inputs to be converted

Examples

$ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (coll.Slice 1 2 3) }}'
[nil 42 true 15 [1 2 3]]