New random namespace for generating random strings and numbers

Signed-off-by: Dave Henderson <dhenderson@gmail.com>

1 files changed, 169 insertions, 0 deletions

diff --git a/docs-src/content/functions/random.yml b/docs-src/content/functions/random.yml
new file mode 100644
index 00000000..b4f8c4cd
--- /dev/null
+++ b/docs-src/content/functions/random.yml
@@ -0,0 +1,169 @@
+ns: random
+title: random functions
+preamble: |
+  Functions for generating random values.
+
+  ### About randomness
+
+  `gomplate` uses Go's [`math/rand`](https://golang.org/pkg/math/rand/) package
+  to generate pseudo-random numbers. Note that these functions are not suitable
+  for use in security-sensitive applications, such as cryptography. However,
+  these functions will not deplete system entropy.
+funcs:
+  - name: random.ASCII
+    description: |
+      Generates a random string of a desired length, containing the set of
+      printable characters from the 7-bit [ASCII](https://en.wikipedia.org/wiki/ASCII)
+      set. This includes _space_ (' '), but no other whitespace characters.
+    pipeline: false
+    arguments:
+      - name: count
+        required: true
+        description: the length of the string to produce (number of characters)
+    examples:
+      - |
+        $ gomplate -i '{{ random.ASCII 8 }}'
+        _woJ%D&K
+  - name: random.Alpha
+    description: |
+      Generates a random alphabetical (`A-Z`, `a-z`) string of a desired length.
+    pipeline: false
+    arguments:
+      - name: count
+        required: true
+        description: the length of the string to produce (number of characters)
+    examples:
+      - |
+        $ gomplate -i '{{ random.Alpha 42 }}'
+        oAqHKxHiytYicMxTMGHnUnAfltPVZDhFkVkgDvatJK
+  - name: random.AlphaNum
+    description: |
+      Generates a random alphanumeric (`0-9`, `A-Z`, `a-z`) string of a desired length.
+    pipeline: false
+    arguments:
+      - name: count
+        required: true
+        description: the length of the string to produce (number of characters)
+    examples:
+      - |
+        $ gomplate -i '{{ random.AlphaNum 16 }}'
+        4olRl9mRmVp1nqSm
+  - name: random.String
+    description: |
+      Generates a random string of a desired length.
+      
+      By default, the possible characters are those represented by the
+      regular expression `[a-zA-Z0-9_.-]` (alphanumeric, plus `_`, `.`, and `-`).
+
+      A different set of characters can be specified with a regular expression,
+      or by giving a range of possible characters by specifying the lower and
+      upper bounds. Lower/upper bounds can be specified as characters (e.g.
+      `"q"`, or escape sequences such as `"\U0001f0AF"`), or numeric Unicode
+      code-points (e.g. `48` or `0x30` for the character `0`).
+
+      When given a range of Unicode code-points, `random.String` will discard
+      non-printable characters from the selection. This may result in a much
+      smaller set of possible characters than intended, so check
+      the [Unicode character code charts](http://www.unicode.org/charts/) to
+      verify the correct code-points.
+    pipeline: false
+    arguments:
+      - name: count
+        required: true
+        description: the length of the string to produce (number of characters)
+      - name: regex
+        required: false
+        description: the regular expression that each character must match (defaults to `[a-zA-Z0-9_.-]`)
+      - name: lower
+        required: false
+        description: lower bound for a range of characters (number or single character)
+      - name: upper
+        required: false
+        description: upper bound for a range of characters (number or single character)
+    examples:
+      - |
+        $ gomplate -i '{{ random.String 8 }}'
+        FODZ01u_
+      - |
+        $ gomplate -i '{{ random.String 16 `[[:xdigit:]]` }}'
+        B9e0527C3e45E1f3
+      - |
+        $ gomplate -i '{{ random.String 20 `[\p{Canadian_Aboriginal}]` }}'
+        ᗄᖖᣡᕔᕫᗝᖴᒙᗌᘔᓰᖫᗵᐕᗵᙔᗠᓅᕎᔹ
+      - |
+        $ gomplate -i '{{ random.String 8 "c" "m" }}'
+        ffmidgjc
+      - |
+        $ gomplate -i 'You rolled... {{ random.String 3 "⚀" "⚅" }}'
+        You rolled... ⚅⚂⚁
+      - |
+        $ gomplate -i 'Poker time! {{ random.String 5 "\U0001f0a1" "\U0001f0de" }}'
+        Poker time! 🂼🂺🂳🃅🂪
+  - name: random.Item
+    description: |
+      Pick an element at a random from a given slice or array.
+    pipeline: true
+    arguments:
+      - name: items
+        required: true
+        description: the input array
+    examples:
+      - |
+        $ gomplate -i '{{ random.Item (seq 0 5) }}'
+        4
+      - |
+        $ export SLICE='["red", "green", "blue"]'
+        $ gomplate -i '{{ getenv "SLICE" | jsonArray | random.Item }}'
+        blue
+  - name: random.Number
+    description: |
+      Pick a random integer. By default, a number between `0` and `100`
+      (inclusive) is chosen, but this range can be overridden.
+
+      Note that the difference between `min` and `max` can not be larger than a
+      63-bit integer (i.e. the unsigned portion of a 64-bit signed integer).
+      The result is given as an `int64`.
+    pipeline: false
+    arguments:
+      - name: min
+        required: false
+        description: The minimum value, defaults to `0`. Must be less than `max`.
+      - name: max
+        required: false
+        description: The maximum value, defaults to `100` (if no args provided)
+    examples:
+      - |
+        $ gomplate -i '{{ random.Number }}'
+        55
+      - |
+        $ gomplate -i '{{ random.Number -10 10 }}'
+        -3
+      - |
+        $ gomplate -i '{{ random.Number 5 }}'
+        2
+  - name: random.Float
+    description: |
+      Pick a random decimal floating-point number. By default, a number between
+      `0.0` and `1.0` (_exclusive_, i.e. `[0.0,1.0)`) is chosen, but this range
+      can be overridden.
+
+      The result is given as a `float64`.
+    pipeline: false
+    arguments:
+      - name: min
+        required: false
+        description: The minimum value, defaults to `0.0`. Must be less than `max`.
+      - name: max
+        required: false
+        description: The maximum value, defaults to `1.0` (if no args provided).
+    examples:
+      - |
+        $ gomplate -i '{{ random.Float }}'
+        0.2029946480303966
+      - |
+        $ gomplate -i '{{ random.Float 100 }}'  
+        71.28595374161743
+      - |
+        $ gomplate -i '{{ random.Float -100 200 }}'
+        105.59119437834909
+        
\ No newline at end of file