About

This package provides three utility functions for bash scripting:

here

Print a message. The core of the package. Two other functions are a few lines wrappers around it.

here2

Print a message with here to stderr.

bye

Print a message with here to stderr and exit.

The functions join their args with a single space to form the message.

The package comes in three editions: full, mini and micro. They differ in here’s capabilities, check out the feature matrix below. Depending on your use case you might want to use light ones at least in releases.

It is probably the most common use scenario of here-bye package to only take advantage of its optionally verbose bye function, the exit function on steroids, configured with env vars.

Important: this package is not tailored for traps. Use locate-exit to verbosely trap EXIT and ERR.

here

By default here just prints a message. What makes it special is:

• You can make it print prefixed messages. It looks like [prefix] message. There can be multiple prefixes formatted as [prefix1][prefix2] message. Each prefix could be either a static string or a special value auto. The latter is replaced with the top element (i.e. the current line) of the current execution context in the form file:lineno func or file:lineno if not inside a function.
• You can make it print the current execution context.

The optional behavior is contolled with two vars:

HERE_PREFIX

Initially it is treated as a comma-separated list so that you can set it with an env var. The package’s init code converts it into an array. You can modify the array in your code to change the prefixes on the fly. Treat it as a stack:

• if you need to add a prefix, do it as HERE_PREFIX+=(prefix)
• if you need to remove a previously added prefix, do it as unset -v HERE_PREFIX[-1]
• if you need to ‘close’ a prefix and ‘open’ another one right away, change the top prefix with HERE_PREFIX[-1]=prefix

Do not assign directly like HERE_PREFIX=(prefix), it could discard prefixes possibly set on script start with env vars.

HERE_CONTEXT

Enable execution context printing with y value.

Feature matrix

	full	mini	micro
prefix	static and auto	static	no
execution context	yes	no	no

here2

You can use here2 message instead of here message >&2. It is a one-line wrapper which literally does that.

bye

By default bye prints a message with here to stderr and exits with code 1. You can set a custom exit code with BYE_EXIT var.

Like here, bye has its own BYE_PREFIX and BYE_CONTEXT. The former is prepended to HERE_PREFIX on the fly. The latter, if set to y, overrides HERE_PREFIX on the fly.

With these vars you can for example only make here calls issued by bye to show the auto prefix and print the context.

Light editions have the same limitations as for here.

Examples

micro

here is a dumb printer, no prefixes, no context. bye supports custom exit codes.

#!/usr/bin/env bash

source here-bye.micro.sh

here 'a message printed by "here"'

BYE_EXIT=2 bye 'a message printed by "bye"'

Result:

a message printed by "here"
a message printed by "bye"

mini

here supports static prefixes.

#!/usr/bin/env bash

source here-bye.mini.sh

f1 () {
    here 'hello from f1'
    bye 'cya later'
}

f2 () {
    here 'hello from f2'
    f1
}

here 'the following messages are prefixed with [config]'

HERE_PREFIX+=(config)

here 'until "config" is popped off the HERE_PREFIX array'
here 'a message printed by "bye" would be prefixed as well'

HERE_PREFIX+=(files)

here 'this message has one more prefix, [files]'

unset -v 'HERE_PREFIX[-1]'

here 'out of "files" subsection'

unset -v 'HERE_PREFIX[-1]'

here 'out of "config" section'

f2

Result:

the following messages are prefixed with [config]
[config] until "config" is popped off the HERE_PREFIX array
[config] a message printed by "bye" would be prefixed as well
[config][files] this message has one more prefix, [files]
[config] out of "files" subsection
out of "config" section
hello from f2
hello from f1
cya later

A useful application of prefixes, even if you dont use them explicitly in the code, could be filtering the script’s output for any here messages:

HERE_PREFIX=token ./script.sh 2>&1 | grep token

full

here supports auto prefix and context.

Modify the source line to include here-bye.sh instead of the mini edition in the above example and run it with env vars HERE_PREFIX=auto BYE_CONTEXT=y to unleash the power.

Result:

[./demo.sh:15] the following messages are prefixed with [config]
[./demo.sh:19][config] until "config" is popped off the HERE_PREFIX array
[./demo.sh:20][config] a message printed by "bye" would be prefixed as well
[./demo.sh:24][config][files] this message has one more prefix, [files]
[./demo.sh:28][config] out of "files" subsection
[./demo.sh:32] out of "config" section
[./demo.sh:11 f2] hello from f2
[./demo.sh:6 f1] hello from f1
[./demo.sh:7 f1] cya later

--- context ---
./demo.sh:7 f1
./demo.sh:12 f2
./demo.sh:34
---

Advanced topics

There is one more config var, an associative array HERE_WRAP, which is only of interest if you wanted to wrap here in a custom function. For example you might want to use another name for it, like say:

say () {
    here "$@"
}

With just that the top element of the execution context would always be the line inside say where here is called. So for example auto prefix would always report the same line. To make it step over say you’d have to add the function to HERE_WRAP:

HERE_WRAP[say]=t

By default the array contains bye and here2.

History

The project originally started with a gist advertised in /r/bash as the exit function on steroids. Multiple people asked me for a context printer not tied to exit. I reworked the original code to separate the printing stuff, thats how here-bye emerged.