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