- more docs -- note that the map cache needs to be able to track multiple DNs

  per entry if we want a recursive operator in the format specifier to work
  correctly

1 files changed, 48 insertions, 5 deletions

diff --git a/doc/design.txt b/doc/design.txt
index e17de42..78341eb 100644
--- a/doc/design.txt
+++ b/doc/design.txt
@@ -123,6 +123,17 @@ configurable via internal APIs -- the map cache itself has no forehand
 knowledge of domain names, map names, or formats, as it merely models
 data in the way that a NIS server might.
 
+[While currently the cache is implemented in a prototyping-friendly list
+ of lists structure, I anticipate that searching through maps of larger
+ than trivial size will be expensive enough that a better internal
+ representation will need to be used.  The main requirement from the NIS
+ protocol-handler side is the ability to find a given key and/or the
+ successor key for a given key, and their matching data items.  The
+ backend requires that the cache also be able to track one or more DNs
+ which are relevant to the value which is being stored in the map, so
+ that it can be updated if an entry with that name is added, removed,
+ modified, or renamed.]
+
 Forcing queries to use the cache provides a couple of benefits over an
 alternate approach of performing an LDAP query for each NIS query:
 * While the directory server is generally only case-preserving, the NIS
@@ -151,15 +162,47 @@ plugin's entry, the backend checks for entries with these attributes:
  * map
  * base
  * filter
- * key
- * value
+ * key[Attribute]
+ * value[Format]
 The backend then instructs the map cache to prepare to hold a map in the
 given domain with the given map name, and then performs a subtree search
 under the specified base for entries which match the provided filter.
 Each found entry is then "added" to the map, using the value of the
-attribute named by the "key" as the key for the entry in the map[, with
-the corresponding value being constructed using the format specifier
-given as the "value"].
+attribute named by the "key[Attribute]" as the key for the entry in the
+map, with the corresponding value in the map being the value of the
+attribute named by the "value" [being constructed using the format
+specifier given as the "valueFormat"].
+
+[The "valueFormat" specifier resembles an RPM format specifier, and can
+ include the values of multiple attributes in any part of the specifier.
+ The backend composes the string using the attribute values stored in
+ the directory server entry, using the format specifier as a guide.  In
+ this way, the NIS map's contents can be constructed to almost any
+ specification, can make use of data stored using any schema.  (That's
+ the plan, anyway.)
+
+ An example specification for a user's entry would look like this:
+   %{uid}:%{userPassword:-*}:%{uidNumber}:%{gidNumber}:%{gecos:-%{cn:-}}:%{homeDirectory}:%{loginShell:-/bin/sh}
+ The syntax borrows from RPM's syntax, which in turn borrows from shell
+ syntax, to allow the specification of alternate values to be used when
+ the directory server entry doesn't include a "userPassword" or "gecos"
+ attribute.
+
+ To ensure safety, any reference to an attribute value which does not
+ also specify an alternate value will cause the directory server entry
+ to be ignored if the referenced attribute has no value defined for that
+ entry, or contains more multiple values.  In the above example, the
+ entry would be ignored if the "uid", "uidNumber", "gidNumber", or
+ "homeDirectory" attributes of the entry did not each contain exactly
+ one value.
+ 
+ The syntax further defines "functions" which can be used to concatenate
+ lists of multiple values into a single result, for example for groups:
+   %{cn}:%{userPassword:-*}:%{gidNumber}:%merge{",","memberUid"})
+ This filter takes advantage of a built-in "merge" function, which
+ processes zero or more values of the "memberUid" attribute and
+ concatenates them together with a "," separator, to generate the list
+ of group members.]
 
 [The filter, key, and value have sensible defaults for the maps which we
  expect to be using -- this is important because it's easy to subtly