- notes on some of the functions

1 files changed, 103 insertions, 1 deletions

diff --git a/doc/design.txt b/doc/design.txt
index ace58f8..6be771b 100644
--- a/doc/design.txt
+++ b/doc/design.txt
@@ -205,7 +205,7 @@ of group members.
 
 The filter, keyFormat, valueFormat, and referred settings have sensible
 defaults for the maps which we expect to be using -- this is important
-because it's easy to subtly construct malformed result strings which
+because it's easy to subtly construct malformed result specifiers which
 could trigger undefined behavior on clients -- for example by leaving
 the user's numeric UID empty in a passwd entry, which may be treated as
 "0" by inattentive clients.
@@ -218,3 +218,105 @@ A function-like invocation expects a comma-separated list of
 double-quoted arguments. and any arguments which contain a double-quote
 need to escape the double-quote using a '\' character -- this character
 itself also needs to be escaped whenever it appears.
+
+Implemented functions:
+  * echo()
+    - Reproduces what it is given.
+    - Example: 
+      %echo("foo","bar") -> foobar
+  * match(ATTRIBUTE,PATTERN[,DEFAULT])
+    - Selects the value of ATTRIBUTE which matches the globbing pattern
+      PATTERN.  If zero or two or more values match, and a DEFAULT was
+      specified, the DEFAULT is produced, otherwise an error occurs.
+    - Example: 
+        dn: cn=group
+	member: bob
+	member: dave
+      %match("member","b*")       -> bob
+      %match("member","d*")       -> dave
+      %match("member","e*")        FAILS
+      %match("member","e*","jim") -> jim
+  * regmatch(ATTRIBUTE,PATTERN[,DEFAULT])
+    - Selects the value of ATTRIBUTE which matches the extended regular
+      expression PATTERN.  If zero or two or more values match, and a
+      DEFAULT was specified, the DEFAULT is produced, otherwise an error
+      occurs.
+    - Example: 
+        dn: cn=group
+	member: bob
+	member: dave
+      %regmatch("member","^b.*")       -> bob
+      %regmatch("member","^d.*")       -> dave
+      %regmatch("member","e")          -> dave
+      %regmatch("member","^e")          FAILS
+      %regmatch("member","^e.*","jim") -> jim
+  * regsub(ATTRIBUTE,PATTERN,TEMPLATE[,DEFAULT])
+    - Selects the value of ATTRIBUTE which matches the extended regular
+      expression PATTERN and uses TEMPLATE to construct the output.  If
+      zero or two or more values match, and a DEFAULT was specified, the
+      DEFAULT is produced, otherwise an error occurs.  The template is
+      used to construct a result using the n'th substring from the
+      matched value by using the sequence "%n" in the template.
+    - Example: 
+        dn: cn=group
+	member: bob
+	member: dave
+      %regsub("member","o","%0")          -> bob
+      %regsub("member","o","%1")          -> 
+      %regsub("member","^o","%0")         FAILS
+      %regsub("member","^d(.).*","%1")    -> a
+      %regsub("member","^(.*)e","t%1y")   -> tdavy
+      %regsub("member","^e","%1")         FAILS
+      %regsub("member","^e.*","%1","jim") -> jim
+  * list(SEPARATOR,ATTRIBUTE[,...])
+    - Creates a separated list of the values of the named attributes for
+      the current entry.  If an attribute has multiple or no values,
+      they are either included or skipped.
+    - Example: 
+        dn: cn=group
+	member: bob
+	member: dave
+      %list(",","member") -> bob,dave
+  * deref(SEPARATOR,THISATTRIBUTE,THATATTRIBUTE)
+    - Creates a separated list of the values of THATATTRIBUTE for
+      directory entries named by this entry's THISATTRIBUTE.
+    - Example: 
+        dn: cn=group
+	member: uid=bob
+	member: uid=pete
+        -
+	dn: uid=bob
+	uid: bob
+        -
+	dn: uid=pete
+	uid: pete
+      %deref(",","member","uid") -> bob,pete
+  * referred(SEPARATOR,THATATTRIBUTE,THATOTHERATTRIBUTE)
+    - Creates a separated list of the values of THATOTHERATTRIBUTE for
+      directory entries which have this entry's name as a value for
+      THATATTRIBUTE.
+    - Example: 
+        dn: cn=group
+        -
+	dn: uid=bob
+	uid: bob
+	memberOf: cn=group
+        -
+	dn: uid=pete
+	uid: pete
+	memberOf: cn=group
+      %referred(",","memberof","uid") -> bob,pete
+  * merge(SEPARATOR,EXPRESSION[,...])
+    - Evaluates and then creates a list using multiple expressions.
+    - Example: 
+        dn: cn=group
+	membername: jim
+	member: uid=bob
+	member: uid=pete
+        -
+	dn: uid=bob
+	uid: bob
+        -
+	dn: uid=pete
+	uid: pete
+      %merge(",","%list(\",\",\"membername\")","%deref(\",\",\"member\",\"uid\")") -> jim,bob,pete