comp.xlib

#!/bin/bash
#   Copyright 2026 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.

# Shared shell completion engine, sourced by a host script such as xlib / x3rd.
#   Scan the annotation of the host script ($0) and generate bash / zsh completion.
#   Entry: the [comp] command of the host, which sources this file and dispatches
#   to the __comp_* functions below.
#
#   The engine knows only the generic kinds (FILE, DIRECTORY, SHELL, KIND, ...).
#   The host declares its own vocabulary and candidates by defining these hooks
#   before this file is loaded:
#       __COMP_KINDS       the kind vocabulary printed by [comp --value KIND]
#       __comp_kind_host   print the kinds of a metavariable the engine does not know
#       __comp_value_host  print the candidates of a kind the engine does not know
#   In the hooks, ordering, dedupe and any config loading are the host's business;
#   the engine only drops candidates that repeat across kinds.
#
#   A command or a case branch that runs on one platform only carries a platform
#   tag at the end of its annotation line: [macOS] or [Linux].  The tag shows up
#   in the host help, while [comp --bash] / [comp --zsh] leave the entry out when
#   the running platform does not match.  See [comp --list PLATFORM].

# Platform tags; a tag is the last word of an annotation line and is not case
# sensitive: 'Volume info or edit [macOS]' -> macos
__comp_tag () {
    local t=${1##* };
    case $t in
        \[[Mm][Aa][Cc][Oo][Ss]\]|\[[Dd][Aa][Rr][Ww][Ii][Nn]\]) printf macos;;
        \[[Ll][Ii][Nn][Uu][Xx]\]) printf linux;;
        *) :;;
    esac
}

# Print a tag that looks like a platform but is not one, e.g. [windows].
__comp_tag_bad () {
    local t=${1##* } u;
    case $t in \[*\]) :;; *) return 1;; esac
    t=${t#[}; t=${t%]};
    u=`printf "%s" "$t" | tr "[:lower:]" "[:upper:]"`;
    case $u in
        MACOS|DARWIN|LINUX) return 1;;
        MAC|OSX|MACOSX|WINDOWS|WIN|WIN32|WIN64|BSD|UNIX|FREEBSD|OPENBSD|ANDROID) printf "%s" "$t";;
        *) return 1;;
    esac
}

# Print the platform of the running system: macos, linux or other.
__comp_os () {
    case $OSTYPE in
        darwin*) printf macos;;
        linux*)  printf linux;;
        *)       printf other;;
    esac
}

