xlib

#!/bin/bash
#   Copyright 2017 bin jin
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.

# Resolve the real script directory, follow symlink
__script_dir () {
    [ "$__SELF_DIR" ] && { printf "%s" "$__SELF_DIR"; return; }
    local src=$0 dir;
    while [ -L "$src" ]; do
        dir=$(cd "$(dirname "$src")" && pwd);
        src=$(readlink "$src");
        case $src in /*) :;; *) src="$dir/$src";; esac
    done
    cd "$(dirname "$src")" && pwd
}
__SELF_DIR=$(__script_dir)

# Framework:
#
#     A function whose name conforms to the specification gets:
#         External invocation.
#         Error handling.
#         Help information.
#         The function list.
#         Shell completion.
#
#     The annotation is both the help text and the completion source; keep it next to the code:
#         A [###] at the line start is for the command; an indented [###] is for the case pattern below it.
#
#     For example:
#         ### [brief_introduction]
#         ### Usage: [function_name] [OPTION]... [OPERAND]...
#         [script_name]_[function_name](){
#             [function_body]
#             case $1 in
#                 ###   -o, --option=FILE   [description]
#                 --option|-o)
#                     [function_body]
#                 ;;
#                 ###   OPERAND=FILE   [description]
#                 *)
#                     [function_body]
#                 ;;
#             esac
#             # exit and display [error_description]
#             exit 1; # [error_description]
#         }
#
#     The metavariable names the completion source:
#         FILE IMAGE DIRECTORY DEVICE PATH HOST ADDRESS MAC ALIAS HOSTIP SHELL KIND
#         {a|b} is an enumeration, e.g., {yes|no}
#         The kinds of this host are declared by __COMP_KINDS, __comp_kind_host and
#         __comp_value_host; the generic engine lives in comp.xlib.
#
#     A platform tag at the end of an annotation line marks it as platform specific:
#         [macOS] or [Linux]; the tag is shown in help and skipped by completion
#         on the other platform.
#
#     [###] is reserved for annotation; any other comment must use [#]:
#         Use [comp --check] to check the annotations.

### Print version and exit
### Usage: version
_xlib_version () {
    printf "0.26.9.26\n" >&2;
    return 0
}

### Control the cursor
### Usage: cur [OPTION]
_xlib_cur () {
    case $1 in
        ###   -, --hide   hide the cursor
        --hide|-)
            printf '\033[?25l'
            # trap 'printf "\033[?25h"; exit' INT; # Show the cursor after Ctrl-C.
        ;;
        ###   +, --show   show the cursor
        --show|+)
            printf '\033[?25h'
        ;;
        "")
            local p=;
            printf '\e[6n';
            read -sdR p;
            printf "${p#*[}\n"
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

### Create or convert a package file [macOS]
### Usage: pkg [OPTION]... [PATH]
_xlib_pkg () {
    [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
    local tmp;
    case $1 in
        ###   -n, --dmg=DIRECTORY   create a DMG from a DIRECTORY
        --dmg|-n)
            shift;
            [ -d "$1" ] || exit 1; # Target directory not found.
            # Trim: # linux:${1:0:-1} -> darwin:${1:0:${#1}-1}
            [ "${1:0-1}" == "/" ] && tmp="${1:0:${#1}-1}" || tmp="$1";
            tmp=${tmp##*/};
            hdiutil create -srcfolder "$1" -skipunreadable -format UDZO "$tmp.dmg" || return 1
        ;;
        ###   -t, --verify=FILE   verify a DMG FILE
        --verify|-t)
            shift;
            [ "${1##*.}" == "dmg" -o "${1##*.}" == "DMG" ] || exit 1; # Invalid format.
            hdiutil verify "$1"
        ;;
        ###   -di, --dmg2iso=FILE   convert a DMG FILE to ISO
        --dmg2iso|-di)
            shift;
            [ -f "$1" ] || exit 1; # DMG file not found.
            [ "${1##*.}" == "dmg" -o "${1##*.}" == "DMG" ] || exit 1; # Not a DMG file.
            tmp=${1##*/};
            tmp=${tmp%.*};
            hdiutil convert "$1" -format UDTO -o "$tmp.iso";
        ;;
        ###   -id, --iso2dmg=FILE   convert an ISO FILE to DMG
        --iso2dmg|-id)
            shift;
            [ -f "$1" ] || exit 1; # ISO file not found.
            [ "${1##*.}" == "iso" -o "${1##*.}" == "ISO" ] || exit 1; # Not an ISO file.
            tmp=${1##*/};
            tmp=${tmp%.*};
            hdiutil convert "$1" -format UDRW -o "$tmp.dmg";
        ;;
        ###   -u, --udf=DIRECTORY   create an ISO from a DIRECTORY
        --udf|-u)
            shift;
            [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
            [ -d "$1" ] || exit 1; # Directory not found.
            # hdiutil makehybrid -iso -joliet -o win8.iso win8.cdr
            hdiutil makehybrid -udf -udf-version 1.02 -o "$1.iso" "$1";
            return 0
        ;;
        ###   -w, --dd=IMAGE|DEVICE   write IMAGE to DEVICE, e.g., /dev/disk2
        --dd|-w)
            shift;
            # caller 0;
            [ -f "$1" ] || exit 1; # Image file not found.
            local target i j k l;
            [ "${2:0:9}" == "/dev/disk" ] && {
                target=$2
            } || {
                # Cut the mount info.
                while read i j k; do
                    [ "${k%% (*}" == "$2" ] && target=$i
                done < <(mount)
            }
            # Trim the slice suffix.
            [[ $target == *disk[0-9]s[0-9] ]] && target=${target%s*};

            case ${1##*.} in
                img)
                    diskutil unmountDisk $target >/dev/null || exit 1; # Cannot unmount this disk.
                    sudo dd if="$1" of=$target bs=4m || exit 1; # The dd command failed.
                ;;
                iso)
                    diskutil unmountDisk $target >/dev/null || exit 1; # Cannot unmount this disk.
                    hdiutil convert "$1" -format UDRW -o "${1%.*}.dmg" >/dev/null;
                    sudo dd if="${1%.*}.dmg" of=$target bs=4m || exit 1; # The dd command failed.
                    rm "${1%.*}.dmg";
                    # sudo dd if="${1%.*}.dmg" of=$target bs=4m & while killall -USR1 dd; do
                    #     sleep 10;
                    # done | _xlib_prefix "%F %T, "
                ;;
                gz)
                    which gzcat >/dev/null 2>&1 || exit 1; # The gzcat command was not found.
                    diskutil unmountDisk $target >/dev/null || exit 1; # Cannot unmount this disk.
                    gzcat "$1" | sudo dd of=$target bs=4m || exit 1; # The dd command failed.
                ;;
                xz)
                    which xzcat >/dev/null 2>&1 || exit 1; # The xzcat command was not found; try 'brew install xz'.
                    diskutil unmountDisk $target >/dev/null || exit 1; # Cannot unmount this disk.
                    xzcat "$1" | sudo dd of=$target bs=4m || exit 1; # The dd command failed.
                ;;
                *)
                    exit 1; # Format not supported.
                ;;
            esac

            sync;
            diskutil eject $target >/dev/null
            return 0
        ;;
        ###   -g, --get[=NUMBER]   get an APK file from the AppStore; NUMBER is the countdown in minutes
        --get|-g)
            [[ ${OSTYPE/darwin/} > 24.9 ]] && {
                printf "\033[31mError: OS version too new.\033[0m\n" >&2;
                return 1
            }
            __get_pkg $2
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

