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