``CONSFIGURATOR`` exported utilities
====================================

API reference
-------------

General
~~~~~~~

Function: ``MULTIPLE-VALUE-MAPCAN``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(multiple-value-mapcan function &rest lists)``

Variant of MAPCAN which preserves multiple return values.

Function: ``WORDS``
^^^^^^^^^^^^^^^^^^^

``(words text)``

Function: ``UNWORDS``
^^^^^^^^^^^^^^^^^^^^^

``(unwords words)``

Function: ``STRIP-PREFIX``
^^^^^^^^^^^^^^^^^^^^^^^^^^

``(strip-prefix prefix string)``

If STRING is prefixed by PREFIX, return the rest of STRING,
otherwise return NIL.

Function: ``MEMSTR=``
^^^^^^^^^^^^^^^^^^^^^

``(memstr= string list)``

Macro: ``DEFINE-SIMPLE-ERROR``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(define-simple-error name &optional parent-types docstring)``

Function: ``PLIST-TO-LONG-OPTIONS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(plist-to-long-options plist)``

Function: ``SYSTEMD-USER-INSTANCE-ARGS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(systemd-user-instance-args args)``

Where ARGS are args to RUN or MRUN for an invocation of a systemd command
which can take "--user", insert the "--user" parameter, and modify or
insert an :ENV parameter so that the call is more likely to succeed.

Macro: ``WITH-LOCAL-TEMPORARY-DIRECTORY``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(with-local-temporary-directory dir &body forms)``

Execute FORMS with a local temporary directory's pathname in DIR.
Currently assumes GNU mktemp(1).

There is no WITH-REMOTE-TEMPORARY-DIRECTORY because POSIX doesn't include a
shell utility to create temporary directories.  If you need a remote temporary
directory, one solution is to convert your property to a :LISP property.

Function: ``PATHNAME-FILE``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(pathname-file pathname)``

Like PATHNAME-NAME but include any file extension.

Function: ``LOCAL-DIRECTORY-CONTENTS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(local-directory-contents pathname)``

Return the immediate contents of PATHNAME, a directory, without resolving
symlinks.  Not suitable for use by :POSIX properties.

Function: ``ENSURE-TRAILING-SLASH``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(ensure-trailing-slash namestring)``

Function: ``DROP-TRAILING-SLASH``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(drop-trailing-slash namestring)``

Macro: ``DEFINE-SIMPLE-PRINT-OBJECT``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(define-simple-print-object class)``

Define an implementation of PRINT-OBJECT suitable for classes representing
simple collections of readably-printable values.

Function: ``CHROOT-PATHNAME``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(chroot-pathname pathname chroot)``

Function: ``IN-CHROOT-PATHNAME``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(in-chroot-pathname pathname chroot)``

Function: ``SH-ESCAPE``
^^^^^^^^^^^^^^^^^^^^^^^

``(sh-escape token-or-cmd &optional s)``

Macro: ``DEFPACKAGE-CONSFIG``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(defpackage-consfig name &body forms)``

Convenience wrapper around DEFPACKAGE for consfigs.
Adds recommended local nicknames for all the property and data source packages
that come with Consfigurator.  Either use this directly or use its macro
expansion as a starting point for your own DEFPACKAGE form for your consfig.

Macro: ``LAMBDA-IGNORING-ARGS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(lambda-ignoring-args &body body)``

Function: ``PARSE-CIDR``
^^^^^^^^^^^^^^^^^^^^^^^^

``(parse-cidr address-with-suffix)``

Function: ``RANDOM-ALPHANUMERIC``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(random-alphanumeric length)``

Return a random alphanumeric string of length LENGTH.

Function: ``VALID-HOSTNAME-P``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(valid-hostname-p string)``

Test whether STRING looks like a valid hostname, as defined by RFCs 952 and
1123.

Macro: ``PROG-CHANGES``
^^^^^^^^^^^^^^^^^^^^^^^

``(prog-changes &body body)``

Function: ``SH-SCRIPT-TO-SINGLE-LINE``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(sh-script-to-single-line script)``

Attempt to convert a multiline POSIX sh script to a single line.

The current implementation is naïve, and certainly unsuitable for converting
arbitrary scripts.  Thus, this function is presently intended to be used only
on simple scripts embedded in source code, written with newlines for the sake
of maintainability.  Converting those scripts to single lines before they are
executed improves Consfigurator's debug output, and also makes process names
visible to remote commands like ps(1) more readable.

Function: ``POSIX-LEFT-TRIM``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(posix-left-trim string)``

Function: ``POSIX-RIGHT-TRIM``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(posix-right-trim string)``

Function: ``POSIX-TRIM``
^^^^^^^^^^^^^^^^^^^^^^^^

``(posix-trim string)``

Progress & debug printing
~~~~~~~~~~~~~~~~~~~~~~~~~

Variable: ``*CONSFIGURATOR-DEBUG-LEVEL*``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Integer.  Higher values mean be more verbose during deploys.

Macro: ``WITH-INDENTED-INFORM``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(with-indented-inform &body forms)``

Function: ``INFORM``
^^^^^^^^^^^^^^^^^^^^

``(inform level output &key strip-empty fresh-line)``

Print something to the user during deploys.

Function: ``INFORMAT``
^^^^^^^^^^^^^^^^^^^^^^

``(informat level control-string &rest format-arguments)``

Print something to the user during deploys using FORMAT.
Be sure to begin CONTROL-STRING with ~& unless you want to continue from
previous output.

Version numbers
~~~~~~~~~~~~~~~

Function: ``VERSION<``
^^^^^^^^^^^^^^^^^^^^^^

``(version< x y)``

Function: ``VERSION<=``
^^^^^^^^^^^^^^^^^^^^^^^

``(version<= x y)``

Function: ``VERSION>``
^^^^^^^^^^^^^^^^^^^^^^

``(version> x y)``

Function: ``VERSION>=``
^^^^^^^^^^^^^^^^^^^^^^^

``(version>= x y)``

Encoding of strings to filenames
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function: ``STRING-TO-FILENAME``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(string-to-filename s)``

Function: ``FILENAME-TO-STRING``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(filename-to-string s)``

Forking utilities
~~~~~~~~~~~~~~~~~

Macro: ``EXIT-CODE-TO-RETVAL``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(exit-code-to-retval exit &key on-failure)``

Function: ``POSIX-LOGIN-ENVIRONMENT``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(posix-login-environment &optional uid logname home)``

Reset the environment after switching UID, or similar, in a :LISP connection.
Does not currently establish a PAM session.

System and libc calls which can fail
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Macro: ``DEFINE-ERROR-RETVAL-CFUN``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(define-error-retval-cfun &key &body defcfun-args)``

Streams
~~~~~~~

Function: ``MAPC-OPEN-INPUT-STREAMS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(mapc-open-input-streams function streams)``

Function: ``MAPC-OPEN-OUTPUT-STREAMS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(mapc-open-output-streams function streams)``