# Get an APK file from the AppStore.
__get_pkg () {
    [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
    # sudo chown -R $USER:`id -gn $USER` /private/var/folders
    # sudo chmod -R 755 /private/var/folders
    [ `ps -ef | grep -c "${0##*/}.*pkg.*-g"` -gt 3 ] && exit 1; # The pkg command is already running.

    # Override the pkg map: pkg[$serial_number]="$path".
    function ___get_pkg_serial_number () {
        local k v;
        while read k v; do
            # Put it in the map.
            [ "$v" ] && pkg[$k]="$v";
        done < <(find "$1" -type f -iname "*.pkg" -exec ls -i {} \; 2>/dev/null); # *.tmp *.pkg
        return 0
    };

    # Hash the file and move it to ~/Downloads.
    function ___get_pkg_complete () {
        [ -f "$1" ] || return 1;
        local name=${1##*/};
        name=${name#*_};
        name=${name%.*};

        {
            printf "NAME: ${1##*/}\n";
            printf "SIZE: ";
            du -h "$1" | awk '{print $1}'
            printf "TIME: ";
            _xlib_str --dhms $(($(date +%s) - $sec_on));
            _xlib_hash "$1"
            mv "$1" ~/Downloads 2>/dev/null || {
                cp "$1" ~/Downloads && printf "\033[31m$1 still exist\033[0m\n"
            }
        } | awk -v name="${name:0:8}, " '{print name $0; fflush(stdout)}'

    };

    local i anchor count_cache=0 pkg=() tmp=/private/var/tmp store_agent countdown=$((${1-1} * 60 * 5)) sec_on=$(date +%s);

    {

        printf -v store_agent /private/var/folders/*/*/C/com.apple.appstoreagent/com.apple.appstore;
        printf "Will listen \033[4m%s\033[0m sec.\n" $(($countdown / 5));

        # Register a hard link from /private/var/tmp.
        ___get_pkg_serial_number "$store_agent";

        # Infinite loop.
        while :; do

            # Exit when all downloads are complete.
            [ $countdown -lt 0 -a ${#pkg[@]} == 0 ] && {
                printf "Exit.\n";
                break
            };

            [ $((countdown -= 1)) == 0 ] && printf "Listening \033[4mstop\033[0m.\n";

            # Search for the downloaded package.
            ___get_pkg_serial_number "$store_agent";

            # Iterate over the package array.
            [ ${#pkg[@]} -gt 0 ] && for i in ${!pkg[@]}; do
                # Already complete.
                [ "${pkg[$i]%/*}" == "$tmp" ] && {
                    ___get_pkg_complete "${pkg[$i]}" &
                    unset pkg[$i];
                    continue
                };

                anchor=$tmp/${i}_${pkg[$i]##*/}; # Anchor file path.

                # Add a hard link.
                [ -f "$anchor" ] || {
                    ln "${pkg[$i]}" "$anchor" && printf "Add \033[4m${pkg[i]##*/}\033[0m.\n";
                };

                # The download is complete.
                [ -f "${pkg[$i]}" ] || {
                    unset pkg[$i];
                    ___get_pkg_complete "$anchor" &
                };
            done;

            [ ${count_cache} != ${#pkg[@]} ] && {
                printf "Count: ${#pkg[@]}\n";
                count_cache=${#pkg[@]}
            };

            sleep 0.2
        done;

    } | _xlib_prefix "%F %T, GPKG, "

    # Wait for all threads to finish.
    wait
}

### Wake on LAN
### Usage: wol [OPTION]... TARGET
_xlib_wol () {
    [ "$1" ] || exit 1; # MAC address is empty.

    source "$(__script_dir)/bash.xlib";

    # Load the [hosts] ini config into map0.
    __load_ini hosts;

    local i j mac_addr broadcast sub seen mac_arr=();
    case $1 in
        ###   -b, --broadcast=ADDRESS|ALIAS   broadcast ADDRESS for all targets
        --broadcast|-b)
            shift;
            # Resolve the broadcast address from an IPv4 address or host alias.
            for i in `__wol_addr "$1"`; do
                _xlib_ip --test "$i" && { broadcast=$i; break; }
            done
            [ "$broadcast" ] || exit 1; # Cannot resolve the broadcast IPv4 address.
            shift
        ;;
        ###   TARGET=ALIAS|HOSTIP   MAC address, hosts alias or IPv4 address
        *)
            # Default broadcast addresses: the subnet of every default route of a
            # physical interface. A machine may hold more than one, and a virtual
            # adapter (a proxy TUN, a VPN) holds a route whose subnet cannot reach
            # the LAN, so only the physical routes count; the order is not
            # significant.
            broadcast=; seen=;
            for i in `__route_gateway`; do
                sub="${i%.*}";
                case " $seen " in *" $sub "*) continue;; esac
                seen="$seen $sub";
                broadcast="$broadcast$sub.255 ";
            done
            [ "$broadcast" ] || exit 1; # Cannot resolve the broadcast IPv4 address.
        ;;
    esac

    [ "$1" ] || exit 1; # MAC address is empty.

    # Resolve all MAC addresses from a MAC address, host alias or IPv4 address.
    for i in "$@"; do
        mac_addr=;
        for j in `__wol_addr "$i"`; do
            [[ ${j//-/:} == *:*:*:*:*:* ]] || continue;
            mac_addr=true;
            mac_arr[${#mac_arr[@]}]=$j;
        done
        [ "$mac_addr" ] || exit 1; # Cannot resolve the MAC address.
    done

    # Wake each MAC address on every broadcast address.
    for i in ${mac_arr[@]}; do
        for j in $broadcast; do
            __wol "$i" "$j";
        done
    done

}

# Print MAC addresses and IPv4 addresses for the [hosts] ini, from a MAC address,
#   host alias or IPv4 address.  Read the ini config from HOME or the script path,
#   and reverse lookup in /etc/hosts.
# Usage: __wol_addr [STRING]
__wol_addr () {
    [ "$1" ] || return 1;
    local i j k line;
    # By MAC address or host alias.
    line=`_map --get "$1"`;
    line=${line:-$1};

    # By IPv4 address.
    if _xlib_ip --test "$1"; then
        # Reverse lookup the host alias in map0.
        if [ "$line" == "$1" ]; then
            _map --keys;
            for i in ${MAP2ARRAY[@]}; do
                j=`_map --get "$i"`;
                for k in ${j//|/ }; do
                    [ "$k" == "$1" ] && { line=$j; break 2; }
                done
            done
        fi

        # Reverse lookup the host name in /etc/hosts, which the [hosts] command updates.
        if [ "$line" == "$1" ]; then
            for i in `awk -v ip="$1" '$1 == ip {for (n = 2; n <= NF; n++) print $n}' /etc/hosts`; do
                j=`_map --get "$i"`;
                [ "$j" ] && { line=$j; break; }
            done
        fi
    fi

    # Print the MAC address and IPv4 address.
    local addr IFS=$IFS"|";
    addr=($line);
    IFS=${IFS%|};
    for i in ${addr[@]}; do
        _xlib_ip --test "$i" && { printf "%s\n" "$i"; continue; }
        [[ ${i//-/:} == *:*:*:*:*:* ]] && printf "%s\n" "$i"
    done

    return 0
}

__wol () {
    # The magic packet is built with the brace expansion of bash, and this script
    # always runs on bash whatever [SHELL] says, so any perl found is usable and
    # is the cheapest sender; python3 and python2 are the fallbacks.
    if which perl >/dev/null 2>&1; then
        printf $(
            {
                printf 'f%.0s' {1..12};
                printf "${1//[:-]/}%.0s" {1..16};
            } | sed 's/../\\x&/g'
        ) | perl -ne 'use Socket; socket(S, AF_INET, SOCK_DGRAM, getprotobyname("udp")); setsockopt(S, SOL_SOCKET, SO_BROADCAST, 1); send(S, $_, 0, pack_sockaddr_in(9, inet_aton("'"$2"'"))); close S' || \
            exit 1; # The perl command failed.

    elif which python3 >/dev/null 2>&1; then
        # 'decode("hex")' of python2 became 'bytes.fromhex' in python3.
        python3 -c 'import socket; S=socket.socket(socket.AF_INET, socket.SOCK_DGRAM); S.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1); S.sendto(bytes.fromhex("".join(["F" * 12, "'"$1"'".replace(":", "").replace("-", "") * 16])), ("'"$2"'", 9))' || \
            exit 1; # The python3 command failed.

    elif which python >/dev/null 2>&1; then
        python -c 'import socket; S=socket.socket(socket.AF_INET, socket.SOCK_DGRAM); S.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1); S.sendto("".join(["F" * 12, "'"$1"'".replace(":", "").replace("-", "") * 16]).decode("hex"), ("'"$2"'", 9))' || \
            exit 1; # The python command failed.

    else
        exit 1; # Not supported.

    fi

}

### Remote tools
### Usage: remote [OPTION]... [ARG]...
_xlib_remote () {
    case $1 in
        ###   -ed25519=HOST   copy the ed25519 public key to HOST; an optional ALIAS suffix may be given
        -ed25519)
            shift;
            __remote_ed25519 "$@"
        ;;
        ###   -scp=PASSWORD COMMAND...   copy files over scp with PASSWORD
        -scp)
            shift;
            __remote_auto_scp "$@"
        ;;
        ###   -tar=PATH   transfer PATH by tar, the first ARG is a tar option
        -tar)
            shift;
            __remote_tar "$@"
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

# For _xlib_remote.
__remote_ed25519 () {
     [ "$1" ] || exit 1; # First argument is empty.
    local ed25519_pub;
    [ -s ~/.ssh/id_ed25519$2.pub ] || ssh-keygen -t ed25519 -P "" -f ~/.ssh/id_ed25519$2;
    printf %s 'mkdir ~/.ssh 2>/dev/null;
printf %s "'`cat ~/.ssh/id_ed25519$2.pub 2>/dev/null`'" >> ~/.ssh/authorized_keys;
chmod 600 ~/.ssh/authorized_keys;
chmod 700 ~/.ssh
' | ssh $1 bash || exit 1; # Unknown error.

    local host=${1#*@} user;
    [ "$host" == "$1" ] && user=${1%@*} || user=$USER;

    printf %s "Host    $host
    HostName        $host
    Port            22
    User            $user
    IdentityFile    ~/.ssh/id_ed25519$2
"
    return 0
}

# For _xlib_remote.
__remote_auto_scp () {
    local password;
    which expect >/dev/null 2>&1 || exit 1; # The expect command was not found.
    password=$1;
    shift;
    expect <<-TCL
	set timeout 150
	spawn scp $*
	expect {
		timeout { exit 2 }
		"*yes/no" { send "yes\r"; exp_continue }
		"*assword:" { send "$password\r" }
	}
	expect {
		timeout { exit 2 }
		"*denied*" { exit 3 }
		"No such" { exit 4 }

####        "100%" { exit 0 }

    }
	expect eof
	TCL

    case $? in
        1)
            exit 1; # Expect error.
        ;;
        2)
            exit 1; # Timed out.
        ;;
        3)
            exit 1; # Password error.
        ;;
        4)
            exit 1; # File not found.
        ;;
        *)
            exit 1; # Unknown error.
        ;;
    esac
}

__remote_tar () {
    [ "$1" ] || exit 1; # Target URL is empty.
    [ "$2" ] || exit 1; # Source URL is empty.
    local option="$1" target_host target_dir source_host source_dir;
    shift;

    target_dir="${1#*:}";
    [ "$target_dir" == "$1" ] || target_host=${1%%:*};
    # ${target_dir:(-1)} == ${target_dir:0-1}
    [ "${target_dir:0-1}" == "/" ] && target_dir="${target_dir:0:${#target_dir}-1}"

    source_dir="${2#*:}";
    [ "$source_dir" == "$2" ] || source_host=${2%%:*};
    [ "${source_dir:0-1}" == "/" ] && source_dir="${source_dir:0:${#source_dir}-1}"

    # echo $target_host, $target_dir, $source_host, $source_dir
    # return 0

    function ___tar_c () {
        {
            [ "${option/P/}" == "$option" ] && \
            printf %s 'cd "'"${2%/*}"'" >/dev/null && tar '$option' - "'"${2##*/}"'"' || \
            printf %s 'tar '$option' - "'"$2"'"'
        } | ssh $1 bash
    };

    function ___tar_x () {
        [ "${option/P/}" == "$option" ] && {
            ssh $1 'cd "'"$2"'" >/dev/null && tar '$option' -'
        } || ssh $1 'tar '$option' - '
    };

    function ___tar_cat_i () {
        ssh $1 'cat > "'"$2"'"'
    };

    function ___tar_cat_o () {
        ssh $1 'cat "'"$2"'"'
    };

    case $option in
        *c*)
            if [ "$target_host" -a "$source_host" ]; then
                # Both sides are remote.
                ___tar_c $source_host "${source_dir}" | ___tar_cat_i $target_host "$target_dir"
            elif [ "$target_host" ]; then
                # Local to remote.
                [ -d "$source_dir" ] || exit 1; # source path not found.
                {
                    [ "${option/P/}" == "$option" ] && {
                        cd "${source_dir%/*}" >/dev/null && tar $option - "${source_dir##*/}"
                        cd "$OLDPWD"
                        :
                    } || tar $option - "${source_dir}"
                } | rcat $target_host "$target_dir";
            else
                # Remote to local.
                ___tar_c $source_host "$source_dir" > "$target_dir";
            fi
        ;;
        *x*)
            if [ "$target_host" -a "$source_host" ]; then
                # Both sides are remote.
                ___tar_cat_o $source_host "${source_dir}" | ___tar_x $target_host "$target_dir"
            elif [ "$target_host" ]; then
                # Local to remote.
                [ -f "$source_dir" ] || exit 1; # source file not found.
                cat "$source_dir" | ___tar_x $target_host "$target_dir"
            else
                # Remote to local.
                cd "$target_dir";
                ___tar_cat_o $source_host "$source_dir" | tar $option -;
                cd "$OLDPWD"
            fi
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac

    return 0
}

### Operating system settings [macOS]
### Usage: oset [OPTION]... [ARG]...
_xlib_oset () {
    [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
    case $1 in
        ###   -v, --version   print the OS version
        --version|-v)
            which sw_vers >/dev/null 2>&1 && {
                sw_vers | awk '{if(/ProductVersion/) {printf $2}; if(/BuildVersion/) print "." $2}';
                :
            } || system_profiler SPSoftwareDataType | \
                awk '/System Version/{gsub(/[()]/, "", $5); print $4 "." $5}'
        ;;
        ###   -a, --allow   allow installation of all apps
        --allow|-a)
            sudo spctl --master-disable;
        ;;
        ###   -aa, --allow-app=FILE   allow running the app bundle FILE
        --allow-app|-aa)
            shift;
            [ -e "$1" ] || exit 1; # App bundle not set or not found.
            sudo spctl --master-disable;
            sudo xattr -r -d com.apple.quarantine "$1"
        ;;
        ###   -, --hidden={yes|no}   show or hide private files and directories
        --hidden|-)
            shift;
            [ "$1" == "yes" -o "$1" == "no" ] || exit 1; # The value must be 'yes' or 'no'.
            defaults write com.apple.finder AppleShowAllFiles $1;
        ;;
        ###   -rl, --re-launch   reset LaunchPad
        --re-launch|-rl)
            defaults write com.apple.dock ResetLaunchPad -bool true;
            killall Dock
        ;;
        ###   -sl, --set-launch=NUMBER   set the LaunchPad ROWS and COLUMNS
        --set-launch|-sl)
            shift;
            if [ "$2" ]; then
                defaults write com.apple.dock springboard-rows -int $1
                defaults write com.apple.dock springboard-columns -int $2
                killall Dock
            elif [ "$1" ]; then
                exit 1; # Columns not set.
            else
                defaults write com.apple.dock springboard-rows Default
                defaults write com.apple.dock springboard-columns Default
                killall Dock
            fi
        ;;
        ###   -u, --uuid[=USER]   print the UUID of USER, default is the current user
        --uuid|-u)
            shift;
            [ "$1" ] || set "" $USER;
            dsmemberutil getuuid -U $1
        ;;
        ###   -s, --sid[=USER]   print the SID of USER, default is the current user
        --sid|-s)
            shift;
            [ "$1" ] || set "" $USER;
            dsmemberutil getsid -U $1
        ;;
        ###   -l, --lock-screen   lock the screen
        --lock-screen|-l)
            # Ctrl + Command + Q
            /System/Library/CoreServices/Menu\ Extras/User.menu/Contents/Resources/CGSession -suspend
        ;;
        ###   --ms, --mobile-sync   open the MobileSync backup DIRECTORY
        --mobile-sync|--ms)
            open ~/Library/Application\ Support/MobileSync/Backup
        ;;
        ###   --logout   log out
        --logout)
            # killall -u $USER;
            # kill -9 `ps -Axjc | awk /loginwindow/'{print $2}'`;
            # # System Preferences -> Universal Access -> Enable access for assistive devices
            # echo a | sudo tee /var/db/.AccessibilityAPIEnabled
            # launchctl bootout user/$(id -u $USER)
            printf 'tell application "System Events"
                log out
            end tell
            ' | osascript
        ;;
        ###   --notify=STRING   display a notification
        --notify)
            shift;
            if [ "$3" ]; then
                osascript -e 'display notification "'"$1"'" with title "'"$2"'" subtitle "'"$3"'"'
            elif [ "$2" ]; then
                osascript -e 'display notification "'"$1"'" with title "'"$2"'"'
            else
                osascript -e 'display notification "'"$1"'" with title "Hi"'
            fi
        ;;
        ###   --button-wait=STRING   display a dialog with a Yes button and wait
        --button-wait)
            shift;
            osascript -e 'display dialog "'"$1"'" buttons "Yes" with icon note'
        ;;
        ###   --button-choose=STRING   display a dialog
        --button-choose)
            shift;
            osascript -e 'display dialog "'"$1"'"'
        ;;
        ###   --set-time=STRING   set the system time
        --set-time)
            shift;
            if [ "$1" ]; then
                date +%m%d%H%M%Y.%S
            else
                date $1
            fi
        ;;
        # Screenshots
        # defaults write com.apple.screencapture location $1

        # DiskUtil Debug
        # defaults write com.apple.DiskUtility DUDebugMenuEnabled 1

        # LaunchPad
        # defaults write com.apple.dock ResetLaunchPad -bool true; killall Dock

        # Spotlight close
        # launchctl unload -w /System/Library/LaunchDaemons/com.apple.metadata.mds.plist

        ###   --sleep   put the system to sleep
        --sleep)
            sudo osascript -e 'tell application "Finder" to sleep'
        ;;
        ###   --list-users   list all users
        --list-users)
            dscl . -list /Users UniqueID
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

