- notes on deref_rf

1 files changed, 88 insertions, 0 deletions

diff --git a/doc/format-specifiers.txt b/doc/format-specifiers.txt
index 60aba66..ed6ef65 100644
--- a/doc/format-specifiers.txt
+++ b/doc/format-specifiers.txt
@@ -263,6 +263,94 @@ Because the plugin attempts to track updates, every attribute used here
 (except for ''VALUEATTRIBUTE'') should be indexed and defined with a
 proper syntax and equality test in the directory server schema.
 
+=== deref_rf ===
+
+  deref_r(''ATTRIBUTE'',''FILTER''[,''OTHERATTRIBUTE'',''OTHERFILTER''[,...]],''VALUEATTRIBUTE'')
+
+Looks for entries named by this entry's ''ATTRIBUTE'' which match the
+''FILTER'', and then by those entries' ''ATTRIBUTE'' which also match
+the ''FILTER'', repeating the search until there are no more entries to
+find named by ''ATTRIBUTE'' in the set of entries seen.
+
+Taking that set as a new starting point, searches for entries named by
+that set's ''OTHERATTRIBUTE'' values which match ''OTHERFILTER'',
+similarly repeating until a new complete set of entries is determined.
+The process continues to be repeated for each listed attribute except
+the last.
+
+When the final set of entries is determined, their ''VALUEATTRIBUTE''
+values will be used to construct the result list.
+
+Here are some example entries:
+
+  dn: cn=group
+  objectclass: group
+  member: cn=othergroup
+  member: uid=bob
+  includedgroup: clan=macleod
+
+  dn: cn=othergroup
+  objectclass: group
+  member: uid=pete
+  uid: bogus
+
+  dn: uid=bob
+  objectclass: user
+  uid: bob
+
+  dn: uid=pete
+  objectclass: user
+  uid: pete
+
+  dn: clan=macleod
+  objectclass: group
+  includedgroup: cn=foundlings
+
+  dn: cn=foundlings
+  objectclass: group
+  member: uid=cmacleod
+  member: uid=dmacleod
+
+  dn: uid=cmacleod
+  objectclass: user
+  uid: cmacleod
+
+  dn: uid=dmacleod
+  objectclass: user
+  uid: dmacleod
+
+And here's how various expressions evaluate for ''cn=group'':
+
+  %deref_rf("member","objectclass=*","foo") -> no values
+  %deref_rf("member","objectclass=user","uid") -> (bob)
+
+When evaluating the first attribute, the ''member'' attribute of
+''cn=group'' against filter 'objectclass=user', produces this set of
+entries:
+
+    * uid=bob (added because it was named by ''cn=group'' and matches
+               the filter)
+
+The result list is pulled from this set of entries.
+
+Here's another example:
+
+  %deref_rf("includedgroup","objectclass=group","member","objectclass=user","uid") -> no values
+
+When evaluating the first attribute, the ''includedgroup'' attribute
+of ''cn=group'' leads to this set of ''objectclass=group'' entries:
+
+    * clan=macleod (named by cn=group)
+
+When evaluating the second attribute, the ''member'' attribute values
+for the previous set of entries produces no ''objectclass=user'' entries.
+
+The result list is, therefore, empty.
+
+Because the plugin attempts to track updates, every attribute used here
+(except for ''VALUEATTRIBUTE'') should be indexed and defined with a
+proper syntax and equality test in the directory server schema.
+
 === referred ===
 
   referred(''SET'',''THATATTRIBUTE'',''THATOTHERATTRIBUTE'')