data functions

A collection of functions that retrieve, parse, and convert structured data.

datasource

Alias: ds

Parses a given datasource (provided by the --datasource/-d argument or defineDatasource).

If the alias is undefined, but is a valid URL, datasource will dynamically read from that URL.

See Datasources for (much!) more information.

Added in gomplate v0.5.0

Usage

datasource alias [subpath]

Arguments

Examples

person.json:

{ "name": "Dave" }

$ gomplate -d person.json -i 'Hello {{ (datasource "person").name }}'
Hello Dave

datasourceExists

Tests whether or not a given datasource was defined on the commandline (with the --datasource/-d argument). This is intended mainly to allow a template to be rendered differently whether or not a given datasource was defined.

Note: this does not verify if the datasource is reachable.

Useful when used in an if/else block.

Added in gomplate v1.3.0

Usage

datasourceExists alias

Arguments

Examples

$ echo '{{if (datasourceExists "test")}}{{datasource "test"}}{{else}}no worries{{end}}' | gomplate
no worries

datasourceReachable

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.

Useful when used in an if/else block.

Added in gomplate v2.5.0

Usage

datasourceReachable alias

Arguments

Examples

$ gomplate -i '{{if (datasourceReachable "test")}}{{datasource "test"}}{{else}}no worries{{end}}' -d test=https://bogus.example.com/wontwork.json
no worries

listDatasources

Lists all the datasources defined, list returned will be sorted in ascending order.

Added in gomplate v3.11.0

Usage

listDatasources

Examples

$ gomplate -d person=env:///FOO -d bar=env:///BAR -i '{{range (listDatasources)}} Datasource-{{.}} {{end}}'
Datasource-bar
Datasource-person

defineDatasource

Define a datasource alias with target URL inside the template. Overridden by the --datasource/-d flag.

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).

This function can provide a good way to set a default datasource when sharing templates.

See Datasources for (much!) more information.

Added in gomplate v2.7.0

Usage

defineDatasource alias url

Arguments

Examples

person.json:

{ "name": "Dave" }

$ gomplate -i '{{ defineDatasource "person" "person.json" }}Hello {{ (ds "person").name }}'
Hello Dave
$ FOO='{"name": "Daisy"}' gomplate -d person=env:///FOO -i '{{ defineDatasource "person" "person.json" }}Hello {{ (ds "person").name }}'
Hello Daisy

include

Includes the content of a given datasource (provided by the --datasource/-d argument).

This is similar to datasource, except that the data is not parsed. There is no restriction on the type of data included, except that it should be textual.

Added in gomplate v1.8.0

Usage

include alias [subpath]

Arguments

Examples

person.json:

{ "name": "Dave" }

input.tmpl:

{
  "people": [
    {{ include "person" }}
  ]
}

$ gomplate -d person.json -f input.tmpl
{
  "people": [
    { "name": "Dave" }
  ]
}

data.JSON

Alias: json

Converts a JSON string into an object. Works for JSON Objects, but will also parse JSON Arrays. Will not parse other valid JSON types.

For more explict JSON Array support, see data.JSONArray.

Encrypted JSON support (EJSON)

If the input is in the 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:

• set the EJSON_KEY environment variable to the private key’s value
• set the EJSON_KEY_FILE environment variable to the path to a file containing the private key
• 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 flag. Defaults to /opt/ejson/keys.

Added in gomplate v1.4.0

Usage

data.JSON in

in | data.JSON

Arguments

Examples

input.tmpl:

Hello {{ (getenv "FOO" | json).hello }}

$ export FOO='{"hello":"world"}'
$ gomplate < input.tmpl
Hello world

data.JSONArray

Alias: jsonArray

Converts a JSON string into a slice. Only works for JSON Arrays.

Added in gomplate v2.0.0

Usage

data.JSONArray in

in | data.JSONArray

Arguments

Examples

input.tmpl:

Hello {{ index (getenv "FOO" | jsonArray) 1 }}

$ export FOO='[ "you", "world" ]'
$ gomplate < input.tmpl
Hello world

data.YAML

Alias: yaml

Converts a YAML string into an object. Works for YAML Objects but will also parse YAML Arrays. This can be used to access properties of YAML objects.

For more explict YAML Array support, see data.JSONArray.

Added in gomplate v2.0.0

Usage

data.YAML in

in | data.YAML

Arguments

Examples

input.tmpl:

Hello {{ (getenv "FOO" | yaml).hello }}

$ export FOO='hello: world'
$ gomplate < input.tmpl
Hello world

data.YAMLArray

Alias: yamlArray

Converts a YAML string into a slice. Only works for YAML Arrays.

Added in gomplate v2.0.0

Usage

data.YAMLArray in

in | data.YAMLArray

Arguments

Examples

input.tmpl:

Hello {{ index (getenv "FOO" | yamlArray) 1 }}

$ export FOO='[ "you", "world" ]'
$ gomplate < input.tmpl
Hello world

data.TOML

Alias: toml

Converts a TOML document into an object. This can be used to access properties of TOML documents.

Compatible with TOML v0.4.0.

Added in gomplate v2.0.0

Usage

data.TOML input

input | data.TOML

Arguments

Examples

input.tmpl:

{{ $t := `[data]
hello = "world"` -}}
Hello {{ (toml $t).hello }}

$ gomplate -f input.tmpl
Hello world

data.CSV

Alias: csv

Converts a CSV-format string into a 2-dimensional string array.

By default, the RFC 4180 format is supported, but any single-character delimiter can be specified.

Added in gomplate v2.0.0

Usage

data.CSV [delim] input

input | data.CSV [delim]

Arguments

Examples

input.tmpl:

