Release Version 2.0.0
This is a major version change, caused by a subtle (yet profound) mechanism when `source`ing files
in `bash`. You can read more about how to handle this change below, but first we'll dive into the
features.
There is a whole group of new functions related to handling semantic version numbers. They are all
prefixed with `_mb_semver` to make them easily discoverable. To get a little background and usage
examples related to this change, refer to !10 and #4. Here is a brief summary:
```bash
source magic.bash
raw_version="$(_mb_semver "1.4.3-rc.1")"
declare -A version="($raw_version)"
[[ "${version[patch]}" -eq 3 ]]
_mb_semver_lt "1.4.3-rc.1" "1.5.0"
_mb_semver_gt "2.1.3" "1.0.9"
_mb_semver_eq "1.2.3-rc.4+00000000" "1.2.3-rc.4+12345678"
```
With the semantic version changes in place, you can now pass positional arguments to `magic.bash`
during sourcing. These will be evaluated and allow you to reduce the previous code for loading the
library to a single line:
```bash
source "${MAGIC_BASH_PATH:-"magic.bash"}" -ge 2.0.0 || exit 1
```
This code will ensure that `magic.bash` is loaded with a version number greater than or equal to
2.0.0.
The "Library version assertions" mentioned above have a side-effect that was only uncovered while
adding documentation for this feature in !11. In some (probably quite common) circumstances, it can
happen that positional arguments passed on the command line while invoking a script end up in
`magic.bash`. As a consequence, `magic.bash` will fail version assertion (due to invalid arguments)
and execution of your script will halt forcefully.
In case you use applications that require different major versions of `magic.bash`, you can work
around the issue with simple shell functions. The idea is that you have both versions of
`magic.bash` installed in separate locations.
Then, if your script is named `foo`, for example, you can add the following code to your `.bashrc`:
```bash
function foo {
env MAGIC_BASH_PATH="/path/to/required/magic.bash" /full/path/to/your/foo "$@"
}
```
If the scripts you need do not support the `MAGIC_BASH_PATH` variable, you can't do anything about
the issue except for modifying the offending script manually. In this case, please get in touch with
the person that develops your script and ask them to fix the issue.
**See !11.**
A breaking change could have been avoided by removing commit `fcb60d27` from !10. This would have
preserved the semver-related changes, at the cost of the "Library version assertions" feature.
At the time of writing this, I (@hartan) think that the benefit of the library version assertions
outweighs the cost of a breaking change. That is because I assume that adoption of this script is
very low (I don't know of any use outside of my own scripts). Under the assumption that adoption
will increase the longer I wait, it's better to have this change in earlier rather than later.
On the other hand, it makes loading the code very comfortable from an authors point of view. The
previous library code didn't have useful mechanisms to require a specific library version. Doing the
version assertion with `_mb_semver_...` functions works, too, but for earlier library versions these
don't exist yet. So, a perfectly backward-compatible use of this feature would have looked something
like this:
```bash
source "${MAGIC_BASH_PATH:-"magic.bash"}" || exit 1
if declare -pf _mb_semver_ge &> /dev/null; then
_mb_semver_ge "$_MB_VERSION" "1.1.0" ||
_mb_fatal "library version too low"
else
# Do old-school version comparison
fi
```
This doesn't convince me, so I went with the breaking change instead.