refactor: Convert bash-core to one file

Author: hyperupcall

Bakefile.sh

@@ -5,9 +5,5 @@ task.test() {
 }
 
 task.docs() {
-	shdoc > './docs/api.md' < <(
-		for f in ./pkg/lib/public/*.sh; do
-			cat "$f"
-		done
-	)
+	shdoc < './pkg/lib/public/bash-core.sh' > './docs/api.md'
 }

README.md

@@ -1,9 +1,11 @@
 # bash-core
 
-Useful functions for any Bash program. Often vital for Basalt programs
+Core functions for any Bash program
 
 ## Summary
 
+The following are functions available for use. See the [api.md](./docs/api.md) for more details
+
 ### `init`
 
 - `core.init`
@@ -17,28 +19,11 @@ Add and remove traps. With these, multiple packages can add or remove traps hand
 - `core.trap_add`
 - `core.trap_remove`
 
-Example
-
-```sh
-some_handler() { printf '%s\n' 'This was called on USR1! ^w^'; }
-core.trap_add 'some_handler' 'USR1'
-kill -USR1 $$
-core.trap_remove 'some_handler' 'USR1'
-```
-
 ### `shopt`
 
 - `core.shopt_push`
 - `core.shopt_pop`
 
-Example
-
-```sh
-core.shopt_push -s extglob
-[[ 'variable' == @(foxtrot|golf|echo|variable) ]] && printf '%s\n' 'Woof!'
-core.shopt_pop
-```
-
 ### `err`
 
 I suppose it can look redundant (compared to `if ! fn; then :; fi`), but it can help make errors a bit more safe in larger applications, since you don't have to worry about a caller forgetting to `if ! fn` or `fn ||` (and terminating the script if `set -e`). It also makes it easier to communicate specific error codes and helps separate between calculated / expected errors and unexpected errors (fatal / faults)
@@ -47,23 +32,12 @@ I suppose it can look redundant (compared to `if ! fn; then :; fi`), but it can
 - `core.err_clear`
 - `core.err_exists`
 
-## `stacktrace`
+### `stacktrace`
 
 Prints the stack trace. Recommended to use with `core.trap_add`
 
 - `core.stacktrace_print`
 
-Example
-
-```sh
-create_some_error() { core.err_clear; core.err_set 'Some error' }
-
-create_some_error || fatal "Did not expect an error"
-if core.err_exists; then
-  printf '%s\n' 'Something happened'
-fi
-```
-
 ## Installation
 
 Use [Basalt](https://github.com/hyperupcall/basalt), a Bash package manager, to add this project as a dependency

docs/api.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Core functions for any large Bash program
+Core functions for any Bash program
 
 ## Index
 
@@ -99,8 +99,8 @@ Sets an error.
 
 #### Arguments
 
-* # @args $1 Error code
-* # @args $2 Error message
+* **$1** (Error): code
+* **$2** (Error): message
 
 #### Variables set
 

pkg/lib/public/bash-core.sh

@@ -1,7 +1,7 @@
 # shellcheck shell=bash
 
 # @name bash-core
-# @description Core functions for any large Bash program
+# @description Core functions for any Bash program
 
 # @description Initiates global variables used by other functions
 # @noargs
@@ -17,21 +17,6 @@ core.init() {
 	declare -ag ___global_shopt_stack___=()
 }
 
-# @description Get version of the package, from the point of the callsite. In other words, it
-# returns the version of the package that has the file containing the direct caller of this
-# @set REPLY The full path to the directory
-# @internal
-core.get_package_dir() {
-	# local start_dir="${1:-"${BASH_SOURCE[1]}"}"
-
-	# while [ ! -f 'basalt.toml' ] && [ "$PWD" != / ]; do
-	# 	if ! cd ..; then
-	# 		return 1
-	# 	fi
-	# done
-	:
-}
-
 # @description Adds a handler for a particular `trap` signal or event. Noticably,
 # unlike the 'builtin' trap, this does not override any other existing handlers
 # @arg $1 string Function to execute on an event. Integers are forbiden
@@ -214,6 +199,68 @@ core.shopt_pop() {
 	___global_shopt_stack___=("${___global_shopt_stack___[@]::${#___global_shopt_stack___[@]}-2}")
 }
 
+# @description Sets an error.
+# @arg $1 Error code
+# @arg $2 Error message
+# @set number ERRCODE Error code
+# @set string ERR Error message
+core.err_set() {
+	if (($# == 1)); then
+		ERRCODE=1
+		ERR=$1
+	elif (($# == 2)); then
+		ERRCODE=$1
+		ERR=$2
+	else
+		printf '%s\n' "Error: bash-error: Incorrect function arguments"
+		return 1
+	fi
+
+	if [ -z "$ERR" ]; then
+		printf '%s\n' "Error: bash-error: Argument for 'ERR' cannot be empty"
+		return 1
+	fi
+}
+
+# @description Clears any of the global error state (sets to empty string).
+# This means any `core.err_exists` calls after this _will_ return `true`
+# @noargs
+# @set number ERRCODE Error code
+# @set string ERR Error message
+core.err_clear() {
+	ERRCODE=
+	ERR=
+}
+
+# @description Checks if an error exists. If `ERR` is not empty, then an error
+# _does_ exist
+# @noargs
+core.err_exists() {
+	if [ -z "$ERR" ]; then
+		return 1
+	else
+		return 0
+	fi
+}
+
+# @description Prints stacktrace
+# @noargs
+# @example
+#  core.trap_add 'err_handler' EXIT
+#  err_handler() {
+#    local exit_code=$?
+#    core.stacktrace_print
+#    exit $?
+#  }
+core.stacktrace_print() {
+	printf '%s\n' 'Stacktrace:'
+
+	local i=
+	for ((i=0; i<${#FUNCNAME[@]}-1; ++i)); do
+		printf '%s\n' "  in ${FUNCNAME[$i]} (${BASH_SOURCE[$i]}:${BASH_LINENO[$i-1]})"
+	done; unset -v i
+} >&2
+
 # @description Determine if color should be printed
 # @internal
 core.should_color_output() {
@@ -236,3 +283,18 @@ core.should_color_output() {
 		return 0
 	fi
 }
+
+# @description Get version of the package, from the point of the callsite. In other words, it
+# returns the version of the package that has the file containing the direct caller of this
+# @set REPLY The full path to the directory
+# @internal
+core.get_package_dir() {
+	# local start_dir="${1:-"${BASH_SOURCE[1]}"}"
+
+	# while [ ! -f 'basalt.toml' ] && [ "$PWD" != / ]; do
+	# 	if ! cd ..; then
+	# 		return 1
+	# 	fi
+	# done
+	:
+}