### Certificate tools
### Usage: cert {selfsign|rsa|ed25519} [OPTION]...
_xlib_cert () {
    case $1 in
        ###   selfsign   create a self-signed certificate
        selfsign)
            # nginx
            shift;
            local host email country="CN" state="BJ" city="BJ" company="ORG" section="dev" days=365;
            while [ "$2" ]; do
                case $1 in
                    ###   -cn, --host=HOST   set the common name (CN)
                    --host|-cn)
                        # Common Name (eg, YOUR name) []:                               /CN             ($IP / $hostname / $alias)
                        host="$2";
                        shift;
                        shift
                    ;;
                    ###   -e, --email=STRING   set the email address
                    --email|-e)
                        # Email Address []:                                             /emailAddress   mail@example.com
                        email="$2";
                        shift;
                        shift
                    ;;
                    ###   -c, --country=STRING   set the country name (C)
                    --country|-c)
                        # Country Name (2 letter code) [AU]:                            /C
                        country="$2";
                        shift;
                        shift
                    ;;
                    ###   -st, --state=STRING   set the state or province name (ST)
                    --state|-st)
                        # State or Province Name (full name) [Some-State]:              /ST
                        state="$2";
                        shift;
                        shift
                    ;;
                    ###   -l, --city=STRING   set the locality name (L)
                    --city|-l)
                        # Locality Name (eg, city) []:                                  /L
                        city="$2";
                        shift;
                        shift
                    ;;
                    ###   -o, --company=STRING   set the organization name (O)
                    --company|-o)
                        # Organization Name (eg, company) [Internet Widgits Pty Ltd]:   /O
                        company="$2";
                        shift;
                        shift
                    ;;
                    ###   -ou, --section=STRING   set the organizational unit name (OU)
                    --section|-ou)
                        # Organizational Unit Name (eg, section) []:                    /OU
                        section="$2";
                        shift;
                        shift
                    ;;
                    ###   --days=NUMBER   set the number of days the certificate is valid
                    --days)
                        days="$2";
                        shift;
                        shift
                    ;;
                    *)
                        exit 1; # Invalid option.
                    ;;
                esac
            done
            [ "$host" ] || exit 1; # Host name is empty.
            [ "$email" ] || exit 1; # Email address is empty.
            local SUBJECT="/C=$country/ST=$state/L=$city/O=$company/OU=$section/CN=$host/emailAddress=$email" \
                SERVER_CERT="./$host/fullchain.pem" \
                SERVER_KEY="./$host/privkey.pem" \
                SERVER_CSR="/tmp/${host}_server.csr" \
                CA_KEY="/tmp/${host}_ca-cert.pem" \
                CA_CERT="./$host/ca.crt";

            mkdir -p "$host";

            # Create the CA.
            openssl genrsa -out $CA_KEY 4096;
            openssl req -new -x509 -days $days -key $CA_KEY -out $CA_CERT -subj "$SUBJECT";

            # Create the server key.
            openssl genrsa -out $SERVER_KEY 4096;

            # Create the server CSR.
            openssl req -new -key $SERVER_KEY -out $SERVER_CSR -subj "$SUBJECT";

            # Self-sign the server CSR.
            openssl x509 -req -days $days -in $SERVER_CSR -CA $CA_CERT -CAkey $CA_KEY -set_serial 01 -out $SERVER_CERT;

        ;;
        ###   rsa[=SUFFIX]   create an RSA key pair, SUFFIX is optional
        rsa)
            shift;
            ssh-keygen -t rsa -P "" -f ~/.ssh/id_rsa$1;
        ;;
        ###   ed25519[=SUFFIX]   create an ed25519 key pair, SUFFIX is optional
        ed25519)
            shift;
            ssh-keygen -t ed25519 -P "" -C "$USER@$HOSTNAME" -f ~/.ssh/id_ed25519$1;
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

