1 files changed, 80 insertions, 58 deletions
diff --git a/err b/err
index bde5b02..5b501ce 100755
--- a/err
+++ b/err
@@ -13,71 +13,93 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# this file was generated from gen-err and meant to be sourced
+
+
+# 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.
+
 err-allow() {
-    if [[ $1 ]]; then
-        echo "errallow help: Undo the complimentary errcatch function."
-    else
-        set +E +o pipefail; trap ERR
-    fi
+  # help: turn off exit and stack trace on error. undoes err-catch
+  set +E +o pipefail; trap ERR
 }
 err-bash-trace() {
-    local -i argc_index=0 frame i start=${1:-1} max_indent=8 indent
-    local source
-    local extdebug=false
-    if [[ $(shopt -p extdebug) == *-s* ]]; then
-        extdebug=true
+  # help: print stack trace
+  #
+  # Note: It does not show function args unless you first run:
+  # shopt -s extdebug
+  # err-catch runs this for you.
+
+  local -i argc_index=0 frame i start=${1:-1} max_indent=8 indent
+  local source
+  local extdebug=false
+  if [[ $(shopt -p extdebug) == *-s* ]]; then
+    extdebug=true
+  fi
+  for ((frame=0; frame < ${#FUNCNAME[@]}-1; frame++)); do
+    argc=${BASH_ARGC[frame]}
+    argc_index+=$argc
+    ((frame < start)) && continue
+    if (( ${#BASH_SOURCE[@]} > 1 )); then
+      source="${BASH_SOURCE[frame+1]}:${BASH_LINENO[frame]}:"
+    fi
+    indent=$((frame-start+1))
+    indent=$((indent < max_indent ? indent : max_indent))
+    printf "%${indent}s↳%sin \`%s" '' "$source" "${FUNCNAME[frame]}"
+    if $extdebug; then
+      for ((i=argc_index-1; i >= argc_index-argc; i--)); do
+        printf " %s" "${BASH_ARGV[i]}"
+      done
     fi
-    for ((frame=0; frame < ${#FUNCNAME[@]}-1; frame++)); do
-        argc=${BASH_ARGC[frame]}
-        argc_index+=$argc
-        ((frame < start)) && continue
-        if (( ${#BASH_SOURCE[@]} > 1 )); then
-            source="${BASH_SOURCE[frame+1]}:${BASH_LINENO[frame]}:"
-        fi
-        indent=$((frame-start+1))
-        indent=$((indent < max_indent ? indent : max_indent))
-        printf "%${indent}sâ†³%sin \`%s" '' "$source" "${FUNCNAME[frame]}"
-        if $extdebug; then
-            for ((i=argc_index-1; i >= argc_index-argc; i--)); do
-                printf " %s" "${BASH_ARGV[i]}"
-            done
-        fi
-        echo \'
-    done
+    echo \'
+  done
 }
 err-catch() {
-    set -E; shopt -s extdebug
-    _err-trap() {
-        err=$?
-        exec >&2
-        set +x
-        echo "${BASH_SOURCE[1]}:${BASH_LINENO[0]}:in \`$BASH_COMMAND' returned $err"
-        err-bash-trace 2
-        set -e
-        "${_errcatch_cleanup[@]}"
-        echo "$0: exiting with code $err"
-        exit $err
-    }
-    trap _err-trap ERR
-    set -o pipefail
+  # help: print stack trace and exit on error.
+  #
+  # Set "${_errcatch_cleanup[@]}" to set a command which will run before exiting.
+  # 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]}:in \`$BASH_COMMAND' returned $err"
+    # err trap does not work within an error trap, the following line:
+    err-bash-trace 2; set -e
+    "${_errcatch_cleanup[@]}"
+    echo "$0: exiting with code $err"
+    exit $err
+  }
+  trap _err-trap ERR
+  set -o pipefail
 }
 err-exit() {
-    exec >&2
-    code=1
-    if [[ $@ ]]; then
-        if [[ ${1/[^0-9]/} == "$1" ]]; then
-            code=$1
-            if [[ $2 ]]; then
-                echo "$2"
-            fi
-        else
-            echo "$0: $1"
-        fi
+  # 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"
+      fi
+    else
+      printf "%s\n" "$0: $1"
     fi
-    echo "${BASH_SOURCE[1]}:${BASH_LINENO[0]}"
-    err-bash-trace 2
-    echo "$0: exiting with code $code"
-    exit $err
+  fi
+  echo "${BASH_SOURCE[1]}:${BASH_LINENO[0]}"
+  err-bash-trace 2
+  echo "$0: exiting with code $code"
+  exit $err
 }
-err-catch-function
+err-catch