include/ipc: Don't send pubsub messages to oneself

When publishing a pubsub message, ipc_endpoint_publish() sends the
message to all subscribers, including the endpoint that is used to
send the message, if it is subscribed to that topic. However, an
endpoint should not receive its own messages.

This commit modifies ipc_endpoint_publish() so that it skips over
the sending endpoint if it is among the recipients.

Add local dummy variable to catch read input

Consume stdin to prevent SIGPIPE for producer

debian/{postinst,postrm}: Add stat overrides for all IPC directories

The post-installation and post-removal scripts in the debian package
do not create or remove stat overrides for the directories in the IPC
directories, possibly leaving ownership and permissions in an
incorrect state.

This commit modifies the post-installation and post-removal scripts
so that stat overrides for IPC directories are correctly created and
removed.

Makefile: Correctly create IPC directories

The command that is supposed to create the directory structure for
IPC messaging is written using brace expansion, despite not being
a shell script. Because GNU Make does not support brace expansion,
it ends up creating an incorrect directory structure.

This commit changes the install rule of the Makefile to avoid brace
expansion.

toolbox: Allow inclusion of test modules when running in shellspec

Toolbox fails to set the module search paths correctly when running
in shellspec, rendering test cases unable to include modules from
test/include.

This commit modifies toolbox to prepend test/include to the module
search path array when executed in shellspec.

test/toolbox: Add test cases for interface/implements mechanism

There are no test cases for the interface/implements mechanism, making
it hard to tell if it works as intended, and if there are regressions.

This commit adds shellspec test cases for the behavior of `interface()'
and `implements()'.

include/uipc: Implement uipc module as extension of ipc module

The uipc module contains several functions that are identical with
their ipc-counterpart. This kind of code-duplication can be avoided
using the new interface/implements mechanism.

This commit modifies the uipc module so that it extends the interface
provided by the ipc module, reusing methods of the ipc module where
possible.

include/ipc: Add functions to ipc interface so it can be extended

The ipc module provides an interface, but it cannot meaningfully
be extended because the interface is missing functions that need to
be overridden by an extending module.

This commit makes several message-related functions public and adds
them to the interface that is provided by the ipc module. This
further adds the `ipc_get_root()' function, which replaces the
`__ipc_root' variable, allowing modules that extend the interface to
use a different root directory.

include/uipc: Make uipc module extend ipc interface

To avoid code duplication, the uipc module should use the encode and
decode functions of the ipc module instead of declaring its own ones.

This commit modifies the uipc module so that it extends the interface
of the ipc module, using the functions provided by the latter.

include/ipc: Make encode and decode methods part of the public API

The ipc and uipc modules use identical methods to encode and decode
data. Instead, one module should allow the other to use its methods.

This commit modifies the IPC module so that it declares the two
methods as part of its interface that can be used by other modules.

toolbox.sh: Don't require all interface methods to be implemented

The interface/implements mechanism requires a module to implement
all methods of the interface that it implements, making modules
that extend other modules impossible.

This commit modifies the `implements()' function to remove the
restriction that a module must implement all interface methods.

toolbox.sh: Allow modules to implement their own interface

The interface/implements mechanism does not allow a module to
implement methods of the interface that it declares. This makes it
impossible to write modules that extend other modules.

This commit changes the interface mechanism so that a module may
provide methods of the interface that it declares. This is done by
renaming module functions if they clash with names of the interface's
method stubs.

toolbox.sh: Don't require interfaces to be included manually

When a module implements an interface, it has to include the module
that defines the interface before calling `implements()'. However,
since the name of an interface and the module that defines it are
necessarily identical, there is no ambiguity and the module should
be included automatically.

