Initial commit

The basic.bash script is based on the one used in
`github.com:lawandorga/laworga-mail-server.git`, and other versions
used by me (which the `lawandorga-mail-server.git` one was based upon).

The notes are generally new, but many of them just a consolidation and
refinement of existing knowledge (of mine).

1 files changed, 112 insertions, 0 deletions

diff --git a/src/basic.bash b/src/basic.bash
new file mode 100644
index 0000000..a951e0c
--- /dev/null
+++ b/src/basic.bash
@@ -0,0 +1,112 @@
+# Basic bash configuration for scripts.
+
+# Copyright 2020-2024 Einhard Leichtfuß
+
+
+###################################
+## Error and termination handling
+
+# See `/docs/error-handling.md` on limitations and annoyances.
+
+
+## What to consider as an error.
+
+# Accessing unset variables is an error.
+set -o nounset
+
+# No `pipefail` (default).
+#  - Enabling this might, in particular, cause unexpected issues in `if`
+#    statements.
+#  - Enable in a subshell whereever necessary.
+
+
+## How to act on error.
+
+function basic::print_stacktrace()
+{
+  local -ri offset="$1"
+
+  local -i i
+  local -a args=()
+  for (( i = offset + 1; i < ${#BASH_SOURCE[@]} - 1; i++ ))
+  do
+    # See also the `caller` bash builtin.
+    args+=( "${BASH_SOURCE[i]} ${BASH_LINENO[i-1]} ${FUNCNAME[i]}" )
+  done
+  args+=( "${BASH_SOURCE[i]} ${BASH_LINENO[i-1]} <main>" )
+
+  basic::stacktrace_prettyprint "$BASH_SUBSHELL" "${args[@]}"
+
+  return 0
+}
+
+# Default function to pretty-print stack trace.
+#  - To be redefined if desired.
+function basic::stacktrace_prettyprint()
+{
+  local -ri subshell_id="$1"
+  shift
+
+  local -i i=$#
+  local msg
+  for msg
+  do
+    printf 'FAILED (%d, %d): %s\n' $subshell_id $((--i)) "$msg" >&2
+  done
+
+  return 0
+}
+
+# On ERR, print stack trace and exit non-zero.
+trap 'basic::print_stacktrace 0; exit 1' ERR
+
+# Inherit traps on ERR.
+set -o errtrace
+
+# If we didn't trap ERR (and exit on ERR), we'd likely want the below.
+#  - Note: `inherit_errexit` is similar to `errtrace`.
+#set -o errexit
+#shopt -s inherit_errexit
+
+
+## How to act on exit.
+
+# Default on_exit() function.
+#  - To be redefined if desired.
+function basic::on_exit()
+{
+  return 0
+}
+
+trap 'basic::on_exit' EXIT
+
+
+
+########################
+## Other shell options
+
+# Disable globbing; set good defaults for when temporarily enabled.
+#  - `extglob` has an effect regardless.
+set -o noglob
+shopt -s nullglob dotglob globasciiranges globstar extglob globskipdots
+
+# Print an error message upon `shift`-ing "too far" (causes ERR regardless).
+shopt -s shift_verbose
+
+# Expand associative array subscripts only once.
+shopt -s assoc_expand_once
+
+# Do not let `source' use PATH.
+shopt -u sourcepath
+
+
+
+##################
+## Other options
+
+# Explicitly set the expected default umask.
+umask 022
+
+
+
+# vi: ft=bash ts=2 sw=0 et