From acd03e1ed6a59b5e6d42e74b76ee0b5a98e645c4 Mon Sep 17 00:00:00 2001 From: Ian Kelling Date: Fri, 13 Jul 2018 14:37:21 -0400 Subject: [PATCH] simplify: remove duplication and update docs --- README | 23 ++++--- err | 138 +++++++++++++++++++++++----------------- err-allow-function | 22 ------- err-bash-trace-function | 45 ------------- err-catch-function | 36 ----------- err-exit-function | 34 ---------- generate-err | 38 ----------- 7 files changed, 91 insertions(+), 245 deletions(-) delete mode 100644 err-allow-function delete mode 100644 err-bash-trace-function delete mode 100644 err-catch-function delete mode 100644 err-exit-function delete mode 100755 generate-err diff --git a/README b/README index ff45665..b8e85f2 100644 --- a/README +++ b/README @@ -1,21 +1,20 @@ -Functions to deal with errors in bash +Bash stack trace and error handling functions -err: usually, just copy and source this. contains the other files +Usually, just copy the err file and source it. Then on any non-zero +return code outside of a conditional, the program will exit and print a +stack trace. +The err file has some functions which you may want to call manually for +different or additional error handling. See the comments at the start of +each one. -err-catch: set a trap on error to do bash-trace and exit -err-allow: undo errcatch -err-exit: exit and print stack trace -bash-trace: print stack trace (best bash stack trace ever) - -the err* functions depend on bash-trace. - -For scripts without any nested function calls, this is usually sufficient: +For scripts where functions are not used, you can optionally use a more +minimal approach: set -eE -o pipefail trap 'echo "$0:$LINENO:error: \"$BASH_COMMAND\" returned $?" >&2' ERR -Cleanup commands or functions can be appended to the ERR trap after a -semicolon within the single quotes. +In the above line, cleanup commands or functions can be appended to the +ERR trap after a semicolon within the single quotes. Related: see my bash script template repo, at https://iankelling.org/git. diff --git a/err b/err index 70dd6b2..1abf559 100644 --- 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 diff --git a/err-allow-function b/err-allow-function deleted file mode 100644 index 265c838..0000000 --- a/err-allow-function +++ /dev/null @@ -1,22 +0,0 @@ -#!/bin/bash -# Copyright (C) 2018 Ian Kelling - -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at - -# http://www.apache.org/licenses/LICENSE-2.0 - -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -err-allow() { - if [[ $1 ]]; then - echo "errallow help: Undo the complimentary errcatch function." - else - set +E +o pipefail; trap ERR - fi -} diff --git a/err-bash-trace-function b/err-bash-trace-function deleted file mode 100644 index f46e165..0000000 --- a/err-bash-trace-function +++ /dev/null @@ -1,45 +0,0 @@ -#!/bin/bash -# Copyright (C) 2018 Ian Kelling - -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at - -# http://www.apache.org/licenses/LICENSE-2.0 - -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# Note: bash-trace will not show function args unless you first run: -# shopt -s extdebug -# Also note, setting extdebug in your .bashrc causes spam in bash 4.4. - -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 - 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 -} diff --git a/err-catch-function b/err-catch-function deleted file mode 100644 index ccb2145..0000000 --- a/err-catch-function +++ /dev/null @@ -1,36 +0,0 @@ -#!/bin/bash -# Copyright (C) 2018 Ian Kelling - -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at - -# http://www.apache.org/licenses/LICENSE-2.0 - -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - - -# runs "${_errcatch_cleanup[@]}" for caller defined error handling. -# While running that, we exit with set -e, no stack trace, as -# err trap does not work within an error trap - -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 -} diff --git a/err-exit-function b/err-exit-function deleted file mode 100644 index e72f2f5..0000000 --- a/err-exit-function +++ /dev/null @@ -1,34 +0,0 @@ -#!/bin/bash -# Copyright (C) 2018 Ian Kelling - -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at - -# http://www.apache.org/licenses/LICENSE-2.0 - -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -err-exit() { - # usage: err-exit [EXIT_CODE] [MESSAGE] - 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 - fi - echo "${BASH_SOURCE[1]}:${BASH_LINENO[0]}" - err-bash-trace 2 - echo "$0: exiting with code $code" - exit $err -} diff --git a/generate-err b/generate-err deleted file mode 100755 index 069e693..0000000 --- a/generate-err +++ /dev/null @@ -1,38 +0,0 @@ -#!/bin/bash -# Copyright 2018 Ian Kelling - -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at - -# http://www.apache.org/licenses/LICENSE-2.0 - -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - - -x="$(readlink -f "$BASH_SOURCE")"; cd ${x%/*} # directory of this file - -cat <<'EOF' >err -#!/bin/bash -# Copyright 2018 Ian Kelling - -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at - -# http://www.apache.org/licenses/LICENSE-2.0 - -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# this file was generated from generate-err and meant to be sourced -EOF -sed -r '/^ *(#|$)/d' *-function >>err -echo err-catch >>err -- 2.25.1