feat(version): use exit code for check to indicate out-of-date versions

It can be handy to have an exit code that allows better status
indication or chaining.

On exit, return one of the following codes:

- 0: Normal exit condition, all checked versions are up-to-date
- 1: Unknown cause of failure
- 2: Normal exit condition, but there are out-of-date versions
- 3: Failed to run some version checks

Component: pkgctl version check
Signed-off-by: Levente Polyak <anthraxx@archlinux.org>

doc/man/pkgctl-version-check.1.asciidoc

@@ -36,6 +36,23 @@ Options
 *-h, --help*::
 	Show a help text
 
+Errors
+------
+
+On exit, return one of the following codes:
+
+*0*::
+	Normal exit condition, all checked versions are up-to-date
+
+*1*::
+	Unknown cause of failure
+
+*2*::
+	Normal exit condition, but there are out-of-date versions
+
+*3*::
+	Failed to run some version checks
+
 See Also
 --------
 

src/lib/version.sh

@@ -47,7 +47,7 @@ pkgctl_version() {
 				# shellcheck source=src/lib/version/check.sh
 				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/check.sh
 				pkgctl_version_check "$@"
-				exit 0
+				exit $?
 				;;
 			upgrade)
 				_DEVTOOLS_COMMAND+=" $1"
@@ -55,7 +55,7 @@ pkgctl_version() {
 				# shellcheck source=src/lib/version/upgrade.sh
 				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/upgrade.sh
 				pkgctl_version_upgrade "$@"
-				exit 0
+				exit $?
 				;;
 			*)
 				die "invalid argument: %s" "$1"

src/lib/version/check.sh

@@ -15,6 +15,14 @@ source /usr/share/makepkg/util/message.sh
 
 set -eo pipefail
 
+readonly PKGCTL_VERSION_CHECK_EXIT_UP_TO_DATE=0
+export PKGCTL_VERSION_CHECK_EXIT_UP_TO_DATE
+readonly PKGCTL_VERSION_CHECK_EXIT_OUT_OF_DATE=2
+export PKGCTL_VERSION_CHECK_EXIT_OUT_OF_DATE
+readonly PKGCTL_VERSION_CHECK_EXIT_FAILURE=3
+export PKGCTL_VERSION_CHECK_EXIT_FAILURE
+
+
 pkgctl_version_check_usage() {
 	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
 	cat <<- _EOF_
@@ -48,6 +56,7 @@ pkgctl_version_check() {
 	local failure=()
 	local current_item=0
 	local section_separator=''
+	local exit_code=${PKGCTL_VERSION_CHECK_EXIT_UP_TO_DATE}
 
 	while (( $# )); do
 		case $1 in
@@ -160,6 +169,7 @@ pkgctl_version_check() {
 	fi
 
 	if (( ${#failure[@]} > 0 )); then
+		exit_code=${PKGCTL_VERSION_CHECK_EXIT_FAILURE}
 		printf "%sFailure%s\n" "${section_separator}${BOLD}${UNDERLINE}" "${ALL_OFF}"
 		section_separator=$'\n'
 		for result in "${failure[@]}"; do
@@ -168,6 +178,7 @@ pkgctl_version_check() {
 	fi
 
 	if (( ${#out_of_date[@]} > 0 )); then
+		exit_code=${PKGCTL_VERSION_CHECK_EXIT_OUT_OF_DATE}
 		printf "%sOut-of-date%s\n" "${section_separator}${BOLD}${UNDERLINE}" "${ALL_OFF}"
 		section_separator=$'\n'
 		for result in "${out_of_date[@]}"; do
@@ -183,6 +194,9 @@ pkgctl_version_check() {
 			"${#out_of_date[@]}" \
 			"${#failure[@]}"
 	fi
+
+	# return status based on results
+	return "${exit_code}"
 }
 
 get_upstream_version() {