Add deprecation warnings with option to turn off

[scop]

Describe the feature/solution

Related to #537, would be good to emit deprecation warnings for deprecated things. Currently a bunch of our deprecations is just in code comments.

Because the deprecation warnings are something end users (as opposed to external completion authors) will see, a setting to turn those off should be added, and referred to in those deprecation warnings. Maybe a global envvar for consistency, see doc/bash_completion.txt

Maintenance (please complete the following information)

• This is a request for new completion
• Link to upstream project query about shipping the completion:

N/A

[akinomyoga]

Because the deprecation warnings are something end users (as opposed to external completion authors) will see, a setting to turn those off should be added, and referred to in those deprecation warnings.

Maybe we can output the warnings only when the deprecated interfaces are first used in the session.

[scop]

Maybe we can output the warnings only when the deprecated interfaces are first used in the session.

Possibly, in addition to the ability to turn them off altogether. An end user who just uses e.g. packaged software shouldn't be modifying files from the packages, but rather preferably report a bug somewhere and then turn the warnings off so they're not bothered by it even once a session after that. Maybe even a possibility to turn each individual warning off separately, so people who want to help with stuff can continue finding new deprecations instead of turning off everything when they see the first one. But dunno if there's any actual audience for such functionality, or if it's just added code/complexity for very little or no gain.

[akinomyoga]

Maybe even a possibility to turn each individual warning off separately, so people who want to help with stuff can continue finding new deprecations instead of turning off everything when they see the first one. But dunno if there's any actual audience for such functionality, or if it's just added code/complexity for very little or no gain.

For those who are willing to continue to help us find new depcreations, I think we may provide an option to specify a log file instead of providing options to turn off each warning. Suppose the variable name to be COMP_WARNING_FILE, the default COMP_WARNING_FILE= (or unset) means the warnings are output to stderr, COMP_WARNING_FILE=/dev/null means completely suppressing the error messages, and COMP_WARNING_FILE=/other/path means appending warning messages into the specified file.

[akinomyoga]

It seems spf13/cobra has a similar variable BASH_COMP_DEBUG_FILE to specify the debug output target. The debug output can be passed to the following function:

__xxxx_debug()
{
    if [[ -n ${BASH_COMP_DEBUG_FILE} ]]; then
        echo "$*" >> "${BASH_COMP_DEBUG_FILE}"
    fi
}

We may think of preparing a similar function

_comp_debug_print() {
    if [[ ! ${COMP_DEBUG_FILE-} ]]; then
        printf '%s\n' "$@"
    elif [[ ${COMP_DEBUG_FILE-} != /dev/null ]]; then
        printf '%s\n' "$@" >> "$COMP_DEBUG_FILE"
    fi
}
declare -gA _comp_debug_deprecated__notified
_comp_debug_deprecated() {
    [[ ${_comp_debug_deprecated__notified[${FUNCNAME[1]}]-} ]] && return 0
    _comp_debug_deprecated__notified[${FUNCNAME[1]}]=yes
    _comp_debug_print "${FUNCNAME[1]}: this is a deprecated function (called by ${BASH_SOURCE[2]-}#L${BASH_LINENO[1]-} ${FUNCNAME[2]-})"
}

and call it in deprecated functions:

_some_deprecated() {
    _comp_debug_deprecated
   do_stuff...
}