# 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 that.

## Purposes

Property application specifications are a domain-specific language which enables

1. combining properties to make new properties, e.g. with `DEFPROPLIST`; and

2. representing the properties which are to be applied to a host in a form which can be serialised using the Lisp printer.

## Definitions

An atomic property application (“propapp”) is a list satisfying the lambda list `(PROPERTY &rest ARGS)` where `PROPERTY` is a symbol naming a property and `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

1. a readably printable Lisp expression, P, known as a property application specification expression, which contains

   1. propapps combined using property combinators; but

   2. 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

   3. evaluating P means an operation equivalent to quoting each propapp occurring in P, and then passing the whole thing as the only argument to `EVAL`; and

2. a list of ASDF systems S; such that

3. evaluating P yields a propapp `(PROPERTY &rest ARGS)`; such that

4. when each of S are loaded, calling `PROPERTY` with `ARGS` will 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

1. 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

2. wrapping a single property combinator which takes a variable number of arguments around the resulting list of Lisp forms, usually `SEQPROPS` or `ESEQPROPS`.

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”):

1. 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;

2. 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

3. the last required or optional argument to the property to be applied is converted to a `&rest` parameter 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 `ESEQPROPS`.

The dotted propapp rules are implemented by `DEFPROP` and `DEFPROPLIST`, which define a macro with the dotted name which performs the replacement.

## Available combinators

### `SEQPROPS`

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 their `:APPLY` subroutines.

### `ESEQPROPS`

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.

### `UNAPPLIED`

Function. Unapplies a single propapp.

### `ON-CHANGE`

Macro. Applies properties when attempting to apply the first did not return `:NO-CHANGE`.

## Remarks

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.

The `PROPS` macro converts an unevaluated propspec into a propspec.

The evaluation of arguments to propapps in unevaluated propspecs appearing in calls to `DEFHOST`, `DEPLOYS.` and `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 `DEFPROPLIST`, `DEPLOY`, and `DEPLOY-THESE`, and the code which produces propspecs in `DEFPROPSPEC`, 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 `:HOSTATTRS` subroutines.

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. `DEFHOST` uses `SEQPROPS`, while `DEFPROPLIST` uses `ESEQPROPS`.

The dotted propapp rules are intended to make applications of properties like `DEPLOYS`, `DEPLOYS-THESE` and `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 "spwhitton@athena.example.com")) athena.example.com
      (a-further-property  val1)
      (additional-property val2))

instead of:

    (deploys '(:ssh (:sudo :as "spwhitton@athena.example.com")) athena.example.com
      (make-propspec :props `((a-further-property  ,val1)
                              (additional-property ,val2))))

## API reference

### Property application specifications

#### Macro: `IN-CONSFIG`

`(in-consfig &rest systems)`

Sets the variable CONSFIG in the current package to SYSTEMS. Used at the top of your consfig, right after IN-PACKAGE.

This is used to record a list of the names of the ASDF systems in which you define your hosts, site-specific properties and deployments. These systems should depend on the “consfigurator” system.

SYSTEMS should satisfy the following condition: in normal usage of Consfigurator, evaluating (mapc #’asdf:load-system SYSTEMS) should be sufficient to define all the properties you intend to apply to hosts and property combinators you intend to use in specifying propspecs.

Consfigurator uses this information when starting up remote Lisp images to effect deployments: it sends over the ASDF systems specified by SYSTEMS.

#### Function: `MAKE-PROPSPEC`

`(make-propspec &key systems propspec)`

Convert a property application specification expression into a property application specification proper by associating it with a list of ASDF systems.

#### Macro: `PROPAPP`

`(propapp form)`

Convert a single element of an unevaluated property application specification expression to a property application specification expression.