assert

#! .desc:
# Assert a string
#! .params:
# <$1> - type(
#     '-single-quote-escaped-argument' - argument escaped with single quotes
#     '-single-quotes-array' - pseudo array of single-quote-escaped arguments
#     '-bit' - N in base 2 that represents a valid bit (valid bit position)
#     '-eq' - N [0,1,00,01...] (integer) equal to another N
#     '-max' - N [0,1,00,01...] (integer) maximum of another N
#     '-min' - N [0,1,00,01...] (integer) minimum of another N
#     '-n' - N [0,1,00,01...] (integer)
#     '-greater-n' - N [0,1,00,01...] (integer) greater than another N
#     '-lower-n' - N [0,1,00,01...] (integer) lower than another N
#     '-natural-n' - natural N [1...] (positive integer)
#     '-whole-n' - whole N [0,1...] (non-negative integer)
#     '-portable-name' - portable ("Portable Filename") name
#     '-absolute-path' - absolute path (/*)
#     '-canonical-path' - lexically canonical (assertable) path
#     '-fs-canonical-path' - semantically canonical (assertable) path
#     '-relative-path' - relative path
#     '-shell-name' - portable shell-parseable name
#     .
# )
# <"$2"> - string
# ["$3"] - string
#! .rc:
# (0) true
# (1) false
# (2) false; bad operand
#! .ec:
# (255) bad input
#! .caveats (-bit):
# > `INT_MAX`. The operands and result of a bitwise operation are integers, so
#   bitwise operations (and shell arithmetic in general) are subject to the
#   system's native integer limits.
#.
assert() {
    case "$1" in
        # Assert $2 is a valid single-quote-escaped argument. A valid
        # single-quote-escaped argument is a shell-parseable string enclosed in
        # single quotes. A single-quote inside a single-quote-escaped argument
        # is escaped with the syntactical expression `'\''`. This string is
        # semantically safe for `eval`.
        #
        # For more information, refer to:
        # > "POSIX.1-2024, Volume: Shell & Utilities, Section: Shell Command
        #   Language, Subsection: Quoting".
        # > "POSIX.1-2024, Volume: Shell & Utilities, Section: Shell Command
        #   Language, Subsection: Escape Character (Backslash)".
        # > "POSIX.1-2024, Volume: Shell & Utilities, Section: Shell Command
        #   Language, Subsection: Single-Quotes".
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: Argument".
        '-single-quote-escaped-argument')
            set -- "$2"; while [ "$1" ] || return 1; do
                [ "${1#\'}" != "$1" ] && set -- "${1#\'}" || return 1

                while [ "$1" ]; do
                    case "${1#*\'}" in
                        \\\'\'*) set -- "${1#*\'\\\'\'}"; continue ;;
                        '') return 0 ;;
                    esac

                    return 1
                done
            done
        ;;
        # Assert $2 is a valid single-quotes array of arguments. A valid
        # single-quotes array is a shell-parseable string consisting of at
        # least one argument, each enclosed in single quotes and delimited
        # by <whitespace>. A single-quote inside a single-quote-escaped
        # argument is escaped with the syntactical expression `'\''`. This
        # string is semantically safe for `eval`.
        #
        # For more information, refer to:
        # > "POSIX.1-2024, Volume: Shell & Utilities, Section: Shell Command
        #   Language, Subsection: Quoting".
        # > "POSIX.1-2024, Volume: Shell & Utilities, Section: Shell Command
        #   Language, Subsection: Escape Character (Backslash)".
        # > "POSIX.1-2024, Volume: Shell & Utilities, Section: Shell Command
        #   Language, Subsection: Single-Quotes".
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: Argument".
        '-single-quotes-array')
            set -- "${2%"${2##*[! ]}"}"; while [ "$1" ] || return 1; do
                set -- "${1#"${1%%[! ]*}"}"

                [ "${1#\'}" != "$1" ] && set -- "${1#\'}" || return 1

                while [ "$1" ]; do
                    case "${1#*\'}" in
                        \\\'\'*) set -- "${1#*\'\\\'\'}"; continue ;;
                        \ *) set -- "${1#*\'}"; continue 2 ;;
                        '') return 0 ;;
                    esac

                    return 1
                done
            done
        ;;
        # Assert $2 is a number in base 2 that represents a valid bit. A valid
        # bit is a natural number that represents a specific bit position in a
        # bitmask and is always a power of 2 (`1`, `2`, `4`, `8`, ...). This is
        # also known as "valid bit position".
        #
        # A number is a power of 2 if performing bitwise AND in the expression
        # `N & (N - 1)` results in zero (the binary representation turns to all
        # zeroes due to the single 1-bit being flipped off, given N was an
        # actual power of 2 in base 2).
        '-bit')
            assert -natural-n "$2" || return 2

            [ "$(($2 & ($2 - 1)))" = 0 ] || return 1
        ;;
        # Assert $2 is a number equal to $3. Leading zeroes are ignored, except
        # `[0] -eq [0]` is true. This comparison essentually emulates the
        # behavior of operator `-eq` of `test` in POSIX shells, just with
        # support for extremely large numbers. This comparison is also known as
        # "lexicographical numeric comparison".
        '-eq')
            assert -n "$2" || return 2
            assert -n "$3" || return 2

            set -- "${2#"${2%%[!0]*}"}" "${3#"${3%%[!0]*}"}"

            [ "$1" = "$2" ] || return 1
        ;;
        # Assert $2 is a number maximum of $3. Leading zeroes are ignored,
        # except `[0] -eq [0]` is true. This comparison essentually emulates
        # the behavior of operator `-le` of `test` in POSIX shells, just with
        # support for extremely large numbers. This comparison is also known as
        # "lexicographical numeric comparison".
        '-max')
            assert -lower-n "$2" "$3" || \
            assert -eq "$2" "$3" || \
            return "$?"
        ;;
        # Assert $2 is a number minimum of $3. Leading zeroes are ignored,
        # except `[0] -eq [0]` is true. This comparison essentually emulates
        # the behavior of operator `-ge` of `test` in POSIX shells, just with
        # support for extremely large numbers. This comparison is also known as
        # "lexicographical numeric comparison".
        '-min')
            assert -greater-n "$2" "$3" || \
            assert -eq "$2" "$3" || \
            return "$?"
        ;;
        # Assert $2 is a number (`0`, `1`, `00`, `01`, ...). A number is any
        # string consisting only of digits. This is also well known as
        # "integer".
        '-n')
            case "${2:-0}${2#*[!0123456789]}" in
                "$2$2") return 0 ;;
            esac

            return 1
        ;;
        # Assert $2 is a number greater than $3. To determine which number is
        # greater, leading zeroes are removed, and the numbers are first
        # compared by length, followed by digit comparison if the lengths are
        # the same. This comparison essentually emulates the behavior of
        # operator `-gt` of `test` in POSIX shells, just with support for
        # extremely large numbers. This comparison is also known as
        # "lexicographical numeric comparison".
        '-greater-n')
            assert -n "$2" && assert -n "$3" || return 2

            set -- "${2#"${2%%[!0]*}"}" "${3#"${3%%[!0]*}"}"

            [ ! "$1" = "$2" ] && [ ! "${#1}" -lt "${#2}" ] || return 1
            [ ! "${#1}" -gt "${#2}" ] || return 0

            while [ "$1" ]; do
                case "$1" in
                    "${2%"${2#?}"}"*) set -- "${1#?}" "${2#?}"; continue ;;
                esac

                if [ "${1%"${1#?}"}" -gt "${2%"${2#?}"}" ]; then
                    return 0
                fi

                return 1
            done
        ;;
        # Assert $2 is a number lower than $3. To determine which number is
        # lower, leading zeroes are removed, and the numbers are first compared
        # by length, followed by digit comparison if the lengths are the same.
        # This comparison essentually emulates the behavior of operator `-lt`
        # of `test` in POSIX shells, just with support for extremely large
        # numbers. This comparison is also known as
        # "lexicographical numeric comparison".
        '-lower-n')
            assert -n "$2" && assert -n "$3" || return 2

            set -- "${2#"${2%%[!0]*}"}" "${3#"${3%%[!0]*}"}"

            [ ! "$1" = "$2" ] && [ ! "${#1}" -gt "${#2}" ] || return 1
            [ ! "${#1}" -lt "${#2}" ] || return 0

            while [ "$1" ]; do
                case "$1" in
                    "${2%"${2#?}"}"*) set -- "${1#?}" "${2#?}"; continue ;;
                esac

                if [ "${1%"${1#?}"}" -lt "${2%"${2#?}"}" ]; then
                    return 0
                fi

                return 1
            done
        ;;
        # Assert $2 is a natural number (`1`, `2`, ...). A natural number is
        # any string consisting only of digits, of which the first is not `0`.
        # Also known as "positive integer" in the POSIX standard.
        '-natural-n')
            case "${2:-0}${2#*[!0123456789]}" in
                0*) return 1 ;;
                "$2$2") return 0 ;;
            esac

            return 1
        ;;
        # Assert $2 is a whole number (`0`, `1`, `2`, ...). A whole number is
        # `0` and any string consisting only of digits, of which the first is
        # not `0`. Also known as "non-negative integer" in the POSIX standard.
        '-whole-n')
            assert -natural-n "$2" || \
            assert -eq "$2" 0 || \
            return "$?"
        ;;
        # Assert $2 is a portable ("Portable Filename") name. A portable name
        # is a string composed of the characters in the portable filename
        # character set, with the following exceptions:
        #
        # - Should not begin with a <hyphen-minus> character. This exception is
        #   currently not being asserted.
        #
        # The character classes have been intentionally expanded to be
        # locale-independent.
        #
        # For more information, refer to:
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: Portable Filename".
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: Portable Filename Character Set".
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: User Name".
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Regular
        #   Expressions, Subsection: RE Bracket Expression".
        '-portable-name')
            case "$2" in
                *[!0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_\.\-]*)
                    return 1
                ;;
            esac

            [ "$2" ] || return 1
        ;;
        # Assert $2 is an absolute (/*) path. An absolute path is any string of
        # which the first character is `/`.
        #
        # For more information, refer to:
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: Absolute Pathname".
        '-absolute-path')
            case "$2" in
                '/'*) return 0 ;;
            esac

            return 1
        ;;
        # Assert $2 is a lexically canonical (assertable) path. A canonical
        # path is largely implementation-defined string that refers to the
        # normalized absolute path. Therefore, a lexical canonical path is:
        #
        # - Assertive: Multiple consecutive slashes (`//`) are removed, `.`
        #   and `..` are resolved. The only exception is two consecutive
        #   slashes (`//`) at the beginning of the string, which is specified
        #   by the POSIX standard as an "implementation-defined" exception.
        # - Absolute: The path is always rooted from `/`.
        #
        # For more information, refer to:
        # > "POSIX.1-2024, Volume: Base Definitions, Section: General Concepts,
        #   Subsection: Pathname Resolution".
        '-canonical-path')
            case "$2" in
                '//'*) set -- "${2#/}" ;;
                *) set -- "$2" ;;
            esac

            case "$1" in
                *'//'*) return 1 ;;
                '/'*) : ;;
                *) return 1 ;;
            esac

            case "$1/" in
                *'/./'* | *'/../'*) return 1 ;;
            esac

            return 0
        ;;
        # Assert $2 is a semantically canonical (assertable) path. A canonical
        # path is largely implementation-defined string that refers to the
        # normalized absolute path. Therefore, a semantic canonical path is:
        #
        # - Assertive: Multiple consecutive slashes (`//`) are removed, `.`
        #   and `..` are resolved.
        # - Semantic: Neither the path nor its segments are a symbolic link on
        #   the filesystem. The actual existence of the path or its segments is
        #   ignored.
        # - Absolute: The path is always rooted from `/`.
        #
        # For more information, refer to:
        # > "POSIX.1-2024, Volume: Base Definitions, Section: General Concepts,
        #   Subsection: Pathname Resolution".
        '-fs-canonical-path')
            case "$2" in
                '/') return 0 ;;
                *'//'*) return 1 ;;
                '/'*) set -- "${2%/}/" ;;
                *) return 1 ;;
            esac

            case "$1" in
                *'/./'* | *'/../'*) return 1 ;;
            esac

            while [ ! -h "${1%/}" ] || return 1; do
                [ "${1%/*/}" ] && set -- "${1%/*/}/" || return 0
            done
        ;;
        # Assert $2 is a relative (partial) path. A relative path is any string
        # of which the first character is not `/`.
        #
        # For more information, refer to:
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: Relative Pathname".
        '-relative-path')
            case "$2" in
                '/'*) return 1 ;;
            esac

            [ "$2" ] || return 1
        ;;
        # Assert $2 is a portable shell-parseable name. A portable
        # shell-parseable name is a string composed of the characters in
        # the portable filename character set, with the following exceptions:
        #
        # - Cannot begin with a digit.
        # - Cannot contain a <hyphen-minus> character.
        # - Cannot contain a <period> character.
        #
        # The character classes have been intentionally expanded to be
        # locale-independent.
        #
        # For more information, refer to:
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: Name".
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Definitions,
        #   Subsection: Portable Filename Character Set".
        # > "POSIX.1-2024, Volume: Base Definitions, Section: Regular
        #   Expressions, Subsection: RE Bracket Expression".
        '-shell-name')
            case "$2" in
                [0123456789]*)
                    return 1
                ;;
                *[!0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]*)
                    return 1
                ;;
            esac

            [ "$2" ] || return 1
        ;;
        *)
            exit 255
        ;;
    esac
}