{{ $c := `C,32
Go,25
COBOL,357` -}}
{{ range ($c | csv) -}}
{{ index . 0 }} has {{ index . 1 }} keywords.
{{ end }}

$ gomplate < input.tmpl
C has 32 keywords.
Go has 25 keywords.
COBOL has 357 keywords.

data.CSVByRow

Alias: csvByRow

Converts a CSV-format string into a slice of maps.

By default, the RFC 4180 format is supported, but any single-character delimiter can be specified.

Also by default, the first line of the string will be assumed to be the header, but this can be overridden by providing an explicit header, or auto-indexing can be used.

Added in gomplate v2.0.0

Usage

data.CSVByRow [delim] [header] input

input | data.CSVByRow [delim] [header]

Arguments

Examples

input.tmpl:

{{ $c := `lang,keywords
C,32
Go,25
COBOL,357` -}}
{{ range ($c | csvByRow) -}}
{{ .lang }} has {{ .keywords }} keywords.
{{ end }}

$ gomplate < input.tmpl
C has 32 keywords.
Go has 25 keywords.
COBOL has 357 keywords.

data.CSVByColumn

Alias: csvByColumn

Like csvByRow, except that the data is presented as a columnar (column-oriented) map.

Added in gomplate v2.0.0

Usage

data.CSVByColumn [delim] [header] input

input | data.CSVByColumn [delim] [header]

Arguments

Examples

input.tmpl:

{{ $c := `C;32
Go;25
COBOL;357` -}}
{{ $langs := ($c | csvByColumn ";" "lang,keywords").lang -}}
{{ range $langs }}{{ . }}
{{ end -}}

$ gomplate < input.tmpl
C
Go
COBOL

data.CUE(unreleased)

Unreleased: This function is in development, and not yet available in released builds of gomplate.

Alias: cue

Converts a CUE document into an object. Any type of CUE document is supported. This can be used to access properties of CUE documents.

Note that the import statement is not yet supported, and will result in an error (except for importing builtin packages).

Usage

data.CUE input

input | data.CUE

Arguments

Examples

$ gomplate -i '{{ $t := `data: {
    hello: "world"
  }` -}}
  Hello {{ (cue $t).data.hello }}'
Hello world

data.ToJSON

Alias: toJSON

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.

Added in gomplate v2.0.0

Usage

data.ToJSON obj

obj | data.ToJSON

Arguments

Examples

This is obviously contrived - json is used to create an object.

input.tmpl:

{{ (`{"foo":{"hello":"world"}}` | json).foo | toJSON }}

$ gomplate < input.tmpl
{"hello":"world"}

data.ToJSONPretty

Alias: toJSONPretty

Converts an object to a pretty-printed (or indented) JSON document. Input objects may be the result of functions like data.JSON, data.YAML, data.JSONArray, or data.YAMLArray functions, or they could be provided by a datasource.

The indent string must be provided as an argument.

Added in gomplate v2.0.0

Usage

data.ToJSONPretty indent obj

obj | data.ToJSONPretty indent

Arguments

Examples

input.tmpl:

{{ `{"hello":"world"}` | data.JSON | data.ToJSONPretty "  " }}

$ gomplate < input.tmpl
{
  "hello": "world"
}

data.ToYAML

Alias: toYAML

Converts an object to a YAML document. Input objects may be the result of data.JSON, data.YAML, data.JSONArray, or data.YAMLArray functions, or they could be provided by a datasource.

Added in gomplate v2.0.0

Usage

data.ToYAML obj

obj | data.ToYAML

Arguments

Examples

This is obviously contrived - data.JSON is used to create an object.

input.tmpl:

{{ (`{"foo":{"hello":"world"}}` | data.JSON).foo | data.ToYAML }}

$ gomplate < input.tmpl
hello: world

data.ToTOML

Alias: toTOML

Converts an object to a TOML document.

Added in gomplate v2.0.0

Usage

data.ToTOML obj

obj | data.ToTOML

Arguments

Examples

$ gomplate -i '{{ `{"foo":"bar"}` | data.JSON | data.ToTOML }}'
foo = "bar"

data.ToCSV

Alias: toCSV

Converts an object to a CSV document. The input object must be a 2-dimensional array of strings (a [][]string). Objects produced by data.CSVByRow and data.CSVByColumn cannot yet be converted back to CSV documents.

Note: With the exception that a custom delimiter can be used, data.ToCSV outputs according to the RFC 4180 format, which means that line terminators are CRLF (Windows format, or \r\n). If you require LF (UNIX format, or \n), the output can be piped through strings.ReplaceAll to replace "\r\n" with "\n".

Added in gomplate v2.0.0

Usage

data.ToCSV [delim] input

input | data.ToCSV [delim]

Arguments

Examples

input.tmpl:

{{ $rows := (jsonArray `[["first","second"],["1","2"],["3","4"]]`) -}}
{{ data.ToCSV ";" $rows }}

$ gomplate -f input.tmpl
first,second
1,2
3,4

data.ToCUE(unreleased)

Unreleased: This function is in development, and not yet available in released builds of gomplate.

Alias: toCUE

Converts an object to a CUE document in canonical format. The input object can be of any type.

This is roughly equivalent to using the cue export --out=cue <file> command to convert from other formats to CUE.

Usage

data.ToCUE input

input | data.ToCUE

Arguments

Examples

$ gomplate -i '{{ `{"foo":"bar"}` | data.JSON | data.ToCUE }}'
{
	foo: "bar"
}

$ gomplate -i '{{ toCUE "hello world" }}'
"hello world"

$ gomplate -i '{{ coll.Slice 1 "two" true | data.ToCUE }}'
[1, "two", true]