github.com/hairyhenderson/gomplate/v4@v4.0.0-pre-2.0.20240520121557-362f058f0c93/docs-src/content/functions/random.yml (about)

     1  ns: random
     2  title: random functions
     3  preamble: |
     4    Functions for generating random values.
     5  
     6    ### About randomness
     7  
     8    `gomplate` uses Go's [`math/rand`](https://golang.org/pkg/math/rand/) package
     9    to generate pseudo-random numbers. Note that these functions are not suitable
    10    for use in security-sensitive applications, such as cryptography. However,
    11    these functions will not deplete system entropy.
    12  funcs:
    13    - name: random.ASCII
    14      released: v3.4.0
    15      description: |
    16        Generates a random string of a desired length, containing the set of
    17        printable characters from the 7-bit [ASCII](https://en.wikipedia.org/wiki/ASCII)
    18        set. This includes _space_ (' '), but no other whitespace characters.
    19      pipeline: false
    20      arguments:
    21        - name: count
    22          required: true
    23          description: the length of the string to produce (number of characters)
    24      examples:
    25        - |
    26          $ gomplate -i '{{ random.ASCII 8 }}'
    27          _woJ%D&K
    28    - name: random.Alpha
    29      released: v3.4.0
    30      description: |
    31        Generates a random alphabetical (`A-Z`, `a-z`) string of a desired length.
    32      pipeline: false
    33      arguments:
    34        - name: count
    35          required: true
    36          description: the length of the string to produce (number of characters)
    37      examples:
    38        - |
    39          $ gomplate -i '{{ random.Alpha 42 }}'
    40          oAqHKxHiytYicMxTMGHnUnAfltPVZDhFkVkgDvatJK
    41    - name: random.AlphaNum
    42      released: v3.4.0
    43      description: |
    44        Generates a random alphanumeric (`0-9`, `A-Z`, `a-z`) string of a desired length.
    45      pipeline: false
    46      arguments:
    47        - name: count
    48          required: true
    49          description: the length of the string to produce (number of characters)
    50      examples:
    51        - |
    52          $ gomplate -i '{{ random.AlphaNum 16 }}'
    53          4olRl9mRmVp1nqSm
    54    - name: random.String
    55      released: v3.4.0
    56      description: |
    57        Generates a random string of a desired length.
    58        
    59        By default, the possible characters are those represented by the
    60        regular expression `[a-zA-Z0-9_.-]` (alphanumeric, plus `_`, `.`, and `-`).
    61  
    62        A different set of characters can be specified with a regular expression,
    63        or by giving a range of possible characters by specifying the lower and
    64        upper bounds. Lower/upper bounds can be specified as characters (e.g.
    65        `"q"`, or escape sequences such as `"\U0001f0AF"`), or numeric Unicode
    66        code-points (e.g. `48` or `0x30` for the character `0`).
    67  
    68        When given a range of Unicode code-points, `random.String` will discard
    69        non-printable characters from the selection. This may result in a much
    70        smaller set of possible characters than intended, so check
    71        the [Unicode character code charts](http://www.unicode.org/charts/) to
    72        verify the correct code-points.
    73      pipeline: false
    74      arguments:
    75        - name: count
    76          required: true
    77          description: the length of the string to produce (number of characters)
    78        - name: regex
    79          required: false
    80          description: the regular expression that each character must match (defaults to `[a-zA-Z0-9_.-]`)
    81        - name: lower
    82          required: false
    83          description: lower bound for a range of characters (number or single character)
    84        - name: upper
    85          required: false
    86          description: upper bound for a range of characters (number or single character)
    87      examples:
    88        - |
    89          $ gomplate -i '{{ random.String 8 }}'
    90          FODZ01u_
    91        - |
    92          $ gomplate -i '{{ random.String 16 `[[:xdigit:]]` }}'
    93          B9e0527C3e45E1f3
    94        - |
    95          $ gomplate -i '{{ random.String 20 `[\p{Canadian_Aboriginal}]` }}'
    96          ᗄᖖᣡᕔᕫᗝᖴᒙᗌᘔᓰᖫᗵᐕᗵᙔᗠᓅᕎᔹ
    97        - |
    98          $ gomplate -i '{{ random.String 8 "c" "m" }}'
    99          ffmidgjc
   100        - |
   101          $ gomplate -i 'You rolled... {{ random.String 3 "⚀" "⚅" }}'
   102          You rolled... ⚅⚂⚁
   103        - |
   104          $ gomplate -i 'Poker time! {{ random.String 5 "\U0001f0a1" "\U0001f0de" }}'
   105          Poker time! 🂼🂺🂳🃅🂪
   106    - name: random.Item
   107      released: v3.4.0
   108      description: |
   109        Pick an element at a random from a given slice or array.
   110      pipeline: true
   111      arguments:
   112        - name: items
   113          required: true
   114          description: the input array
   115      examples:
   116        - |
   117          $ gomplate -i '{{ random.Item (seq 0 5) }}'
   118          4
   119        - |
   120          $ export SLICE='["red", "green", "blue"]'
   121          $ gomplate -i '{{ getenv "SLICE" | jsonArray | random.Item }}'
   122          blue
   123    - name: random.Number
   124      released: v3.4.0
   125      description: |
   126        Pick a random integer. By default, a number between `0` and `100`
   127        (inclusive) is chosen, but this range can be overridden.
   128  
   129        Note that the difference between `min` and `max` can not be larger than a
   130        63-bit integer (i.e. the unsigned portion of a 64-bit signed integer).
   131        The result is given as an `int64`.
   132      pipeline: false
   133      arguments:
   134        - name: min
   135          required: false
   136          description: The minimum value, defaults to `0`. Must be less than `max`.
   137        - name: max
   138          required: false
   139          description: The maximum value, defaults to `100` (if no args provided)
   140      examples:
   141        - |
   142          $ gomplate -i '{{ random.Number }}'
   143          55
   144        - |
   145          $ gomplate -i '{{ random.Number -10 10 }}'
   146          -3
   147        - |
   148          $ gomplate -i '{{ random.Number 5 }}'
   149          2
   150    - name: random.Float
   151      released: v3.4.0
   152      description: |
   153        Pick a random decimal floating-point number. By default, a number between
   154        `0.0` and `1.0` (_exclusive_, i.e. `[0.0,1.0)`) is chosen, but this range
   155        can be overridden.
   156  
   157        The result is given as a `float64`.
   158      pipeline: false
   159      arguments:
   160        - name: min
   161          required: false
   162          description: The minimum value, defaults to `0.0`. Must be less than `max`.
   163        - name: max
   164          required: false
   165          description: The maximum value, defaults to `1.0` (if no args provided).
   166      examples:
   167        - |
   168          $ gomplate -i '{{ random.Float }}'
   169          0.2029946480303966
   170        - |
   171          $ gomplate -i '{{ random.Float 100 }}'  
   172          71.28595374161743
   173        - |
   174          $ gomplate -i '{{ random.Float -100 200 }}'
   175          105.59119437834909
   176