# Print option help; align the description like GNU --help.
__annot_print () {
    local text spec desc rest i w=0 col;
    local -a left_arr=() desc_arr=();
    for text in "$@"; do
        # Split the option part and the description at the first two spaces.
        spec=${text#"${text%%[![:space:]]*}"};
        rest=${spec#*"  "};
        if [ "$rest" == "$spec" ]; then
            desc=
        else
            desc=${rest#"${rest%%[![:space:]]*}"};
            spec=${spec%%  *}
        fi
        # Long option without a short form: indent under the short form.
        case $spec in
            --*) left="    $spec";;
            *) left="$spec";;
        esac
        left_arr[${#left_arr[@]}]="$left";
        desc_arr[${#desc_arr[@]}]="$desc";
        [ ${#left} -gt $w ] && w=${#left};
    done
    col=$((2 + w + 2));
    [ $col -gt 34 ] && col=34;
    for ((i=0; i<${#left_arr[@]}; i++)); do
        if [ ! "${desc_arr[$i]}" ]; then
            printf "  %s\n" "${left_arr[$i]}";
        elif [ $((2 + ${#left_arr[$i]} + 2)) -le $col ]; then
            printf "  %-*s%s\n" $((col - 2)) "${left_arr[$i]}" "${desc_arr[$i]}";
        else
            printf "  %s\n%*s%s\n" "${left_arr[$i]}" "$col" "" "${desc_arr[$i]}";
        fi
    done
}

# Scan the annotation and print records split with [TAB]:
#   C [TAB] [command] [TAB] . [TAB] [help line]                command annotation
#   O [TAB] [command] [TAB] [case pattern] [TAB] [help line]   option annotation
#   W [TAB] . [TAB] . [TAB] [help line]                        unbound annotation
#   A [###] at the line start annotates the next [script]_[command] () {
#   An indented [###] annotates the next [case] pattern
#   [###] is reserved for annotation; any other comment must use [#]
__annot_scan () {
    local line trim text pattern cmd= depth=0 i= u= platform= t=;
    local -a cmd_ann=() op_ann=();
    while IFS= read -r line; do
        trim=${line#"${line%%[![:space:]]*}"};
        # Annotation line.
        case $trim in
            '### '*|'###')
                text=${trim#\#\#\#};
                text=${text# };
                if [ "$trim" == "$line" ]; then
                    cmd_ann[${#cmd_ann[@]}]="$text"
                else
                    op_ann[${#op_ann[@]}]="$text"
                fi
                continue
            ;;
        esac
        # A blank line keeps the pending annotation.
        [ "$trim" ] || continue;
        # Bind or drop the pending option annotation.
        if [ ${#op_ann[@]} -gt 0 ]; then
            if [ "$cmd" ] && [ $depth -ge 1 ] && [ "${trim:0-1}" == ")" ]; then
                pattern=${trim%)};
                platform=;
                for text in "${op_ann[@]}"; do
                    # Only a last word like [macOS] can be a tag.
                    t=${text##* };
                    case $t in '['*']') platform=$(__comp_tag "$text"); [ "$platform" ] && break;; esac
                done
                # The tag applies to the whole case branch; it precedes its [O] lines.
                printf 'Q\t%s\t%s\t%s\n' "$cmd" "$pattern" "${platform:--}";
                for text in "${op_ann[@]}"; do printf 'O\t%s\t%s\t%s\n' "$cmd" "$pattern" "$text"; done
            else
                for text in "${op_ann[@]}"; do printf 'W\t.\t.\t%s\n' "$text"; done
            fi
            op_ann=();
        fi
        # Function definition at the line start.
        if [ "$trim" == "$line" ]; then
            case $line in
                _${0##*/}_*' () {'*)
                    cmd=${line%% *}; cmd=${cmd#_${0##*/}_};
                    # Only the line just above [Usage:] is the brief; the rest is stray.
                    u=-1;
                    for ((i=0; i<${#cmd_ann[@]}; i++)); do
                        case ${cmd_ann[$i]} in
                            Usage:*) u=$i; break;;
                        esac
                    done
                    [ $u -gt 1 ] && for ((i=0; i<u - 1; i++)); do printf 'W\t.\t.\t%s\n' "${cmd_ann[$i]}"; done
                    # The platform tag of the brief precedes the [C] lines of the command.
                    i=$((u > 0 ? u - 1 : 0));
                    text=${cmd_ann[$i]};
                    t=${text##* };
                    case $t in '['*']') platform=$(__comp_tag "$text");; *) platform=;; esac
                    printf 'P\t%s\t.\t%s\n' "$cmd" "${platform:--}";
                    for ((i=(u > 0 ? u - 1 : 0); i<${#cmd_ann[@]}; i++)); do printf 'C\t%s\t.\t%s\n' "$cmd" "${cmd_ann[$i]}"; done
                    cmd_ann=(); depth=0;
                    continue
                ;;
                *' () {'*|'}')
                    for text in "${cmd_ann[@]}"; do printf 'W\t.\t.\t%s\n' "$text"; done
                    cmd=; cmd_ann=(); depth=0;
                    continue
                ;;
            esac
        fi
        # A [###] at the line start must be adjacent to the function.
        for text in "${cmd_ann[@]}"; do printf 'W\t.\t.\t%s\n' "$text"; done
        cmd_ann=();
        [ "$cmd" ] || continue;
        # Case depth.
        case $trim in
            case*' in')
                ((++depth));
                continue
            ;;
            esac*)
                [ $depth -gt 0 ] && ((--depth));
                continue
            ;;
        esac
    done < "$0"
}

# Print option tokens of an option annotation line:
#   '-b, --broadcast=ADDRESS   desc' -> '-b --broadcast'
#   'b, bridge   desc'               -> 'b bridge'
__comp_tokens () {
    local spec=$1 t;
    spec=${spec#"${spec%%[![:space:]]*}"};
    spec=${spec%%  *};
    spec=${spec%%=*};
    spec=${spec%[};
    for t in ${spec//,/ }; do printf "%s " "$t"; done
}

# Scan the annotation and print: [command] [TAB] [option=kind,...]... [TAB] [operand kind,...]
# The platform is the running one by default; [macos], [linux] and [all] are accepted.
__comp_scan () {
    local os=${1:-} kind cmd key text types t;
    local cur= optspec= poskinds= lastpat= supported= skip=;
    case $os in
        macos|linux|all) :;;
        *) os=$(__comp_os);;
    esac
    while IFS=$'\t' read -r kind cmd key text; do
        [ "$kind" == "W" ] && continue;
        [ "$cmd" ] || continue;
        if [ "$cmd" != "$cur" ]; then
            [ "$cur" ] && [ "$supported" ] && printf '%s;%s;%s\n' "$cur" "${optspec# }" "$poskinds";
            cur=$cmd; optspec=; poskinds=; lastpat=; supported=true; skip=;
        fi
        case $kind in
            P) [ "$text" == "-" -o "$os" == all -o "$os" == "$text" ] || supported=;;
            # The platform of the case branch; it is consumed by the first [O] line.
            Q) case $text in -) skip=;; *) skip=$text;; esac;;
            C)
                case $text in
                    Usage:*)
                        poskinds=$(__comp_kinds "$poskinds $(__comp_usage "${text#Usage:}")")
                    ;;
                esac
            ;;
            O)
                [ "$key" == "$lastpat" ] && continue;
                lastpat=$key;
                if [ "$skip" ]; then
                    [ "$os" == all -o "$os" == "$skip" ] || { skip=; continue; }
                fi
                skip=;
                types=$(__comp_type "$(__comp_spec "$text")");
                if [ "$key" == "*" ]; then
                    poskinds=$(__comp_kinds "$poskinds ${types//,/ }")
                else
                    for t in `__comp_tokens "$text"`; do optspec="$optspec $t=$types"; done
                fi
            ;;
        esac
    done < <(__annot_scan);
    [ "$cur" ] && [ "$supported" ] && printf '%s;%s;%s\n' "$cur" "${optspec# }" "$poskinds"
}

# Check the annotation and print warnings.
__comp_check () {
    local kind cmd key text last= usage= warn= bad=;
    while IFS=$'\t' read -r kind cmd key text; do
        case $kind in
            C)
                if [ "$cmd" != "$last" ]; then
                    [ "$last" ] && [ "$usage" != "$last" ] && { printf 'WARN: %s: no Usage line\n' "$last"; warn=true; };
                    last=$cmd; usage=;
                fi
                case $text in
                    Usage:*) usage=$cmd;;
                esac
            ;;
            O|P) :;;
            W) printf 'WARN: unbound annotation: %s\n' "$text"; warn=true;;
        esac
        # Only [macOS] and [Linux] are platform tags.
        case $kind in C|O)
            bad=$(__comp_tag_bad "$text");
            [ "$bad" ] && { printf 'WARN: %s: unknown platform tag: [%s]\n' "$cmd" "$bad"; warn=true; };
        ;; esac
    done < <(__annot_scan);
    [ "$last" ] && [ "$usage" != "$last" ] && { printf 'WARN: %s: no Usage line\n' "$last"; warn=true; };
    [ "$warn" ] && return 1;
    return 0
}

# Print type expression of an option or operand annotation line:
#   '-b, --broadcast=ADDRESS   desc'  -> ADDRESS
#   'TARGET=ALIAS|HOSTIP   desc'  -> ALIAS|HOSTIP
__comp_spec () {
    local spec=$1;
    spec=${spec#"${spec%%[![:space:]]*}"};
    spec=${spec%%  *};
    case $spec in
        *=*)
            # Optional argument style: --opt[=ARG].
            spec=${spec#*=}; spec=${spec%...}; spec=${spec%]};
            printf "%s" "$spec"
        ;;
    esac
}

# Parse the type expression and print kinds joined with ','.
#   ADDRESS -> ipv4, MAC|HOST -> mac,alias,ipv4, {yes|no} -> e:yes:no
__comp_type () {
    local t=$1 i k kinds= vals=;
    case $t in
        '{'*'}')
            t=${t#\{}; t=${t%\}};
            for i in ${t//|/ }; do vals="${vals:+$vals:}$i"; done
            printf "e:%s" "$vals";
            return 0
        ;;
    esac
    for i in ${t//|/ }; do
        k=$(__comp_kind "$i");
        [ "$k" ] && kinds="$kinds ${k//,/ }";
    done
    printf "%s" "$(__comp_kinds "$kinds")"
}

# Parse the usage text and print the kinds of the metavariables.
__comp_usage () {
    local i kind kinds=;
    for i in `printf "%s" "$1" | grep -o '[A-Z][A-Z0-9_]*'`; do
        case $i in
            OPTION|OPTIONS) continue;;
        esac
        kind=$(__comp_kind "$i");
        [ "$kind" ] && kinds="$kinds ${kind//,/ }";
    done
    printf "%s" "$(__comp_kinds "$kinds")"
}

# Kinds implemented by this engine; the host may replace the list with its own.
: "${__COMP_KINDS:=shell kind}"

# Host hooks; the fallbacks keep the engine working on its own.
type __comp_kind_host  >/dev/null 2>&1 || __comp_kind_host  () { :; }
type __comp_value_host >/dev/null 2>&1 || __comp_value_host () { :; }

# Map a GNU metavariable to completion kinds.
__comp_kind () {
    local s;
    s=`printf "%s" "$1" | tr "[:lower:]" "[:upper:]"`;
    case $s in
        FILE)             printf file;;
        IMAGE)            printf file;;
        DIRECTORY|DIR)    printf dir;;
        DEVICE)           printf dir;;
        PATH)             printf file;;
        SHELL)            printf shell;;
        KIND)             printf kind;;
        *)                __comp_kind_host "$s";;
    esac
}

# Dedupe and join kinds with ','.
__comp_kinds () {
    local i out=;
    for i in $1; do
        case ",$out," in
            *",$i,"*) :;;
            *) out="${out:+$out,}$i";;
        esac
    done
    printf "%s" "$out"
}

# Print candidates by kind; kinds are split with ','.
__comp_value_kind () {
    local kind=$1 i j;
    case $kind in
        shell) printf "bash\nzsh\nfish\n";;
        kind)  printf "%s\n" $__COMP_KINDS | sort -u;;
        e:*)   for i in ${kind#e:}; do
                   for j in ${i//:/ }; do printf "%s\n" "$j"; done
               done;;
        *)     __comp_value_host "$kind";;
    esac
}

# Print candidates by kind; kinds are split with ',' and keep their order.
# A kind prints its own candidates in order; this only drops repeats across kinds.
__comp_value () {
    [ "$1" ] || return 1;
    local kind;
    for kind in ${1//,/ }; do
        __comp_value_kind "$kind"
    done | awk '!seen[$0]++'
}

__comp_split () {
    # Split an option spec list; set words, bare and caseentries.
    local spec opt kinds;
    words=; bare=; caseentries=;
    for spec in $1; do
        opt=${spec%%=*}; kinds=${spec#*=};
        words="$words $opt";
        case $opt in -*|+*) :;; *) bare="$bare $opt";; esac
        [ "$kinds" ] && caseentries="$caseentries $opt=$kinds";
    done
}

# Print the bash completion script.
__comp_bash () {
    local name=${0##*/} xlib="$(__script_dir)/${0##*/}";
    local cmd opts poskinds spec opt words bare caseentries scan cmds prev_case reply;
    scan=$(__comp_scan);
    cmds=$(printf '%s\n' "$scan" | cut -d';' -f1 | sort -u | tr '\n' ' ');
    printf '#!/bin/bash
# %s bash completion, auto-generated by: %s comp -i
_%s_completion () {
    local cur prev cmd
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"
    if [ "$COMP_CWORD" == 1 ]; then
        COMPREPLY=($(compgen -W "%s" -- "$cur"))
        return
    fi
    cmd="${COMP_WORDS[1]}"
    case $cmd in
' "$name" "$name" "$name" "$cmds";
    while IFS=';' read cmd opts poskinds; do
        [ "$cmd" ] || continue;
        __comp_split "$opts";
        # The 'case $prev in' block of the options that take a value.
        prev_case=;
        for spec in $caseentries; do
            opt=${spec%%=*};
            printf -v reply '                %s) %s; return;;\n' "$opt" "$(__comp_reply "$xlib" "${spec#*=}")";
            prev_case="$prev_case$reply";
        done
        [ "$prev_case" ] && prev_case="            case \$prev in
$prev_case            esac
";
        # The operand reply; a bare option completes the option names.
        [ "$bare" ] && reply="COMPREPLY=(\$(compgen -W \"${bare# }\" -- \"\$cur\"))" || reply="$(__comp_reply "$xlib" "$poskinds")";
        printf '        %s)
%s            if [[ $cur == -* ]]; then
                COMPREPLY=($(compgen -W "%s" -- "$cur")); return
            fi
            %s; return;;
' "$cmd" "$prev_case" "${words# }" "$reply";
    done <<< "$scan"
    # '-o nosort' needs bash 4.4; older bash rejects it, so fall back to the default.
    printf '    esac
}
complete -o nosort -F _%s_completion %s 2>/dev/null || complete -F _%s_completion %s
' "$name" "$name" "$name" "$name"
}

# Print the bash reply command for kinds.
__comp_reply () {
    local xlib=$1 kinds=$2;
    case $kinds in
        "")     printf ':';;
        *file*) printf 'COMPREPLY=($(compgen -f -- "$cur"))';;
        *dir*)  printf 'COMPREPLY=($(compgen -d -- "$cur"))';;
        *)      printf 'COMPREPLY=($(compgen -W "$("%s" comp --value %s)" -- "$cur"))' "$xlib" "$kinds";;
    esac
}

# Print the zsh completion script.
__comp_zsh () {
    local name=${0##*/} xlib="$(__script_dir)/${0##*/}";
    local cmd opts poskinds spec opt words bare caseentries scan cmds prev_case reply;
    scan=$(__comp_scan);
    cmds=$(printf '%s\n' "$scan" | cut -d';' -f1 | sort -u | tr '\n' ' ');
    printf '#!/bin/zsh
# %s zsh completion, auto-generated by: %s comp -i
_%s_completion () {
    local cur prev cmd
    cur=${words[CURRENT]}
    prev=${words[CURRENT-1]}
    if (( CURRENT == 2 )); then
        compadd -- %s
        return
    fi
    cmd=${words[2]}
    case $cmd in
' "$name" "$name" "$name" "$cmds";
    while IFS=';' read cmd opts poskinds; do
        [ "$cmd" ] || continue;
        __comp_split "$opts";
        # The 'case $prev in' block of the options that take a value.
        prev_case=;
        for spec in $caseentries; do
            opt=${spec%%=*};
            printf -v reply '                %s)\n%s\n' "$opt" "$(__comp_zreply "$xlib" "${spec#*=}" '                    ')";
            prev_case="$prev_case$reply";
        done
        [ "$prev_case" ] && prev_case="            case \$prev in
$prev_case            esac
";
        # The operand reply; a bare option completes the option names.
        [ "$bare" ] && printf -v reply '            compadd -- %s\n            return;;' "${bare# }" || reply="$(__comp_zreply "$xlib" "$poskinds" '            ')";
        printf '        %s)
%s            if [[ $cur == -* ]]; then
                compadd -- %s; return
            fi
%s
' "$cmd" "$prev_case" "${words# }" "$reply";
    done <<< "$scan"
    printf '    esac
}
compdef _%s_completion %s
' "$name" "$name"
}

# Print the zsh reply body for kinds: one command per kind and a trailing
# 'return;;', each line prefixed with the indent $3.
__comp_zreply () {
    local xlib=$1 kinds=$2 indent=$3 kind;
    case $kinds in
        *file*) printf '%s_files\n' "$indent";;
        *dir*)  printf '%s_files -/\n' "$indent";;
        *)      for kind in ${kinds//,/ }; do
                    printf '%scompadd -V %s -- ${(f)"$("%s" comp --value %s)"}\n' "$indent" "$kind" "$xlib" "$kind";
                done;;
    esac
    printf '%sreturn;;\n' "$indent"
}

# Print the fish reply body for kinds, each line prefixed with $3.
# The fish helpers __fish_complete_path / __fish_complete_directories ship with fish.
__comp_freply () {
    local xlib=$1 kinds=$2 indent=$3;
    case $kinds in
        "")     :;;
        *file*) printf '%s__fish_complete_path "$cur"\n' "$indent";;
        *dir*)  printf '%s__fish_complete_directories "$cur"\n' "$indent";;
        *)      printf '%sfor __c in (%s comp --value %s)\n%s    printf "%%s\\n" $__c\n%send\n' "$indent" "$xlib" "$kinds" "$indent" "$indent";;
    esac
}

