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