core: Add @go.print_stack_trace to public API

The primary use case is to provide more helpful error messages from
`. "$_GO_USE_MODULES"`, but it seems generally useful enough to provide
it as part of the public API.

Author: mbland

CONTRIBUTING.md

@@ -310,6 +310,8 @@ it easier to find, count, and possibly transform things.
 
 - Use `@go.printf` for most console output to ensure that the text fits the
   terminal width.
+- Use `@go.print_stack_trace` to provide a detailed error message as
+  appropriate, usually before calling `exit 1`.
 
 ### Gotchas
 

README.md

@@ -323,9 +323,9 @@ Any script in any language can invoke other command scripts by running
 `./go <command> [args..]`. In Bash, however, you can also invoke the `@go`
 function directly as `@go <command> [args...]`.
 
-The `@go` and `@go.printf` functions are available to command scripts written in
-Bash, as Bash command scripts are sourced rather than run using another language
-interpreter.
+The `@go`, `@go.printf`, and `@go.print_stack_trace` functions are available to
+command scripts written in Bash, as Bash command scripts are sourced rather than
+run using another language interpreter.
 
 A number of global variables defined and documented in `go-core.bash`, all
 starting with the prefix `_GO_`, are exported as environment variables and

go-core.bash

@@ -139,6 +139,20 @@ declare _GO_SEARCH_PATHS=("$_GO_CORE_DIR/libexec")
   fi
 }
 
+# Prints the stack trace at the point of the call.
+#
+# Arguments:
+#   omit_caller: If set, this function's caller is removed from the output
+@go.print_stack_trace() {
+  local start_index="${1:+2}"
+  local i
+
+  for ((i=${start_index:-1}; i != ${#FUNCNAME[@]}; ++i)); do
+    @go.printf '  %s:%s %s\n' "${BASH_SOURCE[$i]}" "${BASH_LINENO[$((i-1))]}" \
+      "${FUNCNAME[$i]}"
+  done
+}
+
 # Main driver of ./go script functionality.
 #
 # Arguments:

tests/core/print-stack-trace.bats

@@ -0,0 +1,70 @@
+#! /usr/bin/env bats
+
+load ../environment
+
+teardown() {
+  remove_test_go_rootdir
+}
+
+@test "$SUITE: stack trace from top level of main ./go script" {
+  create_test_go_script '@go.print_stack_trace'
+  run "$TEST_GO_SCRIPT"
+  assert_success "  $TEST_GO_SCRIPT:3 main"
+}
+
+@test "$SUITE: stack trace from top level of main ./go script without caller" {
+  create_test_go_script '@go.print_stack_trace omit_caller'
+  run "$TEST_GO_SCRIPT"
+  assert_success ''
+}
+
+@test "$SUITE: stack trace from function inside main ./go script" {
+  create_test_go_script \
+    'print_stack() {' \
+    '  @go.print_stack_trace' \
+    '}' \
+    'print_stack'
+  run "$TEST_GO_SCRIPT"
+
+  local expected=("  $TEST_GO_SCRIPT:4 print_stack"
+    "  $TEST_GO_SCRIPT:6 main")
+  local IFS=$'\n'
+  assert_success "${expected[*]}"
+}
+
+@test "$SUITE: omit function caller from stack trace" {
+  create_test_go_script \
+    'print_stack() {' \
+    "  @go.print_stack_trace omit_caller" \
+    '}' \
+    'print_stack'
+  run "$TEST_GO_SCRIPT"
+  assert_success "  $TEST_GO_SCRIPT:6 main"
+}
+
+@test "$SUITE: stack trace from subcommand script" {
+  create_test_go_script '@go "$@"'
+  create_test_command_script 'foo' \
+    'foo_func() {' \
+    '  @go foo bar' \
+    '}' \
+    'foo_func'
+  create_test_command_script 'foo.d/bar' \
+    'bar_func() {' \
+    '  @go.print_stack_trace omit_caller' \
+    '}' \
+    'bar_func'
+
+  run "$TEST_GO_SCRIPT" foo
+
+  local go_core_pattern="$_GO_CORE_DIR/go-core.bash:[0-9]+"
+  assert_success
+  assert_line_equals  0 "  $TEST_GO_SCRIPTS_DIR/foo.d/bar:5 source"
+  assert_line_matches 1 "  $go_core_pattern _@go.run_command_script"
+  assert_line_matches 2 "  $go_core_pattern @go"
+  assert_line_equals  3 "  $TEST_GO_SCRIPTS_DIR/foo:3 foo_func"
+  assert_line_equals  4 "  $TEST_GO_SCRIPTS_DIR/foo:5 source"
+  assert_line_matches 5 "  $go_core_pattern _@go.run_command_script"
+  assert_line_matches 6 "  $go_core_pattern @go"
+  assert_line_equals  7 "  $TEST_GO_SCRIPT:3 main"
+}