data functions

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

datasource

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.

Usage

datasource alias [subpath]

Arguments

name description
alias the datasource alias (or a URL for dynamic use)
subpath (optional) the subpath to use, if supported by the datasource

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.

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

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

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.

Usage

defineDatasource alias url

Arguments

name description
alias the datasource alias
url the datasource’s URL

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

ds

Alias to datasource

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.

Usage

include alias [subpath]

Arguments

name description
alias the datasource alias, as provided by --datasource/-d
subpath (optional) the subpath to use, if supported by the datasource

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. Only works for JSON Objects (not Arrays or other valid JSON types). This can be used to access properties of JSON objects.

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.

Usage

data.JSON in
in | data.JSON

Arguments

name description
in (required) the input string

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.

Example

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. Only works for YAML Objects (not Arrays or other valid YAML types). This can be used to access properties of YAML objects.

Example

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.

Example

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.

Usage

toml input

Can also be used in a pipeline:

input | toml

Arguments

name description
input the TOML document to parse

Example

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.

Usage

csv [delim] input

Can also be used in a pipeline:

input | csv [delim]

Arguments

name description
delim (optional) the (single-character!) field delimiter, defaults to ","
input the CSV-format string to parse

Example

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.

Usage

csv [delim] [header] input

Can also be used in a pipeline:

input | csv [delim] [header]

Arguments

name description
delim (optional) the (single-character!) field delimiter, defaults to ","
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
input the CSV-format string to parse

Example

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.

Example

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

Example

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.

Example

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.

Example

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.

Usage

data.ToTOML obj

Can also be used in a pipeline:

obj | data.ToTOML

Arguments

name description
obj the object to marshal as a TOML document

Example

$ 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".

Usage

data.ToCSV [delim] input

Can also be used in a pipeline:

input | data.ToCSV [delim]

Arguments

name description
delim (optional) the (single-character!) field delimiter, defaults to ","
input the object to convert to a CSV

Examples

input.tmpl:

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