diff --git a/README.md b/README.md index 609c3df..3ec37e6 100644 --- a/README.md +++ b/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: ```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 ``` @@ -503,18 +486,7 @@ it uses the [prepare next dev cycle template](#prepare-next-dev-cycle-template) ```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 ``` @@ -599,23 +571,7 @@ Help: ```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 ``` @@ -687,18 +643,7 @@ Help: ```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 ``` @@ -765,15 +710,7 @@ Help: ```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 ``` @@ -864,17 +801,7 @@ Help: ```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 ``` @@ -942,27 +869,7 @@ Help: ```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 ``` @@ -1001,27 +908,7 @@ Help: ```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 ``` @@ -1060,27 +947,7 @@ Help: ```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 ``` @@ -2003,9 +1870,7 @@ cat "$file" -## Source once - -Establishes a guard by creating a variable based on the file which shall be sourced. +## Source utility functions @@ -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 diff --git a/scripts/prepare-next-dev-cycle.sh b/scripts/prepare-next-dev-cycle.sh index 223046e..f12b01b 100755 --- a/scripts/prepare-next-dev-cycle.sh +++ b/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 diff --git a/scripts/release.sh b/scripts/release.sh index ed73624..29f251d 100755 --- a/scripts/release.sh +++ b/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 diff --git a/src/releasing/pre-release-checks-git.sh b/src/releasing/pre-release-checks-git.sh index 7d0dbef..7d10c57 100755 --- a/src/releasing/pre-release-checks-git.sh +++ b/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 diff --git a/src/releasing/prepare-files-next-dev-cycle.sh b/src/releasing/prepare-files-next-dev-cycle.sh index 4161ab8..dec79aa 100755 --- a/src/releasing/prepare-files-next-dev-cycle.sh +++ b/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 diff --git a/src/releasing/prepare-next-dev-cycle-template.sh b/src/releasing/prepare-next-dev-cycle-template.sh index b85631a..1f6284b 100755 --- a/src/releasing/prepare-next-dev-cycle-template.sh +++ b/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 diff --git a/src/releasing/release-files.sh b/src/releasing/release-files.sh index c6a9b57..bfa1d90 100755 --- a/src/releasing/release-files.sh +++ b/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 diff --git a/src/releasing/release-template.sh b/src/releasing/release-template.sh index ab28670..f8ed314 100755 --- a/src/releasing/release-template.sh +++ b/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 diff --git a/src/releasing/update-version-README.sh b/src/releasing/update-version-README.sh index 88d0f01..b844917 100755 --- a/src/releasing/update-version-README.sh +++ b/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 diff --git a/src/releasing/update-version-common-steps.sh b/src/releasing/update-version-common-steps.sh index b75710c..63007e3 100755 --- a/src/releasing/update-version-common-steps.sh +++ b/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 diff --git a/src/releasing/update-version-issue-templates.sh b/src/releasing/update-version-issue-templates.sh index 3fa4ee6..39555fe 100755 --- a/src/releasing/update-version-issue-templates.sh +++ b/src/releasing/update-version-issue-templates.sh @@ -41,7 +41,7 @@ fi sourceOnce "$dir_of_tegonal_scripts/utility/parse-args.sh" function updateVersionIssueTemplates() { - 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 directory additionalPattern # shellcheck disable=SC2034 # is passed by name to parseArguments diff --git a/src/releasing/update-version-scripts.sh b/src/releasing/update-version-scripts.sh index 7f58e15..5a40b0b 100755 --- a/src/releasing/update-version-scripts.sh +++ b/src/releasing/update-version-scripts.sh @@ -41,7 +41,7 @@ fi sourceOnce "$dir_of_tegonal_scripts/utility/parse-args.sh" function updateVersionScripts() { - 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 directory additionalPattern # shellcheck disable=SC2034 # is passed by name to parseArguments diff --git a/src/utility/checks.sh b/src/utility/checks.sh index 0124c3f..800516b 100644 --- a/src/utility/checks.sh +++ b/src/utility/checks.sh @@ -263,7 +263,7 @@ function exitIfArgIsNotVersion() { function checkArgIsVersion() { local versionRegex - 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 value argNumberOrName # shellcheck disable=SC2034 # is passed by name to parseFnArgs diff --git a/src/utility/source-once.doc.sh b/src/utility/source-once.doc.sh index aa2e697..2acb2f0 100644 --- a/src/utility/source-once.doc.sh +++ b/src/utility/source-once.doc.sh @@ -5,7 +5,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 diff --git a/src/utility/source-once.sh b/src/utility/source-once.sh index 2343a7f..08a85b8 100644 --- a/src/utility/source-once.sh +++ b/src/utility/source-once.sh @@ -10,8 +10,7 @@ # Version: v4.3.0-SNAPSHOT ####### Description ############# # -# Utility functions wrapping printf and prefixing the message with a coloured INFO, WARNING or ERROR. -# logError writes to stderr and logWarning and logInfo to stdout +# Utility functions to source files # ####### Usage ################### # @@ -22,7 +21,12 @@ # 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 @@ -59,7 +63,7 @@ function determineSourceOnceGuard() { function sourceOnce_exitIfNotAtLeastOneArg() { if (($# < 1)); then - printf >&2 "you need to pass at least the file you want to source to sourceOnce in \033[0;36m%s\033[0m\nFollowing a description of the parameters:" "${BASH_SOURCE[1]}" + printf >&2 "you need to pass at least the file you want to source to sourceOnce/Always/OrDie in \033[0;36m%s\033[0m\nFollowing a description of the parameters:" "${BASH_SOURCE[1]}" echo >&2 '1. file the file to source' echo >&2 '2... args... additional parameters which are passed to the source command' printStackTraced @@ -67,6 +71,17 @@ function sourceOnce_exitIfNotAtLeastOneArg() { fi } +function sourceOrDie() { + sourceOnce_exitIfNotAtLeastOneArg "$@" + + local -r sourceOrDie_file="$1" + shift 1 || traceAndDie "could not shift by 1" + + # we know that shellcheck cannot follow the non-constant source we don't know the source and thus cannot help out + # shellcheck disable=SC1090 + source "$sourceOrDie_file" "$@" || traceAndDie "there was an error sourcing %s, see above" "$sourceOrDie_file" +} + function sourceOnce() { sourceOnce_exitIfNotAtLeastOneArg "$@" @@ -88,9 +103,7 @@ function sourceOnce() { # shellcheck disable=SC2034 # is used in the sourced file declare __SOURCED__=true - # we know that shellcheck cannot follow the non-constant source we don't know the source and thus cannot help out - # shellcheck disable=SC1090 - source "$sourceOnce_file" "$@" || die "there was an error sourcing %s, see above" "$sourceOnce_file" + sourceOrDie "$sourceOnce_file" "$@" unset __SOURCED__ fi }