fix: Properly pass exit code through. Closes #4

The program for example now quits with exit code `4` if the user calls a
function with `return 4` and `set -e` is enabled

Author: hyperupcall

docs/api.md

@@ -30,7 +30,8 @@ Core functions for any Bash program
 ### core.trap_add()
 
 Adds a handler for a particular `trap` signal or event. Noticably,
-unlike the 'builtin' trap, this does not override any other existing handlers
+unlike the 'builtin' trap, this does not override any other existing handlers. The first argument
+to the handler is the exit code of the last command that ran before the particular 'trap'
 
 #### Example
 
@@ -143,9 +144,11 @@ Prints stacktrace
 
 ```bash
 err_handler() {
-  local exit_code=$?
+  local exit_code=$1 # Note that this isn't `$?`
   core.print_stacktrace
-  exit $exit_code
+  
+  # Note that we're not doing `exit $exit_code` because
+  # that is handled automatically
 }
 core.trap_add 'err_handler' ERR
 ```

pkg/src/public/bash-core.sh

@@ -4,7 +4,8 @@
 # @description Core functions for any Bash program
 
 # @description Adds a handler for a particular `trap` signal or event. Noticably,
-# unlike the 'builtin' trap, this does not override any other existing handlers
+# unlike the 'builtin' trap, this does not override any other existing handlers. The first argument
+# to the handler is the exit code of the last command that ran before the particular 'trap'
 # @arg $1 string Function to execute on an event. Integers are forbiden
 # @arg $2 string Event signal
 # @example
@@ -48,9 +49,16 @@ core.trap_add() {
 		printf -v global_trap_handler_name '%q' "core.private.trap_handler_${signal_spec}"
 
 		if ! eval "$global_trap_handler_name() {
-		core.private.util.trap_handler_common '$signal_spec'
+		local ___exit_code_original=\$?
+		if core.private.util.trap_handler_common '$signal_spec' \"\$___exit_code_original\"; then
+			return \$___exit_code_original
+		else
+			local ___exit_code_user=\$?
+			core.print_error_fn \"User-provided trap handler spectacularly failed with exit code \$___exit_code_user\"
+			return \$___exit_code_user
+		fi
 	}"; then
-			core.panic 'Could not eval function'
+			core.panic 'Failed to eval function'
 		fi
 		# shellcheck disable=SC2064
 		trap "$global_trap_handler_name" "$signal_spec"
@@ -265,9 +273,11 @@ core.panic() {
 # @noargs
 # @example
 #  err_handler() {
-#    local exit_code=$?
+#    local exit_code=$1 # Note that this isn't `$?`
 #    core.print_stacktrace
-#    exit $exit_code
+#    
+#    # Note that we're not doing `exit $exit_code` because
+#    # that is handled automatically
 #  }
 #  core.trap_add 'err_handler' ERR
 core.print_stacktrace() {

pkg/src/util/util.sh

@@ -14,6 +14,7 @@ core.private.util.init() {
 # @internal
 core.private.util.trap_handler_common() {
 	local signal_spec="$1"
+	local code="$2"
 
 	local trap_handlers=
 	IFS=$'\x1C' read -ra trap_handlers <<< "${___global_trap_table___[$signal_spec]}"
@@ -25,7 +26,9 @@ core.private.util.trap_handler_common() {
 		fi
 
 		if declare -f "$trap_handler" &>/dev/null; then
-			"$trap_handler"
+			if "$trap_handler" "$code"; then :; else
+				return $?
+			fi
 		else
 			printf "%s\n" "Warn: core.trap_add: Function '$trap_handler' registered for signal '$signal_spec' no longer exists. Skipping" >&2
 		fi