CONSFIGURATOR.PROPERTY.FILE
API reference
General
Function: FILE:MAP-REMOTE-FILE-LINES
(file:map-remote-file-lines file function)
Apply FUNCTION to the lines of FILE. Safe to use in a :POSIX property.
For efficiency, a :LISP property might want to use streams, but there’s no point in doing that here because WRITE-REMOTE-FILE is synchronous.
Property: FILE:HAS-CONTENT
(file:has-content path content &key mode)
Ensure there is a file at PATH whose content is CONTENT. CONTENT can be a list of lines or a single string.
Property: FILE:EXISTS-WITH-CONTENT
(file:exists-with-content path content &key mode)
Like FILE:HAS-CONTENT, but unapplicable, where unapplying means deleting PATH, rather than restoring any old content it might have had.
The semantics of this property are that if it is applied, the file has content CONTENT, and if it is not applied to a host, the file does not exist. Thus, it should be used to create new files on the host, not to replace the contents of existing files, such as those installed by operating system packages. For replacing the contents of existing files, prefer FILE:HAS-CONTENT.
Property: FILE:CONTAINS-LINES
(file:contains-lines path &rest lines)
Ensure there is a file at PATH containing each of LINES once.
Property: FILE:LACKS-LINES
(file:lacks-lines path &rest lines)
If there is a file at PATH, ensure it does not contain any of LINES.
Property: FILE:LACKS-LINES-MATCHING
(file:lacks-lines-matching path &rest patterns)
If there is a file a PATH, ensure it does not contain any lines matching any of the regular expressions PATTERNS.
Property: FILE:HAS-MODE
(file:has-mode path mode)
Ensure that a file has a particular numeric mode.
Property: FILE:HAS-OWNERSHIP
(file:has-ownership path &key user group)
Ensure that a file has particular ownership and group ownership.
Property: FILE:DOES-NOT-EXIST
(file:does-not-exist &rest paths)
Ensure that files do not exist.
Property: FILE:DIRECTORY-DOES-NOT-EXIST
(file:directory-does-not-exist &rest directories)
Recursively ensure that DIRECTORIES do not exist.
Property: FILE:EMPTY-DIRECTORY-DOES-NOT-EXIST
(file:empty-directory-does-not-exist &rest directories)
Ensure that none of DIRECTORIES exist as empty directories.
Property: FILE:DATA-UPLOADED
(file:data-uploaded iden1 iden2 destination)
Property: FILE:HOST-DATA-UPLOADED
(file:host-data-uploaded destination)
Property: FILE:SECRET-UPLOADED
(file:secret-uploaded iden1 iden2 destination)
Property: FILE:HOST-SECRET-UPLOADED
(file:host-secret-uploaded destination)
Property: FILE:DATA-CACHE-PURGED
(file:data-cache-purged)
Ensure that any prerequisite data cached in the remote home directory is removed.
Property: FILE:REGEX-REPLACED-LINES
(file:regex-replaced-lines file regex replace)
Like s/REGEX/REPLACE/ on the lines of FILE. Uses CL-PPCRE:REGEX-REPLACE, which see for the syntax of REPLACE.
Property: FILE:DIRECTORY-EXISTS
(file:directory-exists dir)
Ensure that a directory and its parents exists.
Property: FILE:CONTAINING-DIRECTORY-EXISTS
(file:containing-directory-exists file)
Ensure that a file’s directory and the latter’s parents exist.
Property: FILE:SYMLINKED
(file:symlinked &key from to)
Ensure FROM is a symlink to TO. Symbolic links are overwritten; it is an error if FROM is another kind of file, except when unapplying.
The link target, TO, is literal: if it is a relative path, then it is not relative to the remote home directory, but instead relative to the directory that contains FROM. To create a link with a target under the remote home directory, you can use one or more ‘../’, or an absolute path.
Property: FILE:IS-COPY-OF
(file:is-copy-of dest source)
Ensure that DEST is a copy of SOURCE. SOURCE may be a regular file or a symbolic link, in which case the target of the link will be copied.
Config files
Property: FILE:CONTAINS-CONF-SPACE
(file:contains-conf-space file &rest pairs)
Where FILE is a config file in which keys and values are separated by spaces and there are no sections, and PAIRS is a list of even length of alternating keys and values, set each of these keys and values in FILE.
If there are any other lines which set values for the same keys, they will be commented out; the first commented or uncommented line for each key will be uncommented and used to set the value, if it exists.
Property: FILE:CONTAINS-CONF-TAB
(file:contains-conf-tab file &rest pairs)
Like FILE:CONTAINS-CONF-SPACE, but separate keys and values with a tab rather than a space when updating lines.
Property: FILE:CONTAINS-CONF-EQUALS
(file:contains-conf-equals file &rest pairs)
Where FILE is a config file in which keys and values are separated by “ = ” and there are no sections, and PAIRS is a list of even length of alternating keys and values, set each of these keys and values in FILE.
If there are any other lines which set values for the same keys, they will be commented out; the first commented or uncommented line for each key will be uncommented and used to set the value, if it exists.
Property: FILE:CONTAINS-CONF-UNSPACED
(file:contains-conf-unspaced file &rest pairs)
Where FILE is a config file in which keys and values are separated by “=”, without spaces, there are no sections, and PAIRS is a list of even length of alternating keys and values, set each of these keys and values in FILE.
If there are any other lines which set values for the same keys, they will be commented out; the first commented or uncommented line for each key will be uncommented and used to set the value, if it exists.
Property: FILE:CONTAINS-CONF-SHELL
(file:contains-conf-shell file &rest pairs)
Where FILE is a shell config file, like those in /etc/default, and PAIRS is a list of even length of alternating keys and values, set each of these keys and values in FILE.
If there are any other lines which set values for the same keys, they will be commented out; the first commented or uncommented line for each key will be uncommented and used to set the value, if it exists.
Property: FILE:CONTAINS-INI-SETTINGS
(file:contains-ini-settings file &rest triples)
Where FILE is an INI file, and each of TRIPLES is a list of three elements, a section name, key and value, set those keys and values in FILE. Keys containing ‘=’ are not supported.
If there are any other lines which set values for the same keys in the same sections, they will be commented out. The first commented or uncommented line for each key in its section will be uncommented and used to set the value, if it exists.
Some normalisation will be performed: whitespace around the ‘=’ will be removed, and semicolon comment chars will be replaced with ‘#’.
Function: FILE:UPDATE-UNIX-TABLE
(file:update-unix-table file source target entries &key no-source)
Ensure that the UNIX table at FILE (e.g. /etc/fstab) contains each of ENTRIES, using a simple merge procedure: existing lines of the file with the same value for the TARGETth field are updated to match the corresponding members of ENTRIES, except that if the SOURCEth field of the existing entry is not NO-SOURCE and the corresponding member of ENTRIES is STRING= to either NO-SOURCE or “PLACEHOLDER”, use the existing field value.
Sort the lines to avoid certain possible failures. For each pair of lines, if the TARGETth or the SOURCEth field of the first line is a path and a subpath of the TARGETth field of the second line, sort the second line earlier. Otherwise, try to avoid disturbing line order. This avoids failures to mount because the filesystem containing the mount point is not mounted yet, and ensures that partitions containing things like swap files are mounted before an attempt is made to activate the swap, set up the bind mount, etc.