From a5c2ac43f553ffaa446df2a79f9e4a4d47e9629d Mon Sep 17 00:00:00 2001
From: Ian Kelling <iank@fsf.org>
Date: Fri, 7 Sep 2018 21:52:07 -0400
Subject: [PATCH] better docs, consistent output to stderr

---
 err | 74 ++++++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 46 insertions(+), 28 deletions(-)

diff --git a/err b/err
index 518b17e..5d62d67 100644
--- a/err
+++ b/err
@@ -19,22 +19,30 @@
 # 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.
 
+
+#######################################
+# Undoes err-catch. turns off exit and stack trace on error.
+#######################################
 err-allow() {
-  # help: turn off exit and stack trace on error. undoes err-catch
   set +E +o pipefail; trap ERR
 }
 
-err-bash-trace() {
-  # help: print stack trace
-  #
-  # Note: It does not show function args unless you first run:
-  # shopt -s extdebug
-  # which err-catch & err-print does for you.
-  #
-  # $1 is the frame to start printing on. default -1. Useful when
-  # printing from an ERR trap function.
 
-  local -i argc_index=0 frame i start=${1:-1} max_indent=8 indent
+#######################################
+# Print stack trace
+#
+# usage: err-bash-trace [FRAME_START]
+#
+# It does not show function args unless you first run:
+# shopt -s extdebug
+# which err-catch & err-print does for you.
+#
+# FRAME_START   The frame to start printing on. default=0. Useful when
+#               printing from an ERR trap function to avoid printing
+#               that function.
+#######################################
+err-bash-trace() {
+  local -i argc_index=0 frame i start=${1:-0} max_indent=8 indent
   local source
   local extdebug=false
   if [[ $(shopt -p extdebug) == *-s* ]]; then
@@ -43,11 +51,11 @@ err-bash-trace() {
   for ((frame=0; frame < ${#FUNCNAME[@]}-1; frame++)); do
     argc=${BASH_ARGC[frame]}
     argc_index+=$argc
-    ((frame < start)) && continue
+    ((frame <= start)) && continue
     if (( ${#BASH_SOURCE[@]} > 1 )); then
       source="${BASH_SOURCE[frame+1]}:${BASH_LINENO[frame]}:"
     fi
-    indent=$((frame-start+1))
+    indent=$((frame-start))
     indent=$((indent < max_indent ? indent : max_indent))
     printf "%${indent}s↳%sin \`%s" '' "$source" "${FUNCNAME[frame]}"
     if $extdebug; then
@@ -57,14 +65,16 @@ err-bash-trace() {
     fi
     echo \'
   done
+  return 0
 }
 
+#######################################
+# On error print stack trace and exit
+#
+# Globals:
+#   ${_errcatch_cleanup[@]}  Optional command & args that will run before exiting
+#######################################
 err-catch() {
-  # help: on errors: print stack trace and exit
-  #
-  # You can set "${_errcatch_cleanup[@]}" to a command and it will run before exiting.
-  # This function depends on err-bash-trace.
-
   set -E; shopt -s extdebug
   _err-trap() {
     err=$?
@@ -81,6 +91,9 @@ err-catch() {
   set -o pipefail
 }
 
+#######################################
+# On error, print stack trace
+#######################################
 err-print() {
   # help: on errors: print stack trace
   #
@@ -99,25 +112,29 @@ err-print() {
 }
 
 
+#######################################
+# On error, print stack trace
+#
+# 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() {
-  # usage: err-exit [EXIT_CODE] [MESSAGE]
-  # help: exit and print stack trace.
-  #
-  # Use this instead of the exit command to be more informative. default
-  # EXIT_CODE is 1. If only one of EXIT_CODE and MESSAGE is given,
-  # we consider it to be an exit code if it is a number.
-  # This function depends on err-bash-trace.
-
   exec >&2
   code=1
   if [[ "$*" ]]; then
     if [[ ${1/[^0-9]/} == "$1" ]]; then
       code=$1
       if [[ $2 ]]; then
-        printf '%s\n' "$2"
+        printf '%s\n' "$2" >&2
       fi
     else
-      printf '%s\n' "$0: $1"
+      printf '%s\n' "$0: $1" >&2
     fi
   fi
   echo "${BASH_SOURCE[1]}:${BASH_LINENO[0]}"
@@ -126,4 +143,5 @@ err-exit() {
   exit $err
 }
 
+# We want this more often than not, so run it now.
 err-catch
-- 
2.25.1