feat: Add fns for better error reporting

Author: hyperupcall

docs/api.md

@@ -13,10 +13,12 @@ Core functions for any Bash program
 * [core.err_set()](#coreerr_set)
 * [core.err_clear()](#coreerr_clear)
 * [core.err_exists()](#coreerr_exists)
+* [core.err_print()](#coreerr_print)
 * [core.print_stacktrace()](#coreprint_stacktrace)
 * [core.print_error()](#coreprint_error)
 * [core.print_warn()](#coreprint_warn)
 * [core.print_info()](#coreprint_info)
+* [core.panic()](#corepanic)
 * [core.should_output_color()](#coreshould_output_color)
 * [core.get_package_info()](#coreget_package_info)
 * [core.init()](#coreinit)
@@ -126,6 +128,10 @@ _does_ exist
 
 _Function has no arguments._
 
+### core.err_print()
+
+Prints the current error stored
+
 ### core.print_stacktrace()
 
 Prints stacktrace
@@ -167,6 +173,10 @@ Print an informative message to standard output
 
 * **$1** (string): message
 
+### core.panic()
+
+Use when a serious fault occurs. It will print the current ERR (if it exists)
+
 ### core.should_output_color()
 
 Determine if color should be printed. Note that this doesn't

pkg/src/public/bash-core.sh

@@ -263,6 +263,13 @@ core.err_exists() {
 	fi
 }
 
+# @description Prints the current error stored
+core.err_print() {
+	printf '%s\n' 'Error found:'
+	printf '%s\n' "  ERRCODE: $ERRCODE" >&2
+	printf '%s\n' "  ERR: $ERR" >&2
+}
+
 # @description Prints stacktrace
 # @noargs
 # @example
@@ -293,6 +300,7 @@ core.print_stacktrace() {
 
 		printf '%s\n' "  in ${FUNCNAME[$i]} ($file:${BASH_LINENO[$i-1]})"
 
+		# shellcheck disable=SC1007
 		if ! CDPATH= cd -- "$old_cd"; then
 			cd_failed='yes'
 		fi
@@ -327,6 +335,17 @@ core.print_info() {
 	printf '%s\n' "Info: ${FUNCNAME[1]}${msg:+": "}$msg"
 }
 
+# @description Use when a serious fault occurs. It will print the current ERR (if it exists)
+core.panic() {
+	local code="${1-1}"
+
+	if core.err_exists; then
+		core.err_print
+	fi
+	core.print_stacktrace
+	exit "$code"
+}
+
 # @description Determine if color should be printed. Note that this doesn't
 # use tput because simple environment variable checking heuristics suffice
 core.should_output_color() {