Tags

Tags give the ability to mark specific points in history as being important

  • 2.0.0

    896c5154 · build: Bump project version to 2.0.0 ·
    Release: Release 2.0.0 
    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.

  • 1.0.2

    4d14812c · build: Bump project version to 1.0.2 ·
    Release: Release 1.0.2 
    Release Version 1.0.2

Another fix release, this time with a focus on error context handling. The fixed bugs mostly dealt
with handling empty messages or context stacks, see !9 for details.

In case you were unaware, there's a function called `_mb_err_ctx` that allows you to track error
context. Its function is inspired by the [`anyhow` rust crate][1] and it works
something like this:

```bash
source magic.bash

_mb_err_ctx push "failed to read user config"
loc="$(_get_user_config_file)" ||
    _mb_fatal "failed to determine user config file"
config="$(_parse_user_config "$loc")" ||
    _mb_fatal "failed to parse user config file"
\# ... etc.
_mb_err_ctx pop
```

Now if, in this hypothetical example, the `_parse_cli_arguments` function has
an error and exits, the error context will be printed as a series of error
messages to stderr.

This is just a contrived example of course, and you can nest error contexts to
arbitrary depth. Try it out if you want to provide helpful errors to users!

Another notable advancement in this release is the introduction of tests. In
the future we'll hopefully be able to catch regressions before they make it
into a release. That's all for today.

Happy scripting!

[1]: https://github.com/dtolnay/anyhow

  • 1.0.1

    64b2f947 · build: Bump version to 1.0.1 ·
    Release: Release 1.0.1 
    Release Version 1.0.1

This release fixes a couple of bugs relating to using `magic.bash` in nested scripts (see !4) and to
formatting multi line error messages (see !5). Especially the latter has user-facing impact and
should make some of your error messages more pleasant to read.

Apart from that, the documentation received some love and all files in this repository carry a
proper copyright notice. The project is now basically REUSE 3.3 compliant, getting a badge to prove
this is a WIP for the next release.

Happy hacking!

  • 1.0.0

    6c1ab488 · ci: Assert that version numbers match ·
    Release: Release 1.0.0 
    Release Version 1.0.0

This is the first standalone release of `magic.bash`, a library with *Useful functions I don't want
to write twice*.

The library was previously used (in a very similar form) by many other of my shell scripts, and
until now it has been living [in my `shell-helpers` repository][1]. Since I've come to use it across
multiple other projects, though, I decided it is time to publish this in a way that gives it more
visibility and better maintenance.

Since the API has been stable for ~2 years now I'm skipping major version 0 in favor of an immediate
stable release.

Happy scripting!

[1]: https://gitlab.com/c8160/shell-helpers