docs: Add preliminary docs

Author: hyperupcall

Bakefile.sh

@@ -1,5 +1,5 @@
 # shellcheck shell=bash
 
-task.gen() {
-	deno run --allow-read --allow-write ./scripts/parse.ts --write
+task.docs() {
+	shdoc < './pkg/src/public/bash-term.sh' > './docs/api-term.md'
 }

bake

@@ -20,6 +20,104 @@ if [ "$0" != "${BASH_SOURCE[0]}" ] && [ "$BAKE_INTERNAL_CAN_SOURCE" != 'yes' ];
 	return 1
 fi
 
+# @description Prints `$1` formatted as an error and the stacktrace to standard error,
+# then exits with code 1
+# @arg $1 string Text to print
+bake.die() {
+	if [ -n "$1" ]; then
+		__bake_error "$1. Exiting"
+	else
+		__bake_error 'Exiting'
+	fi
+	__bake_print_big '<- ERROR'
+
+	__bake_print_stacktrace
+
+	exit 1
+}
+
+# @description Prints `$1` formatted as a warning to standard error
+# @arg $1 string Text to print
+bake.warn() {
+	if __bake_is_color; then
+		printf "\033[1;33m%s:\033[0m %s\n" 'Warn' "$1"
+	else
+		printf '%s: %s\n' 'Warn' "$1"
+	fi
+} >&2
+
+# @description Prints `$1` formatted as information to standard output
+# @arg $1 string Text to print
+bake.info() {
+	if __bake_is_color; then
+		printf "\033[0;34m%s:\033[0m %s\n" 'Info' "$1"
+	else
+		printf '%s: %s\n' 'Info' "$1"
+	fi
+}
+
+# @description Dies if any of the supplied variables are empty. Deprecated in favor of 'bake.assert_not_empty'
+# @arg $@ string Names of variables to check for emptiness
+# @see bake.assert_not_empty
+bake.assert_nonempty() {
+	__bake_internal_warn "Function 'bake.assert_nonempty' is deprecated. Please use 'bake.assert_not_empty' instead"
+	bake.assert_not_empty "$@"
+}
+
+# @description Dies if any of the supplied variables are empty
+# @arg $@ string Names of variables to check for emptiness
+bake.assert_not_empty() {
+	local variable_name=
+	for variable_name; do
+		local -n ____variable="$variable_name"
+
+		if [ -z "$____variable" ]; then
+			bake.die "Failed because variable '$variable_name' is empty"
+		fi
+	done; unset -v variable_name
+}
+
+# @description Dies if a command cannot be found
+# @arg $1 string Command name to test for existence
+bake.assert_cmd() {
+	local cmd=$1
+
+	if [ -z "$cmd" ]; then
+		bake.die "Argument must not be empty"
+	fi
+
+	if ! command -v "$cmd" &>/dev/null; then
+		bake.die "Failed to find command '$cmd'. Please install it before continuing"
+	fi
+}
+
+# @description Change the behavior of Bake
+# @arg $1 string Name of config property to change
+# @arg $2 string New value of config property
+bake.cfg() {
+	local cfg=$1
+	local value=$2
+
+	case $cfg in
+	stacktrace)
+		case $value in
+			yes|no) __bake_cfg_stacktrace=$value ;;
+			*) __bake_internal_die2 "Config property '$cfg' accepts only either 'yes' or 'no'" ;;
+		esac
+		;;
+	pedantic-task-cd)
+		case $value in
+			yes) trap '__bake_trap_debug' 'DEBUG' ;;
+			no) trap - 'DEBUG' ;;
+			*) __bake_internal_die2 "Config property '$cfg' accepts only either 'yes' or 'no'" ;;
+		esac
+		;;
+	*)
+		__bake_internal_die2 "No config property matched '$cfg'"
+		;;
+	esac
+}
+
 # @description Prints stacktrace
 # @internal
 __bake_print_stacktrace() {
@@ -31,25 +129,39 @@ __bake_print_stacktrace() {
 		fi
 
 		local i=
-		for ((i=0;i<${#FUNCNAME[@]}-1;i++)); do
-			local __bash_source=${BASH_SOURCE[$i]}; __bash_source="${__bash_source##*/}"
+		for ((i=0; i<${#FUNCNAME[@]}-1; ++i)); do
+			local __bash_source="${BASH_SOURCE[$i]}"; __bash_source=${__bash_source##*/}
 			printf '%s\n' "  in ${FUNCNAME[$i]} ($__bash_source:${BASH_LINENO[$i-1]})"
 		done; unset -v i __bash_source
 	fi
 } >&2
 
-# @description Function 'trap' calls on 'ERR'
+# @description Function that is executed when the 'ERR' event is trapped
 # @internal
 __bake_trap_err() {
 	local error_code=$?
 
 	__bake_print_big "<- ERROR"
-	__bake_internal_error "Your 'Bakefile.sh' did not exit successfully"
+	__bake_internal_error "Your Bakefile did not exit successfully (exit code $error_code)"
 	__bake_print_stacktrace
 
 	exit $error_code
 } >&2
 
+__global_bake_trap_debug_current_function=
+__bake_trap_debug() {
+	local current_function="${FUNCNAME[1]}"
+
+	if [[ $current_function != "$__global_bake_trap_debug_current_function" \
+			&& $current_function == task.* ]]; then
+		if ! cd "$BAKE_ROOT"; then
+			__bake_internal_die "Failed to cd to \$BAKE_ROOT"
+		fi
+	fi
+
+	__global_bake_trap_debug_current_function=$current_function
+} >&2
+
 # @description Test whether color should be outputed
 # @exitcode 0 if should print color
 # @exitcode 1 if should not print color
@@ -62,6 +174,25 @@ __bake_is_color() {
 	fi
 }
 
+# @description Calls `__bake_internal_error` and terminates with code 1
+# @arg $1 string Text to print
+# @internal
+__bake_internal_die() {
+	__bake_internal_error "$1. Exiting"
+	exit 1
+}
+
+# @description Calls `__bake_internal_error` and terminates with code 1. Before
+# doing so, it closes with "<- ERROR" big text
+# @arg $1 string Text to print
+# @internal
+__bake_internal_die2() {
+	__bake_print_big '<- ERROR'
+
+	__bake_internal_error "$1. Exiting"
+	exit 1
+}
+
 # @description Prints `$1` formatted as an internal Bake error to standard error
 # @arg $1 Text to print
 # @internal
@@ -84,15 +215,8 @@ __bake_internal_warn() {
 	fi
 } >&2
 
-# @description Calls `__bake_internal_error` and terminates with code 1
-# @arg $1 string Text to print
-# @internal
-__bake_internal_die() {
-	__bake_internal_error "$1. Exiting"
-	exit 1
-}
-
-# @description Prints `$1` formatted as an error to standard error
+# @description Prints `$1` formatted as an error to standard error. This is not called because
+# I do not wish to surface a public 'bake.error' function. All errors should halt execution
 # @arg $1 string Text to print
 # @internal
 __bake_error() {
@@ -103,7 +227,7 @@ __bake_error() {
 	fi
 } >&2
 
-# @description Nicely prints all 'Basalt.sh' tasks to standard output
+# @description Nicely prints all 'Bakefile.sh' tasks to standard output
 # @internal
 __bake_print_tasks() {
 	# shellcheck disable=SC1007,SC2034
@@ -144,7 +268,11 @@ __bake_print_big() {
 	fi
 } >&2
 
-__bake_set_vars() {
+# @description Parses the arguments. This also includes setting the the 'BAKE_ROOT'
+# and 'BAKE_FILE' variables
+# @set REPLY Number of times to shift
+# @internal
+__bake_parse_args() {
 	unset REPLY; REPLY=
 	local -i total_shifts=0
 
@@ -153,7 +281,7 @@ __bake_set_vars() {
 	-f)
 		BAKE_FILE=$2
 		if [ -z "$BAKE_FILE" ]; then
-			__bake_internal_die 'File must not be empty. Exiting'
+			__bake_internal_die "A value was not specified for for flag '-f"
 		fi
 		((total_shifts += 2))
 		if ! shift 2; then
@@ -164,7 +292,7 @@ __bake_set_vars() {
 			__bake_internal_die "Specified file '$BAKE_FILE' does not exist"
 		fi
 		if [ ! -f "$BAKE_FILE" ]; then
-			__bake_internal_die "Specified path '$BAKE_FILE' is not actually a file"
+			__bake_internal_die "Specified file '$BAKE_FILE' is not actually a file"
 		fi
 		;;
 	-h)
@@ -195,7 +323,7 @@ __bake_set_vars() {
 
 			printf '%s' "$PWD"
 		); then
-			__bake_internal_die "Could not find 'Bakefile.sh'"
+			__bake_internal_die "Failed to find 'Bakefile.sh'"
 		fi
 		BAKE_FILE="$BAKE_ROOT/Bakefile.sh"
 	fi
@@ -211,106 +339,27 @@ __bake_set_vars() {
 	REPLY=$total_shifts
 }
 
-# @description Prints `$1` formatted as an error and the stacktrace to standard error,
-# then exits with code 1
-# @arg $1 string Text to print
-bake.die() {
-	if [ -n "$1" ]; then
-		__bake_error "$1. Exiting"
-	else
-		__bake_error 'Exiting'
-	fi
-	__bake_print_big '<- ERROR'
-
-	__bake_print_stacktrace
-
-	exit 1
-}
-
-# @description Prints `$1` formatted as a warning to standard error
-# @arg $1 string Text to print
-bake.warn() {
-	if __bake_is_color; then
-		printf "\033[1;33m%s:\033[0m %s\n" 'Warn' "$1"
-	else
-		printf '%s: %s\n' 'Warn' "$1"
-	fi
-} >&2
-
-# @description Prints `$1` formatted as information to standard output
-# @arg $1 string Text to print
-bake.info() {
-	if __bake_is_color; then
-		printf "\033[0;34m%s:\033[0m %s\n" 'Info' "$1"
-	else
-		printf '%s: %s\n' 'Info' "$1"
-	fi
-}
-
-# @description Dies if any of the supplied variables are empty. Deprecated in favor of 'bake.assert_not_empty'
-# @arg $@ string Variable names to print
-# @see bake.assert_not_empty
-bake.assert_nonempty() {
-	__bake_internal_warn "Function 'bake.assert_nonempty' is deprecated. Please use 'bake.assert_not_empty' instead"
-	bake.assert_not_empty
-}
-
-# @description Dies if any of the supplied variables are empty
-# @arg $@ string Variable names to print
-bake.assert_not_empty() {
-	local variable_name=
-	for variable_name; do
-		local -n variable="$variable_name"
-
-		if [ -z "$variable" ]; then
-			bake.die "Failed because variable '$variable_name' is empty"
-		fi
-	done; unset -v variable_name
-}
-
-# @description Dies if a command cannot be found
-# @arg $1 string Command to test for existence
-bake.assert_cmd() {
-	local cmd=$1
-
-	if [ -z "$cmd" ]; then
-		bake.die "Argument must not be empty"
-	fi
-
-	if ! command -v "$cmd" &>/dev/null; then
-		bake.die "Failed to find command '$cmd'. Please install it before continuing"
-	fi
-}
-
-# @description Edit configuration that affects the behavior of Bake
-# @arg $1 string Configuration option to change
-# @arg $2 string Value of configuration property
-bake.cfg() {
-	local cfg=$1
-	local value=$2
-
-	case $cfg in
-		stacktrace)
-			__bake_cfg_stacktrace=$value
-	esac
-}
-
+# @description Main function
+# @internal
 __bake_main() {
-	__bake_cfg_stacktrace='yes'
+	__bake_cfg_stacktrace='no'
 
-	set -Eeo pipefail
+	set -ETeo pipefail
 	shopt -s dotglob extglob globasciiranges globstar lastpipe shift_verbose
-	export LANG='C' LC_CTYPE='C' LC_NUMERIC='C' LC_TIME='C' LC_COLLATE='C' LC_MONETARY='C' LC_MESSAGES='C' \
-		LC_PAPER='C' LC_NAME='C' LC_ADDRESS='C' LC_TELEPHONE='C' LC_MEASUREMENT='C' LC_IDENTIFICATION='C' LC_ALL='C'
+	export LANG='C' LC_CTYPE='C' LC_NUMERIC='C' LC_TIME='C' LC_COLLATE='C' \
+		LC_MONETARY='C' LC_MESSAGES='C' LC_PAPER='C' LC_NAME='C' LC_ADDRESS='C' \
+		LC_TELEPHONE='C' LC_MEASUREMENT='C' LC_IDENTIFICATION='C' LC_ALL='C'
 	trap '__bake_trap_err' 'ERR'
+	bake.cfg pedantic-task-cd 'no'
 
 	# Set `BAKE_{ROOT,FILE}`
 	BAKE_ROOT=; BAKE_FILE=
-	__bake_set_vars "$@"
+	__bake_parse_args "$@"
 	if ! shift "$REPLY"; then
 		__bake_internal_die 'Failed to shift'
 	fi
 
+	# shellcheck disable=SC1007
 	local __bake_key= __bake_value=
 	local __bake_arg=
 	for __bake_arg; do case $__bake_arg in