Add standalone uuid(1) utility

1 files changed, 134 insertions, 0 deletions

diff --git a/doc/uuid.en.1.adoc b/doc/uuid.en.1.adoc
new file mode 100644
index 0000000..6366acb
--- /dev/null
+++ b/doc/uuid.en.1.adoc
@@ -0,0 +1,134 @@
+= uuid(1)
+
+
+
+== NAME
+
+uuid - generate or validate a UUIDv4
+
+
+
+== SYNOPSYS
+
+*uuid* [_STRING_]
+
+
+
+== EXAMPLES
+
+
+=== Print a UUID on the terminal
+
+....
+$ uuid
+d3891787-c952-af17-d697-0df3b85981e1
+....
+
+
+=== Create a new UUID as part of a path
+
+....
+dir="$PWD"/"$(uuid)"/data
+....
+
+
+=== Validate a given UUID
+
+....
+ID="$(basename -- "$directory")"
+if ! uuid "$ID"; then
+	echo "Bad UUID in directory: $ID" >&2
+	exit 1
+fi
+....
+
+
+
+== DESCRIPTION
+
+The *uuid* utility generates a new UUID when no _STRING_ is given and write it
+to _stdout_.  If a _STRING_ is given, *uuid* validates it and exits, and
+produces no output.
+
+
+
+== OPERANDS
+
+_STRING_:: If it is
+
+  *not given*::: generate a brand new random UUIDv4, print it to _stdout_ and exit
+    normally;
+  *given*::: test if it is a valid UUIDv4 and exit normally if so.
+
+
+
+== IO
+
+
+=== STDIN
+
+Not used.
+
+
+=== STDOUT
+
+The UUIDv4 format is made of byte blocks encoded as hexadecimals, using a
+<hyphen-minus>('`-`') as the block separator:
+
+....
+XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
+....
+
+An example output is:
+
+....
+cb46d0c0-b2aa-4a6c-a119-8deace2544a2
+....
+
+
+=== STDERR
+
+Not used.
+
+
+=== INPUT FILES
+
+None.
+
+
+=== OUTPUT FILES
+
+None.
+
+
+
+== EXIT STATUS
+
+0:: Generating or validating a UUID was successfull.
+3:: UUID validation failed.
+
+
+
+== CONFORMING TO
+
+The v4 UUID defined in *RFC 9562*.
+
+
+
+== SEE ALSO
+
+
+
+== AUTHORS
+
+mailto:eu@euandre.org[EuAndreh] and contributors.
+
+
+
+== BUGS
+
+* Report bugs to the mailto:~euandreh/public-inbox@lists.sr.ht[mailing list].
+  Use the subject "[uuid] BUG or TASK: <description>".
+* Browse bugs https://euandre.org/git/uuid/TODOs.html[online].
+* https://euandre.org/git/uuid/[Homepage].
+* https://lists.sr.ht/~euandreh/public-inbox?search=%5Buuid%5D[Comments and discussions].