introduce sourceOrDie to avoid the repetition of traceOrDie

Author: robstoll

README.md

@@ -138,7 +138,7 @@ The scripts are ordered by topic:
 	- [Parse utils](#parse-utils)
 	- [Recursive `declare -p`](#recursive-declare--p)
 	- [Replace Snippets](#replace-snippets)
-	- [`source` once](#source-once)
+	- [`source` once/always/or die](#source-utility-functions)
 	- [Update Documentation](#update-bash-documentation)
 
 # Continuous Integration
@@ -410,24 +410,7 @@ Help:
 
 <!-- auto-generated, do not modify here but in src/releasing/release-files.sh -->
 ```text
-Parameters:
--v                            The version to release in the format vX.Y.Z(-RC...)
--k|key                        The GPG private key which shall be used to sign the files
---sign-fn                     Function which is called to determine what files should be signed. It should be based find and allow to pass further arguments (we will i.a. pass -print0)
--b|--branch                   (optional) The expected branch which is currently checked out -- default: main
---project-dir                 (optional) The projects directory -- default: .
--p|--pattern                  (optional) pattern which is used in a perl command (separator /) to search & replace additional occurrences. It should define two match groups and the replace operation looks as follows: \${1}$version\${2}
--nv|--next-version            (optional) the version to use for prepare-next-dev-cycle -- default: is next minor based on version
---prepare-only                (optional) defines whether the release shall only be prepared (i.e. no push, no tag, no prepare-next-dev-cycle) -- default: false
---before-pr-fn                (optional) defines the function which is executed before preparing the release (to see if we should release) and after preparing the release -- default: beforePr (per convention defined in scripts/before-pr.sh). No arguments are passed
---prepare-next-dev-cycle-fn   (optional) defines the function which is executed to prepare the next dev cycle -- default: perpareNextDevCycle (per convention defined in scripts/prepareNextDevCycle). The following arguments are passed: -v nextVersion --pattern additionalPattern --project-dir projectsRootDir --before-pr-fn beforePrFn
---after-version-update-hook   (optional) if defined, then this function is called after versions were updated and before calling beforePr. The following arguments are passed: -v version --project-dir projectsRootDir and --pattern additionalPattern
-
---help     prints this help
---version  prints the version of this script
 
-INFO: Version of release-files.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-release-files-help>
@@ -503,18 +486,7 @@ it uses the [prepare next dev cycle template](#prepare-next-dev-cycle-template)
 
 <!-- auto-generated, do not modify here but in src/releasing/prepare-files-next-dev-cycle.sh -->
 ```text
-Parameters:
--v                            the version for which we prepare the dev cycle
---project-dir                 (optional) The projects directory -- default: .
--p|--pattern                  (optional) pattern which is used in a perl command (separator /) to search & replace additional occurrences. It should define two match groups and the replace operation looks as follows: \${1}$version\${2}
---before-pr-fn                (optional) defines the function which is executed before preparing the release (to see if we should release) and after preparing the release -- default: beforePr (per convention defined in scripts/before-pr.sh). No arguments are passed
---after-version-update-hook   (optional) if defined, then this function is called after versions were updated and before calling beforePr. The following arguments are passed: -v version --project-dir projectsRootDir and --pattern additionalPattern
 
---help     prints this help
---version  prints the version of this script
-
-INFO: Version of prepare-files-next-dev-cycle.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-prepare-files-next-dev-cycle-help>
@@ -599,23 +571,7 @@ Help:
 
 <!-- auto-generated, do not modify here but in src/releasing/release-template.sh -->
 ```text
-Parameters:
--v                            The version to release in the format vX.Y.Z(-RC...)
---release-hook                performs the main release task such as (run tests) create artifacts, deploy artifacts
--b|--branch                   (optional) The expected branch which is currently checked out -- default: main
---project-dir                 (optional) The projects directory -- default: .
--p|--pattern                  (optional) pattern which is used in a perl command (separator /) to search & replace additional occurrences. It should define two match groups and the replace operation looks as follows: \${1}$version\${2}
--nv|--next-version            (optional) the version to use for prepare-next-dev-cycle -- default: is next minor based on version
---prepare-only                (optional) defines whether the release shall only be prepared (i.e. no push, no tag, no prepare-next-dev-cycle) -- default: false
---before-pr-fn                (optional) defines the function which is executed before preparing the release (to see if we should release) and after preparing the release -- default: beforePr (per convention defined in scripts/before-pr.sh). No arguments are passed
---prepare-next-dev-cycle-fn   (optional) defines the function which is executed to prepare the next dev cycle -- default: perpareNextDevCycle (per convention defined in scripts/prepareNextDevCycle). The following arguments are passed: -v nextVersion --pattern additionalPattern --project-dir projectsRootDir --before-pr-fn beforePrFn
---after-version-update-hook   (optional) if defined, then this function is called after versions were updated and before calling beforePr. The following arguments are passed: -v version --project-dir projectsRootDir and --pattern additionalPattern
 
---help     prints this help
---version  prints the version of this script
-
-INFO: Version of release-template.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-release-template-help>
@@ -687,18 +643,7 @@ Help:
 
 <!-- auto-generated, do not modify here but in src/releasing/prepare-next-dev-cycle-template.sh -->
 ```text
-Parameters:
--v                            the version for which we prepare the dev cycle
---project-dir                 (optional) The projects directory -- default: .
--p|--pattern                  (optional) pattern which is used in a perl command (separator /) to search & replace additional occurrences. It should define two match groups and the replace operation looks as follows: \${1}$version\${2}
---before-pr-fn                (optional) defines the function which is executed before preparing the release (to see if we should release) and after preparing the release -- default: beforePr (per convention defined in scripts/before-pr.sh). No arguments are passed
---after-version-update-hook   (optional) if defined, then this function is called after versions were updated and before calling beforePr. The following arguments are passed: -v version --project-dir projectsRootDir and --pattern additionalPattern
-
---help     prints this help
---version  prints the version of this script
 
-INFO: Version of prepare-next-dev-cycle-template.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-prepare-next-dev-cycle-template-help>
@@ -765,15 +710,7 @@ Help:
 
 <!-- auto-generated, do not modify here but in src/releasing/pre-release-checks-git.sh -->
 ```text
-Parameters:
--v            The version to release in the format vX.Y.Z(-RC...)
--b|--branch   (optional) The expected branch which is currently checked out -- default: main
 
---help     prints this help
---version  prints the version of this script
-
-INFO: Version of pre-release-checks-git.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-pre-release-checks-git-help>
@@ -864,17 +801,7 @@ Help:
 
 <!-- auto-generated, do not modify here but in src/releasing/update-version-common-steps.sh -->
 ```text
-Parameters:
---for-release   true if update is for release in which case we hide the sneak-peek banner and toggle sections for release, if false then we show the sneak-peek banner and toggle the section for development
--v              The version to release in the format vX.Y.Z(-RC...)
---project-dir   (optional) The projects directory -- default: .
--p|--pattern    (optional) pattern which is used in a perl command (separator /) to search & replace additional occurrences. It should define two match groups and the replace operation looks as follows: \${1}$version\${2}
 
---help     prints this help
---version  prints the version of this script
-
-INFO: Version of update-version-common-steps.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-update-version-common-steps-help>
@@ -942,27 +869,7 @@ Help:
 
 <!-- auto-generated, do not modify here but in src/releasing/update-version-README.sh -->
 ```text
-Parameters:
--v             The version to release in the format vX.Y.Z(-RC...)
--f|--file      (optional) the file where search & replace shall be done -- default: ./README.md
--p|--pattern   (optional) pattern which is used in a perl command (separator /) to search & replace additional occurrences. It should define two match groups and the replace operation looks as follows: \${1}$version\${2}
-
---help     prints this help
---version  prints the version of this script
-
-Examples:
-# update version for ./README.md
-update-version-README.sh -v v0.1.0
-
-# update version for ./docs/index.md
-update-version-README.sh -v v0.1.0 -f ./docs/index.md
 
-# update version for ./README.md
-# also replace occurrences of the defined pattern
-update-version-README.sh -v v0.1.0 -p "(VERSION=['\"])[^'\"]+(['\"])"
-
-INFO: Version of update-version-README.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-update-version-README-help>
@@ -1001,27 +908,7 @@ Help:
 
 <!-- auto-generated, do not modify here but in src/releasing/update-version-scripts.sh -->
 ```text
-Parameters:
--v               The version to release in the format vX.Y.Z(-RC...)
--d|--directory   (optional) the working directory in which *.sh are searched (also in subdirectories) / you can also specify a file -- default: ./src
--p|--pattern     (optional) pattern which is used in a perl command (separator /) to search & replace additional occurrences. It should define two match groups and the replace operation looks as follows: \${1}$version\${2}
-
---help     prints this help
---version  prints the version of this script
-
-Examples:
-# update version to v0.1.0 for all *.sh in ./src and subdirectories
-update-version-scripts.sh -v v0.1.0
-
-# update version to v0.1.0 for all *.sh in ./scripts and subdirectories
-update-version-scripts.sh -v v0.1.0 -d ./scripts
 
-# update version to v0.1.0 for all *.sh in ./src and subdirectories
-# also replace occurrences of the defined pattern
-update-version-scripts.sh -v v0.1.0 -p "(VERSION=['\"])[^'\"]+(['\"])"
-
-INFO: Version of update-version-scripts.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-update-version-scripts-help>
@@ -1060,27 +947,7 @@ Help:
 
 <!-- auto-generated, do not modify here but in src/releasing/update-version-issue-templates.sh -->
 ```text
-Parameters:
--v               The version to release in the format vX.Y.Z(-RC...)
--d|--directory   (optional) the working directory in which *.y(a)ml are searched (also in subdirectories) / you can also specify a file -- default: ./.github/ISSUE_TEMPLATE
--p|--pattern     (optional) pattern which is used in a perl command (separator /) to search & replace additional occurrences. It should define two match groups and the replace operation looks as follows: \${1}$version\${2}
-
---help     prints this help
---version  prints the version of this script
 
-Examples:
-# update version to v0.1.0 for all *.y(a)ml in ./.github/ISSUE_TEMPLATE and subdirectories
-update-version-issue-templates.sh -v v0.1.0
-
-# update version to v0.1.0 for all *.y(a)ml in ./tpls and subdirectories
-update-version-issue-templates.sh -v v0.1.0 -d ./tpls
-
-# update version to v0.1.0 for all *.y(a)ml in ./.github/ISSUE_TEMPLATE and subdirectories
-# also replace occurrences of the defined pattern
-update-version-issue-templates.sh -v v0.1.0 -p "(VERSION=['\"])[^'\"]+(['\"])"
-
-INFO: Version of update-version-issue-templates.sh is:
-v4.3.0-SNAPSHOT
 ```
 
 </releasing-update-version-issue-templates-help>
@@ -2003,9 +1870,7 @@ cat "$file"
 
 </utility-replace-snippet>
 
-## Source once
-
-Establishes a guard by creating a variable based on the file which shall be sourced.
+## Source utility functions
 
 <utility-source-once>
 
@@ -2018,7 +1883,12 @@ shopt -s inherit_errexit
 dir_of_tegonal_scripts="$(cd -- "$(dirname -- "${BASH_SOURCE[0]:-$0}")" >/dev/null && pwd 2>/dev/null)/../lib/tegonal-scripts/src"
 source "$dir_of_tegonal_scripts/setup.sh" "$dir_of_tegonal_scripts"
 
-source "$dir_of_tegonal_scripts/utility/source-once.sh"
+# setup.sh already sources source-once.sh hence no need for the following (as usual):
+# source "$dir_of_tegonal_scripts/utility/source-once.sh"
+
+# more or less shortcut for `source ... || traceAndDie "..."
+# will be used by sourceOnce and sourceAlways (although they don't contain ..OrDie in the name)
+sourceOrdie "foo.sh"
 
 sourceOnce "foo.sh"    # creates a variable named sourceOnceGuard_foo__sh which acts as guard and sources foo.sh
 sourceOnce "foo.sh"    # will source nothing as sourceOnceGuard_foo__sh is already defined

scripts/prepare-next-dev-cycle.sh

@@ -31,7 +31,7 @@ sourceOnce "$dir_of_tegonal_scripts/releasing/prepare-files-next-dev-cycle.sh"
 sourceOnce "$scriptsDir/before-pr.sh"
 
 function prepareNextDevCycle() {
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	# shellcheck disable=SC2034   # they seem unused but are necessary in order that parseArguments doesn't create global readonly vars
 	local version projectsRootDir additionalPattern beforePrFn

scripts/release.sh

@@ -43,7 +43,7 @@ function release() {
 		die "You need to have shellspec installed if you want to create a release."
 	fi
 
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	local version
 	# shellcheck disable=SC2034   # they seem unused but are necessary in order that parseArguments doesn't create global readonly vars

src/releasing/pre-release-checks-git.sh

@@ -45,8 +45,8 @@ sourceOnce "$dir_of_tegonal_scripts/utility/git-utils.sh"
 sourceOnce "$dir_of_tegonal_scripts/utility/parse-args.sh"
 
 function preReleaseCheckGit() {
-	local versionRegex versionParamPatternLong
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	local versionParamPatternLong
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	local version branch
 	# shellcheck disable=SC2034   # is passed by name to parseArguments

src/releasing/prepare-files-next-dev-cycle.sh

@@ -73,7 +73,7 @@ sourceOnce "$dir_of_tegonal_scripts/releasing/prepare-next-dev-cycle-template.sh
 function prepareFilesNextDevCycle() {
 	local versionParamPatternLong projectsRootDirParamPatternLong
 	local additionalPatternParamPatternLong beforePrFnParamPatternLong afterVersionUpdateHookParamPatternLong
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	local version afterVersionUpdateHook projectsRootDir additionalPattern beforePrFn afterVersionUpdateHook
 	# shellcheck disable=SC2034   # is passed by name to parseArguments

src/releasing/prepare-next-dev-cycle-template.sh

@@ -73,10 +73,10 @@ sourceOnce "$dir_of_tegonal_scripts/utility/parse-args.sh"
 sourceOnce "$dir_of_tegonal_scripts/releasing/update-version-common-steps.sh"
 
 function prepareNextDevCycleTemplate() {
-	local versionRegex versionParamPatternLong projectsRootDirParamPatternLong
+	local versionParamPatternLong projectsRootDirParamPatternLong
 	local additionalPatternParamPatternLong beforePrFnParamPatternLong afterVersionUpdateHookParamPatternLong
 	local forReleaseParamPatternLong
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	local version projectsRootDir additionalPattern beforePrFn afterVersionUpdateHook
 	# shellcheck disable=SC2034   # is passed by name to parseArguments

src/releasing/release-files.sh

@@ -92,7 +92,7 @@ function releaseFiles() {
 	local versionParamPatternLong projectsRootDirParamPatternLong
 	local additionalPatternParamPatternLong afterVersionUpdateHookParamPatternLong releaseHookParamPatternLong
 	local findForSigningParamPatternLong beforePrFnParamPatternLong prepareNextDevCycleFnParamPatternLong
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	local version key findForSigning branch projectsRootDir additionalPattern
 	# shellcheck disable=SC2034   # seems unused but is set in deduce-next-version

src/releasing/release-template.sh

@@ -96,7 +96,7 @@ function releaseTemplate() {
 	local additionalPatternParamPatternLong prepareOnlyParamPatternLong
 	local beforePrFnParamPatternLong prepareNextDevCycleFnParamPatternLong afterVersionUpdateHookParamPatternLong
 	local forReleaseParamPatternLong releaseHookParamPatternLong
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	local version releaseHook branch projectsRootDir additionalPattern nextVersion prepareOnly
 	local beforePrFn prepareNextDevCycleFn afterVersionUpdateHook

src/releasing/update-version-README.sh

@@ -41,7 +41,7 @@ fi
 sourceOnce "$dir_of_tegonal_scripts/utility/parse-args.sh"
 
 function updateVersionReadme() {
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	local version file additionalPattern
 	# shellcheck disable=SC2034   # is passed by name to parseArguments

src/releasing/update-version-common-steps.sh

@@ -71,7 +71,7 @@ sourceOnce "$dir_of_tegonal_scripts/releasing/update-version-scripts.sh"
 
 function updateVersionCommonSteps() {
 	local forReleaseParamPatternLong versionParamPatternLong additionalPatternParamPatternLong
-	source "$dir_of_tegonal_scripts/releasing/common-constants.source.sh" || traceAndDie "could not source common-constants.source.sh"
+	sourceOrDie "$dir_of_tegonal_scripts/releasing/common-constants.source.sh"
 
 	local forRelease version projectsRootDir additionalPattern
 	# shellcheck disable=SC2034   # is passed by name to parseArguments