diff --git a/docs/templates.md b/docs/templates.md index 1687da8..943ce1e 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -4,157 +4,170 @@ Templates are written in Go's [`text/template`](http://golang.org/pkg/text/templ [[_TOC_]] +## Flat key/value caveats and considerations + +Because the [templates only see a flat list of key/value pairs](../README.md#getv-templates), certain operations will behave differently than the CLI (notably `getv` itself). +Take the following yaml for example: + +```yaml +credentials: + username: foo + password: bar +``` + +Would be seen by inside the templates as: + +```yaml +/credentials/username: foo +/credentials/password: bar +``` + +In a template, `getv` (and similar value-based functions) can only "see" full keys (e.g. `/credentials/username`). +Asking a template for a partial key (e.g. `/credentials`) will fail. +Additional functions, like `ls` and `lsdir` can provide access to inspecting and ranging on sub-keys. + +## Wildcards + +Some commands allow for wildcard key matching using `*`. +A `*` does not match `/`. +Multiple `*` are allowed such as `/foo/*/bar/*`. + ## Template Functions ### add Adds two int values. -```text -{{add 1 3}} +```console +$ clconf getv / --template-string '{{add 1 3}}' +4 ``` ### asJsonString -Converts the supplied value to a properly encoded JSON string. For any value that is not currently of type string, `fmt.Sprintf("%v", value)` will be used to convert prior to encoding. This should only be used on _leaf_ values. +Converts the supplied value to a properly encoded JSON string. +For any value that is not currently of type string, `fmt.Sprintf("%v", value)` will be used to convert prior to encoding. -```text -{{printf "{\"key\": %s}" (asJsonString (getv "/some/value"))}} +```console +$ clconf --pipe getv / --template-string '{{printf "{\"safeforjson\": %s}" (asJsonString (getv "/notsafeforjson"))}}' <: error calling get: /foo/*: key does not exist +``` + +[Caveat's apply](#flat-keyvalue-caveats-and-considerations): + +```console +$ clconf --pipe getv / --template-string '{{with get "/foo"}}k: {{.Key}}, v: {{.Value}}{{end}}' <: error calling get: /foo: key does not exist ``` ### getenv Wrapper for [os.Getenv](https://golang.org/pkg/os/#Getenv). Retrieves the value of the environment variable named by the key. It returns the value, which will be empty if the variable is not present. Optionally, you can give a default value that will be returned if the key is not present. -```text -export HOSTNAME=`hostname` -``` +```console +MYENV=foo clconf getv / --template-string '[{{getenv "MYENV"}}]' +[foo] -```text -hostname: {{getenv "HOSTNAME"}} -``` +$ MYENV= clconf getv / --template-string '[{{getenv "MYENV"}}]' +[] -#### getenv with a default value +# Default used when defined and empty +$ MYENV= clconf getv / --template-string '[{{getenv "MYENV" "adefault"}}]' +[adefault] -```text -ipaddr: {{getenv "HOST_IP" "127.0.0.1"}} +$ clconf getv / --template-string '[{{getenv "MYENV" "adefault"}}]' +[adefault] + +# Does not fail if not defined +$ clconf getv / --template-string '[{{getenv "MYENV"}}]' +[] ``` ### getksvs -Returns all values, []string, where key matches its argument, sorted by key. Optionally specify `int` to sort the values as integers. Returns an error if key is not found. +Returns all values, []string, where key matches its argument, sorted by key. +Specify optional argument `int` to sort the keys as integers. +Returns an error if key is not found. +Wildcards are allowed. Preserve the order of list inputs: -```bash +```console $ clconf --pipe getv --template-string '{{getksvs "/foo/*" "int"}}' <: error calling getv: /foo/hip: key does not exist ``` -#### With a default value +[Caveat's apply](#flat-keyvalue-caveats-and-considerations): -```text -value: {{getv "/key" "default_value"}} +```console +$ clconf --pipe getv / --template-string '{{getv "/foo"}}' <: error calling getv: /foo: key does not exist ``` ### getvs -Returns all values, []string, where key matches its argument. Returns an error if key is not found. +Returns all values, []string, where key matches its argument, string-sorted. +Wildcard required. -```text -{{range getvs "/*"}} - value: {{.}} -{{end}} +```console +$ clconf --pipe getv / --template-string '{{getvs "/foo/*"}}' < %s\n" .}}{{- end -}} -{{- range lsdir "/foo" -}}{{printf "/foo -> %s\n" .}}{{- end -}} -{{- range lsdir "/foo/hip" -}}{{printf "/foo/hip -> %s\n" .}}{{- end -}} -``` + zap: bop +EOF +[hip,zip] -Would print: +$ clconf --pipe getv / --template-string '[{{join (lsdir "/foo/hip") ","}}]' < foo -/foo -> hip -/foo -> zap -/foo -> zip -/foo/hip -> 0 -/foo/hip -> 1 +# No results here because /foo/zip/zap would be a full key +$ clconf --pipe getv / --template-string '[{{join (lsdir "/foo/zip") ","}}]' <: error calling parseBool: strconv.ParseBool: parsing "R": invalid syntax + +$ clconf getv / --template-string '{{parseBool "-1"}}' +Error: template execute: execute template: template: cli:1:2: executing "cli" at : error calling parseBool: strconv.ParseBool: parsing "-1": invalid syntax + +$ clconf getv / --template-string '{{parseBool "0"}}' +false +``` + ### regexReplace Given a regex, an original string and a replacement string run [`regexp.ReplaceAllString`](https://golang.org/pkg/regexp/#Regexp.ReplaceAllString) and return the result. Returns an error if the regex fails to compile. -```bash +```console $ clconf --pipe getv --template-string '{{regexReplace "o+" "foo" "e"}}' < /dev/null fe ``` @@ -440,9 +760,12 @@ fe Alias for the [strings.Replace](https://golang.org/pkg/strings/#Replace) function. -```text -{{$backend := getv "/services/backend/nginx"}} -backend = {{replace $backend "-" "_" -1}} +```console +$ clconf getv / --template-string '{{replace "foo" "o" "e" -1}}' +fee + +$ clconf getv / --template-string '{{replace "foo" "o" "e" 1}}' +feo ``` ### reverse @@ -453,11 +776,25 @@ Reverses a list. If the list is `KVPair`, will compare keys, not values. Alias for the [template.Seq](https://golang.org/pkg/template/#Seq) function. +```console +$ clconf getv / --template-string '{{range (seq 1 10) }}{{.}}{{"\n"}}{{end}}' +1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +``` + ### sort Sorts the input ([]interface{}) by translating it to the specified type (one of `int`, `string`, default: `string`) -```bash +```console clconf --pipe getv --template-string '{{sort (getvs "/foo/*") }}' <