conf.sh(3) -- easy loading of configuration files
==============================================

## SYNOPSIS

`. $(librelib conf)`

## DESCRIPTION

`conf.sh` is a Bash(1) library to easily load various configuration
files related to Arch Linux/Parabola(7) and libretools(7).

I recommend reading the source yourself--it is mostly
self-explanatory, and is shorter than this document.

### VARIABLES

When loading configuration files in a program run with `sudo`(8), it
is often desirable to load the configuration files from the home
directory of the user who called `sudo`, instead of from /root.

To accommodate this, instead of using the usual $<USER> and $<HOME>,
`conf.sh` sets $<LIBREUSER> and $<LIBREHOME>, which it then uses.

   * <LIBREUSER>:
     If $<SUDO_USER> is set, then $<LIBREUSER> is set to
     that. Otherwise, $<LIBREUSER> is set to the value of $<USER>.
   * <LIBREHOME>:
     If $<LIBREUSER> == $<USER>, then $<LIBREHOME> is set to the value
     of $<HOME>.  Otherwise, it is set to the default home directory
     of the user $<LIBREUSER>.

Further, `conf.sh` works with XDG; it sets and uses
$<XDG_CONFIG_HOME> and $<XDG_CACHE_HOME> with the following values:

   * <XDG_CONFIG_HOME>:
     If it isn't already set, it is set to "$<LIBREHOME>/.config" and
     exported.
   * <XDG_CACHE_HOME>:
     If it isn't already set, it is set to "$<LIBREHOME>/.cache" and
     exported.

Note that only the XDG_* variables are exported.

### GENERIC ROUTINES

The following routines take a "slug" to refer to a group of
configuration files; that is the basename of the files.  For example,
<SLUG>='abs' will identify `/etc/abs.conf` and `$<LIBREHOME>/.abs.conf`.

The routines you will likely actually use are:

   * `load_files` <SLUG>:
     Loads the configuration files for <SLUG>, loading the files in
     the correct order, and checking the appropriate environmental
     variables.
   * `check_vars` <SLUG> <VARS>...:
     Checks to see if all of <VARS> are defined.  If any of them
     aren't, it prints a message to configure them in the
     configuration files for <SLUG>, and returns with a non-zero
     status.

There are also two more routines that are used internally by
the above.  You are unlikely to use them directly, but they might
be useful for debugging.

   * `list_files` <SLUG>:
     Lists (newline-separated) the configuration files that must be
     considered for <SLUG>.  Files listed later take precedence over
     files listed earlier.
   * `list_envvars` <SLUG>:
     Lists (newline-separated) the environmental variables that take
     precedence over the settings in the configuration files for
     <SLUG>.  For example, in `makepkg.conf`(8) (<SLUG>=makepkg), if the
     <PACKAGER> environmental variable is set, the value in the
     configuration file is ignored.

### MAKEPKG.CONF ROUTINES

These two routines exist to get and set individual variables in
`makepkg.conf`().  See the output of `list_files makepkg` for exactly
what set of files that refers to.

These routines do NOT work with array settings.

   * `get_conf_makepkg` <VAR> <DEFAULT>:
     If <VAR> is set, return it's value, considering environmental
     variables.  If it is not set, return <DEFAULT>.  The printed
     value is then trailed by a newline.
   * `set_conf_makepkg` <VAR> <VALUE>:
     Set the variable <VAR> equal to <VALUE> in the configuration file
     of highest precedence that already exists, and is writable.  If
     no files fit this description, the routine does nothing and
     returns a non-zero exit status.

### PKGBUILD ROUTINES

These two routines deal with loading `PKGBUILD`(5) files.

   * `unset_PKGBUILD`:
     Unsets all variables and functions that might be set in a
     `PKGBUILD`(5) file, including those specific to `librefetch`(8).
   * `load_PKGBUILD` [<FILE>]:
     "Safely" loads a PKGBUILD.  Everything that it would normally set
     is unset first, $<CARCH> is set according to `makepkg.conf`(5),
     then the file is loaded.  The file to be loaded is <FILE>, or
     "./PKGBUILD" by default.  This isn't safe, security wise, in that
     the PKGBUILD is free to execute code.

### SLUGS

The differences in behavior for anything that takes a slug comes down
to the differences in the output for `list_files` and `list_envvars`.

The "known" slugs are "abs", "makepkg", and "libretools".  If anything
else is given, then:

   * `list_files` will give back "/etc/libretools.d/<SLUG>.conf" and
     "$<XDG_CONFIG_HOME>/libretools/<SLUG>.conf"
   * `list_envvars` will give back an empty list.

The rules for <SLUG>=(abs|makepkg|libretools) are more easily
expressed in code than prose, so it is recommended that you look at
that.

## BUGS

`get_conf_makepkg` and `set_conf_makepkg` do not work with arrays.

## SEE ALSO

librelib(7)

abs.conf(5), makepkg.conf(5), libretools.conf(5), PKGBUILD(5)

chroot.conf(5), librefetch.conf(5)