Property application specifications (“propspecs”)
If you understand the difference between propspecs and unevaluated propspecs
well enough to be able to read and understand most of the uses of
DEFPROPLIST in Consfigurator’s own source, then you can probably get away
without working through this section of the manual. You can build your own
propspecs by taking uses of
DEFPROPLIST in Consfigurator’s own source as
models. What follows is mainly for those who want to implement new property
combinators, though normal usage of Consfigurator should not require doing
Property application specifications are a domain-specific language which enables
combining properties to make new properties, e.g. with
representing the properties which are to be applied to a host in a form which can be serialised using the Lisp printer.
An atomic property application (“propapp”) is a list satisfying the lambda
(PROPERTY &rest ARGS) where
PROPERTY is a symbol naming a
ARGS satisfies that property’s lambda list, or the empty
list, which means a no-op property. A property combinator is a function
which takes at least one propapp as one of its arguments and returns a single
propapp, or a macro which takes at least propapp as one of its arguments and
returns an expression which yields a single propapp (in the return values of
property combinators, often
PROPERTY will be a gensym). A property
application specification is
a readably printable Lisp expression, P, known as a property application specification expression, which contains
propapps combined using property combinators; but
no free variables except as bound by macro property combinators, i.e., such that the evaluation of P would not be affected by any dynamic or lexical context; where
evaluating P means an operation equivalent to quoting each propapp occurring in P, and then passing the whole thing as the only argument to
a list of ASDF systems S; such that
evaluating P yields a propapp
(PROPERTY &rest ARGS); such that
when each of S are loaded, calling
ARGSwill apply each of the propapps occurring in P in accordance with the combinators occuring in P.
A property application specification should not contain any binding forms except as will be eliminated after macroexpansion.
We do not always cleanly distinguish between property application specifications and property application specification expressions, and the abbreviation “propspec” refers to both. It is usually clear from the context which is meant. Within Lisp they are easy to distinguish because property application specifications are CLOS objects, whereas property application specification expressions are just conses.
An unevaluated property application specification expression (“unevaluated propspec”) is a list of Lisp forms which can be converted into a property application specification expression by
replacing each argument in each propapp with the result of evaluating that argument in the dynamic and lexical contexts in which the unevaluated propspec occurs; and
wrapping a single property combinator which takes a variable number of arguments around the resulting list of Lisp forms, usually
That is, the arguments to propapps in unevaluated propspecs are forms which
will produce the arguments to the properties, rather than those arguments
themselves. There is one special case: if the symbol naming the property ends
with the character
., then the propapp is replaced with a new one
according to the following rules (the “dotted propapp rules”):
the property to be applied is the property named by the symbol in the same package and with the same name as the first element of the propapp, but with the trailing period removed from the name;
the first argument is not evaluated if it is a list whose first element is a keyword, or a if it is a list of lists where the first element of the first list is a keyword; and
the last required or optional argument to the property to be applied is converted to a
&restparameter and its elements are treated as an embedded unevaluated propspec, which is recursively converted into a propspec according to the usual evaluation rules, where the surrounding combinator is
The dotted propapp rules are implemented by
which define a macro with the dotted name which performs the replacement.
Function. Applies each of the propapps passed as arguments without stopping
if any of them signal a failed change. Semantically, the propapps are ordered
with respect to their
:HOSTATTRS subroutines, but not with respect to
Function. Applies each of the propapps passed as arguments, stopping and signalling a failed change if any of the propapps signal a failed change. Semantically, each propapp implicitly depends upon the preceding propapps.
Function. Unapplies a single propapp.
Macro. Applies properties when attempting to apply the first did not return
The conversion of an unevaluated propspec into a propspec must resolve any free variable references, except where those will be resolved by macro property combinators.
PROPS macro converts an unevaluated propspec into a propspec.
The evaluation of arguments to propapps in unevaluated propspecs appearing in
DEPLOYS-THESE. cannot retrieve
hostattrs, because these propspecs will be evaluated as part of the initial
definitions of hosts, before they have any hostattrs. By contrast, the
unevaluated propspecs in calls to
DEPLOY-THESE, and the code which produces propspecs in
may retrieve hostattrs set by other properties, because that code is run in
the context of a host which has already been defined. You cannot retrieve
hostattrs set by properties in the propspec resulting from evaluating the
evaluated propspec, however, since that propspec has not yet been applied to
the host. New hostattrs should not be pushed outside of the definitions of
The elements of unevaluated propspecs are typically arguments to macros, such
that the context of evaluation for forms which produce the arguments to the
propapps is the context in which the call to the containing macro appears.
The single property combinator which will be wrapped around the list of forms
depends on the macro.
The dotted propapp rules are intended to make applications of properties like
CHROOT:DEBOOTSTRAPPED, which take
property application specifications as arguments, easier to read and write in
the most common cases. For example, you can write:
(deploys. (:ssh (:sudo :as "firstname.lastname@example.org")) athena.example.com (a-further-property val1) (additional-property val2))
(deploys '(:ssh (:sudo :as "email@example.com")) athena.example.com (make-propspec :props `((a-further-property ,val1) (additional-property ,val2))))