github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs-src/content/functions/conv.yml (about)

     1  ns: conv
     2  title: conversion functions
     3  preamble: |
     4    These are a collection of functions that mostly help converting from one type
     5    to another - generally from a `string` to something else, and vice-versa.
     6  funcs:
     7    - name: conv.Bool
     8      alias: bool
     9      description: |
    10        **Note:** See also [`conv.ToBool`](#conv-tobool) for a more flexible variant.
    11  
    12        Converts a true-ish string to a boolean. Can be used to simplify conditional statements based on environment variables or other text input.
    13      pipeline: true
    14      arguments:
    15        - name: in
    16          required: true
    17          description: the input string
    18      rawExamples:
    19        - |
    20          _`input.tmpl`:_
    21          ```
    22          {{if bool (getenv "FOO")}}foo{{else}}bar{{end}}
    23          ```
    24  
    25          ```console
    26          $ gomplate < input.tmpl
    27          bar
    28          $ FOO=true gomplate < input.tmpl
    29          foo
    30          ```
    31    - name: conv.Default
    32      alias: default
    33      description: |
    34        Provides a default value given an empty input. Empty inputs are `0` for numeric
    35        types, `""` for strings, `false` for booleans, empty arrays/maps, and `nil`.
    36  
    37        Note that this will not provide a default for the case where the input is undefined
    38        (i.e. referencing things like `.foo` where there is no `foo` field of `.`), but
    39        [`conv.Has`](#conv-has) can be used for that.
    40      pipeline: true
    41      arguments:
    42        - name: default
    43          required: true
    44          description: the default value
    45        - name: in
    46          required: true
    47          description: the input
    48      examples:
    49        - |
    50          $ gomplate -i '{{ "" | default "foo" }} {{ "bar" | default "baz" }}'
    51          foo bar
    52    - name: conv.Dict
    53      deprecated: Renamed to [`coll.Dict`](#coll-dict)
    54      alias: dict
    55      description: |
    56        Dict is a convenience function that creates a map with string keys.
    57        Provide arguments as key/value pairs. If an odd number of arguments
    58        is provided, the last is used as the key, and an empty string is
    59        set as the value.
    60  
    61        All keys are converted to strings.
    62  
    63        This function is equivalent to [Sprig's `dict`](http://masterminds.github.io/sprig/dicts.html#dict)
    64        function, as used in [Helm templates](https://docs.helm.sh/chart_template_guide#template-functions-and-pipelines).
    65  
    66        For creating more complex maps, see [`data.JSON`](../data/#data-json) or [`data.YAML`](../data/#data-yaml).
    67  
    68        For creating arrays, see [`conv.Slice`](#conv-slice).
    69      arguments:
    70        - name: in...
    71          required: true
    72          description: The key/value pairs
    73      examples:
    74        - |
    75          $ gomplate -i '{{ conv.Dict "name" "Frank" "age" 42 | data.ToYAML }}'
    76          age: 42
    77          name: Frank
    78          $ gomplate -i '{{ dict 1 2 3 | toJSON }}'
    79          {"1":2,"3":""}
    80        - |
    81          $ cat <<EOF| gomplate
    82          {{ define "T1" }}Hello {{ .thing }}!{{ end -}}
    83          {{ template "T1" (dict "thing" "world")}}
    84          {{ template "T1" (dict "thing" "everybody")}}
    85          EOF
    86          Hello world!
    87          Hello everybody!
    88    - name: conv.Slice
    89      deprecated: Renamed to [`coll.Slice`](#coll-slice)
    90      alias: slice
    91      description: |
    92        Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables.
    93      pipeline: false
    94      arguments:
    95        - name: in...
    96          required: true
    97          description: the elements of the slice
    98      examples:
    99        - |
   100          $ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
   101          Hello, Bart
   102          Hello, Lisa
   103          Hello, Maggie
   104    - name: conv.Has
   105      deprecated: Renamed to [`coll.Has`](#coll-has)
   106      alias: has
   107      description: |
   108        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.
   109      pipeline: false
   110      arguments:
   111        - name: in
   112          required: true
   113          description: The object or list to search
   114        - name: item
   115          required: true
   116          description: The item to search for
   117      examples:
   118        - |
   119          $ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
   120          there is a bar
   121        - |
   122          $ export DATA='{"foo": "bar"}'
   123          $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
   124          {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
   125          bar
   126        - |
   127          $ export DATA='{"baz": "qux"}'
   128          $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
   129          {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
   130          THERE IS NO FOO
   131    - name: conv.Join
   132      alias: join
   133      description: |
   134        Concatenates the elements of an array to create a string. The separator string `sep` is placed between elements in the resulting string.
   135      arguments:
   136        - name: in
   137          required: true
   138          description: the array or slice
   139        - name: sep
   140          required: true
   141          description: the separator
   142      examples:
   143        - |
   144          $ gomplate -i '{{ $a := slice 1 2 3 }}{{ join $a "-" }}'
   145          1-2-3
   146    - name: conv.URL
   147      alias: urlParse
   148      description: |
   149        Parses a string as a URL for later use. Equivalent to [url.Parse](https://golang.org/pkg/net/url/#Parse)
   150      arguments:
   151        - name: in
   152          required: true
   153          description: the URL string to parse
   154      rawExamples:
   155        - |
   156          _`input.tmpl`:_
   157          ```
   158          {{ $u := conv.URL "https://example.com:443/foo/bar" }}
   159          The scheme is {{ $u.Scheme }}
   160          The host is {{ $u.Host }}
   161          The path is {{ $u.Path }}
   162          ```
   163  
   164          ```console
   165          $ gomplate < input.tmpl
   166          The scheme is https
   167          The host is example.com:443
   168          The path is /foo/bar
   169          ```
   170    - name: conv.ParseInt
   171      description: |
   172        _**Note:**_ See [`conv.ToInt64`](#conv-toint64) instead for a simpler and more flexible variant of this function.
   173  
   174        Parses a string as an int64. Equivalent to [strconv.ParseInt](https://golang.org/pkg/strconv/#ParseInt)
   175      rawExamples:
   176        - |
   177          _`input.tmpl`:_
   178          ```
   179          {{ $val := conv.ParseInt (getenv "HEXVAL") 16 32 }}
   180          The value in decimal is {{ $val }}
   181          ```
   182  
   183          ```console
   184          $ HEXVAL=7C0 gomplate < input.tmpl
   185  
   186          The value in decimal is 1984
   187          ```
   188    - name: conv.ParseFloat
   189      description: |
   190        _**Note:**_ See [`conv.ToFloat`](#conv-tofloat) instead for a simpler and more flexible variant of this function.
   191  
   192        Parses a string as an float64 for later use. Equivalent to [strconv.ParseFloat](https://golang.org/pkg/strconv/#ParseFloat)
   193      rawExamples:
   194        - |
   195          _`input.tmpl`:_
   196          ```
   197          {{ $pi := conv.ParseFloat (getenv "PI") 64 }}
   198          {{- if (gt $pi 3.0) -}}
   199          pi is greater than 3
   200          {{- end }}
   201          ```
   202  
   203          ```console
   204          $ PI=3.14159265359 gomplate < input.tmpl
   205          pi is greater than 3
   206          ```
   207    - name: conv.ParseUint
   208      description: |
   209        Parses a string as an uint64 for later use. Equivalent to [strconv.ParseUint](https://golang.org/pkg/strconv/#ParseUint)
   210      rawExamples:
   211        - |
   212          _`input.tmpl`:_
   213          ```
   214          {{ conv.ParseInt (getenv "BIG") 16 64 }} is max int64
   215          {{ conv.ParseUint (getenv "BIG") 16 64 }} is max uint64
   216          ```
   217  
   218          ```console
   219          $ BIG=FFFFFFFFFFFFFFFF gomplate < input.tmpl
   220          9223372036854775807 is max int64
   221          18446744073709551615 is max uint64
   222          ```
   223    - name: conv.Atoi
   224      description: |
   225        _**Note:**_ See [`conv.ToInt`](#conv-toint) and [`conv.ToInt64`](#conv-toint64) instead for simpler and more flexible variants of this function.
   226  
   227        Parses a string as an int for later use. Equivalent to [strconv.Atoi](https://golang.org/pkg/strconv/#Atoi)
   228      rawExamples:
   229        - |
   230          _`input.tmpl`:_
   231          ```
   232          {{ $number := conv.Atoi (getenv "NUMBER") }}
   233          {{- if (gt $number 5) -}}
   234          The number is greater than 5
   235          {{- else -}}
   236          The number is less than 5
   237          {{- end }}
   238          ```
   239  
   240          ```console
   241          $ NUMBER=21 gomplate < input.tmpl
   242          The number is greater than 5
   243          ```
   244    - name: conv.ToBool
   245      description: |
   246        Converts the input to a boolean value.
   247        Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"`
   248        (any capitalizations). All other values are considered `false`.
   249      pipeline: true
   250      arguments:
   251        - name: input
   252          required: true
   253          description: The input to convert
   254      examples:
   255        - |
   256          $ gomplate -i '{{ conv.ToBool "yes" }} {{ conv.ToBool true }} {{ conv.ToBool "0x01" }}'
   257          true true true
   258          $ gomplate -i '{{ conv.ToBool false }} {{ conv.ToBool "blah" }} {{ conv.ToBool 0 }}'
   259          false false false
   260    - name: conv.ToBools
   261      description: |
   262        Converts a list of inputs to an array of boolean values.
   263        Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"`
   264        (any capitalizations). All other values are considered `false`.
   265      pipeline: true
   266      arguments:
   267        - name: input
   268          required: true
   269          description: The input array to convert
   270      examples:
   271        - |
   272          $ gomplate -i '{{ conv.ToBools "yes" true "0x01" }}'
   273          [true true true]
   274          $ gomplate -i '{{ conv.ToBools false "blah" 0 }}'
   275          [false false false]
   276    - name: conv.ToInt64
   277      description: |
   278        Converts the input to an `int64` (64-bit signed integer).
   279  
   280        This function attempts to convert most types of input (strings, numbers,
   281        and booleans), but behaviour when the input can not be converted is
   282        undefined and subject to change. Unconvertable inputs may result in
   283        errors, or `0` or `-1`.
   284  
   285        Floating-point numbers (with decimal points) are truncated.
   286      arguments:
   287        - name: in
   288          required: true
   289          description: the value to convert
   290      examples:
   291        - |
   292          $ gomplate -i '{{conv.ToInt64 "9223372036854775807"}}'
   293          9223372036854775807
   294        - |
   295          $ gomplate -i '{{conv.ToInt64 "0x42"}}'
   296          66
   297        - |
   298          $ gomplate -i '{{conv.ToInt64 true }}'
   299          1
   300    - name: conv.ToInt
   301      description: |
   302        Converts the input to an `int` (signed integer, 32- or 64-bit depending
   303        on platform). This is similar to [`conv.ToInt64`](#conv-toint64) on 64-bit
   304        platforms, but is useful when input to another function must be provided
   305        as an `int`.
   306  
   307        See also [`conv.ToInt64`](#conv-toint64).
   308      arguments:
   309        - name: in
   310          required: true
   311          description: the value to convert
   312      examples:
   313        - |
   314          $ gomplate -i '{{conv.ToInt "9223372036854775807"}}'
   315          9223372036854775807
   316        - |
   317          $ gomplate -i '{{conv.ToInt "0x42"}}'
   318          66
   319        - |
   320          $ gomplate -i '{{conv.ToInt true }}'
   321          1
   322    - name: conv.ToInt64s
   323      description: |
   324        Converts the inputs to an array of `int64`s.
   325  
   326        This delegates to [`conv.ToInt64`](#conv-toint64) for each input argument.
   327      arguments:
   328        - name: in...
   329          required: true
   330          description: the inputs to be converted
   331      examples:
   332        - |
   333          gomplate -i '{{ conv.ToInt64s true 0x42 "123,456.99" "1.2345e+3"}}'
   334          [1 66 123456 1234]
   335    - name: conv.ToInts
   336      description: |
   337        Converts the inputs to an array of `int`s.
   338  
   339        This delegates to [`conv.ToInt`](#conv-toint) for each input argument.
   340      arguments:
   341        - name: in...
   342          required: true
   343          description: the inputs to be converted
   344      examples:
   345        - |
   346          gomplate -i '{{ conv.ToInts true 0x42 "123,456.99" "1.2345e+3"}}'
   347          [1 66 123456 1234]
   348    - name: conv.ToFloat64
   349      description: |
   350        Converts the input to a `float64`.
   351  
   352        This function attempts to convert most types of input (strings, numbers,
   353        and booleans), but behaviour when the input can not be converted is
   354        undefined and subject to change. Unconvertable inputs may result in
   355        errors, or `0` or `-1`.
   356      arguments:
   357        - name: in
   358          required: true
   359          description: the value to convert
   360      examples:
   361        - |
   362          $ gomplate -i '{{ conv.ToFloat64 "8.233e-1"}}'
   363          0.8233
   364          $ gomplate -i '{{ conv.ToFloat64 "9,000.09"}}'
   365          9000.09
   366    - name: conv.ToFloat64s
   367      description: |
   368        Converts the inputs to an array of `float64`s.
   369  
   370        This delegates to [`conv.ToFloat64`](#conv-tofloat64) for each input argument.
   371      arguments:
   372        - name: in...
   373          required: true
   374          description: the inputs to be converted
   375      examples:
   376        - |
   377          $ gomplate -i '{{ conv.ToFloat64s true 0x42 "123,456.99" "1.2345e+3"}}'
   378          [1 66 123456.99 1234.5]
   379    - name: conv.ToString
   380      description: |
   381        Converts the input (of any type) to a `string`.
   382  
   383        The input will always be represented in _some_ way.
   384      arguments:
   385        - name: in
   386          required: true
   387          description: the value to convert
   388      examples:
   389        - |
   390          $ gomplate -i '{{ conv.ToString 0xFF }}'
   391          255
   392          $ gomplate -i '{{ dict "foo" "bar" | conv.ToString}}'
   393          map[foo:bar]
   394          $ gomplate -i '{{ conv.ToString nil }}'
   395          nil
   396    - name: conv.ToStrings
   397      description: |
   398        Converts the inputs (of any type) to an array of `string`s
   399  
   400        This delegates to [`conv.ToString`](#conv-tostring) for each input argument.
   401      arguments:
   402        - name: in...
   403          required: true
   404          description: the inputs to be converted
   405      examples:
   406        - |
   407          $ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (slice 1 2 3) }}'
   408          [nil 42 true 15 [1 2 3]]