diff options
| -rw-r--r-- | doc/data.rst | 51 | ||||
| -rw-r--r-- | src/data.lisp | 5 |
2 files changed, 31 insertions, 25 deletions
diff --git a/doc/data.rst b/doc/data.rst index a32acb1..ae657c6 100644 --- a/doc/data.rst +++ b/doc/data.rst @@ -4,32 +4,19 @@ Prerequisite data Naming ------ -A piece of prerequisite data is identified by two strings. Typically the -first of these specifies the context in which the data is relevant. For an -ssh host key, for example, this context would be a hostname. If it's ``nil`` -then the data is valid in any context. The second of these identifies the -data within its context. This is often just the filename in which the -prerequisite data will eventually be stored. It might also be a -human-readable string describing the purpose of the data. - -Reserved names -~~~~~~~~~~~~~~ - -These are exclusive semantics for certain possible pairs of strings -identifying prerequisite data -- to avoid confusion and potential clashes, do -not use prerequisite data identified by strings matching these conditions for -other purposes. +An item of prerequisite data is identified by two strings, called ``IDEN1`` +and ``IDEN2``; together these are the *prerequisite data identifiers* for an +item of prerequisite data. Typically ``IDEN1`` specifies the context in which +the data is relevant, and ``IDEN2`` identifies the data within its context. +``IDEN2`` is very often the filename in which the prerequisite data will +eventually be stored. It might also be a human-readable string describing the +purpose of the data. The following are the valid forms of ``IDEN1``, and +their meanings. - ``(HOSTNAME . PATH)`` means the data that should be uploaded to ``PATH`` on ``HOSTNAME`` (and usually nowhere else, except in the case of, e.g., a public key). ``PATH`` must be absolute, not relative. -- ``(_CONTEXT . ITEM)`` is an arbitrary prerequisite data context named - ``CONTEXT``; typically ``CONTEXT`` will be a network or grouping name, - rather than referring to a single host. ``ITEM`` might be a path or some - other identifier. Reserved for consfigs; will not be used by property - definitions included with Consfigurator. - - ``("--lisp-system" . SYSTEM)`` means the data is Lisp code which, when loaded, defines the packages and symbols contained in the ASDF system ``SYSTEM`` @@ -49,9 +36,25 @@ other purposes. - ``("--luks-passphrase" . VOLUME-LABEL)`` means a LUKS passphrase for volume with label ``VOLUME-LABEL``. -(Proposed convention: Except for the first two items above, these reserved -names should start with ``--`` and use ``--`` to separate parameter values -within the string. Hostnames cannot start with a hyphen.) +- Any other ``IDEN1`` beginning with exactly two hyphens is reserved for + future use. + +- ``(_CONTEXT . ITEM)`` is an arbitrary prerequisite data context named + ``CONTEXT``; typically ``CONTEXT`` will be a network or grouping name, + rather than referring to a single host. ``ITEM`` might be a path or some + other identifier. Reserved for consfigs; will not be used by property + definitions included with Consfigurator, and should not be used by third + party extensions. + +- ``(---CONTEXT . ITEM)`` is, similarly, an arbitrary prerequisite data + context named ``CONTEXT``. This form is intended for contexts similar to + the reserved names beginning with two hyphens: types of information rather + than site-local network or grouping names. This form will not be used by + property definitions included with Consfigurator, but may be used by both + consfigs and third party extensions. + +Any other forms are invalid. In particular, an ``IDEN1`` that is not a valid +hostname and does not begin with a hyphen or an underscore must not be used. Mechanics --------- diff --git a/src/data.lisp b/src/data.lisp index 307d0c1..ac5c6e9 100644 --- a/src/data.lisp +++ b/src/data.lisp @@ -1,6 +1,6 @@ ;;; Consfigurator -- Lisp declarative configuration management system -;;; Copyright (C) 2021 Sean Whitton <spwhitton@spwhitton.name> +;;; Copyright (C) 2021-2022 Sean Whitton <spwhitton@spwhitton.name> ;;; This file is free software; you can redistribute it and/or modify ;;; it under the terms of the GNU General Public License as published by @@ -173,6 +173,9 @@ This function is called by property :APPLY and :UNAPPLY subroutines." (missing-iden1 condition) (missing-iden2 condition))))) (defun %get-data (iden1 iden2) + (alet (first-char iden1) + (unless (or (char= #\_ it) (char= #\- it) (valid-hostname-p iden1)) + (simple-program-error "Invalid IDEN1: ~S" iden1))) (let* ((idenpair (cons iden1 iden2)) (from-source (query-data-sources iden1 iden2)) (from-source-version (and from-source (car from-source))) |