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.

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)