SearingTruth on Nostr: Or inline descriptions and comments fellow citizen SwiftOnSecurity. I'm about to ...

Or inline descriptions and comments fellow citizen SwiftOnSecurity.

I'm about to drive Linus crazy ... :)
ST

#!/bin/bash
#set -u # Set safe scripting options
set -o nounset
#*******************************************************************************
#* *
#* *
#* Key Variable Functions *
#* *
#* *
#*******************************************************************************
#
# Description:
# Functions to manage key name/value pairs in strings, arrays and text
# files. The names and values can contain any special characters, including
# newlines.
#
# --------
# Overview
# --------
#
# Nomenclature
# ~~~~~~~~~~~~
# Key Variable
# Key Variable string. The string consists of a Key Name and Key Value
# seperated by an equals sign. For example "Key1=Key 1 value".
#
# Key Name
# The Key Name part of a Key Variable.
#
# Key Value
# The Key Value part of a Key Variable.
#
# Key File
# A text file that contains Key Variables. The recommended suffix is
# ".kv" but any name can be used.
#
# Key Array
# An array that contains Key Variables.
#
# Encoded Characters
# All special characters in Key Variables are encoded into ASCII hex
# format so they can used as regular characters and avoid shell
# interpretation and translation. For example the "@" character is
# encoded as "\x40".
#
# Escape Encoded Characters
# There are times when Encoded Characters must have their backslashes
# escaped by another backslash so they can be used in procedures that
# would otherwise translate the Encoded Character to it's ASCII
# character. For example the "@" character would be Escape Encoded as
# "\\x40". Note that these character encodings are temporary and are
# never stored in a Key Variable.
#
# Architecture
# ~~~~~~~~~~~~
# Key Variables overcome the common problem of dealing with special
# characters in programs by encoding special ASCII characters into their
# hexadecimal equivalent at the most fundamental level - the Key Variable.
# For example the "@" character is encoded as "\x40".
#
# Key Variables simply consist of an encoded key name, an ASCII equals sign,
# and an encoded key value, in the form of "name=value".
#
# These Key Variables can then either be used alone, or combined in text
# files referred to as Key Files or arrays referenced as Key Arrays. All
# Key Names must be unique in files and arrays.
#
# Equivalent functions are provided for creating, writing, reading, listing,
# deleting, and searching Key Variables, Key Files, and Key Arrays.
# Functions are also provided to copy and merge Key Files and Key Arrays.
# Search functions can target any part of Key Names or Key Values, enabling
# light database type functionality.
#
# Note that Key Names and Key Values can contain newlines they can be used
# to store newline seperated arrays, even when the array values contain
# newlines themselves, which further enables the construction of
# multidimensional arrays.
#
# For example, in the bash shell names and values may be created with the
# newline ($'\n') character and then reconstituted with something like
# "array=($key_value).
#
# Key names and values have been tested to function correctly with
# most common special characters. Problems with other characters can be
# corrected by adding them to the "Encoded String Special Character Array"
# in the "Standard Functions Variables" file. The following special
# characters have been verified to function correctly:
#
# ~ ! @ # $ % ^ & * ( ) _ + ` - = { } | \ : " ; ' < > ? , . / \n