This commit modifies the function `implements()' so that it includes
the interface's module before registering the implementation.

toolbox.sh: Make interface methods point to error stub by default

Modules that declare an interface are expected to implement all
methods, prefixing method names with an underscore. However, since
there may be (partially) unimplemented interfaces, the framework
should not make such assumptions about implementations.

This commit modifies the implementation of interfaces so that
methods reference an error stub by default, which warns the caller
that the method is not implemented.

toolbox.sh: Implement naive interfaces and inheritance

The ipc and uipc modules provide the same API to the module user,
but the user cannot easily switch between the two implementations
because toolbox modules do not have a notion of interfaces.

This commit adds a very primitive means for modules to declare and
implement interfaces: when a module declares an interface, a vtable
is allocated in the form of an associative array, and call stubs
are generated which call the functions referenced in the vtable.
A module that implements an interface can then override entries in
the interface's vtable.

test/conf: Add test cases for the conf module

There are no test cases for the conf module, making it impossible to
verify if the module works as intended, and to make sure that commits
do not introduce regressions.

This commit adds a spec file with test cases for the conf module,
adding tests for basic properties of the module's public API.

debian: Increase package version to 0.3.5-1

This commit updates the debian package changelog, increasing the
package version to 0.3.5-1.

include/json: Make json_array_to_lines() use compact JSON notation

Because the whitespace that is printed by jq when outputting arrays
and objects in non-compact notation does not match the whitespace
that is expected by the test cases, the tests fail.

This commit modifies the `json_array_to_lines()' function so that it
outputs data in compact JSON notation, and changes the test cases so
they do not expect any whitespace at all.

include/json: Fix parsing of output from jq in json_array_tail()

The `json_array_tail()' function does not correctly handle return
values and parse output from jq, causing it to incorrectly handle
arrays that contain arrays or objects.

This commit modifies `json_array_tail()' so that it correctly
recognizes the type of data read from jq.

include/json: Fix error handling in json_array_head()

Because json_array_head() does not correctly check the return value
from jq, it does not correctly detect if an array is empty.

This commit fixes the function so that it does not rely on the return
value from `jq -e', since it returns an error if the boolean value false
was retrieved.

test/{ipc,uipc}: Fix the path to the JSON schema validator

The test specs for the ipc and uipc modules assume to be executed
in the test directory. Thus, they call the JSON schema validator
using a path that is relative to the test directory. However, the
test specs should assume to be executed in the root directory of
the source tree.

This commit changes the paths to the JSON schema validator in the
test specs for the ipc and uipc modules so they are relative to
the root of the source tree.

test.sh: Prefer toolbox in same directory over globally installed one

Because test.sh uses the environment's PATH, it ends up using whatever
toolbox is installed in the environment, instead of the toolbox that it
was shipped with.

This commit modifies the test script so that it overrides the path,
making tests use the toolbox they were distributed with. This also
removes unnecessary PATH modifications from the test specs.

include/inst: Add log module to dependencies

The inst module uses functions from the log module without including
the module.

This commit changes the constructor of the inst module so that the
log module is included directly.

docs: Add module reference

None of the modules and functions in toolbox are documented. Thus,
users have to read the source code to understand how functions work,
and to find out what functions are there to begin with.

This commit adds a module reference, documenting modules and the
functions that they implement. The following modules are documented
in the reference:

 - array
 - conf
 - mutex
 - wmutex
 - git
 - inst
 - queue
 - opt
 - is
 - sem
 - json
 - log

include/uipc: Don't store private endpoints in per-user directories

Private endpoints are stored in per-user directories that are created
when the uipc module is loaded. However, the mode and ownership that
the directory is created with may be incorrect, depending on the mode
of the parent directory.

This commit modifies the uipc module so that endpoints are not created
in per-user directories, and moves the necessary directory creation
code to the Makefile, where it will be executed during installation.

include/ipc: Don't store private endpoints in per-user directories

Private endpoints are stored in per-user directories that are created
when the ipc module is loaded. However, the mode and ownership that
the directory is created with may be incorrect, depending on the mode
of the parent directory.

This commit modifies the ipc module so that endpoints are not created
in per-user directories, and moves the necessary directory creation
code to the Makefile, where it will be executed during installation.

test: Set default GPG key when testing ipc module

When initializing the environment for tests of the ipc module, the
default GPG key is not explicitly set. Because newer GPG versions do
not automatically set the default key, no default key is set, causing
sign operations to fail.

This commit modifies the test cases for the ipc module so that the
default GPG key is set during the test setup.

The default key is not set automatically on newer GPG versions

test: Use toolbox in parent directory for tests

Because none of the test specs set PATH, tests use the toolbox version
that is installed in the environment, not the one that is being tested.

This commit modifies the test specs so they prepend the parent directory
to PATH. Further, this adds a symbolic link to the includes in the parent
directory, making sure the correct includes path is searched first.

include/ipc: Remove timeout logic from ipc_endpoint_recv()

The function `ipc_endpoint_recv()' contains logic to handle timeouts
during message reception, even though timeouts are already handled by
the queue.