### Display device driver info [macOS]
### Usage: drv [OPTION]
_xlib_drv () {
    case $1 in
        ###   -v, --info   print hardware info
        --info|-v)
            if [[ $OSTYPE == darwin* ]]; then
                printf ";\n";
                system_profiler SPHardwareDataType | \
                    awk -F : '{if($2 != ""){sub(/^[[:space:]]+/, "", $1); printf "; %+28s %s\n", $1 ":", $2}}'
                printf ";\n\n";
            else
                :
            fi
        ;;
        ###   -l, --list   list loaded kernel extensions
        --list|-l)
            if [[ $OSTYPE == darwin* ]]; then
                # /System/Library/Extensions /Library/Extensions
                kextstat
            else
                :
            fi
        ;;
        ###   -r, --refresh   prune the kernel extension cache
        --refresh|-r)
            if [[ $OSTYPE == darwin* ]]; then
                sudo kextcache -prune-staging
            else
                :
            fi
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

### Print MD5, SHA-1, SHA-256 and SHA-512 checksums
### Usage: hash [FILE]
_xlib_hash () {
    which openssl >/dev/null 2>&1 || exit 1; # The openssl command was not found.
    local h_code;
    {
        # 'tee' feeds all four digests from a single read of the input.
        for h_code in $(
            {
                [ -f "$1" ] && {
                    cat "$1" | tee >(openssl dgst -sha1 >&2) >(openssl dgst -md5 >&2) >(openssl dgst -sha256 >&2) | openssl dgst -sha512;
                    :
                } || tee >(openssl dgst -sha1 >&2) >(openssl dgst -md5 >&2) >(openssl dgst -sha256 >&2) | openssl dgst -sha512;
            } 2>&1
        ); do
            if [ ${#h_code} == 32 ]; then
                printf "MD5: $h_code\n";
            elif [ ${#h_code} == 40 ]; then
                printf "SHA1: $h_code\n";
            elif [ ${#h_code} == 64 ]; then
                printf "SHA256: $h_code\n";
            elif [ ${#h_code} == 128 ]; then
                printf "SHA512: $h_code\n";
            fi
        done
    } | sort # Make the report order deterministic.
}

### Volume info or edit [macOS]
### Usage: vol [OPTION]... [ARG]...
_xlib_vol () {
    [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
    case $1 in
        # --encrypts-all|-eca)
        #     local args;
        #     while read args; do
        #         set $args;
        #         [ "${2#/Volumes/}" == "$2" ] || diskutil apfs enableFileVault $1 -user disk
        #     done < <(__vol_list)
        # ;;
        # --encrypts|-ec)
        #     __vol_list
        # ;;
        ###   -w, --wipes=DIRECTORY   wipe the free space on the volume at DIRECTORY
        --wipes|-w)
            shift;
            [ -d "$1" ] || exit 1; # Target path not found.
            diskutil secureErase freespace 3 $1
        ;;
        ###   -im, --createinstallmedia=DEVICE   create a bootable install media on DEVICE
        --createinstallmedia|-im)
            shift;
            [ -d "$1" ] || exit 1; # Target device not found.
            [ -d "$2" ] || set -- "$1" "/Applications/Install";
            while read tmp; do
                break;
            done < <(find "$2"*/ -iname "createinstallmedia" 2>/dev/null);
            [ -f "$tmp" ] || exit 1; # Install source not found.
            [ -f "${tmp%Resources*}SharedSupport/InstallInfo.plist" ] || {
                if [ -f "/macOS Install Data/InstallInfo.plist" ]; then
                    sudo mkdir -p "${tmp%Resources*}SharedSupport";
                    find "/macOS Install Data" -type f -exec sudo ln {} "${tmp%Resources*}SharedSupport" \;
                # else
                #     exit 1; # need to run the 'install app' and exit before 'reboot'
                fi
            };
            /usr/libexec/PlistBuddy \
                -c 'Print :CFBundleDisplayName' \
                -c 'Print :DTSDKName' \
                -c 'Print :CFBundleShortVersionString' \
                -c 'Print :DTSDKBuild' \
                    "${tmp%Resources*}Info.plist" | awk '{printf $0 " "};END{printf "\n"}'
            # sudo "$tmp" --volume "$1" --applicationpath "${tmp%/Contents*}" --nointeraction;
            sudo "$tmp" --volume "$1" --nointeraction;
            touch "/Volumes/Install "*/.metadata_never_index
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

# __vol_list () {
#     local args;
#     while read args; do
#         set ${args/+->/#} >/dev/null 2>&1 || continue;
#         [ "$1" == "|" ] && shift;
#         [ $# -le 1 ] && continue;
#
#         if [ "$1$2" == "#Volume" ]; then
#             printf "$3 $4 "
#         # elif [ "$1$2$3" == "APFSVolumeDisk" ]; then
#         #     printf "$5 "
#         elif [ "$1$2" == "MountPoint:" ]; then
#             if [ "$3" == "Not" ]; then
#                 printf %s "- "
#             else
#                 printf "$3 "
#             fi
#         elif [ "$1" == "FileVault:" ]; then
#             printf "$2\n"
#         fi
#     done < <(diskutil apfs list)
# }

### Directory tools
### Usage: dir [OPTION]... [ARG]...
_xlib_dir () {
    case $1 in
        ###   -uh, --unhidden=DIRECTORY   clear the hidden flag on all entries in DIRECTORY [macOS]
        --unhidden|-uh)
            shift;
            [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
            [ -d "$1" ] || exit 1; # Target not found or not a directory.
            chflags nohidden "$1"/*;
            sudo spctl --master-disable;
        ;;
        ###   -lcdi, --list-container-data-info   print container metadata [macOS]
        --list-container-data-info|-lcdi)
            # TODO: OSTYPE?
            local i;
            for i in ~/Library/Containers/*-*-????-*-*; do
                printf '%s # %s\n' "$i" $(
                    defaults read "$i"/.com.apple.containermanagerd.metadata.plist MCMMetadataIdentifier
                );
            done | sort -k 2
        ;;
        ###   --own=DIRECTORY   set the owner of DIRECTORY to the second argument, default 'bin'
        --own)
            shift;
            [ -d "$1" ] || exit 1; # Directory not found.
            local USER arg;
            USER=${2:-bin};
            # ${1:(-1)} == ${1:0-1}
            [ ${1:(-1)} == / ] && arg="${1:0:${#1}-1}" || arg="$1";
            sudo chown -R $USER:`id -gn $USER` "$arg" || return 1;
            sudo chmod -R 644 "$arg/*"
            sudo find "$arg" -type d -exec chmod 755 {} \;
        ;;
        ###   --boot=DIRECTORY   rebuild the boot file in DIRECTORY [macOS]
        --boot)
            [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
            shift;
            [ -f "$1/com.apple.recovery.boot/kernelcache" ] || exit 1; # Boot file not found.
            sudo bless --folder "$1/com.apple.recovery.boot" --label "Recovery HD";
            # 426F6F74-0000-11AA-AA11-00306543ECAC
            # [ "${1##*/}" == "dmtest" -a "${2##*/}" == "BaseSystem.dmg" -a -d "$3" ] && "$2" ensureRecoveryPartition "$3" "$2" 0 0 "${2%.*}.chunklist"
        ;;
        ###   -c, --count[=DIRECTORY]   count files in DIRECTORY, default is the current directory
        --count|-c)
            shift;
            [ "$1" ] && {
                [ -d "$1" ] || exit 1; # Target not found or not a directory.
                :
            } || set -- \.;
            # ls -alR "$1" 2>/dev/null | grep -c '^-'
            find "$1" -type f | grep -c '/'
        ;;
        ###   -u, --unique[=DIRECTORY]   search for duplicate files in DIRECTORY [Linux]
        --unique|-u)
            [[ $OSTYPE == darwin* ]] && exit 1; # Not supported on macOS (OS X).
            shift;
            # TODO
            local i pi size path1 sum name1 temp tmp path_arr=() name_arr=() out=".#Trash";
            touch "$out.log" || exit 1; # Output error.
            mkdir -p "$out";
            while read size path1; do
                [ "$temp" == "$size" ] || {
                    [ ${#path_arr[@]} -gt 1 ] && \
                    while read sum name1; do
                        [ "$sum" ] && printf "${sum:0:8},${name1//%/%%}\n";
                        [ "$tmp" == "$sum" ] || {
                            [ ${#name_arr[@]} -gt 1 ] && {

                                # Save the first file.
                                unset name_arr[0];
                                for pi in ${!name_arr[@]}; do
                                    pi="${name_arr[$pi]}";
                                    printf "$temp,MOVE ";
                                    # Move the file to the new file.
                                    if [ "$pi" == "${pi%/*}" ]; then
                                        mv -v "./$pi" "$out"
                                    else
                                        mkdir -p "$out/${pi%/*}";
                                        mv -v "./$pi" "$out/${pi%/*}"
                                    fi
                                done

                                printf "\n"
                            };

                            # Sync status.
                            tmp="$sum";
                            name_arr=()
                        };
                        [ -f "$name1" ] && name_arr[${#name_arr[@]}]="$name1"
                    done < <(
                        {
                            for i in ${!path_arr[@]}; do
                                sha256sum "${path_arr[$i]}" &
                            done
                            wait
                        } | sort --key=1 | uniq --all-repeated --check-chars=64;
                        printf "\n";
                    );

                    # Sync status.
                    temp="$size";
                    path_arr=()
                };
                [ -f "$path1" ] && path_arr[${#path_arr[@]}]="${path1#*./}";
            done < <(
                find "${@:-.}" -not -empty -type f -not -iregex ".*$out.*" -printf "%s            %p\n" | \
                    sort --key=1 | \
                    uniq --all-repeated --check-chars=12;
                printf "\n";
            ) 2>&1 | tee -a $out.log;

        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

### Lock the screen
### Usage: lock
_xlib_lock () {
    :
}

### String management
### Usage: str [OPTION]... [STRING]...
_xlib_str () {
    case $1 in
        ###   -l, --lower[=STRING]   convert STRING to lower case
        --lower|-l)
            shift;
            [ "$1" ] && {
                tr "[:upper:]" "[:lower:]" <<< "$@"
            } || tr "[:upper:]" "[:lower:]";
        ;;
        ###   -u, --upper[=STRING]   convert STRING to upper case
        --upper|-u)
            shift;
            [ "$1" ] && {
                tr "[:lower:]" "[:upper:]" <<< "$@";
            } || tr "[:lower:]" "[:upper:]"
        ;;
        ###   -xv, --xmlvalue=TAG   print the values of XML TAG
        --xmlvalue|-xv)
            shift;
            [ "$1" ] || exit 1; # Argument is empty.
            # grep -oP '(?<=\>)[\d\w_]+(?=\<\/'$1')' && return 0;
            perl -ne 'STDOUT->autoflush; print m/(?<=\>)[\d\w_]+(?=\<\/'"$1"')/g, "\n"' && return 0;
            return 1
        ;;
        ###   --tac[=FILE]   print FILE in reverse
        --tac)
            shift;
            if which perl >/dev/null; then
                [ "$1" ] && {
                    perl -e 'print reverse <>' "$1"
                    :
                } || perl -e 'print reverse <>'
            else
                [ "$1" ] && {
                    sed '1!G;h;$!d' "$1"
                    :
                } || sed '1!G;h;$!d'
            fi
        ;;
        # --xmltrim|-xt)
        #     # -xt [text_file_path] Get XML without annotations.
        #     shift;
        #     awk '/<!--/{i++}/-->/{i--}!i&&!/-->/&&!/^$/' "$@"
        # ;;
        # --spacetrim|-st)
        #     -st [text_file_path]  Replace all spaces with one space.
        #     shift;
        #     [ -f "$1" ] || exit 1; # File not found.
        #     [ "`uname`" == "Linux" ] && {
        #         sed -r ':1;N;$!b1;s/\s+/ /g' "$1"
        #         :
        #     } || perl -i -pe 's/\s+/ /g' "$1"
        # ;;
        ###   -ua, --unascii=PATH   print text that is not ASCII in PATH
        --unascii|-ua)
            shift;
            if [ -d "$1" ]; then
                grep -r '[^[:alnum:][:punct:][:space:]]' "$1";
            elif [ -f "$1" ]; then
                grep '[^[:alnum:][:punct:][:space:]]' "$1";
            else
                grep '[^[:alnum:][:punct:][:space:]]'
            fi
        ;;
        ###   -n, --now   print the current time as YYYYmmddHHMMSS
        --now|-n)
            date +%Y%m%d%H%M%S
        ;;
        ###   -r, --random[=NUMBER]   print a random string of NUMBER characters
        --random|-r)
            shift;
            # local rand=`dd if=/dev/random bs=1 count=${1:-32} 2>/dev/null | base64 | tr -d '\n'`; # tr -d '\n' support linux
            openssl rand -base64 ${1:-9} | tr -d '\n' | sed "s/[^0-9A-Za-z]/${RANDOM:0:1}/g"
        ;;
        ###   -U, --uuid   print a UUID
        --uuid|-U)
            # macOS ships 'uuidgen'; the Linux kernel exposes one without a package.
            [[ $OSTYPE == darwin* ]] && uuidgen || cat /proc/sys/kernel/random/uuid
        ;;
        ###   -t, --dhms=SECONDS   format SECONDS as Nd Nh Nm Ns
        --dhms|-t)
            shift;
            _xlib_inum $1 || exit 1; # Not a number.
            local out=$(($1 % 60))s;
            [ $1 -ge 60 ] && {
                out=$(($1 % 3600 / 60))m\ $out;
                [ $1 -ge 3600 ] && {
                    out=$(($1 % 86400 / 3600))h\ $out;
                    [ $1 -ge 86400 ] && out=$(($1 / 86400))d\ $out
                }
            };
            printf "$out\n"
        ;;
        ###   -pw, --passwd=STRING   print the crypt hash of STRING
        --passwd|-pw)
            shift;
            which openssl >/dev/null 2>&1 || exit 1; # The openssl command was not found.
            [ "$1" ] || exit 1; # Argument is empty.
            openssl passwd -1 "$1"
        ;;
        ###   -lcs=STRING STRING   print the longest common subsequence
        -lcs)
            source "$(__script_dir)/bash.xlib";
            _lcs "$2" "$3"
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

### Show CPU times [Linux]
### Usage: cpu
_xlib_cpu () {
    [[ $OSTYPE == darwin* ]] && exit 1; # Not supported on macOS (OS X).
    local REPLY;
    while true; do
        read < /proc/stat; printf "$REPLY\n";
        sleep 1;
    done | \
        awk '{printf "%s, %5.1f%\n", strftime("%F %T"), (1 - ($5 - idle) / ($1+$2+$3+$4+$5+$6+$7 - totel)) * 100; idle=$5; totel=$1+$2+$3+$4+$5+$6+$7;}'
}

### Show or find IPv4
### Usage: ip [OPTION]... [ARG]...
_xlib_ip () {
    case $1 in
        ###   -l, --list   print the local IPv4 addresses
        --list|-l)
            __ipv4_list
        ;;
        ###   -f, --find=MAC|ALIAS   search for IPv4 by MAC address or hosts alias
        --find|-f)
            shift;
            source "$(__script_dir)/bash.xlib";
            __ip_find "$@"
        ;;
        ###   -t, --test=STRING   test whether STRING is an IPv4 address
        --test|-t)
            shift;
            __ipv4_test "$@"
        ;;
        # Convert a CIDR prefix (e.g., 1.1.1.0/24) to a subnet mask (e.g., 1.1.1.0 255.255.255.0).
        # See https://doc.m0n0.ch/quickstartpc/intro-CIDR.html.
        ###   -c2s, --cidr2subnet=CIDR   convert CIDR to a subnet mask
        --cidr2subnet|-c2s)
            shift;
            [ "$1" ] || exit 1; # Argument is empty.
            set ${1/\// };

            local submask i=0 octets=$(($2 / 8)) \
                sub_octet=$((256 - 2 ** (8 - ($2 % 8) ) ));

            for ((; i < 4; i += 1))
            do
                if [ $i -lt $octets ]; then
                    submask+=".255";

                elif [ $i == $octets ]; then
                    submask+=".$sub_octet";

                else
                    submask+=".0"

                fi
            done
            printf "$1 ${submask:1}"
        ;;
        # Convert a subnet mask (e.g., 1.1.1.0 255.255.255.0) to a CIDR prefix (e.g., 1.1.1.0/24).
        ###   -s2c, --subnet2cidr=ADDRESS MASK   convert a subnet mask to CIDR
        --subnet2cidr|-s2c)
            shift;
            [ "$2" ] || exit 1; # Argument is empty.

            function _exponent() {
                local base=$1 power=2 exponent=0;
                while [ $((base /= $power)) -gt 0 ]; do
                    ((exponent += 1));
                done
                printf $exponent;

            }

            local mask prefix=0
            for mask in ${2//\./ }; do
                (( prefix += 8 - $(_exponent $((256 - $mask))) ))
            done
            printf $1/$prefix
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

# Test whether STR is an IPv4 address.
__ipv4_test () {
    [ "$1" ] || return 1;
    [ ${#1} -gt 15 ] && return 1;
    # Skip an option.
    [ "${1:0:1}" == "-" ] && return 1;
    [[ $1 != *[^.0-9]* && $1 == [1-9]*[0-9] && $1 != *..* ]] || return 1;
    local a IFS=$IFS".";
    a=($1);
    [ ${#a[@]} == 4 ] || return 1;
    for a in ${a[@]}; do
        [ $a -gt 255 ] && return 1;
    done
    return 0
}

# Print the interfaces that the system itself reports as physical hardware.
# A virtual adapter - a proxy TUN, a VPN, a VM or a container bridge - holds a
# default route of its own, but its subnet cannot reach the LAN, so every route
# and address below is limited to this list.
__if_physical () {
    local ifs= dev;
    if [[ $OSTYPE == darwin* ]]; then
        # The hardware port list is the classification of macOS itself; it holds
        # no tunnel of any kind.
        ifs=`networksetup -listallhardwareports 2>/dev/null | awk '/^Device: /{print $2}'`;
    else
        # The kernel exposes a bus device for a physical NIC; a tunnel, a bridge
        # or a container/virtual interface has no '/sys/class/net/<name>/device'.
        for dev in /sys/class/net/*; do
            [ -e "$dev/device" ] && ifs="$ifs ${dev##*/}";
        done
    fi
    # No classification available: drop the well known virtual names instead.
    [ "$ifs" ] || ifs=`ifconfig -a 2>/dev/null | awk -F: '/^[a-z][a-z0-9]*:/{print $1}' | \
        grep -vE '^(lo|gif|stf|tun|tap|utun|ppp|ipsec|awdl|llw|bridge|vmenet|vmnet|docker|veth|virbr|wg|dummy|sit|ip6tnl|nlmon)[0-9a-z]*$'`;
    printf "%s\n" $ifs
}

# Print the [DEVICE GATEWAY] of every IPv4 default route.
__route_default () {
    if [[ $OSTYPE == darwin* ]]; then
        # Destination Gateway Flags Netif Expire
        netstat -rn -f inet 2>/dev/null | \
            awk '$1 == "default" && $2 ~ /^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/ {print $4, $2}'
    elif which ip >/dev/null 2>&1; then
        ip route show default 2>/dev/null | \
            awk '{d=""; g=""; for (i=1; i<=NF; i++) {if ($i == "via") g=$(i+1); if ($i == "dev") d=$(i+1)};
                if (d != "" && g ~ /^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/) print d, g}'
    else
        # 'route -n' of net-tools or busybox: Destination Gateway Genmask Flags Metric Ref Use Iface
        route -n 2>/dev/null | \
            awk '$1 == "0.0.0.0" && $2 ~ /^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/ {print $8, $2}'
    fi
}

# Print the gateway of every default route of a physical interface; the order is
# not significant. A route list that the physical filter empties falls back to
# every default gateway, so a missing classification still finds the LAN.
__route_gateway () {
    local dev gw physical= settled= any=;
    physical=" $(__if_physical | tr '\n' ' ')";
    while read dev gw; do
        [ "$gw" ] || continue;
        case " $any " in *" $gw "*) continue;; esac
        any="$any $gw";
        case $physical in
            *" $dev "*) settled="$settled $gw";;
        esac
    done < <(__route_default);
    printf "%s\n" ${settled:-$any}
}

# Print the local IPv4 addresses of the physical interfaces.
__ipv4_list () {
    local physical;
    physical=" $(__if_physical | tr '\n' ' ')";
    if [[ $OSTYPE == darwin* ]]; then
        ifconfig 2>/dev/null | awk -v p="$physical" '
            /^[a-z][a-z0-9]*:/ {dev = $1; sub(/:$/, "", dev); keep = (index(p, " " dev " ") > 0)}
            keep && $1 == "inet" {print $2}
        '
    elif which ip >/dev/null 2>&1; then
        # Linux: 'ip' is iproute2, preinstalled on mainstream distributions;
        # 'ifconfig' is the net-tools fallback. POSIX awk only: mawk has no 'gensub'.
        ip -o -4 addr show 2>/dev/null | awk -v p="$physical" '
            {dev = $2; sub(/@.*/, "", dev)}
            index(p, " " dev " ") > 0 && $4 !~ /^(127\.|169\.254\.)/ {sub(/\/.*/, "", $4); print $4}
        '
    else
        ifconfig -a 2>/dev/null | awk -v p="$physical" '
            /^[a-z][a-z0-9]*:/ {dev = $1; sub(/:$/, "", dev); keep = (index(p, " " dev " ") > 0)}
            keep && $1 == "inet" {sub(/.*:/, "", $2); if ($2 !~ /^(127\.|169\.254\.)/) print $2}
        '
    fi
}

# Print the ARP (neighbour) entry of an IPv4 address.
__arp_show () {
    [[ $OSTYPE == darwin* ]] && { arp $1 2>/dev/null; return; };
    # 'arp' is net-tools, which is not preinstalled on Linux; prefer iproute2.
    if which ip >/dev/null 2>&1; then
        ip neigh show "$1" 2>/dev/null
    elif which arp >/dev/null 2>&1; then
        arp -n "$1" 2>/dev/null | tr "[:upper:]" "[:lower:]"
    fi
    :
}

# Clear the ARP (neighbour) cache.
__arp_flush () {
    [[ $OSTYPE == darwin* ]] && { sudo arp -ad >/dev/null 2>&1; return; };
    if which ip >/dev/null 2>&1; then
        ip neigh flush all >/dev/null 2>&1
    elif which arp >/dev/null 2>&1; then
        arp -n 2>/dev/null | awk 'NR>1 {system("arp -d "$1)}' >/dev/null 2>&1
    fi
    :
}

# For _xlib_ip.
__ip_find () {
    [ "$1" ] || exit 1; # MAC address or host name is empty.

    # Clear the ARP cache.
    __arp_flush;

    local i j max_len=0 r key mac range route_ip;

    # Get [setting]. The default gateways come from the physical interfaces only,
    # like [wol] and [ip --list]; a virtual adapter holds a default route of its
    # own whose subnet cannot reach the LAN.
    __load_ini sip_setting;
    route_ip=`_map --get route`;
    # arr=(${var//,/ }) is only supported by bash.
    route_ip=(${route_ip//,/ } `__route_gateway`);
    # Trim the host part of the address.
    for i in ${!route_ip[@]}; do
        _set --add "${route_ip[$i]%.*}" >/dev/null || unset route_ip[$i];
    done
    range=`_map --get range`;
    [ "$range" ] || range="1-127";

    exclude_ip=`_map --get exclude`;
    [ "$exclude_ip" ] && exclude_ip=(${exclude_ip//,/ });
    _map --clear;

    __load_ini hosts;

    local arg mac_addr mac_addr_arr=() tmp;
    for arg in "$@"; do

        # Get from the map.
        mac_addr=`_map --get $arg`;
        mac_addr=${mac_addr:-$arg};

        # Replace the separator; skip a value like 'a-bc'.
        [[ $mac_addr == *-*-*-*-*-* ]] && mac_addr=${mac_addr//-/:};

        [[ $mac_addr == *:*:*:*:*:* ]] && {
            # Cache the maximum variable length.
            [ ${#arg} -gt $max_len ] && max_len=${#arg};
            # Convert to lowercase.
            mac_addr=`_xlib_str --lower $mac_addr`;

            if [[ $OSTYPE == darwin* ]]; then
                # Trim the leading zero: 0a:0b:1c:1d:1e:1f -> a:b:1c:1d:1e:1f.
                tmp="";
                for i in ${mac_addr//|/ }; do
                    [[ $i == *:*:*:*:*:* ]] && \
                    for j in {0..9} {a..f}; do
                        i=${i//0$j/$j}
                    done
                    [ "$tmp" ] && tmp="$tmp|$i" || tmp="$i"
                done
                mac_addr=$tmp;
            fi

            # Add the prefix.
            mac_addr_arr[${#mac_addr_arr[@]}]=$arg@$mac_addr;
        }
    done

    [ ${#mac_addr_arr[@]} == 0 ] && return 0;

    # For the offset.
    max_len=$((max_len / 5 * 5 + 5));

    # fork: Resource temporarily unavailable
    function __match_mac () {
        local i j key t="-W 2";
        # macOS 'ping -t' is a timeout; Linux 'ping -t' is the TTL and the timeout is '-W'.
        [[ $OSTYPE == darwin* ]] && t="-t 2";
        ping -c 2 $t $1 >/dev/null 2>&1;
        j=`__arp_show $1`;
        for mac_addr in ${mac_addr_arr[@]}; do
            # Cache the key.
            key=${mac_addr%%@*};
            # Split the array with '|'.
            mac_addr=(${mac_addr//[@|]/ });
            unset mac_addr[0];
            for i in ${mac_addr[@]}; do
                [[ $j == *$i* ]] && printf "%-${max_len}s$1\n" $key
                # Like nbtstat.
                # [[ `smbutil status $1 2>/dev/null` == *$i* ]] && printf $1
            done
        done
    } 2>/dev/null;

    # Initialize the thread valve.
    _thread_valve --init 32;

    for r in ${route_ip[@]}; do
        for i in `seq ${range/-/ }`; do
            j=true;
            for e in ${exclude_ip[@]}; do [ "${r%.*}.$i" == "$e" ] && j=false; done
            # Get a thread.
            $j && _thread_valve --run __match_mac ${r%.*}.$i
        done
    done

    # Destroy the thread valve.
    _thread_valve --destroy;

    # Print an IPv4 address for each unmatched MAC address.
    for mac_addr in ${mac_addr_arr[@]}; do
        [ "${mac_addr/@/}" == "$mac_addr" -o "${mac_addr/[0-9].[0-9]*.*[0-9].[0-9]/}" == "$mac_addr" ] && continue;
        # Cache the key.
        key=${mac_addr%%@*};
        # Split the array with '|'.
        mac_addr=(${mac_addr//[@|]/ });
        unset mac_addr[0];
        for i in ${mac_addr[@]}; do
            _xlib_ip --test $i && printf "%-${max_len}s$i\n" $key
        done
    done

    # Clear the ARP cache.
    __arp_flush;

}

# __hosts () {
#     printf %s '##
# # Host Database
# #
# # localhost is used to configure the loopback interface
# # when the system is booting.  Do not change this entry.
# ##
# 127.0.0.1	localhost
# 255.255.255.255	broadcasthost
# ::1             localhost
# '
# }

### Update hosts from the ini config
### Usage: hosts
### Read the ini config from HOME or the script path, for example:
###   [hosts]
###   abc.org=01-12-23-34-45-56
###   www.a.com=192.168.1.1
_xlib_hosts () {
    source "$(__script_dir)/bash.xlib";

    # Load the ini into map1.
    __load_ini hosts 1 || exit 1; # The ini config was not found.

    # Get the map1 key array into MAP2ARRAY.
    _map 1 --keys;
    local i j k line host_new lf;
    printf -v lf "\n";

    while read line; do
        # Override the MAC address in map1 when the value is not an IPv4 address.
        _xlib_ip --test "$(_map 1 --get ${line%% *})" || {
            _map 1 --put $line >/dev/null;
            printf "%s\n" "$line"
        }
    done < <(_xlib_ip --find ${MAP2ARRAY[@]});

    # Clear map0, which the sip command used before.
    _map --clear;

    # Get the map1 key-value array into MAP2ARRAY.
    _map 1 --arr || exit 1; # Unknown error

    for ((i=0; i<${#MAP2ARRAY[@]}; i+=2)); do
        _xlib_ip --test ${MAP2ARRAY[i + 1]} && _map --put "${MAP2ARRAY[$i]}" "${MAP2ARRAY[i + 1]}" >/dev/null;
    done

    while read line; do
        k=($line);
        j=`_map --get "${k[1]}"` && {
            _map --remove "${k[1]}" >/dev/null;
            [ "$j" == "$k" ] || {
                host_new+="${line/$k/$j}$lf";
                continue
            };
        }
        host_new+="$line$lf";
    done < <(cat /etc/hosts);

    # Empty the array.
    _map --arr || unset MAP2ARRAY;

    for ((i=0; i<${#MAP2ARRAY[@]}; i+=2)); do
        host_new+="${MAP2ARRAY[i + 1]}	${MAP2ARRAY[i]}$lf"
    done

    printf %s "$host_new" | sudo tee /etc/hosts >/dev/null

}

# # Test mac address
# __imac () {
#     [ "$1" ] || return 1;
#     # Skip an option.
#     [ "${1:0:1}" == "-" ] && return 1;
#     [[ $1 != *[^-:0-9a-fA-F]* && $1 != *--* && $1 != *::* && $1 == [0-9a-fA-F]*[0-9a-fA-F] && $1 != *[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]* ]] || return 1
#     local a IFS=$IFS":-";
#     a=($1);
#     [ ${#a[@]} == 6 ] || return 1;
#     return 0
# }

### Connect to a VNC server [macOS]
### Usage: vnc ADDRESS[:PORT]
_xlib_vnc () {
    [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
    _xlib_ip --test $1 || exit 1; # Argument is not an IPv4 address.
    open vnc://$1;
    return 0
}

### Start a disposable HTTP server
### Usage: httpd PORT [FILE]
_xlib_httpd () {
    _xlib_inum $1 || exit 1; # Argument is not a port.
    which nc >/dev/null 2>&1 || which ncat >/dev/null 2>&1 || exit 1; # The nc command was not found.
    if [ -s "$2" ]; then
        {
            printf "HTTP/1.1 200 OK\n\n";
            cat "$2";
        } | __httpd_listen $1
    else
        printf "HTTP/1.1 200 OK\n\nNETCAT\n" | __httpd_listen $1

    fi
}

# Listen on a port and print the request; pick the arguments of the local netcat.
__httpd_listen () {
    local port=$1 bin=ncat opt="-l";
    # GNU netcat and busybox need '-l -p PORT'; BSD/OpenBSD netcat takes '-l PORT'.
    which ncat >/dev/null 2>&1 || {
        bin=nc;
        case `nc -h 2>&1` in *GNU*|*[Bb]usy[Bb]ox*) opt="-l -p";; esac
    };
    $bin $opt "$port"
}

### Test whether STRING is a number
### Usage: inum STRING
_xlib_inum () {
    [ "$1" ] || return 2;
    [[ $1 != *[^0-9]* && $1 != 0[0-9]* ]] || return 1;
    return 0
}

### Tag each line with a prefix, supporting the date format
### Usage: COMMAND | prefix [STRFTIME]
_xlib_prefix () {
    [ "$1" ] || exit 1; # Argument is empty.
    source "$(__script_dir)/bash.xlib";
    _prefix "$@"
}

### Plist editor [macOS]
### Usage: plist [OPTION]... FILE
_xlib_plist () {
    [[ $OSTYPE == darwin* ]] || exit 1; # Only macOS (OS X) is supported.
    # Tools: plutil, defaults, /usr/libexec/PlistBuddy.
    which plutil >/dev/null 2>&1 || xcode-select --install 2>/dev/null
    [ $# -lt 2 ] && exit 1; # Invalid option.
    [ "${2##*.}" == "plist" ] || exit 1; # File format not supported.
    case $1 in
        ###   -g, --get=FILE KEY   print the value of KEY in the plist FILE
        --get|-g)
            shift;
            [ -f "$1" ] || exit 1; # File does not exist.
            [ "$2" ] || exit 1; # Key does not exist.
            # /usr/libexec/PlistBuddy -c "Print :$2" "$1"
            defaults read "$1" "$2"
        ;;
        ###   -x, --xml=FILE   print the plist FILE as XML
        --xml|-x)
            shift;
            [ -f "$1" ] || exit 1; # File does not exist.
            plutil -convert xml1 "$1" -o - || exit 1; # The plutil command failed.
        ;;
        ###   -j, --json=FILE   print the plist FILE as JSON
        --json|-j)
            shift;
            [ -f "$1" ] || exit 1; # File does not exist.
            plutil -convert json -r "$1" -o - || exit 1; # The plutil command failed.
            printf "\n"
        ;;
        ###   -b, --binary=FILE   serialize the plist FILE to stdout
        --binary|-b)
            shift;
            [ -f "$1" ] && exit 1; # File already exists.
            sudo plutil -convert binary1 -o "$1" - || exit 1; # The plutil command failed.
        ;;
        ###   --load=FILE   load the launchd plist FILE
        --load)
            shift;
            [ -f "$1" ] || exit 1; # File does not exist.
            sudo launchctl load -wF "$1"
        ;;
        ###   --unload=FILE   unload the launchd plist FILE
        --unload)
            shift;
            [ -f "$1" ] || exit 1; # File does not exist.
            sudo launchctl unload -w "$1"
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

# __file_sub_time () {
#     [ -f "$1" ] || return 1;
#     printf $(( (`date +%s` - `stat -f "%a" "$1"`) / 60 / 60 ))
# }

# Load the .*.ini config.
__load_ini () {
    [ "$1" ] || return 1;
    local line is_catch=false;
    while read line; do
        [ "$line" == "" ] && continue;
        if [ "${line/=/}" == "$line" ]; then
            [ "$line" == "[$1]" ] && is_catch=true || is_catch=false;
        elif $is_catch; then
            _map $2 --put ${line%%=*} ${line#*=} >/dev/null
        fi
    done < <(cat "$(__script_dir)"/.*.ini ~/.*.ini 2>/dev/null | awk -F \; 'gsub(/\r|\\$/, ""); gsub(/\\/, "\\\\"); {print $1}' | uniq);

    # # read environment variable
    # while read line; do
    #     [ "$line" == "" -o "${line/=/}" == "$line" ] && continue;
    #     _xlib_ip --test ${line#*=} || {
    #         __imac ${line#*=} || continue
    #     };
    #     _map $2 --put "${line%%=*}" "${line#*=}" >/dev/null;
    # done < <(set);

   [ `_map $2 --size` == 0 ] && return 1;
   return 0
}

# The completion kinds of xlib, added to the generic engine in comp.xlib.
__COMP_KINDS="alias mac ipv4 hostip shell kind";

# Map a metavariable of the annotation; the argument is uppercase.
__comp_kind_host () {
    case $1 in
        HOST)        printf 'alias,ipv4';;
        ADDRESS|IP)  printf ipv4;;
        MAC)         printf mac;;
        ALIAS)       printf alias;;
        HOSTIP)      printf hostip;;
    esac
}

# Print the candidates of a kind of xlib; [hosts] ini needs _map of bash.xlib.
# The kind prints its own candidates in order, versions sort as versions.
__comp_value_host () {
    source "$(__script_dir)/bash.xlib";
    local kind=$1 i j ini= version=;
    case $kind in
        alias|mac|hostip) __load_ini hosts;;
    esac
    case $kind in
        ipv4|hostip)
            # 'sort -V' is GNU/uutils; busybox and some BSD sorts reject it, so
            # fall back to a plain sort instead of failing the completion.
            version=-V;
            sort -V </dev/null >/dev/null 2>&1 || version=;
        ;;
    esac
    {
        case $kind in
            alias)
                _map --keys;
                for i in ${MAP2ARRAY[@]}; do printf "%s\n" "$i"; done
            ;;
            mac)
                _map --values;
                for i in ${MAP2ARRAY[@]}; do
                    for j in ${i//|/ }; do
                        [[ ${j//-/:} == *:*:*:*:*:* ]] && printf "%s\n" "$j"
                    done
                done
            ;;
            ipv4)
                __ipv4_list
            ;;
            hostip)
                # An IP in /etc/hosts that is not in the [hosts] ini.
                _map --keys;
                for i in ${MAP2ARRAY[@]}; do ini="$ini $i"; done;
                _map --values;
                for i in ${MAP2ARRAY[@]}; do
                    for j in ${i//|/ }; do ini="$ini $j"; done
                done;
                for i in `awk '{print $1}' /etc/hosts`; do
                    __ipv4_test "$i" || continue;
                    case $i in 0.*|127.*|169.254.*|2[2-5][0-9].*) continue;; esac
                    case " $ini " in *" $i "*) continue;; esac
                    printf "%s\n" "$i"
                done
            ;;
        esac
    } | sort -u $version
}

### Shell completion, auto-generated from annotations
### Usage: comp [OPTION]...
_xlib_comp () {
    source "$(__script_dir)/comp.xlib";
    case $1 in
        ###   -b, --bash   print the bash completion script
        --bash|-b)
            shift;
            __comp_bash "$@"
        ;;
        ###   -z, --zsh   print the zsh completion script
        --zsh|-z)
            shift;
            __comp_zsh "$@"
        ;;
        ###   -f, --fish   print the fish completion script
        --fish|-f)
            shift;
            __comp_fish "$@"
        ;;
        ###   -i, --install[=SHELL]   install completion to HOME, default is the current shell
        --install|-i)
            shift;
            __comp_install "$@" || exit 1; # Completion installation failed.
        ;;
        ###   -v, --value=KIND   print the candidates of KIND
        --value|-v)
            shift;
            __comp_value "$@"
        ;;
        ###   -l, --list[={macos|linux|all}]   print the parsed completion metadata
        --list|-l)
            shift;
            __comp_scan "${1:-}" | tr ';' '\t'
        ;;
        ###   -c, --check   check annotation and print warnings
        --check|-c)
            shift;
            __comp_check || exit 1 # Annotation warning found.
        ;;
        *)
            exit 1; # Invalid option.
        ;;
    esac
}

# # args path size(MB)
# __ramfs () {
#     # https://gist.github.com/Roman2K/3238fb441e298369198e
#     case $1 in
#         --mount|-m)
#             # hdid = hdiutil attach
#             local ramfs_dev=`hdid -nomount ram://$(($3 * 1024 * 1024 / 512))`;
#             newfs_hfs -v "ramfs" ${ramfs_dev};
#             mkdir -p "$2";
#             # mount -o nobrowse -t hfs ${ramfs_dev} "$2"
#             mount -o noatime -t hfs ${ramfs_dev} "$2"
#         ;;
#         --umount|-u)
#             ramfs_dev=`df "$2" | tail -1 | awk '{ print $1 }'`;
#             umount "$2";
#             hdiutil detach ${ramfs_dev}
#         ;;
#         *)
#             printf "\033[31m$1: invalid option\033[0m\n" >&2
#         ;;
#     esac
# }

#################################################
#                   Framework                   #
# # # # # # # # # # # # # # # # # # # # # # # # #

# Print error info.
_func_err () {
    [[ "$4$6" == exit_${0##*/}* ]] && {
        # local err=`awk 'NR=='$2'{print}' "$0"`;
        local err=`sed -n $2p "$0"`
        # Print the line text after '#'.
        printf "\033[31mError:${err##*#} \033[33m($0:$2)\033[0m\n" >&2;
        exit $(($5 % 256))
    };

    # WARNING: 0 <= $? <= 255; return 256 gives $? = 0.
    [ "$4" == "return" ] && exit $(($5 % 256));

    # A command was not found: the dispatch of an unknown command, or a missing
    # external command.
    [ $1 == 127 ] && {
        [[ $4 == *'${0##*/}'* ]] && { printf "\033[31mError: No function found \033[0m\n" >&2; exit 1; };
        printf "\033[31mError: Command not found: %s \033[33m($0:$2)\033[0m\n" "$4" >&2; exit 127
    };

    exit 0
}


# Show the function info.
_func_annotation () {
    source "$(__script_dir)/comp.xlib";
    local kind cmd key text last= found=;
    local -a cmd_lines=() opt_lines=();
    if [ "$1" ]; then
        # Show one command.
        while IFS=$'\t' read -r kind cmd key text; do
            [ "$cmd" == "$1" ] || continue;
            found=true;
            case $kind in
                O) opt_lines[${#opt_lines[@]}]="$text";;
                P|Q) :;;
                *) cmd_lines[${#cmd_lines[@]}]="$text";;
            esac
        done < <(__annot_scan);
        [ "$found" ] || return 1;
        # split the command annotation around the Usage line
        local -a pre_usage=() post_usage=();
        local usage_line= seen_usage=;
        for text in "${cmd_lines[@]}"; do
            case $text in
                Usage:*)
                    seen_usage=true;
                    usage_line=$text
                ;;
                *)
                    if [ "$seen_usage" ]; then
                        post_usage[${#post_usage[@]}]="$text"
                    else
                        pre_usage[${#pre_usage[@]}]="$text"
                    fi
                ;;
            esac
        done
        [ ${#pre_usage[@]} -gt 0 ] && printf "%s\n" "${pre_usage[@]}";
        [ "$seen_usage" ] && printf "\n%s\n\n" "$usage_line";
        [ ${#post_usage[@]} -gt 0 ] && printf "%s\n" "${post_usage[@]}";
        [ ${#opt_lines[@]} -gt 0 ] && {
            [ ${#post_usage[@]} -gt 0 ] && printf "\n";
            __annot_print "${opt_lines[@]}"
        };
        if [ ${#post_usage[@]} -gt 0 ] || [ ${#opt_lines[@]} -gt 0 ] || [ ! "$seen_usage" ]; then
            printf "\n";
        fi
        return 0

    else
        # Show all commands; the first line of each command annotation is the
        # brief, with its [macOS] / [Linux] tag kept at the end of the line.
        while IFS=$'\t' read -r kind cmd key text; do
            [ "$kind" == "C" ] || continue;
            [ "$cmd" == "$last" ] && continue;
            last=$cmd;
            # Left aligned at 15 characters.
            printf "%-15s%s\n" "$cmd" "$text";
        done < <(__annot_scan)
    fi

}

# Cache and exit.
# bash >= 4.1 resets $LINENO to 1 inside an EXIT trap, so track the real line with
# a DEBUG trap there; older bash (the 3.2 shipped with macOS) reports it directly.
[ "${BASH_VERSINFO[0]}" -gt 4 -o "${BASH_VERSINFO[0]}" -eq 4 -a "${BASH_VERSINFO[1]}" -ge 1 ] && {
    set -T;
    trap 'case $LINENO in 1|"") :;; *) __err_line=$LINENO;; esac' DEBUG
};
trap '_func_err $? "${__err_line:-$LINENO}" $BASH_LINENO $BASH_COMMAND ${FUNCNAME[@]}' EXIT

# # # # # # # # # # # # # # # # # # # # # # # # #
#                   Framework                   #
#################################################

# Test for a help option.
[[ ! "$1" || "$1" == "-h" || "$1" == "--help" ]] && {
    _func_annotation | sort;
    exit 0
} || [[ "$2" == "-h" || "$2" == "--help" ]] && {
    # Test for a help option.
    _func_annotation $1 || printf "\033[31mError: No function found \033[0m\n" >&2;
    exit $?
};

# $*, "$*" and $@ cannot preserve $#; only "$@" preserves the native structure.

# Normalize [--option=value] into [--option] [value]
args=();
for i in "$@"; do
    case $i in
        -*=*) args[${#args[@]}]="${i%%=*}"; args[${#args[@]}]="${i#*=}";;
        *)    args[${#args[@]}]="$i";;
    esac
done

# main
_${0##*/}_"${args[@]}"

# hdiutil attach *.dmg
# hdiutil detach *.dmg
# sudo bless --folder=/Volumes/BOOT --file=/Volumes/BOOT/EFI/BOOT/BOOTX64.efi --setBoot --lgacy
# sudo asr restore -source /Volumes/OS\ X\ Install\ ESD/BaseSystem.dmg -target /Volumes/Untitled -erase -format HFS+

# diskutil rename "$1" "RHD"
# touch .metadata_never_index
# mkdir com.apple.recovery.boot
#    BaseSystem.chunklist
#    boot.efi
#    BaseSystem.dmg
#    com.apple.Boot.plist
#    .disk_label
#    PlatformSupport.plist
#    kernelcache
#    .disk_label_2x
#    SystemVersion.plist


# Erasing Disk: 0%... 10%... 20%... 30%...100%...
# Copying installer files to disk...
# Copy complete.
# Making disk bootable...
# Copying boot files...
# Copy complete.
# Done.

    # .Trashes
    # .fseventsd
    # .IABootFiles
    # Install OS X Yosemite.app
    # .IABootFilesSystemVersion.plist
    # Library
    # .IAPhysicalMedia
    # System
    # .Spotlight-V100
    # usr

# ./System/Library/CoreServices/boot.efi
# ./usr/standalone/i386/boot.efi