1 files changed, 126 insertions, 0 deletions
diff --git a/src/lib/conf.sh.3.ronn b/src/lib/conf.sh.3.ronn
new file mode 100644
index 0000000..0974bdb
--- /dev/null
+++ b/src/lib/conf.sh.3.ronn
@@ -0,0 +1,126 @@
+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.
+
+### 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 telling the user to configure them in
+     the configuration files for <SLUG>, 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", "libretools", and anything
+beginning with "xbs".  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)