This commit removes the unnecessary timeout logic from the ipc module.

include/uipc: Remove timeout logic from uipc_endpoint_recv()

The function `uipc_endpoint_recv()' contains logic to handle timeouts
during message reception, even though timeouts are already handled by
the queue.

This commit removes the unnecessary timeout logic from the uipc module.

include/uipc: Adjust permissions to allow inter-user IPC

Because the sgid bit is not set on the uipc directory, endpoints do
not inherit the group ownership from the parent directory. Thus,
endpoints are created with a user's primary group instead of the IPC
group, making inter-user IPC communication impossible.

This commit modifies the uipc module and the post-install script of
the debian package so that the sgid bit is set on the uipc directory
and endpoints are created with the correct permissions for uipc
communication between users.
This commit also modifies the Makefile so that the uipc directory is
created during toolbox installation.

Makefile,README: Use ':' to separate user and group in chown calls

The use of '.' to separate the user and group in calls to chown has
been deprecated for a while, and newer chown versions now print a
warning if '.' is used instead of ':'.

This commit updates all chown calls in toolbox to use ':'.

include/opt: Don't treat options with values as arrays

Because the bit pattern __opt_flag_is_array has more than one set
bit, it is not enough to use a bitwise and to check if an option is
an array, but that is what `opt_print_help()' does.

This commit modifies `opt_print_help()' so that it checks whether
the result of the bitwise and equals __opt_flag_is_array, avoiding
any option with a value to be treated as an array.

toolbox.sh: Add the script path to the module search paths

Toolbox requires modules to be located either in ~/.toolbox/include
or in /usr/share/toolbox/include. This is somewhat inconvenient when
developing scripts with modules that are not supposed to be shared
with other scripts.

This commit adds the path of the executing script to the module
search path, allowing script-private modules to be placed in a
directory called "include" next to the script.

toolbox.sh: Don't mask realpath's return value

When determining the location of toolbox.sh, the result from realpath
is passed to dirname to remove the script name from the path. However,
both commands are executed in the same statement, causing the return
value of realpath to be masked by dirname.

This commit splits the statement into separate steps, so that return
values are not masked.

include/opt: Add array options

Options with multiple values stored in an array can be implemented
using callbacks, but it is somewhat hacky and would be nicer if the
opt module had explicit support for options with multiple values.

This commit adds the "a" attribute, allowing options to be declared
as arrays. The default value of an array option must be the name of
the array that values shall be appended to.

include/inst: Silence shellcheck if unused variables are parameters

When scanning the `inst' module with shellcheck, warnings are issued
about unused variables. However, the unused variables are function
parameters, which have to be declared per toolbox convention.

This commit adds comments instructing shellcheck to ignore the
unused function parameters.

include/inst: Fix syntax error that prevents module from being loaded

The function `_inst_handle_opt_stop()' in the inst module contains a
syntax error that prevents the module from being loaded.

This commit removes the stray `then' token that causes the syntax
error.

include/inst: Allow terminated instances to be cleaned up properly

The signal handler that is registered by `_inst_run()' catches the
EXIT and QUIT signals, which causes the handler to be executed one
more time before the process ends. The semaphore that the handler
will attempt to manipulate at that point will have already been
removed, causing the handler to end up in an infinite loop.

This commit changes the trap call so that the EXIT and QUIT signals
are not handled, preventing the signal handler from being executed
more than once.

include/ipc: Adjust permissions to allow inter-user IPC

Because the sgid bit is not set on the IPC directory, endpoints do
not inherit the group ownership from the parent directory. Thus,
endpoints are created with a user's primary group instead of the IPC
group, making inter-user IPC communication impossible.

This commit modifies the IPC module and the post-install script of
the debian package so that the sgid bit is set on the IPC directory
and endpoints are created with the correct permissions for IPC
communication between users.

include/inst: Split _inst_handle_opt() to fix exit behavior

The handler for `--stop' and `--list' options always exits, even
when the option it was invoked for was neither.

This commit splits the handler into two handlers that serve only
one option, avoiding the incorrect behavior.

include/queue: Create data file when queue is created

