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).

### 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; <LIBREUSER> and
<LIBREHOME> are not 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_conf` {<SLUG>.conf|<ABSPATH>} [<VARS>...]:
     Loads the configuration files for <SLUG>, loading the files in
     the correct order, and checking the appropriate environmental
     variables.  Alternatively, instead of giving a <SLUG>, you may
     give an absolute filepath to a configuration file (bypassing
     `list_files`, see below) which will be loaded with no
     environmental overrides (bypassing `list_envvars`, see below).

     If any <VARS> are listed, check to make sure that each of them is
     defined.  If any of them are not defined, it prints a message
     telling the user to configure them in the appropriate files, and
     returns with a non-zero status.
   * `get_var` <SLUG> <VAR> <DEFAULT>:
     If <VAR> is set in the configuration for <SLUG>, print its
     value, considering environmental variables.  If it is not set,
     return <DEFAULT>.  This does NOT work for array variables.
   * `set_var` <SLUG> <VAR> <VALUE>:
     Set the variable <VAR> equal to <VALUE> in the configuration file
     for <SLUG> 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.  This does NOT work
     for array variables.

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

   * `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.

### 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_var` and `set_var` 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)

<!--
  Copyright (C) 2013-2015, 2017-2018, 2024  Luke T. Shumaker <lukeshu@parabola.nu>

  SPDX-License-Identifier: GPL-2.0-or-later

  This file is part of Parabola Libretools.

  Libretools is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 2 of the License, or
  (at your option) any later version.

  Libretools is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-->
