New uuid namespace

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

1 files changed, 82 insertions, 0 deletions

diff --git a/docs-src/content/functions/uuid.yml b/docs-src/content/functions/uuid.yml
new file mode 100644
index 00000000..54ea5e7d
--- /dev/null
+++ b/docs-src/content/functions/uuid.yml
@@ -0,0 +1,82 @@
+ns: uuid
+title: UUID functions
+preamble: |
+  Functions for generating, parsing, and manipulating UUIDs.
+
+  A UUID is a 128 bit (16 byte) _Universal Unique IDentifier_ as defined
+  in [RFC 4122][]. Only RFC 4112-variant UUIDs can be generated, but all variants
+  (even invalid ones) can be parsed and manipulated. Also, gomplate only supports
+  generating version 1 and 4 UUIDs (with 4 being the most commonly-used variety
+  these days). Versions 2, 3, and 5 are able to be supported: [log an issue][] if
+  this is required for your use-case.
+
+  [RFC 4122]: https://en.wikipedia.org/wiki/Universally_unique_identifier
+  [log an issue]: https://github.com/hairyhenderson/gomplate/issues/new
+funcs:
+  - name: uuid.V1
+    description: |
+      Create a version 1 UUID (based on the current MAC address and the current date/time).
+
+      Use [`uuid.V4`](#uuid-v4) instead in most cases.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{ uuid.V1 }}'
+        4d757e54-446d-11e9-a8fa-72000877c7b0
+  - name: uuid.V4
+    description: |
+      Create a version 4 UUID (randomly generated).
+
+      This function consumes entropy.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{ uuid.V4 }}'
+        40b3c2d2-e491-4b19-94cd-461e6fa35a60
+  - name: uuid.Nil
+    description: |
+      Returns the _nil_ UUID, that is, `00000000-0000-0000-0000-000000000000`,
+      mostly for testing scenarios.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{ uuid.Nil }}'
+        00000000-0000-0000-0000-000000000000
+  - name: uuid.IsValid
+    description: |
+      Checks that the given UUID is in the correct format. It does not validate
+      whether the version or variant are correct.
+    pipeline: true
+    arguments:
+      - name: uuid
+        required: true
+        description: The uuid to check
+    examples:
+      - |
+        $ gomplate -i '{{ if uuid.IsValid "totally invalid" }}valid{{ else }}invalid{{ end }}'
+        invalid
+      - |
+        $ gomplate -i '{{ uuid.IsValid "urn:uuid:12345678-90ab-cdef-fedc-ba9876543210" }}'
+        true
+  - name: uuid.Parse
+    description: |
+      Parse a UUID for further manipulation or inspection.
+
+      This function returns a `UUID` struct, as defined in the [github.com/google/uuid](https://godoc.org/github.com/google/uuid#UUID) package. See the docs for examples of functions or fields you can call.
+
+      Both the standard UUID forms of `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` and
+      `urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` are decoded as well as the
+      Microsoft encoding `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}` and the raw hex
+      encoding (`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`).
+    pipeline: true
+    arguments:
+      - name: uuid
+        required: true
+        description: The uuid to parse
+    examples:
+      - |
+        $ gomplate -i '{{ $u := uuid.Parse uuid.V4 }}{{ $u.Version }}, {{ $u.Variant}}'
+        VERSION_4, RFC4122
+      - |
+        $ gomplate -i '{{ (uuid.Parse "000001f5-4470-21e9-9b00-72000877c7b0").Domain }}'
+        Person