print_stack_trace: Make skip_callers arg numerical

Realized it'd be very handy to support the removal of callers beyond the
immediate caller in the `lib/log` module after experimenting with
`@go.print_stack_trace` to `@go.log FATAL` calls.

Author: mbland

go-core.bash

@@ -141,16 +141,36 @@ declare _GO_SEARCH_PATHS=("$_GO_CORE_DIR/libexec")
 
 # Prints the stack trace at the point of the call.
 #
+# If supplied, the `skip_callers` argument should be a positive integer (i.e. 1
+# or greater) to remove the caller (and possibly the caller's caller, and so on)
+# from the resulting stack trace.
+#
 # Arguments:
-#   omit_caller: If set, this function's caller is removed from the output
+#   skip_callers: The number of callers to skip over when printing the stack
 @go.print_stack_trace() {
-  local start_index="${1:+2}"
+  local skip_callers="$1"
+  local result=0
   local i
 
-  for ((i=${start_index:-1}; i != ${#FUNCNAME[@]}; ++i)); do
+  if [[ -n "$skip_callers" && ! "$skip_callers" =~ ^[1-9][0-9]*$ ]]; then
+    @go.printf '%s argument %s not a positive integer; printing full stack\n' \
+      "$FUNCNAME" "'$skip_callers'" >&2
+    result=1
+  elif [[ "$skip_callers" -ge "${#FUNCNAME[@]}" ]]; then
+    @go.printf '%s argument %d exceeds stack size %d; printing full stack\n' \
+      "$FUNCNAME" "$skip_callers" "$((${#FUNCNAME[@]} - 1))" >&2
+    result=1
+  fi
+
+  if [[ "$result" -ne '0' ]]; then
+    skip_callers=0
+  fi
+
+  for ((i=$skip_callers + 1; i != ${#FUNCNAME[@]}; ++i)); do
     @go.printf '  %s:%s %s\n' "${BASH_SOURCE[$i]}" "${BASH_LINENO[$((i-1))]}" \
       "${FUNCNAME[$i]}"
   done
+  return "$result"
 }
 
 # Main driver of ./go script functionality.

lib/internal/use

@@ -91,7 +91,7 @@ for __go_module_name in "$@"; do
 
       if [[ ! -f "$__go_module_file" ]]; then
         @go.printf 'ERROR: Module %s not found at:\n' "$__go_module_name" >&2
-        @go.print_stack_trace omit_caller >&2
+        @go.print_stack_trace 1 >&2
         exit 1
       fi
     fi
@@ -100,7 +100,7 @@ for __go_module_name in "$@"; do
   if ! . "$__go_module_file"; then
     @go.printf 'ERROR: Failed to import %s module from %s at:\n' \
       "$__go_module_name" "$__go_module_file" >&2
-    @go.print_stack_trace omit_caller >&2
+    @go.print_stack_trace 1 >&2
     exit 1
   fi
 done

tests/core/print-stack-trace.bats

@@ -13,7 +13,7 @@ teardown() {
 }
 
 @test "$SUITE: stack trace from top level of main ./go script without caller" {
-  create_test_go_script '@go.print_stack_trace omit_caller'
+  create_test_go_script '@go.print_stack_trace 1'
   run "$TEST_GO_SCRIPT"
   assert_success ''
 }
@@ -35,13 +35,45 @@ teardown() {
 @test "$SUITE: omit function caller from stack trace" {
   create_test_go_script \
     'print_stack() {' \
-    "  @go.print_stack_trace omit_caller" \
+    "  @go.print_stack_trace 1" \
     '}' \
     'print_stack'
   run "$TEST_GO_SCRIPT"
   assert_success "  $TEST_GO_SCRIPT:6 main"
 }
 
+@test "$SUITE: bad skip_callers argument prints entire trace" {
+  create_test_go_script \
+    'print_stack() {' \
+    "  @go.print_stack_trace foobar" \
+    '}' \
+    'print_stack'
+  run "$TEST_GO_SCRIPT"
+
+  local error_msg=("@go.print_stack_trace argument 'foobar' not a positive"
+    'integer; printing full stack')
+  assert_failure
+  assert_line_equals 0 "${error_msg[*]}"
+  assert_line_equals 1 "  $TEST_GO_SCRIPT:4 print_stack"
+  assert_line_equals 2 "  $TEST_GO_SCRIPT:6 main"
+}
+
+@test "$SUITE: skipping too many callers prints entire trace" {
+  create_test_go_script \
+    'print_stack() {' \
+    "  @go.print_stack_trace 100" \
+    '}' \
+    'print_stack'
+  run "$TEST_GO_SCRIPT"
+
+  local error_msg=('@go.print_stack_trace argument 100 exceeds stack size 2;'
+    'printing full stack')
+  assert_failure
+  assert_line_equals 0 "${error_msg[*]}"
+  assert_line_equals 1 "  $TEST_GO_SCRIPT:4 print_stack"
+  assert_line_equals 2 "  $TEST_GO_SCRIPT:6 main"
+}
+
 @test "$SUITE: stack trace from subcommand script" {
   create_test_go_script '@go "$@"'
   create_test_command_script 'foo' \
@@ -51,7 +83,7 @@ teardown() {
     'foo_func'
   create_test_command_script 'foo.d/bar' \
     'bar_func() {' \
-    '  @go.print_stack_trace omit_caller' \
+    '  @go.print_stack_trace 1' \
     '}' \
     'bar_func'