The data file that contains the queue data is not created when a
queue is created, but rather when data is inserted into the queue.
This causes issues in applications that use queues to share between
users because they need so set permissions on the entire queue at
the time of initialization. However, because the data file is not
created at that time, its permissions cannot be set.

This commit modifies `queue_init()' so that the data file is created
together with the queue.

include/queue: Base64-encoded data in queues

Queues are line-oriented, but the queue functions do not make sure
that user data does not contain newlines, causing data corruption
if the user inserts data that contains newlines.

This commit modifies the queue to store data in base64 format,
avoiding data-dependent behavior.

include/queue: Turn queue into a simple FIFO

The queue module contains functions for file queues and queues with
unique contents, which should be used into separate modules to keep
modules simple and avoid mistakes such as using functions for normal
queues on file-queues.

This commit removes functions for file and unique queues from the
queue module, turning queues into simple FIFO data structures.

include/inst: Move instance root to /tmp

Instance data is currently kept in the user's home directory, which
has the side-effect that data from crashed instances is not removed
when the machine reboots. Such instances will be shown by `--list',
and prevent singleton instances to be started.

This commit addresses the issue by moving the instance root to /tmp,
which *should* be a non-persistent filesystem.

include/inst: Store the instance root directory in a variable

The directory that all instance directories are contained within is
not kept in a variable, causing several functions to construct the
path from TOOLBOX_HOME. Hence, the root directory is effectively
declared in more than one place.

This commit introduces the global variable `__inst_root', which
points to the directory that contains all instance data, making it
unnecessary to construct the path from TOOLBOX_HOME.

README: Use uipc in PubSub example instead of ipc

The readme uses the ipc module to explain how to implement simple
pubsub-based messaging using toolbox. However, the ipc module is
somewhat awkward to configure because it uses GPG and requires the
user to generate unencrypted keys.

This commit modifies the readme to introduce the uipc module instead
of the ipc module, since the former is easier to set up.

README: Don't use apt-key in installation instructions

The installation instructions for Debian-based distros use apt-key
to add the repository's GPG key, however apt-key is deprecated.

This commit changes the instructions to use /etc/apt/trusted.gpg.d
instead of apt-key.

test: Remove BATS test cases

All of the BATS test cases have been migrated to shellspec and can
be removed, since BATS is not used for toolbox tests anymore.

This commit removes all remaining BATS test cases.

test: Add test cases for sem module

There are currently no shellspec test cases for the sem module,
making it impossible to check if the module is working correctly.

This commit adds shellspec test cases for the public functions of
the sem module. The test cases are equivalent to the old BATS test
cases.

test: Add test cases for mutex and wmutex functions

There are currently no shellspec test cases for the mutex and wmutex
modules, making it impossible to check if they are working correctly.

This commit adds test cases for all functions in the mutex and wmutex
modules.

include/mutex: Don't write to stderr when mutex_unlock() fails

When a mutex could not be unlocked, the rm call in mutex_unlock()
writes an error message directly to stderr. However, the function
should only return an error without writing to stderr.

This commit modifies mutex_unlock() so that it does not write to
stderr.

include/wmutex: Don't write to stderr when wmutex_unlock() fails

When a wmutex could not be unlocked, the rm call in wmutex_unlock()
writes an error message directly to stderr. However, the function
should only return an error without writing to stderr.

This commit modifies wmutex_unlock() so that it does not write to
stderr.

utils/ipc-sshtunnel: Use tabs for indentation, spaces for alignment

Some parts of ipc-sshtunnel.sh use spaces for indentation and tabs
for alignment, but tabs should be used for indentation and spaces
for alignment.

This commit fixes the indentation and alignment in ipc-sshtunnel.

utils/ipc-ssltunnel: Initialize global variables

In ipc-ssltunnel, global variables are used to store the topics and
hooks that are passed to ipc-tap and ipc-inject. These variables are
declared in main(), however not all of them are initialized. While
this is not a bug, the function should either initialize all of the
arrays or none at all.

This commit modifies ipc-ssltunnel to initialize all of the arrays
in main().

utils/ipc-sshtunnel: Merge local_to_remote() and remote_to_local()

Except for the position of the call to ssh, the local_to_remote()
and remote_to_local() functions in ipc-sshtunnel are completely
identical.

This commit merges the two functions into one. The new function
expects the caller to pass the direction of the tunnel to be
established in the first argument.

utils/ipc-sshtunnel: Remove unused argument `endpoint'

