each value in HOSTATTRS plist is now prepend-only

Previous approach would have required us to deep copy the list when we wanted
to use things like DEPLOY, DEPLOY-THESE and connections like :DEBIAN-SBCL, but
that would have meant that adding new kinds of hostattrs would have required
writing copy methods.  The new semantics should enable us to do the same
things with hostattrs with only shallow copying.

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

2 files changed, 33 insertions, 16 deletions

diff --git a/doc/hosts.rst b/doc/hosts.rst
new file mode 100644
index 0000000..885a447
--- /dev/null
+++ b/doc/hosts.rst
@@ -0,0 +1,19 @@
+Hosts
+=====
+
+The HOSTATTRS list
+------------------
+
+This is a plist of lists, such that for each keyword symbol identifying a type
+of static informational attribute, there is a list of entries.  Property
+``:HOSTATTRS`` subroutines may only push new entries to the front of each such
+sublist, using the function ``PUSH-HOSTATTR``.
+
+The relationship between older and newer entries in the sublist for each type
+of static informational attribute is attribute-dependent.  For example, for
+the ``:DATA`` attribute, the order of entries does not matter and each item is
+equally a piece of prerequisite data required by the host's properties.  For
+other kinds of attribute, it might be that later entries supercede earlier
+ones, or that the entries should be combined in some way.  Property ``:APPLY``
+subroutines decide how to interpret each type of static informational
+attribute.
diff --git a/doc/properties.rst b/doc/properties.rst
index 79808e3..115ef76 100644
--- a/doc/properties.rst
+++ b/doc/properties.rst
@@ -10,23 +10,21 @@ arguments.  At least one of ``:hostattrs`` or ``:apply`` must be present.
 ``:hostattrs`` subroutines
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Executed in the root Lisp to (i) add and modify static informational
-attributes of hosts to which this property is applied or is to be applied;
-and (ii) check that applying this property makes sense -- e.g. that we're not
-trying to install a package using apt(1) on a FreeBSD host.
-
-When this subroutine is called, ``*HOSTATTRS*`` will be bound to the plist of
-static informational attributes of the host to which the property is to be
-applied, which may be modified.
-
-Should signal the condition ``INCOMPATIBLE-PROPERTY`` if the contents of
-``*HOSTATTRS*`` indicates that the property should not be applied to this
-host.
-
-Should be a pure function aside from looking at and modifying ``*HOSTATTRS*``.
+Executed in the root Lisp to (i) add static informational attributes of hosts
+to which this property is applied or is to be applied; and (ii) check that
+applying this property makes sense -- e.g. that we're not trying to install a
+package using apt(1) on a FreeBSD host.
+
+Can retrieve existing static informational attributes using ``GET-HOSTATTRS``.
+Should signal the condition ``INCOMPATIBLE-PROPERTY`` if existing static
+informational attributes indicate that the property should not be applied to
+this host.  Can use ``PUSH-HOSTATTRS`` and ``REQUIRE-DATA`` to add new entries
+to the host's static information atributes.
+
+Other than as described in the previous paragraph, should be a pure function.
 In particular, should not examine the actual state of the host.  Essentially a
-conversion of the arguments to the property to appropriate static information
-attributes.
+conversion of the arguments to the property to appropriate static
+informational attributes.
 
 ``:check`` subroutines
 ~~~~~~~~~~~~~~~~~~~~~~