From c60bcd69b543d399e8cfce23130b2e05bdb01618 Mon Sep 17 00:00:00 2001 From: Dave Henderson Date: Tue, 11 Sep 2018 22:57:32 -0400 Subject: Improve docs for conv namespace Signed-off-by: Dave Henderson --- docs/content/functions/conv.md | 322 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 284 insertions(+), 38 deletions(-) (limited to 'docs') diff --git a/docs/content/functions/conv.md b/docs/content/functions/conv.md index 0cc2cf31..0c8bffc1 100644 --- a/docs/content/functions/conv.md +++ b/docs/content/functions/conv.md @@ -16,7 +16,22 @@ to another - generally from a `string` to something else, and vice-versa. Converts a true-ish string to a boolean. Can be used to simplify conditional statements based on environment variables or other text input. -#### Example +### Usage +```go +conv.Bool in +``` + +```go +in | conv.Bool +``` + +### Arguments + +| name | description | +|------|-------------| +| `in` | _(required)_ the input string | + +### Examples _`input.tmpl`:_ ``` @@ -41,7 +56,23 @@ Note that this will not provide a default for the case where the input is undefi (i.e. referencing things like `.foo` where there is no `foo` field of `.`), but [`conv.Has`](#conv-has) can be used for that. -#### Example +### Usage +```go +conv.Default default in +``` + +```go +in | conv.Default default +``` + +### Arguments + +| name | description | +|------|-------------| +| `default` | _(required)_ the default value | +| `in` | _(required)_ the input | + +### Examples ```console $ gomplate -i '{{ "" | default "foo" }} {{ "bar" | default "baz" }}' @@ -101,19 +132,23 @@ Hello everybody! **Alias:** `slice` -Creates a slice. Useful when needing to `range` over a bunch of variables. +Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables. -#### Example - -_`input.tmpl`:_ -``` -{{range slice "Bart" "Lisa" "Maggie"}} -Hello, {{.}} -{{- end}} +### Usage +```go +conv.Slice in... ``` +### Arguments + +| name | description | +|------|-------------| +| `in...` | _(required)_ the elements of the slice | + +### Examples + ```console -$ gomplate < input.tmpl +$ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}' Hello, Bart Hello, Lisa Hello, Maggie @@ -127,7 +162,7 @@ Reports whether a given object has a property with the given key, or whether a g ### Usage ```go -conv.Has in item +conv.Has in item ``` ### Arguments @@ -140,18 +175,15 @@ conv.Has in item ### Examples ```console -$ gomplate -i '{{ $l := slice "foo" "bar" "baz" -}} -there is {{ if has $l "bar" }}a{{else}}no{{end}} bar' +$ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar' there is a bar ``` - ```console $ export DATA='{"foo": "bar"}' $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}} {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}' bar ``` - ```console $ export DATA='{"baz": "qux"}' $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}} @@ -163,29 +195,45 @@ THERE IS NO FOO **Alias:** `join` -Concatenates the elements of an array to create a string. The separator string sep is placed between elements in the resulting string. - -#### Example +Concatenates the elements of an array to create a string. The separator string `sep` is placed between elements in the resulting string. -_`input.tmpl`_ -``` -{{ $a := `[1, 2, 3]` | jsonArray }} -{{ join $a "-" }} +### Usage +```go +conv.Join in sep ``` +### Arguments + +| name | description | +|------|-------------| +| `in` | _(required)_ the array or slice | +| `sep` | _(required)_ the separator | + +### Examples + ```console -$ gomplate -f input.tmpl +$ gomplate -i '{{ $a := 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](https://golang.org/pkg/net/url/#Parse) -#### Example +### Usage +```go +conv.URL in +``` + +### Arguments + +| name | description | +|------|-------------| +| `in` | _(required)_ the URL string to parse | + +### Examples _`input.tmpl`:_ ``` @@ -204,9 +252,12 @@ The path is /foo/bar ## `conv.ParseInt` -Parses a string as an int64 for later use. Equivalent to [strconv.ParseInt](https://golang.org/pkg/strconv/#ParseInt) +_**Note:**_ See [`conv.ToInt64`](#conv-toint64) instead for a simpler and more flexible variant of this function. + +Parses a string as an int64. Equivalent to [strconv.ParseInt](https://golang.org/pkg/strconv/#ParseInt) -#### Example + +### Examples _`input.tmpl`:_ ``` @@ -222,9 +273,12 @@ The value in decimal is 1984 ## `conv.ParseFloat` +_**Note:**_ See [`conv.ToFloat`](#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](https://golang.org/pkg/strconv/#ParseFloat) -#### Example + +### Examples _`input.tmpl`:_ ``` @@ -243,6 +297,9 @@ pi is greater than 3 Parses a string as an uint64 for later use. Equivalent to [strconv.ParseUint](https://golang.org/pkg/strconv/#ParseUint) + +### Examples + _`input.tmpl`:_ ``` {{ conv.ParseInt (getenv "BIG") 16 64 }} is max int64 @@ -257,8 +314,13 @@ $ BIG=FFFFFFFFFFFFFFFF gomplate < input.tmpl ## `conv.Atoi` +_**Note:**_ See [`conv.ToInt`](#conv-toint) and [`conv.ToInt64`](#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](https://golang.org/pkg/strconv/#Atoi) + +### Examples + _`input.tmpl`:_ ``` {{ $number := conv.Atoi (getenv "NUMBER") }} @@ -284,6 +346,7 @@ Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"` ```go conv.ToBool input ``` + ```go input | conv.ToBool ``` @@ -335,42 +398,225 @@ $ gomplate -i '{{ conv.ToBools false "blah" 0 }}' ## `conv.ToInt64` -Converts the input to an `int64`. +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. + +### Usage +```go +conv.ToInt64 in +``` + +### Arguments + +| name | description | +|------|-------------| +| `in` | _(required)_ the value to convert | + +### Examples ```console $ gomplate -i '{{conv.ToInt64 "9223372036854775807"}}' 9223372036854775807 ``` +```console +$ gomplate -i '{{conv.ToInt64 "0x42"}}' +66 +``` +```console +$ gomplate -i '{{conv.ToInt64 true }}' +1 +``` ## `conv.ToInt` -Converts the input to an `int`. This is similar to `conv.Atoi`, but handles booleans and numbers as well as strings. +Converts the input to an `int` (signed integer, 32- or 64-bit depending +on platform). This is similar to [`conv.ToInt64`](#conv-toint64) on 64-bit +platforms, but is useful when input to another function must be provided +as an `int`. + +See also [`conv.ToInt64`](#conv-toint64). + +### Usage +```go +conv.ToInt in +``` + +### Arguments + +| name | description | +|------|-------------| +| `in` | _(required)_ the value to convert | + +### Examples ```console -$ gomplate -i '{{conv.ToInt (gt 1 2)}}' -0 +$ gomplate -i '{{conv.ToInt "9223372036854775807"}}' +9223372036854775807 +``` +```console +$ gomplate -i '{{conv.ToInt "0x42"}}' +66 +``` +```console +$ gomplate -i '{{conv.ToInt true }}' +1 ``` ## `conv.ToInt64s` -Converts the inputs to an array of `int64`s +Converts the inputs to an array of `int64`s. + +This delegates to [`conv.ToInt64`](#conv-toint64) for each input argument. + +### Usage +```go +conv.ToInt64s in... +``` + +### Arguments + +| name | description | +|------|-------------| +| `in...` | _(required)_ the inputs to be converted | + +### Examples + +```console +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 `int`s +Converts the inputs to an array of `int`s. + +This delegates to [`conv.ToInt`](#conv-toint) for each input argument. + +### Usage +```go +conv.ToInts in... +``` + +### Arguments + +| name | description | +|------|-------------| +| `in...` | _(required)_ the inputs to be converted | + +### Examples + +```console +gomplate -i '{{ conv.ToInts true 0x42 "123,456.99" "1.2345e+3"}}' +[1 66 123456 1234] +``` ## `conv.ToFloat64` -Converts the input to a `float64` +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`. + +### Usage +```go +conv.ToFloat64 in +``` + +### Arguments + +| name | description | +|------|-------------| +| `in` | _(required)_ the value to convert | + +### Examples + +```console +$ 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 `float64`s +Converts the inputs to an array of `float64`s. + +This delegates to [`conv.ToFloat64`](#conv-tofloat64) for each input argument. + +### Usage +```go +conv.ToFloat64s in... +``` + +### Arguments + +| name | description | +|------|-------------| +| `in...` | _(required)_ the inputs to be converted | + +### Examples + +```console +$ 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` +Converts the input (of any type) to a `string`. + +The input will always be represented in _some_ way. + +### Usage +```go +conv.ToString in +``` + +### Arguments + +| name | description | +|------|-------------| +| `in` | _(required)_ the value to convert | + +### Examples + +```console +$ 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 `string`s + +This delegates to [`conv.ToString`](#conv-tostring) for each input argument. + +### Usage +```go +conv.ToStrings in... +``` + +### Arguments + +| name | description | +|------|-------------| +| `in...` | _(required)_ the inputs to be converted | + +### Examples + +```console +$ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (slice 1 2 3) }}' +[nil 42 true 15 [1 2 3]] +``` -- cgit v1.2.3