The local_to_remote() and local_to_remote() functions in ipc-sshtunnel
take a parameter `endpoint', which is never used.

This commit removes the unused parameter.

utils/ipc-sshtunnel: Allow hooks to be passed on the command line

The ipc-tap and ipc-inject utility scripts allow hooks to be passed
on the command line that implement custom behavior upon receipt of
certain topics or tags. However, because ipc-sshtunnel does not take
hooks as command line arguments, this functionality cannot be used
with tunnels established using ipc-sshtunnel.

This commit modifies ipc-sshtunnel so that users may specify hooks
that will be passed on to ipc-tap and ipc-inject.

utils/ipc-sshtunnel: Add script for establishing IPC-over-SSH tunnels

This commit adds ipc-sshtunnel, a utility script for establishing a
bi-directional tunnel for IPC PubSub messages over SSH. This allows
scripts on separate machines to communicate even without a shared
file system.

utils/ipc-tap: Check if a hook is present before executing it

When ipc-tap calls per-topic hooks, it does not check if a hook was
set, causing an error to be emitted when no hook for a topic was set.

This commit modifies ipc-tap so that it checks if a hook is set before
executing it.

toolbox.sh: Suppress errors in command_not_found_handle()

When the user enters an unknown command, or a script contains an
unknown command, the command_not_found_handle() function provides
suggestions if the unknown command appears to be in a module.
However, because the function does not suppress errors when looking
for modules in the module search paths, it emits errors if any of
the search paths do not exist.

This commit makes the command_not_found_handle() function suppress
errors if any of the module search paths do not exist.

utils/ipc-inject: Don't inject messages with header

When ipc-inject injects a message, it uses ipc_endpoint_publish()
to re-publish it in its entirety, including the wrapper it was
received in, causing it to be double-wrapped.

This commit modifies ipc-inject so that it re-publishes only the
data of the received message, instead of the entire message.

utils: Implement hooks in ipc-tap and ipc-inject

To correctly forward foundry messages using ipc-tap and ipc-inject,
it is necessary to move data that is usually not transferred over
IPC messages. In order to transfer this data over ipc-tap and
ipc-inject, hooks are necessary that allow user-data to be generated
on the ipc-tap side and consumed on the ipc-inject side.

This commit implements a simple mechanism that allows the user to
specify hooks that are called by ipc-tap whenever a message on a
user-defined topic is encountered. The hook can then inject
messages into ipc-tap's data stream. On the ipc-inject side, the
user may define hooks that are called when a user-message with a
application-defined tag is encountered, allowing the injected
message to be handled on the ipc-inject side.

utils: Add interceptor and injector for IPC PubSub messages

Because the IPC module uses the file system to exchange messages,
remote systems cannot communicate without a shared file system such
as NFS. However, NFS may not be an option due to resource and
security constraints.

This commit adds the ipc-tap and ipc-inject utilities, which can be
used to bridge messages over an SSH connection. As the name suggests,
the ipc-tap utility taps into topics and outputs messages published
on those topics to standard output.
The ipc-inject reads messages from standard input and injects them
into local PubSub topics.

include/sem: Implement sem_trywait() using sem_wait() with 0 timeout

Because sem_trywait() does not unlock the waitlock if the counter is
greater than 1, the next caller will be left waiting until sem_post()
is executed.

This commit changes sem_trywait() to call sem_wait() with a timeout
of 0 seconds, since this issue does not affect sem_wait().

debian: Increase package version to 0.3.4-1

This commit increases the package version to 0.3.4-1.

include/uipc: Add "topic" field to pubsub UIPC messages

Messages that were sent with uipc_endpoint_publish() don't contain
information about the topic that they were published on, making it
impossible for the receiver to determine what topic a message was
published on if they are subscribed to more than one topic.

This commit adds a new field "topic" to UIPC messages and modifies
uipc_endpoint_publish() so that it sets the field appropriately. This
further adds the function uipc_msg_get_topic() that may be used to
determine the topic a UIPC message was published on.

include/ipc: Add "topic" field to pubsub IPC messages

Messages that were sent with ipc_endpoint_publish() don't contain
information about the topic that they were published on, making it
impossible for the receiver to determine what topic a message was
published on if they are subscribed to more than one topic.

This commit adds a new field "topic" to IPC messages and modifies
ipc_endpoint_publish() so that it sets the field appropriately. This
further adds the function ipc_msg_get_topic() that may be used to
determine the topic an IPC message was published on.

test/ipc: Fix comparisons in test cases for ipc_endpoint_recv()

In the test cases for ipc_endpoint_recv(), the comparisons used to
check the correctness of the received data are inverted, causing the
tests to fail when they should succeed and vice-versa.

This commit inverts the incorrect conditions.

test/ipc: Fix return values in test case for ipc_endpoint_open()

When testing whether ipc_endpoint_open() correctly opens a private
endpoint, the return values of the test case are inverted, causing
the test to fail when it should succeed and vice-versa.

This commit inverts the return values of the test case.

test/ipc: Make setup() function idempotent

The setup() function in the test spec for the ipc module is not
idempotent, causing the second and all subsequent test cases that
use it to fail.

This commit modifies the setup() function so that it does not fail
if it is called more than once.

test/ipc: Fix typo in test case for ipc_endpoint_send()

The test case that checks if ipc_endpoint_send() can send messages
to private endpoints contains a typo, causing the test case to fail.

This commit fixes the typo in the test case.

include/opt: Add a default regex and action

The regex and action of an option may be unset, making it necessary
to check their value before using them.

This commit modifies the opt module to define a default regex and
action in case the user didn't provide one, allowing the parser to
omit checks if the two are unset.

include/opt: Initialize value of options that don't have a value

The opt module uses the value of options that aren't followed by a
parameter to count how often the option was on the command line.
However, in this case it never initializes the value.

This commit modifies the opt module so that it initializes the
value of options that are not followed by a parameter to 0.

include/opt: Remove summary of short options from help text

The help text displayed by the opt module contains a summary of all
short options in the title. However, a cursory search showed that
most commandline tools don't do that. Thus, this "feature" may be
removed.

This commit removes the summary of short options from the title of
the help text.

include/opt: Improve code readability

There are several functions in the opt module where local variables
are not declared in the most narrow block possible, statements are
needlessly spread over multiple lines, and values used only once
are assigned to variables; all of which impeding readability.

This commit modifies the opt module to remove cases of assign-once-
read-once variables, remove integer increments on separate lines,
make the "scope" of variables narrower, and declare variables
with a type, where possible.

include/opt: Remove unnecessary array __opt_long

The data that is stored in opt's __opt_long array is a subset of
the data stored in __opt_map. The operations that the module does
on __opt_long might just as well be performed on __opt_map without
affecting the behavior of the module.

This commit removes the __opt_long array from the module and
changes the affected functions to use __opt_map instead.

include/opt: Show default values in help text

The opt module does not show the default values of options in the
help text, leaving the user guessing what the values of options are
if they are not specified on the command line.

This commit modifies `opt_print_help()` so that it displays the
default values of options that have a value and a default set.

include/opt: Use associative array to track missing options

The opt module does not track missing options, but instead checks
on demand if required options are missing by inspecting all options'
flags and value. This approach is needlessly complicated and slow.

This commit changes the opt module to track required options using
an associative array, allowing the check for missing options to be
performed in constant time.

include/opt: Use an associative array to simplify flag parsing

When parsing the flags of an option, the opt module uses a case
construct, which looks clumsy, isn't very easy to read, and makes
adding new flags more complicated than need be.

This commit modifies the opt module to use an associative array
to simplify flag parsing. This way, the parser only has to use a
flag as index into the array in order to find out its internal
value.

include/opt: Remove unused variable __opt_num

The opt module counts the number of options that were defined, but
the count is never used.

This commit removes the unused variable.

test/opt: Add test cases for opt module

There are currently no test cases, making it difficult to verify
automatically if the opt module is implemented correctly, and to
detect regressions.

This commit adds a set of shellspec test cases for the opt module.

include/opt: Make return values of opt_get() more helpful

The function `opt_get()` returns 0 when an option is valid but was
not set. This makes it impossible to distinguish if the value of
the option is the empty string or it does not have a value at all.
Further, it does not return an error if an invalid option's value
was requested.

This commit fixes the behavior of `opt_get()` so that it returns 0
if an option is valid and has a value (default or user-defined), 1
in case that the option name is invalid, and 2 in case that the
option name is valid but it does not have a value.

include/opt: Emit an error if a required parameter is missing

When an option expecting a parameter is not passed one, `opt_parse()`
does not fail because of an incorrect comparison.

This commit fixes the comparison so that `opt_parse()` fails and
prints an error message when a required parameter is missing.

include/opt: Emit an error message when an option is redefined

When the caller attempts to redefine an option, `opt_add_arg()` fails
without printing an error message, leaving the situation undetected
if the caller does not check the return value of the call.

This commit modifies `opt_add_arg()` to print an error message when
a caller attempts to redefine an option.

include/opt: Use column command to align help text

When printing the help text, the opt module aligns columns manually
by tracking the longest option name and inserting the required amount
of spaces into the output. This is needlessly complicated considering
there are simpler ways to align output.

This commit modifies the opt module to use the column command to
align the table of options in the help text.

include/opt: Print correct script name on older bash versions

The opt module references $BASH_ARGV0 to get the name of the running
script. However, the variable does not exist on older bash versions,
causing a gap in the help text.

This commit modifies the opt module to access the script name from
$0, which should be available on all bash versions.

toolbox.sh: Make command-not-found errors more helpful

Command-not-found errors often occur because the user forgot to
include a module. In such cases, it would be helpful if the default
error message included suggestions for modules to include.

This commit adds a `command_not_found_handle()` function that
overrides bash's default behavior: aside of the usual error message,
this function will print all module names that the missing function
may be part of (as determined by its name) to stderr.

include/uipc: Add module for unsigned message-based IPC

The IPC module cannot be used without GPG for message signing and
verification, which makes the module unusable if GPG cannot be used.

This commit adds the uipc module, which implements functions similar
to those of the ipc module, but without message authentication.

include/inst: Expect arguments from opt_get_argv() in multiple lines

The inst module expects `opt_get_argv()` to print all command line
arguments in one line, however the behavior of `opt_get_argv()` has
been changed to print arguments line-by-line.

This commit modifies the inst module so that it expects arguments to
be returned one per line by `opt_get_argv()`.

include/opt: Make opt_get_argv() print arguments line-by-line

Because `opt_get_argv()` prints the entire command line in one line,
callers cannot reliably parse individual arguments from the output.

This commit modifies `opt_get_argv()` to print the arguments line-
by-line.

include/ipc: Remove unnecessary variables in _ipc_msg_new()

The `_ipc_msg_new()` function has one duplicate and one unused
variable declaration that can be removed.

This commit removes the unnecessary variable declarations from
`_ipc_msg_new()`.

include/log: Don't mangle whitespaces

Because IFS is not set in `_log_write()`, logging functions silently
drop whitespace from the beginning and end of each line.

This commit modifies `_log_write()` to set IFS to the empty string
when invoking `read`, so that whitespaces are not stripped.

include/mutex: Use $$ instead of $BASHPID to identify the owner

The mutex module uses $BASHPID to identify the owner of a mutex,
causing scripts to be unable to unlock a mutex that was created in a
subshell (which is what happens when using the ipc module).

This commit changes the mutex module to use $$ to identify the owner
of a mutex, allowing child processes to unlock their parent's mutexes
and vice-versa.

include/ipc: Fix bug in unsubscribe logic when closing an endpoint

When `ipc_endpoint_close()` attempts to remove all subscriptions of
an endpoint, the list that it iterates over includes the directory
containing the subscriptions, causing the function to emit an error.

This commit fixes the way that `ipc_endpoint_close()` determines the
list of subscriptions to be removed.

include/array: Improve performance of array_to_lines()

`array_to_lines()` calls `echo` for every element in the array, which
is wasteful and scales very poorly.

This commit modifies `array_to_lines()` so that it uses a single call
to `printf` to print all array elements.

This issue was pointed out by reddit user u/oh5nxo.

README: Add note about GPG keys to configuration section

To use the ipc module, users need to have a usable gpg keypair, but
the README does not mention that.

This commit adds a paragraph about GPG to the configuration section
of the README.

debian: Make toolbox package depend on gnupg2

The ipc module uses gpg2, but gnupg2 is not among the dependencies
of the toolbox package.

This commit adds gnupg2 to the dependencies of the toolbox package.

README: Add a usage example

The readme does not explain how to use toolbox.

This commit adds two short examples how to use toolbox.