more accurate interactive trace, refactor

[errhandle.git] / err

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

# Commentary: Bash stack trace and error handling functions. This file
# is meant to be sourced. It loads some functions which you may want to
# call manually (see the comments at the start of each one), and then
# runs err-catch. See the README file for a slightly longer explanation.


#######################################
# Print stack trace
#
# usage: err-bash-trace [MESSAGE]
#
# 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 & err-print do for you.
#
# MESSAGE       Message to print just before the stack trace.
#
# _frame_start  Optional variable to set before calling. The frame to
#               start printing on. default=1. Useful when printing from
#               an ERR trap function to avoid printing that function.
#######################################
err-bash-trace() {
  local -i argc_index=0 frame i start=${_frame_start:-1}
  local source
  if [[ $1 ]]; then
    printf "%s\n" "$1"
  fi
  for ((frame=0; frame < ${#FUNCNAME[@]}; frame++)); do
    argc=${BASH_ARGC[frame]}
    argc_index+=$argc
    ((frame < start)) && continue
    if (( ${#BASH_SOURCE[@]} > 1 )); then
      source="${BASH_SOURCE[frame]}:${BASH_LINENO[frame-1]}:"
    fi
    printf "  from %sin \`%s" "$source" "${FUNCNAME[frame]}"
    if shopt extdebug >/dev/null; then
      for ((i=argc_index-1; i >= argc_index-argc; i--)); do
        printf " %s" "${BASH_ARGV[i]}"
      done
    fi
    echo \'
  done
  return 0
}

#######################################
# On error print stack trace and exit
#
# Globals:
#   errcatch-cleanup  If set, this command will run just before exiting.
#######################################
err-catch() {
  set -E;
  # This condition avoids starting the bash debugger in the case that
  # this is sourced from a startup file, and you use a login shell to
  # run a command. Avoid doing that if you want function arguments in
  # your trace.
  if [[ $- != *c* ]] || ! shopt login_shell >/dev/null; then
    shopt -s extdebug
  fi
  _err-trap() {
    err=$?
    exec >&2
    set +x
    local msg="${BASH_SOURCE[1]}:${BASH_LINENO[0]}: \`$BASH_COMMAND' returned $err"
    if (( ${#FUNCNAME[@]} > 2 )); then
      local _frame_start=2
      err-bash-trace "$msg"
    else
      echo "$msg"
    fi
    set -e # err trap does not work within an error trap
    if type -t errcatch-cleanup >/dev/null; then
      errcatch-cleanup
    fi
    echo "$0: exiting with status $err"
    exit $err
  }
  trap _err-trap ERR
  set -o pipefail
}


#######################################
# Internal function for err-catch-interactive.
# Prints stack trace from interactive shell trap.
# Usage: see err-catch-interactive
#######################################

_err-bash-trace-interactive() {
  local ret bash_command argc pattern i
  # We have these passed to us because they are lost inside the
  # function.
  ret=$1
  bash_command="$2"
  argc=$(( $3 - 1 ))
  shift 3
  argv=("$@")
  for pattern in "${err_catch_ignore[@]}"; do
    # shellcheck disable=SC2053
    if [[ ${BASH_SOURCE[0]} == $pattern ]]; then
      return 0
    fi
  done
  if (( ${#FUNCNAME[@]} > _err_func_last )); then
    echo ERR: \`$bash_command\' returned $ret
  fi
  _err_func_last=${#FUNCNAME[@]}
  if (( _err_func_last > 1 )); then
    printf "  from \`%s" "${FUNCNAME[1]}"
    if shopt extdebug >/dev/null; then
      for ((i=argc; i >= 0; i--)); do
        printf " %s" "${argv[i]}"
      done
    fi
    printf "\' defined at %s:%s\n" "${BASH_SOURCE[1]}" "$(declare -F "${FUNCNAME[1]}"|awk "{print \$2}")"
    return $ret
  fi
}

#######################################
# For interactive shells: on error, print stack trace and return
#
# Note: 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. Initialized to ignore bash-completion scripts on debian
#                     based systems.
#   _err_func_last    Used internally in err-bash-trace-interactive
#
#######################################
err-catch-interactive() {
  if ! test ${err_catch_ignore+defined}; then
    err_catch_ignore=(
      '/etc/bash_completion.d/*'
      '*/bash-completion/*'
    )
  fi
  declare -i _err_func_last=0
  set -E; shopt -s extdebug
  # shellcheck disable=SC2154
  trap '_err-bash-trace-interactive $? "$BASH_COMMAND" ${BASH_ARGC[0]} "${BASH_ARGV[@]}"' ERR
  set -o pipefail
}


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

#######################################
# On error, print stack trace
#######################################
err-print() {
  # help: on errors: print stack trace
  #
  # This function depends on err-bash-trace.

  set -E; shopt -s extdebug
  _err-trap() {
    err=$?
    exec >&2
    set +x
    echo "${BASH_SOURCE[1]}:${BASH_LINENO[0]}: \`$BASH_COMMAND' returned $err"
    err-bash-trace 2
  }
  trap _err-trap ERR
  set -o pipefail
}


#######################################
# 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 is 1.
# MESSAGE    Print MESSAGE to stderr. If only one of EXIT_CODE
#            and MESSAGE is given, we consider it to be an
#            exit code if it is a number.
#######################################
err-exit() {
  exec >&2
  code=1
  if [[ "$*" ]]; then
    if [[ ${1/[^0-9]/} == "$1" ]]; then
      code=$1
      if [[ $2 ]]; then
        printf '%s\n' "$2" >&2
      fi
    else
      printf '%s\n' "$0: $1" >&2
    fi
  fi
  echo "${BASH_SOURCE[1]}:${BASH_LINENO[0]}"
  err-bash-trace 2
  echo "$0: exiting with code $code"
  exit $err
}

# We want this more often than not, so run it now.
if [[ $- == *i* ]]; then
  err-catch-interactive
else
  err-catch
fi