Fix error with ssh, big refactor

[errhandle.git] / err

#!/bin/bash
# Copyright (C) 2019 Ian Kelling
# SPDX-License-Identifier: GPL-3.0-or-later

# Commentary: Print stack trace and exit/return on errors, or use
# functions below for for more details and manual error handling. See
# end of file for credits etc.

#######################################
# err-catch: Setup trap on ERR to print stack trace and exit (or return
# if the shell is interactive). This is the most common use case so we
# run it after defining it, you can call err-allow to undo that.
#
# This also sets pipefail because it's a good practice to catch more
# errors.
#
# Note: In interactive shell, stack calling line number is not
# available, so we print function definition lines.
#
# Globals
#
#  err_catch_ignore  Array containing glob patterns to test against
#                    filenames to ignore errors from in interactive
#                    shell. Initialized to ignore bash-completion
#                    scripts on debian based systems.
#
#  err-cleanup       If set, this command will run just before exiting.
#
#  _err_func_last    Used internally in err-bash-trace-interactive
#
#######################################
err-catch() {
  set -E;
  if [[ $- == *i* ]]; then
    if ! test ${err_catch_ignore+defined}; then
      err_catch_ignore=(
        '/etc/bash_completion.d/*'
        '*/bash-completion/*'
      )
    fi
    declare -i _err_func_last=0
    shopt -s extdebug
    # shellcheck disable=SC2154
    trap '_err-bash-trace-interactive $? "$BASH_COMMAND" ${BASH_ARGC[0]} "${BASH_ARGV[@]}" || return $?' ERR
  else
    # Man bash on exdebug: "If set at shell invocation, arrange to
    # execute the debugger". We want to avoid that, but I want this file
    # to be sourceable from bash startup files. noninteractive ssh and
    # sources .bashrc on invocation. login_shell sources things on
    # invocation.
    #
    # extdebug allows us to print function arguments in our stack trace.
    if ! shopt login_shell >/dev/null && [[ ! $SSH_CONNECTION ]]; then
      shopt -s extdebug
    fi
    trap err-exit ERR
  fi
  set -o pipefail
}
# This is the most common use case so run it now.
err-catch

#######################################
# Undo err-catch/err-catch-interactive
#######################################
err-allow() {
  shopt -u extdebug
  set +E +o pipefail
  trap ERR
}

#######################################
# err-exit: Print stack trace and exit
#
# Use this instead of the exit command to be more informative.
#
# usage: err-exit [-EXIT_CODE] [MESSAGE]
#
# EXIT_CODE  Default: $? if it is nonzero, otherwise 1.
# MESSAGE    Print MESSAGE to stderr. Default:
#            ${BASH_SOURCE[1]}:${BASH_LINENO[0]}: `$BASH_COMMAND' returned $?
#
# Globals
#
#   err-cleanup   If set, this command will run just before exiting.
#
#######################################
err-exit() {
  local err=$?
  # This has to come before most things or vars get changed
  local msg="${BASH_SOURCE[1]}:${BASH_LINENO[0]}: \`$BASH_COMMAND' returned $err"
  set +x
  if [[ $1 == -* ]]; then
    err=${1#-}
    shift
  elif (( ! err )); then
    err=1
  fi
  if [[ $1 ]]; then
    msg="$1"
  fi
  printf "%s\n" "$msg" >&2
  err-bash-trace 2
  set -e # err trap does not work within an error trap
  if type -t err-cleanup >/dev/null; then
    err-cleanup
  fi
  printf "%s: exiting with status %s\n" "$0" "$err" >&2
  exit $err
}

#######################################
# Print stack trace
#
# usage: err-bash-trace [FRAME_START]
#
# This function is called by the other functions which print stack
# traces.
#
# It does not show function args unless you first run:
# shopt -s extdebug
# which err-catch does for you.
#
# FRAME_START  Optional variable to set before calling. The frame to
#              start printing on. default=1. If ${#FUNCNAME[@]} <=
#              FRAME_START + 1, don't print anything because we are at
#              the top level of the script and better off printing a
#              general message, for example see what our callers print.
#
#######################################
err-bash-trace() {
  local -i argc_index=0 frame i frame_start=${1:-1}
  local source_loc
  if (( ${#FUNCNAME[@]} <= frame_start + 1 )); then
    return 0
  fi
  for ((frame=0; frame < ${#FUNCNAME[@]}; frame++)); do
    argc=${BASH_ARGC[frame]}
    argc_index+=$argc
    if ((frame < frame_start)); then continue; fi
    if (( ${#BASH_SOURCE[@]} > 1 )); then
      source_loc="${BASH_SOURCE[frame]}:${BASH_LINENO[frame-1]}:"
    fi
    printf "  from %sin \`%s" "$source_loc" "${FUNCNAME[frame]}" >&2
    if shopt extdebug >/dev/null; then
      for ((i=argc_index-1; i >= argc_index-argc; i--)); do
        printf " %s" "${BASH_ARGV[i]}" >&2
      done
    fi
    echo \' >&2
  done
  return 0
}

#######################################
# Internal function for err-catch. Prints stack trace from interactive
# shell trap.
#
# Usage: see err-catch-interactive
#######################################
_err-bash-trace-interactive() {
  if (( ${#FUNCNAME[@]} <= 1 )); then
    return 0
  fi

  for pattern in "${err_catch_ignore[@]}"; do
    # shellcheck disable=SC2053
    if [[ ${BASH_SOURCE[1]} == $pattern ]]; then
      return 0
    fi
  done

  local ret bash_command argc pattern i last
  last=$_err_func_last
  _err_func_last=${#FUNCNAME[@]}
  # We have these passed to us because they are lost inside the
  # function.
  ret=$1
  bash_command="$2"
  argc=$(( $3 - 1 ))
  shift 3
  argv=("$@")
  # The trap returns a nonzero, then gets called again. This condition
  # tells us if we are the first.
  if (( _err_func_last > last  )); then
    printf "ERR: \`%s\' returned %s\n" "$bash_command" $ret >&2
  fi
  printf "  from \`%s" "${FUNCNAME[1]}" >&2
  if shopt extdebug >/dev/null; then
    for ((i=argc; i >= 0; i--)); do
      printf " %s" "${argv[i]}" >&2
    done
  fi
  printf "\' defined at %s:%s\n" "${BASH_SOURCE[1]}" "$(declare -F "${FUNCNAME[1]}"|awk "{print \$2}")" >&2
  if [[ -t 1 ]]; then
    return $ret
  else
    # Part of an outgoing pipe, avoid getting get us stuck in a weird
    # subshell if we returned nonzero, which would happen in a situation
    # like this:
    #
    # tf() { while read -r line; do :; done < <(asdf); };
    # tf
    #
    # Note: exit $ret also avoids the stuck subshell problem, and I
    # can't notice any difference, but this seems more proper.
    return 0
  fi
}

# Credits etc:
#
# Related: see my bash script template repo at https://iankelling.org/git.
#
#
# Please email me if you have a patches, bugs, feedback, or if you use
# it or republish it since I'm not aware of any users yet
# Ian Kelling <ian@iankelling.org>.
#
# Tested on bash 4.4.20(1)-release (x86_64-pc-linux-gnu). If you test