# Print the fish completion script. fish autoloads it from
# ~/.config/fish/completions/, so [comp -i] only has to write the file.
__comp_fish () {
    local name=${0##*/} xlib="$(__script_dir)/${0##*/}";
    local cmd opts poskinds spec opt words bare caseentries scan cmds prev_case reply opt_case;
    scan=$(__comp_scan);
    cmds=$(printf '%s\n' "$scan" | cut -d';' -f1 | sort -u | tr '\n' ' ');
    printf '#!/usr/bin/env fish
# %s fish completion, auto-generated by: %s comp -i
function __%s_completion
    set -l toks (commandline -opc)
    set -l cur (commandline -ct)
    if test (count $toks) -le 1
        printf "%%s\\n" %s
        return
    end
    set -l cmd $toks[2]
    set -l prev $toks[-1]
    switch $cmd
' "$name" "$name" "$name" "$cmds";
    while IFS=';' read cmd opts poskinds; do
        [ "$cmd" ] || continue;
        __comp_split "$opts";
        # The 'case $prev in' block of the options that take a value.
        prev_case=;
        for spec in $caseentries; do
            opt=${spec%%=*};
            printf -v reply '            case %s
%s
                return
' "$opt" "$(__comp_freply "$xlib" "${spec#*=}" '                ')";
            prev_case="$prev_case$reply";
        done
        [ "$prev_case" ] && prev_case="            switch \$prev
$prev_case            end
";
        # The option names, only while the current word starts with '-'.
        opt_case=;
        [ "${words# }" ] && opt_case="            if string match -qr -- \"^-\" \$cur
                printf \"%s\\n\" ${words# }
                return
            end
";
        # The operand reply; a bare option completes the bare words.
        [ "$bare" ] && printf -v reply '            printf "%%s\\n" %s\n' "${bare# }" || reply="$(__comp_freply "$xlib" "$poskinds" '            ')";
        printf '        case %s
%s%s%s
' "$cmd" "$prev_case" "$opt_case" "$reply";
    done <<< "$scan"
    printf '    end
end
complete -c %s -f -a '"'"'(__%s_completion)'"'"'
' "$name" "$name"
}

# Install the completion into HOME.
__comp_install () {
    local shell_name=${1:-${SHELL##*/}} file rc;
    case $shell_name in
        bash)
            file=$HOME/.${0##*/}.comp.bash;
            rc=$HOME/.bashrc;
            __comp_bash > "$file" || return 1 # Write file error.
        ;;
        zsh)
            file=$HOME/.${0##*/}.comp.zsh;
            rc=$HOME/.zshrc;
            __comp_zsh > "$file" || return 1 # Write file error.
        ;;
        fish)
            # fish loads every file in this directory on demand; no rc line.
            file=${XDG_CONFIG_HOME:-$HOME/.config}/fish/completions/${0##*/}.fish;
            mkdir -p "${file%/*}" || return 1;
            __comp_fish > "$file" || return 1 # Write file error.
            printf "%s\n" "$file";
            return 0
        ;;
        *)
            printf "\033[31mError: shell not supported: %s (supported: bash zsh fish)\033[0m\n" "$shell_name" >&2;
            return 1 # Shell not supported.
        ;;
    esac
    printf "source %s\n" "$file";
    # Load the completion in the rc file; it must be after 'compinit' for zsh.
    grep -Fq "${file##*/}" "$rc" 2>/dev/null || {
        printf "\n# %s shell completion, keep it after compinit\nsource %s\n" "$shell_name" "$file" >> "$rc" || return 1;
        printf "# added the line above to %s, restart the shell to take effect\n" "$rc" >&2
    }
}